Package 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 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.