Package org.eclipse.hono.util

Class CredentialsObject

java.lang.Object

org.eclipse.hono.util.CredentialsObject

public final class CredentialsObject
extends Object

Encapsulates the credentials information for a device as defined by the Credentials API.

Field Summary

Fields

Modifier and Type	Field	Description
protected io.vertx.core.json.JsonObject	json	The JSON object to map all values to/from.

Constructor Summary

Constructors

Constructor	Description
CredentialsObject()	Empty default constructor.
CredentialsObject(String deviceId, String authId, String type)	Creates new credentials for an authentication identifier.

Method Summary

Modifier and Type	Method	Description
CredentialsObject	addSecret(io.vertx.core.json.JsonObject secret)	Adds a secret.
CredentialsObject	addSecret(Map<String,Object> secret)	Adds a secret.
void	checkSecrets()	Checks if this credentials object contains secrets that comply with the Credentials API specification.
void	checkSecrets(BiConsumer<String,io.vertx.core.json.JsonObject> secretValidator)	Checks if this credentials object contains secrets that comply with the Credentials API specification.
void	checkValidity()	Checks if this credentials object is in a consistent state.
void	checkValidity(BiConsumer<String,io.vertx.core.json.JsonObject> secretValidator)	Checks if this credentials object is in a consistent state.
static io.vertx.core.json.JsonObject	emptySecret(Instant notBefore, Instant notAfter)	Creates an otherwise empty secret for a not-before and a not-after instant.
static CredentialsObject	fromClearTextPassword(String deviceId, String username, String clearTextPassword, Instant notBefore, Instant notAfter)	Creates a credentials object for a device based on a username and clear text password.
static CredentialsObject	fromClientCertificate(String deviceId, X509Certificate certificate, Instant notBefore, Instant notAfter)	Creates a credentials object for a device based on a client certificate.
static CredentialsObject	fromHashedPassword(String deviceId, String username, String passwordHash, String hashAlgorithm, Instant notBefore, Instant notAfter, byte[] salt)	Creates a credentials object for a device based on a username and password hash.
static CredentialsObject	fromPresharedKey(String deviceId, String authId, byte[] key, Instant notBefore, Instant notAfter)	Creates a credentials object for a device and auth ID.
static CredentialsObject	fromSubjectDn(String deviceId, X500Principal subjectDn, Instant notBefore, Instant notAfter)	Creates a credentials object for a device based on a subject DN.
String	getAuthId()	Gets the authentication identifier that these credentials are used for.
List<io.vertx.core.json.JsonObject>	getCandidateSecrets()	Filters the currently valid secrets from the secrets on record.
<T> List<T>	getCandidateSecrets(Function<io.vertx.core.json.JsonObject,T> projection)	Filters the currently valid secrets from the secrets on record.
String	getDeviceId()	Gets the identifier of the device that these credentials belong to.
static Instant	getNotAfter(io.vertx.core.json.JsonObject secret)	Gets the not after instant of a secret.
static Instant	getNotBefore(io.vertx.core.json.JsonObject secret)	Gets the not before instant of a secret.
protected static <T> T	getProperty(io.vertx.core.json.JsonObject parent, String name, Class<T> clazz)	Gets a property value.
protected static <T> T	getProperty(io.vertx.core.json.JsonObject parent, String name, Class<T> clazz, T defaultValue)	Gets a property value.
<T> T	getProperty(String name, Class<T> clazz)	Gets a property value.
<T> T	getProperty(String name, Class<T> clazz, T defaultValue)	Gets a property value.
io.vertx.core.json.JsonArray	getSecrets()	Gets this credentials' secret(s).
String	getType()	Gets the type of these credentials.
static io.vertx.core.json.JsonObject	hashedPasswordSecretForClearTextPassword(String clearTextpassword, Instant notBefore, Instant notAfter)	Creates a hashed-password secret for a clear text password.
static io.vertx.core.json.JsonObject	hashedPasswordSecretForPasswordHash(String passwordHash, String hashAlgorithm, Instant notBefore, Instant notAfter, byte[] salt)	Creates a hashed-password secret for a password hash.
static io.vertx.core.json.JsonObject	hashedPasswordSecretForPasswordHash(String passwordHash, String hashAlgorithm, Instant notBefore, Instant notAfter, String encodedSalt)	Creates a hashed-password secret for a password hash.
boolean	isEnabled()	Checks whether these credentials are enabled.
static boolean	isInValidityPeriod(io.vertx.core.json.JsonObject secret, Instant instant)	Checks if a given instant of time falls into a secret's validity period.
CredentialsObject	setAuthId(String authId)	Sets the authentication identifier that these these credentials are used for.
CredentialsObject	setDeviceId(String deviceId)	Sets the identifier of the device that these credentials belong to.
CredentialsObject	setEnabled(boolean enabled)	Sets whether these credentials are enabled.
CredentialsObject	setProperty(String name, Object value)	Adds a property to this tenant.
CredentialsObject	setType(String type)	Sets the type of these credentials.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

