com.oracle.iot.client.trust

Interface TrustedAssetsManager

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

public interface TrustedAssetsManager
extends java.io.Closeable

The TrustedAssetsManager interface defines methods for handling trust material used for activation and authentication to the IoT CS. Depending on the capability of the client or device as well as on the security requirements implementations of this interface may simply store sensitive trust material in a plain persistent store, in some keystore or in a secure token.

Authentication of Devices with the IoT CS

Before/Upon Device Activation

A device must authenticate with the OAuth service using a client assertion signed with the shared secret in order to retrieve an access token to perform activation with the IoT CS server.

After Device Activation

A device must authenticate with the OAuth service using a client assertion signed with the generated private key in order to retrieve an access token to perform activation with the IoT CS server.

Authentication of Pre-activated Enterprise Applications with the IoT CS

Before/Upon Application Activation

If an enterprise application is pre-activated, the application (client) has already been provisioned with an endpoint ID and a shared secret or key pair and this step does not apply and must not be performed.

After Application Activation

Depending on the provisioned credentials (a shared secret or key pair), a pre-activated enterprise application must either:

• if only provisioned with a shared secret, authenticate with the OAuth service using a client assertion signed with the shared secret in order to retrieve an access token to perform activation with the IoT CS server.
• [Not Supported in 1.1] if provisioned with a private key and certificate, authenticate with the OAuth service using a client assertion signed with the generated private key in order to retrieve an access token to perform activation with the IoT CS server.

Authentication of Enterprise Applications with the IoT CS (non pre-activated) [Not Supported in 1.1]

Before/Upon Application Activation

An enterprise application which is not pre-activated must authenticate with the OAuth service using a client assertion signed with the shared secret in order to retrieve an access token to perform activation with the IoT CS server.

After Application Activation

An enterprise application must must authenticate with the OAuth service using a client assertion signed with the generated private key in order to retrieve an access token to perform activation with the IoT CS server.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	TrustedAssetsManager.Factory

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DISABLE_LONG_POLLING_PROPERTY

Method Summary

Modifier and Type	Method and Description
void	generateKeyPair(java.lang.String algorithm, int keySize) Generates the key pair to be used for assertion-based client authentication with the IoT CS.
java.lang.String	getClientId() Retrieves the ID of this client.
byte[]	getEncryptedSharedSecret() Deprecated. This method is not called by the client library
byte[]	getEndpointCertificate() Retrieves the assigned endpoint certificate.
java.lang.String	getEndpointId() Retrieves the assigned endpoint ID.
java.security.PublicKey	getPublicKey() Retrieves the public key to be used for certificate request.
java.lang.String	getServerHost() Retrieves the IoT CS server host name.
int	getServerPort() Retrieves the IoT CS server port.
java.lang.String	getServerScheme() Retrieves the protocol scheme that should be used to talk to the IoT CS.
java.util.Vector<byte[]>	getTrustAnchorCertificates() Retrieves the trust anchor or most-trusted Certification Authority (CA) certificates to be used to validate the IoT CS server certificate chain.
boolean	isActivated() Returns whether the client is activated.
void	reset() Resets the trust material back to its provisioning state; in particular, the key pair is erased.
void	setEndPointCredentials(java.lang.String endpointId, byte[] certificate) Sets the assigned endpoint ID and certificate as returned by the activation procedure.
byte[]	signWithPrivateKey(byte[] data, java.lang.String algorithm) Signs the provided data using the specified algorithm and the private key.
byte[]	signWithSharedSecret(byte[] data, java.lang.String algorithm, java.lang.String hardwareId) Signs the provided data using the specified algorithm and the shared secret of the device indicated by the given hardware id.

Methods inherited from interface java.io.Closeable

close

Field Detail

DISABLE_LONG_POLLING_PROPERTY

static final java.lang.String DISABLE_LONG_POLLING_PROPERTY

See Also:

Constant Field Values

Method Detail

getServerHost

java.lang.String getServerHost()

Retrieves the IoT CS server host name.

Returns:

the IoT CS server host name.

Throws:

java.lang.IllegalStateException - if this method is called prior to the TrustedAssetsManager is fully initialized.

getServerPort

int getServerPort()

Retrieves the IoT CS server port.

Returns:

the IoT CS server port.

Throws:

java.lang.IllegalStateException - if this method is called prior to the TrustedAssetsManager is fully initialized.

getServerScheme

java.lang.String getServerScheme()

Retrieves the protocol scheme that should be used to talk to the IoT CS. The IoT CS client library code recognizes "https".

Returns:

the IoT CS server protocol scheme.

Throws:

java.lang.IllegalStateException - if this method is called prior to the TrustedAssetsManager is fully initialized.

getClientId

java.lang.String getClientId()

Retrieves the ID of this client. If the client is a device, the client ID is the activation ID; if the client is a pre-activated enterprise application, the client ID corresponds to the assigned endpoint ID. The client ID is used along with a client secret derived from the shared secret to perform secret-based client authentication with the IoT CS server.

Returns:

the ID of this client.

Throws:

java.lang.IllegalStateException - if this method is called prior to the TrustedAssetsManager is fully initialized.

