com.amazonaws.cloudhsm.jce.provider

Class CloudHsmProvider

java.lang.Object

java.util.Dictionary<K,V>

java.util.Hashtable<java.lang.Object,java.lang.Object>

java.util.Properties

java.security.Provider

java.security.AuthProvider

com.amazonaws.cloudhsm.jce.provider.CloudHsmProvider

All Implemented Interfaces:

java.io.Closeable, java.io.Serializable, java.lang.AutoCloseable, java.lang.Cloneable, java.util.Map<java.lang.Object,java.lang.Object>

public class CloudHsmProvider
extends java.security.AuthProvider
implements java.io.Closeable

CloudHsmProvider defines the “CloudHSM” cryptographic service provider.

Refer to Supported mechanisms for Client SDK 5 for supported algorithms and their names.

CloudHsmProvider implements AuthProvider for authenticating explicitly with HSMs. Otherwise, authentication may be done implicitly from system properties or environment variables. See Provide credentials to the JCE provider.

Since:

5.4.0

See Also:

AuthProvider, Provide credentials to the JCE provider, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.security.Provider

java.security.Provider.Service

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CLOUDHSM_KEYSTORE_TYPE Type name for creating KeyStores with the CloudHSM provider.
static java.lang.String	PROVIDER_NAME CloudHSM provider name.

Constructor Summary

Constructors

Constructor and Description
CloudHsmProvider() Constructs an instance of CloudHsmProvider.
CloudHsmProvider(CloudHsmProviderConfig providerConfig) Constructs an instance of CloudHsmProvider.
CloudHsmProvider(java.lang.String path) Constructs an instance of CloudHsmProvider.

Method Summary

Modifier and Type	Method and Description
void	close() Queues the sockets and connections that the provider has taken to the HSM for closure.
java.lang.String	getInfo() getInfo() returns information about the underlying CloudHSM Provider.
void	login(javax.security.auth.Subject subject, javax.security.auth.callback.CallbackHandler handler) Logs in to the configured CloudHSM cluster.
void	logout() Logs out from the configured CloudHSM cluster.
void	setCallbackHandler(javax.security.auth.callback.CallbackHandler handler) Sets the login CallbackHandler for the CloudHSM provider.

Methods inherited from class java.security.Provider

clear, compute, computeIfAbsent, computeIfPresent, elements, entrySet, forEach, get, getName, getOrDefault, getProperty, getService, getServices, getVersion, keys, keySet, load, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, toString, values

Methods inherited from class java.util.Properties

getProperty, list, list, load, loadFromXML, propertyNames, save, setProperty, store, store, storeToXML, storeToXML, stringPropertyNames

Methods inherited from class java.util.Hashtable

clone, contains, containsKey, containsValue, equals, hashCode, isEmpty, size

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

CLOUDHSM_KEYSTORE_TYPE

public static final java.lang.String CLOUDHSM_KEYSTORE_TYPE

Type name for creating KeyStores with the CloudHSM provider.

See Also:

KeyStore, Constant Field Values

PROVIDER_NAME

public static final java.lang.String PROVIDER_NAME

CloudHSM provider name.

After registering the CloudHSM provider with Security, access the provider using this name.

See Also:

Security, Provider, Constant Field Values

Constructor Detail

CloudHsmProvider

public CloudHsmProvider()
                 throws java.io.IOException,
                        ProviderInitializationException,
                        javax.security.auth.login.LoginException

Constructs an instance of CloudHsmProvider.

The instance can be created to programmatically add CloudHsmProvider to Java Security Class. This constructor will try to use the configuration file from the default location that is installed with the CloudHSM SDK package installation.

This constructor will attempt to log in to the configured CloudHSM cluster if credentials are found in system properties or environment variables. See Provide credentials to the JCE provider.

Throws:

java.io.IOException - if the CloudHSM configuration file does not exist or cannot be read.

ProviderInitializationException - if there is an error initializing the Provider.

javax.security.auth.login.LoginException - if implicit credentials are present, but there is an error logging in.

java.lang.IllegalStateException - if a default CloudHSM provider instance has already been initialized.

See Also:

Provide credentials to the JCE provider

CloudHsmProvider