json

protected final io.vertx.core.json.JsonObject json

The JSON object to map all values to/from.

Constructor Detail

CredentialsObject

public CredentialsObject()

Empty default constructor.

CredentialsObject

public CredentialsObject(String deviceId,
                         String authId,
                         String type)

Creates new credentials for an authentication identifier.

Note that an instance created using this constructor does not contain any secrets.

Parameters:

deviceId - The device to which the credentials belong.

authId - The authentication identifier of the credentials.

type - The type of credentials.

Method Detail

setProperty

public CredentialsObject setProperty(String name,
                                     Object value)

Adds a property to this tenant.

Parameters:

name - The property name.

value - The property value.

Returns:

This credentials object for command chaining.

Throws:

NullPointerException - if name is null.

getDeviceId

public String getDeviceId()

Gets the identifier of the device that these credentials belong to.

Returns:

The identifier or null if not set.

setDeviceId

public CredentialsObject setDeviceId(String deviceId)

Sets the identifier of the device that these credentials belong to.

Parameters:

deviceId - The identifier.

Returns:

This credentials object for method chaining.

getType

public String getType()

Gets the type of these credentials.

Returns:

The type or null if not set.

setType

public CredentialsObject setType(String type)

Sets the type of these credentials.

Parameters:

type - The credentials type.

Returns:

This credentials object for method chaining.

getAuthId

public String getAuthId()

Gets the authentication identifier that these credentials are used for.

Returns:

The identifier or null if not set.

setAuthId

public CredentialsObject setAuthId(String authId)

Sets the authentication identifier that these these credentials are used for.

Parameters:

authId - The identifier.

Returns:

This credentials object for method chaining.

isEnabled

public boolean isEnabled()

Checks whether these credentials are enabled.

The default value is true.

Returns:

true if these credentials can be used for authenticating devices.

setEnabled

public CredentialsObject setEnabled(boolean enabled)

Sets whether these credentials are enabled.

The default value is true.

Parameters:

enabled - true if these credentials can be used for authenticating devices.

Returns:

This credentials object for method chaining.

getSecrets

public io.vertx.core.json.JsonArray getSecrets()

Gets this credentials' secret(s).

The elements of the returned list are of type JsonObject.

Returns:

The (potentially empty) list of secrets.

addSecret

public CredentialsObject addSecret(io.vertx.core.json.JsonObject secret)

Adds a secret.

Parameters:

secret - The secret to set.

Returns:

This credentials object for method chaining.

addSecret

public CredentialsObject addSecret(Map<String,Object> secret)

Adds a secret.

Parameters:

secret - The secret to set.

Returns:

This credentials object for method chaining.

checkValidity

public void checkValidity()

Checks if this credentials object is in a consistent state.

Throws:

IllegalStateException - if any of the properties have invalid/inconsistent values. The exception's message property may contain a description of the problem.

checkValidity

public void checkValidity(BiConsumer<String,io.vertx.core.json.JsonObject> secretValidator)

Checks if this credentials object is in a consistent state.

Parameters:

secretValidator - A custom check that is performed for each secret. The validator should throw an exception to indicate a failure to validate the secret.

Throws:

IllegalStateException - if any of the properties have invalid/inconsistent values. The exception's message property may contain a description of the problem.

checkSecrets

public void checkSecrets()

Checks if this credentials object contains secrets that comply with the Credentials API specification.

Throws:

IllegalStateException - if no secrets are set or any of the secrets' not-before and not-after properties are malformed.

checkSecrets

public void checkSecrets(BiConsumer<String,io.vertx.core.json.JsonObject> secretValidator)

Checks if this credentials object contains secrets that comply with the Credentials API specification.

Parameters:

secretValidator - a custom check that is performed for each secret in addition to the standard checks. The validator should throw an exception to indicate a failure to validate the secret.

Throws:

NullPointerException - if the validator is null.

IllegalStateException - if no secrets are set or any of the secrets' not-before and not-after properties are malformed or if the given validator fails for any of the secrets.

getCandidateSecrets

public List<io.vertx.core.json.JsonObject> getCandidateSecrets()

Filters the currently valid secrets from the secrets on record.

A secret is considered valid if the current instant of time falls into its validity period.

Returns:

The secrets.

getCandidateSecrets

public <T> List<T> getCandidateSecrets(Function<io.vertx.core.json.JsonObject,T> projection)

