com.authlete.common.types

Interface HSM

public interface HSM

Hardware Security Module.

This is the interface that needs to be implemented for an HSM. Authlete loads implementations of this interface dynamically. The way Authlete finds implementations is disclosed only to customers who use on-premises Authlete as necessary.

Since:

2.97

Method Summary

Modifier and Type	Method and Description
Map<String,Object>	createKey(Hsk hsk) Create a key on the HSM.
byte[]	decrypt(Hsk hsk, Map<String,Object> info, byte[] data) Decrypt data.
void	deleteKey(Hsk hsk, Map<String,Object> info) Delete a key on the HSM.
String	getName() The name of the HSM.
String	getPublicKey(Hsk hsk, Map<String,Object> info) Get the public key that corresponds to the key on the HSM.
byte[]	sign(Hsk hsk, Map<String,Object> info, byte[] data) Sign data and return the signature.
boolean	supportsJweAlg(JWEAlg alg) Check if the HSM supports the specified encryption algorithm.
boolean	supportsJwsAlg(JWSAlg alg) Check if the HSM supports the specified signing algorithm.

Method Detail

getName

String getName()

The name of the HSM.

The name is used as a value of the hsmName request parameter of the /api/hsk/create API (cf. HskCreateRequest.getHsmName()).

The name must match the regular expression "^[a-zA-Z][0-9a-zA-Z_]{0,29}".

Returns:

The name of the HSM.

supportsJwsAlg

boolean supportsJwsAlg(JWSAlg alg)

Check if the HSM supports the specified signing algorithm.

This method is called from within the implementation of the /api/hsk/create API. If this method returns false, the API call is rejected.

Parameters:

alg - A signing algorithm.

Returns:

true if the HSM supports the signing algorithm.

supportsJweAlg

boolean supportsJweAlg(JWEAlg alg)

Check if the HSM supports the specified encryption algorithm.

This method is called from within the implementation of the /api/hsk/create API. If this method returns false, the API call is rejected.

Parameters:

alg - An encryption algorithm.

Returns:

true if the HSM supports the encryption algorithm.

createKey

Map<String,Object> createKey(Hsk hsk)
                      throws IOException

Create a key on the HSM.

The argument hsk holds conditions for a key to be created. All properties of hsk except handle and publicKey properties have non-null values.

The implementation of this method is required to create a key on the HSM that meets the conditions. Then, if possible, the implementation should retrieve the public key that corresponds to the created key, convert the format of the public key into base64-encoded DER, and set it back to hsk by calling Hsk.setPublicKey(String). If the implementation did not set the public key, Authlete will call getPublicKey(Hsk, Map) after this method finishes.

The implementation of this method may return information associated with the created key as a Map. It is highly likely that the HSM returns an identifier of the created key which will be needed later for signing or decrypting. Such information can be embedded in the map. For example, like below.

 Map<String, Object> info = new HashMap<String, Object>();
 info.put("identifier", identifier);
 

The map returned from createKey() is converted into JSON, encrypted, and then stored into Authlete's database. The map will be used later as the info argument of other methods such as sign(Hsk, Map, byte[]).

Parameters:

hsk - Conditions for a key to be created.

Returns:

HSM-specific information associated with the newly created key.

Throws:

IOException - Failed to create a key on the HSM.

deleteKey

void deleteKey(Hsk hsk,
               Map<String,Object> info)
        throws IOException

Delete a key on the HSM.

In the case where the target key does not exist on the HSM, the implementation of this method does not have to raise an exception.

Parameters:

hsk - Information about the key.

info - HSM-specific information associated with the key. This is the map returned from createKey(Hsk).

Throws:

IOException - Failed to delete the key.

getPublicKey

String getPublicKey(Hsk hsk,
                    Map<String,Object> info)
             throws IOException

Get the public key that corresponds to the key on the HSM.

The format of the returned public key should be base64-encoded DER. See "Illustrated X.509 Certificate" about the format.

Parameters:

hsk - Information about the key.

info - HSM-specific information associated with the key. This is the map returned from createKey(Hsk).

Returns:

The public key in base64-encoded DER format.

Throws:

IOException - Failed to get the public key.

sign

byte[] sign(Hsk hsk,
            Map<String,Object> info,
            byte[] data)
     throws IOException

Sign data and return the signature.

Parameters:

hsk - Information about the key.

info - HSM-specific information associated with the key. This is the map returned from createKey(Hsk).

data - The target data to sign.

Returns:

The signature generated by the signing.

Throws:

IOException - Failed to sign the data.

decrypt

byte[] decrypt(Hsk hsk,
               Map<String,Object> info,
               byte[] data)
        throws IOException

Decrypt data.

Parameters:

hsk - Information about the key.

info - HSM-specific information associated with the key. This is the map returned from createKey(Hsk).

data - Data encrypted with the public key that corresponds to the key on the HSM.

Returns:

Decrypted data.

Throws:

IOException - Failed to decrypt the data.