getPublicKey

java.security.PublicKey getPublicKey()

Retrieves the public key to be used for certificate request.

Note: on ME platform SATSA is required.

Returns:

the public key or null if not present

Throws:

java.lang.IllegalStateException - if this method is called prior to the key pair is generated.

getTrustAnchorCertificates

java.util.Vector<byte[]> getTrustAnchorCertificates()

Retrieves the trust anchor or most-trusted Certification Authority (CA) certificates to be used to validate the IoT CS server certificate chain.

Returns:

a Vector of DER-encoded trust anchor certificates (byte arrays).

setEndPointCredentials

void setEndPointCredentials(java.lang.String endpointId,
                            byte[] certificate)
                     throws TrustException

Sets the assigned endpoint ID and certificate as returned by the activation procedure. Upon a call to this method, a compliant implementation of the TrustedAssetsManager interface must ensure the persistence of the provided endpoint credentials. This method can only be called once; unless the TrustedAssetsManager has been reset.

If the client is a pre-activated enterprise application, the endpoint ID has already been provisioned and calling this method MUST fail with an IllegalStateException.

Parameters:

endpointId - the assigned endpoint ID.

certificate - the DER-encoded certificate issued by the server or an empty array if no certificate was provided by the server.

Throws:

java.lang.IllegalStateException - if this method is called prior to the TrustedAssetsManager is fully initialized. or if this method is called while endpoint credentials have already been assigned.

java.lang.NullPointerException - if endpointId or certificate is null.

TrustException - if any error occurs performing the operation.

getEndpointId

java.lang.String getEndpointId()

Retrieves the assigned endpoint ID.

Returns:

the assigned endpoint ID.

Throws:

java.lang.IllegalStateException - if this method is called prior to the TrustedAssetsManager is fully initialized, in particular if this method is called before the client is successfully activated and the endpoint ID set.

getEndpointCertificate

byte[] getEndpointCertificate()

Retrieves the assigned endpoint certificate.

Returns:

the DER-encoded certificate or an empty array if no certificate was assigned.

Throws:

java.lang.IllegalStateException - if this method is called prior to the TrustedAssetsManager is fully initialized, in particular if this method is called before the device is successfully activated and the endpoint certificate set.

generateKeyPair

void generateKeyPair(java.lang.String algorithm,
                     int keySize)
              throws TrustException

Generates the key pair to be used for assertion-based client authentication with the IoT CS.

Parameters:

algorithm - the key algorithm.

keySize - the key size.

Throws:

TrustException - if any error occurs performing the operation.

java.lang.IllegalStateException - if this method is called after the client has been activated.

java.lang.NullPointerException - if algorithm is null.

java.lang.IllegalArgumentException - if size is negative or zero or otherwise unsupported.

signWithPrivateKey

byte[] signWithPrivateKey(byte[] data,
                          java.lang.String algorithm)
                   throws TrustException

Signs the provided data using the specified algorithm and the private key. This method is only use for assertion-based client authentication with the IoT CS.

Parameters:

data - the data to sign.

algorithm - the signature algorithm to use.

Returns:

the signature.

Throws:

TrustException - if any error occurs retrieving the necessary key material or performing the operation.

java.lang.NullPointerException - if algorithm or data is null.

getEncryptedSharedSecret

@Deprecated
byte[] getEncryptedSharedSecret()
                                     throws TrustException

Deprecated. This method is not called by the client library

Retrieves the device's shared secret to be used for post-production registration (optional). The shared secret may be generated if not already provisioned. The returned shared secret is encrypted using some pre-provisioned key - such as a public key / certificate of the IoT CS.

Returns:

the encrypted shared secret.

Throws:

java.lang.IllegalStateException - if this method is called prior to the TrustedAssetsManager is fully initialized.

TrustException - if this operation is not supported or if any error occurs performing the operation.

signWithSharedSecret

byte[] signWithSharedSecret(byte[] data,
                            java.lang.String algorithm,
                            java.lang.String hardwareId)
                     throws TrustException

Signs the provided data using the specified algorithm and the shared secret of the device indicated by the given hardware id. If the hardware id is not provisioned, a TrustException is thrown. Passing null for hardwareId is identical to passing getClientId().

Parameters:

data - the data to be hashed.

algorithm - the hash algorithm to use.

hardwareId - the hardware id of the device whose shared secret is to be used for signing.

Returns:

the hash of the data.

Throws:

TrustException - if any error occurs retrieving the necessary key material or performing the operation.

java.lang.NullPointerException - if algorithm or data is null.

isActivated

boolean isActivated()

Returns whether the client is activated. The client is deemed activated if it has at least been assigned endpoint ID.

Returns:

whether the client is activated.

Throws:

java.lang.IllegalStateException - if this method is called prior to the TrustedAssetsManager is fully initialized.

reset

void reset()
    throws TrustException

Resets the trust material back to its provisioning state; in particular, the key pair is erased. The client will have to go, at least,through activation again; depending on the provisioning policy in place, the client may have to go through registration again.

Throws:

TrustException - if any exception occurs.