Filters the currently valid secrets from the secrets on record.

A secret is considered valid if the current instant of time falls into its validity period.

Type Parameters:

T - The type of the property that the candidate secrets are projected on.

Parameters:

projection - A function to apply to each candidate secret. This function can be used to project the secret to one of its properties. The function may return null in order to omit the candidate secret from the result list.

Returns:

The properties that the secrets have been projected on.

Throws:

NullPointerException - if the function is null.

isInValidityPeriod

public static boolean isInValidityPeriod(io.vertx.core.json.JsonObject secret,
                                         Instant instant)

Checks if a given instant of time falls into a secret's validity period.

Parameters:

secret - The secret to check against.

instant - The instant of time.

Returns:

true if the instant falls into the secret's validity period.

getNotBefore

public static Instant getNotBefore(io.vertx.core.json.JsonObject secret)

Gets the not before instant of a secret.

Parameters:

secret - The secret.

Returns:

The instant or null if not-before is not set or uses an invalid time stamp format.

getNotAfter

public static Instant getNotAfter(io.vertx.core.json.JsonObject secret)

Gets the not after instant of a secret.

Parameters:

secret - The secret.

Returns:

The instant or null if not-after is not set or uses an invalid time stamp format.

emptySecret

public static io.vertx.core.json.JsonObject emptySecret(Instant notBefore,
                                                        Instant notAfter)

Creates an otherwise empty secret for a not-before and a not-after instant.

Parameters:

notBefore - The point in time from which on the credentials are valid or null if there is no such constraint.

notAfter - The point in time until the credentials are valid or null if there is no such constraint.

Returns:

The secret.

Throws:

IllegalArgumentException - if not-before is not before not-after.

fromHashedPassword

public static CredentialsObject fromHashedPassword(String deviceId,
                                                   String username,
                                                   String passwordHash,
                                                   String hashAlgorithm,
                                                   Instant notBefore,
                                                   Instant notAfter,
                                                   byte[] salt)

Creates a credentials object for a device based on a username and password hash.

The credentials created are of type hashed-password. The authentication identifier will be set to the given username.

Parameters:

deviceId - The device identifier.

username - The username.

passwordHash - The password hash.

hashAlgorithm - The algorithm that has been used to create the password hash.

notBefore - The point in time from which on the credentials are valid.

notAfter - The point in time until the credentials are valid.

salt - The salt to use for creating the password hash.

Returns:

The credentials.

Throws:

NullPointerException - if any of device ID, authentication ID, password hash or hash algorithm are null.

IllegalArgumentException - if the not-before instant does not lie before the not after instant or if the algorithm is not supported.

fromClearTextPassword

public static CredentialsObject fromClearTextPassword(String deviceId,
                                                      String username,
                                                      String clearTextPassword,
                                                      Instant notBefore,
                                                      Instant notAfter)

Creates a credentials object for a device based on a username and clear text password.

The credentials created are of type hashed-password. The authentication identifier will be set to the given username.

Parameters:

deviceId - The device identifier.

username - The username.

clearTextPassword - The password.

notBefore - The point in time from which on the credentials are valid.

notAfter - The point in time until the credentials are valid.

Returns:

The credentials.

Throws:

NullPointerException - if any of device ID, authentication ID or password are null.

IllegalArgumentException - if the not-before instant does not lie before the not after instant or if the algorithm is not supported.

hashedPasswordSecretForPasswordHash

public static io.vertx.core.json.JsonObject hashedPasswordSecretForPasswordHash(String passwordHash,
                                                                                String hashAlgorithm,
                                                                                Instant notBefore,
                                                                                Instant notAfter,
                                                                                byte[] salt)

Creates a hashed-password secret for a password hash.

Parameters:

passwordHash - The Base64 encoded password hash.

hashAlgorithm - The algorithm used for creating the password hash.

notBefore - The point in time from which on the secret is valid.

notAfter - The point in time until the secret is valid.

salt - The salt to use for creating the password hash.

Returns:

The secret.

Throws:

NullPointerException - if any of password hash or hash algorithm are null.

IllegalArgumentException - if the not-before instant does not lie before the not after instant or if the algorithm is not supported.

hashedPasswordSecretForPasswordHash

public static io.vertx.core.json.JsonObject hashedPasswordSecretForPasswordHash(String passwordHash,
                                                                                String hashAlgorithm,
                                                                                Instant notBefore,
                                                                                Instant notAfter,
                                                                                String encodedSalt)

Creates a hashed-password secret for a password hash.

Parameters:

passwordHash - The Base64 encoded password hash.

hashAlgorithm - The algorithm used for creating the password hash.

notBefore - The point in time from which on the secret is valid.