public CloudHsmProvider(java.lang.String path)
                 throws java.io.IOException,
                        ProviderInitializationException,
                        javax.security.auth.login.LoginException

Constructs an instance of CloudHsmProvider.

The instance can be created to programmatically add CloudHsmProvider to Java Security Class. This constructor will try to use the configuration file from the path provided.

This constructor will attempt to log in to the configured CloudHSM cluster if credentials are found in system properties or environment variables. See Provide credentials to the JCE provider.

Parameters:

path - Filesystem location of the desired CloudHSM configuration file.

Throws:

java.io.IOException - if the CloudHSM configuration file does not exist or cannot be read.

ProviderInitializationException - if there is an error initializing the Provider.

javax.security.auth.login.LoginException - if implicit credentials are present, but there is an error logging in.

java.lang.IllegalStateException - if a CloudHSM provider instance has already been initialized.

See Also:

Provide credentials to the JCE provider

CloudHsmProvider

public CloudHsmProvider(CloudHsmProviderConfig providerConfig)
                 throws java.io.IOException,
                        ProviderInitializationException,
                        javax.security.auth.login.LoginException

Constructs an instance of CloudHsmProvider.

The instance can be created to programmatically add CloudHsmProvider to Java Security Class. This constructor will try to use the configuration builder from the providerConfig provided.

This constructor will attempt to log in to the configured CloudHSM cluster if credentials are found in system properties or environment variables. See Provide credentials to the JCE provider.

Parameters:

providerConfig - an instance of com.amazonaws.cloudhsm.jce.provider.builder.CloudHsmProviderConfig which contains the CloudHsm configuration.

Throws:

java.io.IOException - When there is an exception when reading or retrieving the configuration.

ProviderInitializationException - if there is an error initializing the Provider.

javax.security.auth.login.LoginException - if implicit credentials are present, but there is an error logging in.

java.lang.IllegalStateException - if a CloudHSM provider with the same identifier has been created already.

See Also:

Provide credentials to the JCE provider

Method Detail

getInfo

public java.lang.String getInfo()

getInfo() returns information about the underlying CloudHSM Provider.

The response contains the following data:

• deviceLabel
• deviceManufacturerID
• deviceModel
• maxPinLen
• minPinLen
• hardwareVersion
• firmwareVersion
• isHardware
• utcTime

Overrides:

getInfo in class java.security.Provider

Returns:

Device information or null if there is a retrieval error.

login

public void login(javax.security.auth.Subject subject,
                  javax.security.auth.callback.CallbackHandler handler)
           throws javax.security.auth.login.LoginException

Logs in to the configured CloudHSM cluster.

Calling this method is not required if credentials were found in system properties or environment variables at the time this provider was constructed. See Provide credentials to the JCE provider.

Specified by:

login in class java.security.AuthProvider

Parameters:

subject - the Subject that may contain principals/credentials used for authentication or may be populated with additional principals/credentials after successful authentication has completed. This parameter may be null.

handler - the CallbackHandler used by this provider to obtain authentication information from the caller, which may be null.

Throws:

javax.security.auth.login.LoginException - if the callback handler is not present or provides invalid credentials.

See Also:

Provide credentials to the JCE provider, UsernamePasswordAuthHandler

logout

public void logout()
            throws LogoutException

Logs out from the configured CloudHSM cluster.

This method is not available if login was performed implicitly using system properties or environment variables.

Specified by:

logout in class java.security.AuthProvider

Throws:

LogoutException - if the user is not logged in

java.lang.IllegalStateException - if login was initially performed implicitly

See Also:

login(Subject, CallbackHandler)

setCallbackHandler

public void setCallbackHandler(javax.security.auth.callback.CallbackHandler handler)

Sets the login CallbackHandler for the CloudHSM provider.

If login() is called with the handler parameter set to null, this CallbackHandler is used.

Specified by:

setCallbackHandler in class java.security.AuthProvider

Parameters:

handler - CallbackHandler to be used for login.

close

public void close()

Queues the sockets and connections that the provider has taken to the HSM for closure. After all JCE operations have been finished or finalized, the sockets will be closed. After calling this method, the provider instance will no longer be able to preform any new cryptographic operations.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable