Class KeyClient


  • public class KeyClient
    extends Client
    Author:
    Endi S. Dewata, Abhishek Koneru
    • Constructor Detail

      • KeyClient

        public KeyClient​(PKIClient client,
                         java.lang.String subsystem)
                  throws java.lang.Exception
        Throws:
        java.lang.Exception
    • Method Detail

      • init

        public void init()
                  throws java.lang.Exception
        Throws:
        java.lang.Exception
      • setTransportCert

        public void setTransportCert​(org.mozilla.jss.crypto.X509Certificate transportCert)
                              throws java.lang.Exception
        Throws:
        java.lang.Exception
      • listKeys

        public KeyInfoCollection listKeys​(java.lang.String clientKeyID,
                                          java.lang.String status,
                                          java.lang.Integer maxSize,
                                          java.lang.Integer maxTime,
                                          java.lang.Integer start,
                                          java.lang.Integer size,
                                          java.lang.String realm)
                                   throws java.lang.Exception
        List/Search archived secrets in the DRM.
        Parameters:
        clientKeyID - -- Client Key Identifier
        status - -- Status of the keys to be listed
        maxSize - -- Maximum number of keys to be fetched
        maxTime - -- Maximum time for the operation to take
        start - -- Start index of list
        size - -- Size of the list to be returned.
        realm - - authz realm
        Returns:
        a KeyInfoCollection object.
        Throws:
        java.lang.Exception
      • listKeys

        public KeyInfoCollection listKeys​(java.lang.String clientKeyID,
                                          java.lang.String status,
                                          java.lang.Integer maxSize,
                                          java.lang.Integer maxTime,
                                          java.lang.Integer start,
                                          java.lang.Integer size)
                                   throws java.lang.Exception
        Throws:
        java.lang.Exception
      • listRequests

        public KeyRequestInfoCollection listRequests​(java.lang.String requestState,
                                                     java.lang.String requestType,
                                                     java.lang.String realm)
                                              throws java.lang.Exception
        Search key requests in the DRM based on the state/type of the requests.
        Parameters:
        requestState - -- State of the requests to be queried.
        requestType - -- Type of the requests to be queried.
        realm - -- Authz Realm
        Returns:
        a KeyRequestCollection object.
        Throws:
        java.lang.Exception
      • listRequests

        public KeyRequestInfoCollection listRequests​(java.lang.String requestState,
                                                     java.lang.String requestType)
                                              throws java.lang.Exception
        Throws:
        java.lang.Exception
      • listRequests

        public KeyRequestInfoCollection listRequests​(java.lang.String requestState,
                                                     java.lang.String requestType,
                                                     java.lang.String clientKeyID,
                                                     RequestId start,
                                                     java.lang.Integer pageSize,
                                                     java.lang.Integer maxResults,
                                                     java.lang.Integer maxTime,
                                                     java.lang.String realm)
                                              throws java.lang.Exception
        List/Search key requests in the DRM
        Parameters:
        requestState - -- State of the requests to be queried.
        requestType - -- Type of the requests to be queried.
        clientKeyID - -- Client Key Identifier
        start - -- Start index of list
        pageSize - -- Size of the list to be returned.
        maxResults - -- Maximum number of requests to be fetched
        maxTime - -- Maximum time for the operation to take
        realm - -- Authz Realm
        Returns:
        a KeyRequestInfoCollection object.
        Throws:
        java.lang.Exception
      • getRequestInfo

        public KeyRequestInfo getRequestInfo​(RequestId id)
                                      throws java.lang.Exception
        Return a KeyRequestInfo object for a specific request.
        Parameters:
        id - -- A Request Id object
        Returns:
        the KeyRequestInfo object for a specific request.
        Throws:
        java.lang.Exception
      • getKeyInfo

        public KeyInfo getKeyInfo​(KeyId id)
                           throws java.lang.Exception
        Get the info in the KeyRecord for a specific secret in the DRM.
        Parameters:
        id - -- key id for secret
        Returns:
        the KeyInfo object for a specific request.
        Throws:
        java.lang.Exception
      • getActiveKeyInfo

        public KeyInfo getActiveKeyInfo​(java.lang.String clientKeyID)
                                 throws java.lang.Exception
        Get the info in the KeyRecord for the active secret in the DRM.
        Parameters:
        clientKeyID - -- Client Key Identifier
        Throws:
        java.lang.Exception
      • modifyKeyStatus

        public void modifyKeyStatus​(KeyId id,
                                    java.lang.String status)
                             throws java.lang.Exception
        Modify the status of a key
        Parameters:
        id - -- key id for secret
        status - -- Status to be set for the key
        Throws:
        java.lang.Exception
      • approveRequest

        public void approveRequest​(RequestId id)
                            throws java.lang.Exception
        Approve a secret recovery request
        Parameters:
        id - -- Id of the request
        Throws:
        java.lang.Exception
      • rejectRequest

        public void rejectRequest​(RequestId id)
                           throws java.lang.Exception
        Reject a secret recovery request
        Parameters:
        id - -- Id of the request
        Throws:
        java.lang.Exception
      • cancelRequest

        public void cancelRequest​(RequestId id)
                           throws java.lang.Exception
        Cancel a secret recovery request
        Parameters:
        id - -- Id of the request
        Throws:
        java.lang.Exception
      • recoverKey

        public KeyRequestResponse recoverKey​(KeyId keyId,
                                             byte[] sessionWrappedPassphrase,
                                             byte[] transWrappedSessionKey,
                                             byte[] nonceData,
                                             java.lang.String b64Certificate)
                                      throws java.lang.Exception
        Create a request to recover a secret. To retrieve a symmetric key or passphrase, the only parameter that is required is the KeyId object. It is possible (but not required) to pass in the session keys/passphrase and nonceData for the retrieval at this time. To retrieve an asymmetric key, the keyId and the the base-64 encoded certificate is required.
        Parameters:
        keyId - -- key id for secret
        sessionWrappedPassphrase - -- A passphrase wrapped by a session key
        transWrappedSessionKey - -- The session key, used to wrap the passphrase, wrapped by the DRM transport cert.
        nonceData - -- IV parameter used while encrypting the passphrase using the session key.
        b64Certificate - -- A certificate in encoded using Base64
        Returns:
        A KeyRequestResponse object containing information about the key request and the key.
        Throws:
        java.lang.Exception
      • retrieveKeyData

        public KeyData retrieveKeyData​(KeyRecoveryRequest data)
                                throws java.lang.Exception
        Retrieve a secret from the DRM.
        Parameters:
        data - -- a KeyRecoveryRequest containing the keyId of the secret being retrieved, the request_id of the approved recovery request and a wrapping mechanism.
        Returns:
        A Key object containing the wrapped secret.
        Throws:
        java.lang.Exception
      • generateSessionKey

        public org.mozilla.jss.crypto.SymmetricKey generateSessionKey()
                                                               throws java.lang.Exception
        Throws:
        java.lang.Exception
      • retrieveKey

        public KeyData retrieveKey​(KeyId keyId,
                                   org.mozilla.jss.crypto.SymmetricKey sessionKey)
                            throws java.lang.Exception
        Retrieve a secret (passphrase or symmetric key) from the DRM. To ensure data security in transit, the data will be returned encrypted by a session key (168 bit 3DES symmetric key) - which is first wrapped (encrypted) by the public key of the DRM transport certificate before being sent to the DRM. This method will call CryptoUtil methods to generate the session key and wrap it with the DRM transport cert. The function will return the Key object, but with the secret set to the variable data. (The decryption of the encryptedData is done on the client side i.e. the secret is not transmitted as it is by the server.)
        Parameters:
        keyId - -- key id for secret
        Returns:
        A Key object containing the unwrapped secret (set to the attribute data).
        Throws:
        java.lang.Exception - - Exceptions of type NoSuchAlgorithmException, IllegalStateException, TokenException, CertificateEncodingException, InvalidKeyException, InvalidAlgorithmParameterException, BadPaddingException, IllegalBlockSizeException
      • processKeyData

        public void processKeyData​(Key data,
                                   org.mozilla.jss.crypto.SymmetricKey sessionKey)
                            throws java.lang.Exception
        Throws:
        java.lang.Exception
      • retrieveKeyByRequest

        public KeyData retrieveKeyByRequest​(RequestId requestId,
                                            org.mozilla.jss.crypto.SymmetricKey sessionKey)
                                     throws java.lang.Exception
        Throws:
        java.lang.Exception
      • retrieveKey

        public KeyData retrieveKey​(KeyId keyId,
                                   byte[] transWrappedSessionKey)
                            throws java.lang.Exception
        Retrieve a secret (passphrase or symmetric key) from the DRM. This function generates a key recovery request, approves it, and retrieves the secret referred to by keyId. This assumes that only one approval is required to authorize the recovery. The parameter transWrappedSessionKey refers to the session key wrapped with the transport cert. The method will simply pass the data to the DRM, and will return the secret wrapped in the session key. The secret will still need to be unwrapped by the caller.
        Parameters:
        keyId - -- key id for secret
        transWrappedSessionKey - -- session key wrapped by the transport cert.
        Returns:
        A Key object containing the wrapped secret.
        Throws:
        java.lang.Exception - - Exceptions of type NoSuchAlgorithmException, IllegalStateException, TokenException, CertificateEncodingException, InvalidKeyException, InvalidAlgorithmParameterException, BadPaddingException, IllegalBlockSizeException
      • retrieveKeyByPassphrase

        public KeyData retrieveKeyByPassphrase​(KeyId keyId,
                                               java.lang.String passphrase)
                                        throws java.lang.Exception
        The secret is secured in transit by wrapping the secret with the passphrase using PBE encryption. CryptoUtil methods will be called to create the data to securely send the passphrase to the DRM. Basically, three pieces of data will be sent: - the passphrase wrapped by a 168 bit 3DES symmetric key (the session key). - the session key wrapped with the public key in the DRM transport certificate. - an ivps vector to be used as nonceData.
        Parameters:
        keyId - -- key id of secret.
        passphrase - -- passphrase used to wrap the secret in the response.
        Returns:
        A Key object with the secret wrapped with the passphrase.
        Throws:
        java.lang.Exception - - Exceptions of type NoSuchAlgorithmException, IllegalStateException, TokenException, CertificateEncodingException, InvalidKeyException, InvalidAlgorithmParameterException, BadPaddingException, IllegalBlockSizeException
      • retrieveKeyByRequestWithPassphrase

        public Key retrieveKeyByRequestWithPassphrase​(RequestId requestId,
                                                      java.lang.String passphrase)
                                               throws java.lang.Exception
        Throws:
        java.lang.Exception
      • retrieveKeyUsingWrappedPassphrase

        public KeyData retrieveKeyUsingWrappedPassphrase​(KeyId keyId,
                                                         byte[] transWrappedSessionKey,
                                                         byte[] sessionWrappedPassphrase,
                                                         byte[] nonceData)
                                                  throws java.lang.Exception
        This method generates a key recovery request, approves it, and retrieves the secret referred to by keyId. This assumes that only one approval is required to authorize the recovery. The method will return the secret encrypted by the passphrase using PBE Encryption. The secret will still need to be decrypted by the caller.
        Parameters:
        keyId - -- key id for secret
        transWrappedSessionKey - -- Session key wrapped with the transport cert
        sessionWrappedPassphrase - -- Passphrase wrapped with the session key
        nonceData - -- nonce data used for encryption.
        Returns:
        A Key object with the secret wrapped by the passphrase provided.
        Throws:
        java.lang.Exception - - Exceptions of type NoSuchAlgorithmException, IllegalStateException, TokenException, CertificateEncodingException, InvalidKeyException, InvalidAlgorithmParameterException, BadPaddingException, IllegalBlockSizeException
      • retrieveKeyByPKCS12

        public KeyData retrieveKeyByPKCS12​(KeyId keyId,
                                           java.lang.String certificate,
                                           java.lang.String passphrase)
                                    throws java.lang.Exception
        Retrieve an asymmetric private key and return it as PKCS12 data. This function generates a key recovery request, approves it, and retrieves the secret referred to by key_id in a PKCS12 file. This assumes that only one approval is required to authorize the recovery.
        Parameters:
        keyId - -- key id for secret
        certificate - -- the certificate associated with the private key
        passphrase - -- A passphrase for the pkcs12 file.
        Returns:
        A Key object with the wrapped secret
        Throws:
        java.lang.Exception
      • archiveSecret

        public KeyRequestResponse archiveSecret​(java.lang.String clientKeyId,
                                                byte[] secret,
                                                java.lang.String realm)
                                         throws java.lang.Exception
        Archive a secret on the KRA. Requires a user-supplied client ID. There can be only one active key with a specified client ID. If a record for a duplicate active key exists, a BadRequestException is thrown.
        Parameters:
        clientKeyId - -- Client Key Identfier
        secret - -- Secret to be archived
        realm - -- authorization realm
        Returns:
        A KeyRequestResponse object with information about the request.
        Throws:
        java.lang.Exception - - Exceptions of type NoSuchAlgorithmException, IllegalStateException, TokenException, IOException, CertificateEncodingException, InvalidKeyException, InvalidAlgorithmParameterException, BadPaddingException, IllegalBlockSizeException
      • archiveSecret

        public KeyRequestResponse archiveSecret​(java.lang.String clientKeyId,
                                                byte[] secret)
                                         throws java.lang.Exception
        Throws:
        java.lang.Exception
      • getWrapAlgorithmName

        public java.lang.String getWrapAlgorithmName()
      • archiveSymmetricKey

        public KeyRequestResponse archiveSymmetricKey​(java.lang.String clientKeyId,
                                                      org.mozilla.jss.crypto.SymmetricKey secret,
                                                      java.lang.String keyAlgorithm,
                                                      java.lang.Integer keySize,
                                                      java.lang.String realm)
                                               throws java.lang.Exception
        Archive a symmetric key on the DRM. Requires a user-supplied client ID. There can be only one active key with a specified client ID. If a record for a duplicate active key exists, a BadRequestException is thrown.
        Parameters:
        clientKeyId - -- Client Key Identifier
        keyAlgorithm - -- Algorithm used by the symmetric key
        keySize - -- Strength of the symmetric key (secret)
        realm - -- authorization realm
        Returns:
        A KeyRequestResponse object with information about the request.
        Throws:
        java.lang.Exception - - Exceptions of type NoSuchAlgorithmException, IllegalStateException, TokenException, IOException, CertificateEncodingException, InvalidKeyException, InvalidAlgorithmParameterException, BadPaddingException, IllegalBlockSizeException
      • archiveSymmetricKey

        @Deprecated
        public KeyRequestResponse archiveSymmetricKey​(java.lang.String clientKeyId,
                                                      org.mozilla.jss.crypto.SymmetricKey secret,
                                                      java.lang.String keyAlgorithm,
                                                      java.lang.Integer keySize)
                                               throws java.lang.Exception
        Deprecated.
        Throws:
        java.lang.Exception
      • archiveEncryptedData

        public KeyRequestResponse archiveEncryptedData​(java.lang.String clientKeyId,
                                                       java.lang.String dataType,
                                                       java.lang.String keyAlgorithm,
                                                       java.lang.Integer keySize,
                                                       java.lang.String algorithmOID,
                                                       byte[] nonceData,
                                                       byte[] encryptedData,
                                                       byte[] transWrappedSessionKey,
                                                       java.lang.String realm)
                                                throws java.lang.Exception
        Archive a secret (symmetric key or passphrase) on the DRM. This method is useful if the caller wants to do their own wrapping of the secret, or if the secret was generated on a separate client machine and the wrapping was done there.
        Parameters:
        clientKeyId - -- Client Key Identifier
        dataType - -- Type of secret being archived
        keyAlgorithm - -- Algorithm used - if the secret is a symmetric key
        keySize - -- Strength of the symmetric key (secret)
        algorithmOID - -- OID of the algorithm used for the symmetric key wrap
        nonceData - -- nonce data
        encryptedData - -- which is the secret wrapped by a session key (168 bit 3DES symmetric key)
        transWrappedSessionKey - -- session key wrapped by the transport cert.
        realm - -- authorization realm
        Returns:
        A KeyRequestResponse object with information about the request.
        Throws:
        java.lang.Exception
      • archiveEncryptedData

        @Deprecated
        public KeyRequestResponse archiveEncryptedData​(java.lang.String clientKeyId,
                                                       java.lang.String dataType,
                                                       java.lang.String keyAlgorithm,
                                                       java.lang.Integer keySize,
                                                       java.lang.String algorithmOID,
                                                       byte[] nonceData,
                                                       byte[] encryptedData,
                                                       byte[] transWrappedSessionKey)
                                                throws java.lang.Exception
        Deprecated.
        Throws:
        java.lang.Exception
      • archivePKIOptions

        public KeyRequestResponse archivePKIOptions​(java.lang.String clientKeyId,
                                                    java.lang.String dataType,
                                                    java.lang.String keyAlgorithm,
                                                    int keySize,
                                                    byte[] pkiArchiveOptions,
                                                    java.lang.String realm)
                                             throws java.lang.Exception
        Archive a secret (symmetric key or passphrase) on the DRM using a PKIArchiveOptions data format.
        Parameters:
        clientKeyId - -- Client Key Identifier
        dataType - -- Type of secret bring archived
        keyAlgorithm - -- Algorithm used if the secret is a symmetric key
        keySize - -- Strength of the symmetric key
        pkiArchiveOptions - -- is the data to be archived wrapped in a PKIArchiveOptions structure
        realm - -- authorization realm
        Returns:
        A KeyRequestResponse object with information about the request.
        Throws:
        java.lang.Exception
      • archivePKIOptions

        @Deprecated
        public KeyRequestResponse archivePKIOptions​(java.lang.String clientKeyId,
                                                    java.lang.String dataType,
                                                    java.lang.String keyAlgorithm,
                                                    int keySize,
                                                    byte[] pkiArchiveOptions)
                                             throws java.lang.Exception
        Deprecated.
        Throws:
        java.lang.Exception
      • generateSymmetricKey

        public KeyRequestResponse generateSymmetricKey​(java.lang.String clientKeyId,
                                                       java.lang.String keyAlgorithm,
                                                       int keySize,
                                                       java.util.List<java.lang.String> usages,
                                                       java.lang.String transWrappedSessionKey,
                                                       java.lang.String realm)
                                                throws java.lang.Exception
        Generate and archive a symmetric key in the DRM.
        Parameters:
        clientKeyId - -- Client Key Identifier
        keyAlgorithm - -- Algorithm to be used to generate the key
        keySize - -- Strength of the keys
        usages - -- Usages of the generated key.
        transWrappedSessionKey - - client generated session key wrapped by KRA transport key
        realm - -- authorization realm
        Returns:
        a KeyRequestResponse which contains a KeyRequestInfo object that describes the URL for the request and generated key.
        Throws:
        java.lang.Exception
      • generateSymmetricKey

        @Deprecated
        public KeyRequestResponse generateSymmetricKey​(java.lang.String clientKeyId,
                                                       java.lang.String keyAlgorithm,
                                                       int keySize,
                                                       java.util.List<java.lang.String> usages,
                                                       java.lang.String transWrappedSessionKey)
                                                throws java.lang.Exception
        Deprecated.
        Throws:
        java.lang.Exception
      • generateAsymmetricKey

        public KeyRequestResponse generateAsymmetricKey​(java.lang.String clientKeyId,
                                                        java.lang.String keyAlgorithm,
                                                        int keySize,
                                                        java.util.List<java.lang.String> usages,
                                                        byte[] transWrappedSessionKey,
                                                        java.lang.String realm)
                                                 throws java.lang.Exception
        Generate and archive an asymmetric keys in the DRM
        Parameters:
        clientKeyId - -- Client Key Identifier
        keyAlgorithm - -- Algorithm to be used to generate the asymmetric keys
        keySize - -- Strength of the keys
        usages - -- key usages
        transWrappedSessionKey - -- client generated session key wrapped by the KRA transport key
        realm - -- authorization realm
        Throws:
        java.lang.Exception
      • generateAsymmetricKey

        @Deprecated
        public KeyRequestResponse generateAsymmetricKey​(java.lang.String clientKeyId,
                                                        java.lang.String keyAlgorithm,
                                                        int keySize,
                                                        java.util.List<java.lang.String> usages,
                                                        byte[] transWrappedSessionKey)
                                                 throws java.lang.Exception
        Deprecated.
        Throws:
        java.lang.Exception