notAfter - The point in time until the secret is valid.

encodedSalt - The Base64 encoded salt to use for creating the password hash or null if the password has been hashed without a salt.

Returns:

The secret.

Throws:

NullPointerException - if any of password hash or hash algorithm are null.

IllegalArgumentException - if the not-before instant does not lie before the not after instant or if the algorithm is not supported.

hashedPasswordSecretForClearTextPassword

public static io.vertx.core.json.JsonObject hashedPasswordSecretForClearTextPassword(String clearTextpassword,
                                                                                     Instant notBefore,
                                                                                     Instant notAfter)

Creates a hashed-password secret for a clear text password.

Parameters:

clearTextpassword - The password.

notBefore - The point in time from which on the secret is valid.

notAfter - The point in time until the secret is valid.

Returns:

The secret.

Throws:

NullPointerException - if password is null.

IllegalArgumentException - if the not-before instant does not lie before the not after instant or if the algorithm is not supported.

fromPresharedKey

public static CredentialsObject fromPresharedKey(String deviceId,
                                                 String authId,
                                                 byte[] key,
                                                 Instant notBefore,
                                                 Instant notAfter)

Creates a credentials object for a device and auth ID.

The credentials created are of type psk.

Parameters:

deviceId - The device identifier.

authId - The authentication identifier.

key - The shared key.

notBefore - The point in time from which on the credentials are valid.

notAfter - The point in time until the credentials are valid.

Returns:

The credentials.

Throws:

NullPointerException - if any of device ID, authentication ID or password is null.

IllegalArgumentException - if the not-before instant does not lie before the not after instant.

fromClientCertificate

public static CredentialsObject fromClientCertificate(String deviceId,
                                                      X509Certificate certificate,
                                                      Instant notBefore,
                                                      Instant notAfter)

Creates a credentials object for a device based on a client certificate.

The credentials created are of type x509-cert. The authentication identifier will be set to the certificate's subject DN using the serialization format defined by RFC 2253, Section 2.

Parameters:

deviceId - The device identifier.

certificate - The device's client certificate.

notBefore - The point in time from which on the credentials are valid.

notAfter - The point in time until the credentials are valid.

Returns:

The credentials.

Throws:

NullPointerException - if device ID or certificate are null.

IllegalArgumentException - if the not-before instant does not lie before the not after instant.

fromSubjectDn

public static CredentialsObject fromSubjectDn(String deviceId,
                                              X500Principal subjectDn,
                                              Instant notBefore,
                                              Instant notAfter)

Creates a credentials object for a device based on a subject DN.

The credentials created are of type x509-cert. The authentication identifier will be set to the subject DN using the serialization format defined by RFC 2253, Section 2.

Parameters:

deviceId - The device identifier.

subjectDn - The subject DN.

notBefore - The point in time from which on the credentials are valid.

notAfter - The point in time until the credentials are valid.

Returns:

The credentials.

Throws:

NullPointerException - if device ID or subject DN are null.

IllegalArgumentException - if the not-before instant does not lie before the not after instant.

getProperty

public final <T> T getProperty(String name,
                               Class<T> clazz)

Gets a property value.

Type Parameters:

T - The type of the property.

Parameters:

name - The property name.

clazz - The target type.

Returns:

The property value or null if the property is not set or is of an unexpected type.

Throws:

NullPointerException - if name is null.

getProperty

public final <T> T getProperty(String name,
                               Class<T> clazz,
                               T defaultValue)

Gets a property value.

Type Parameters:

T - The type of the property.

Parameters:

name - The property name.

defaultValue - A default value to return if the property is null.

clazz - The target type.

Returns:

The property value or the default value if the property is not set or is of an unexpected type.

Throws:

NullPointerException - if name is null.

getProperty

protected static final <T> T getProperty(io.vertx.core.json.JsonObject parent,
                                         String name,
                                         Class<T> clazz)

Gets a property value.

Type Parameters:

T - The type of the property.

Parameters:

parent - The JSON to get the property value from.

name - The property name.

clazz - The target type.

Returns:

The property value or null if the property is not set or is of an unexpected type.

Throws:

NullPointerException - if any of the parameters is null.

getProperty

protected static final <T> T getProperty(io.vertx.core.json.JsonObject parent,
                                         String name,
                                         Class<T> clazz,
                                         T defaultValue)

Gets a property value.

Type Parameters:

T - The type of the property.

Parameters:

parent - The JSON to get the property value from.

name - The property name.

defaultValue - A default value to return if the property is null or is of an unexpected type.

clazz - The target type.

Returns:

The property value or the given default value if the property is not set or is of an unexpected type.

Throws:

NullPointerException - if any of the parameters except defaultValue is null.