com.netscape.certsrv.key

Class KeyClient

java.lang.Object

com.netscape.certsrv.client.Client

com.netscape.certsrv.key.KeyClient

public class KeyClient
extends Client

Author:

Endi S. Dewata, Abhishek Koneru

Field Summary

Fields

Modifier and Type	Field and Description
KeyResource	keyClient
KeyRequestResource	keyRequestClient

Fields inherited from class com.netscape.certsrv.client.Client

client, clients, name, subsystem

Constructor Summary

Constructors

Constructor and Description
KeyClient(PKIClient client, java.lang.String subsystem)

Method Summary

Modifier and Type	Method and Description
void	approveRequest(RequestId id) Approve a secret recovery request
KeyRequestResponse	archiveEncryptedData(java.lang.String clientKeyId, java.lang.String dataType, java.lang.String keyAlgorithm, int keySize, java.lang.String algorithmOID, byte[] nonceData, byte[] encryptedData, byte[] transWrappedSessionKey) Archive a secret (symmetric key or passphrase) on the DRM.
KeyRequestResponse	archivePassphrase(java.lang.String clientKeyId, java.lang.String passphrase) Archive a passphrase on the DRM.
KeyRequestResponse	archivePKIOptions(java.lang.String clientKeyId, java.lang.String dataType, java.lang.String keyAlgorithm, int keySize, byte[] pkiArchiveOptions) Archive a secret (symmetric key or passphrase) on the DRM using a PKIArchiveOptions data format.
KeyRequestResponse	archiveSymmetricKey(java.lang.String clientKeyId, org.mozilla.jss.crypto.SymmetricKey secret, java.lang.String keyAlgorithm, int keySize) Archive a symmetric key on the DRM.
void	cancelRequest(RequestId id) Cancel a secret recovery request
KeyRequestResponse	generateAsymmetricKey(java.lang.String clientKeyId, java.lang.String keyAlgorithm, int keySize, java.util.List<java.lang.String> usages, byte[] transWrappedSessionKey) Generate and archive an asymmetric keys in the DRM
KeyRequestResponse	generateSymmetricKey(java.lang.String clientKeyId, java.lang.String keyAlgorithm, int keySize, java.util.List<java.lang.String> usages, java.lang.String transWrappedSessionKey) Generate and archive a symmetric key in the DRM.
KeyInfo	getActiveKeyInfo(java.lang.String clientKeyID) Get the info in the KeyRecord for the active secret in the DRM.
CryptoProvider	getCrypto()
KeyInfo	getKeyInfo(KeyId id) Get the info in the KeyRecord for a specific secret in the DRM.
KeyRequestInfo	getRequestInfo(RequestId id) Return a KeyRequestInfo object for a specific request.
void	init()
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) List/Search archived secrets in the DRM.
KeyRequestInfoCollection	listRequests(java.lang.String requestState, java.lang.String requestType) Search key requests in the DRM based on the state/type of the requests.
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) List/Search key requests in the DRM
void	modifyKeyStatus(KeyId id, java.lang.String status) Modify the status of a key
KeyRequestResponse	recoverKey(KeyId keyId, byte[] sessionWrappedPassphrase, byte[] transWrappedSessionKey, byte[] nonceData, java.lang.String b64Certificate) Create a request to recover a secret.
void	rejectRequest(RequestId id) Reject a secret recovery request
Key	retrieveKey(KeyId keyId) Retrieve a secret (passphrase or symmetric key) from the DRM.
Key	retrieveKey(KeyId keyId, byte[] transWrappedSessionKey) Retrieve a secret (passphrase or symmetric key) from the DRM.
Key	retrieveKeyByPassphrase(KeyId keyId, java.lang.String passphrase) The secret is secured in transit by wrapping the secret with the passphrase using PBE encryption.
Key	retrieveKeyByPKCS12(KeyId keyId, java.lang.String certificate, java.lang.String passphrase) Retrieve an asymmetric private key and return it as PKCS12 data.
Key	retrieveKeyData(KeyRecoveryRequest data) Retrieve a secret from the DRM.
Key	retrieveKeyUsingWrappedPassphrase(KeyId keyId, byte[] transWrappedSessionKey, byte[] sessionWrappedPassphrase, byte[] nonceData) This method generates a key recovery request, approves it, and retrieves the secret referred to by keyId.
void	setCrypto(CryptoProvider crypto)
void	setTransportCert(java.lang.String transportCert) Set the value of the transport cert.

Methods inherited from class com.netscape.certsrv.client.Client

addClient, createProxy, getClient, getName, getSubsystem, removeClient

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

keyClient

public KeyResource keyClient

keyRequestClient

public KeyRequestResource keyRequestClient

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.net.URISyntaxException

Throws:

java.net.URISyntaxException

getCrypto

public CryptoProvider getCrypto()

setCrypto

public void setCrypto(CryptoProvider crypto)

setTransportCert

public void setTransportCert(java.lang.String transportCert)

Set the value of the transport cert. The HEADER and FOOTER should be removed from the string. HEADER - CertData.HEADER FOOTER - CertData.FOOTER

Parameters:

transportCert -

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)

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.

Returns:

a KeyInfoCollection object.

listRequests

public KeyRequestInfoCollection listRequests(java.lang.String requestState,
                                             java.lang.String requestType)

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.

Returns:

a KeyRequestCollection object.

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)

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

Returns:

a KeyRequestInfoCollection object.

getRequestInfo

public KeyRequestInfo getRequestInfo(RequestId id)

Return a KeyRequestInfo object for a specific request.

Parameters:

id - -- A Request Id object

Returns:

the KeyRequestInfo object for a specific request.

getKeyInfo

public KeyInfo getKeyInfo(KeyId id)

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.

getActiveKeyInfo

public KeyInfo getActiveKeyInfo(java.lang.String clientKeyID)

Get the info in the KeyRecord for the active secret in the DRM.

Parameters:

clientKeyID - -- Client Key Identifier

Returns:

modifyKeyStatus

public void modifyKeyStatus(KeyId id,
                            java.lang.String status)

Modify the status of a key

Parameters:

id - -- key id for secret

status - -- Status to be set for the key

approveRequest

public void approveRequest(RequestId id)

Approve a secret recovery request

Parameters:

id - -- Id of the request

rejectRequest

public void rejectRequest(RequestId id)

Reject a secret recovery request

Parameters:

id - -- Id of the request

cancelRequest

public void cancelRequest(RequestId id)

Cancel a secret recovery request

Parameters:

id - -- Id of the request

recoverKey

public KeyRequestResponse recoverKey(KeyId keyId,
                                     byte[] sessionWrappedPassphrase,
                                     byte[] transWrappedSessionKey,
                                     byte[] nonceData,
                                     java.lang.String b64Certificate)

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.

retrieveKeyData

public Key retrieveKeyData(KeyRecoveryRequest data)

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.

retrieveKey

public Key retrieveKey(KeyId keyId)
                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

retrieveKey

public Key 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 Key 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

retrieveKeyUsingWrappedPassphrase

public Key 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 Key retrieveKeyByPKCS12(KeyId keyId,
                               java.lang.String certificate,
                               java.lang.String passphrase)

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

archivePassphrase

public KeyRequestResponse archivePassphrase(java.lang.String clientKeyId,
                                            java.lang.String passphrase)
                                     throws java.lang.Exception

Archive a passphrase 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 Identfier

passphrase - -- Secret passphrase to be archived

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

public KeyRequestResponse archiveSymmetricKey(java.lang.String clientKeyId,
                                              org.mozilla.jss.crypto.SymmetricKey secret,
                                              java.lang.String keyAlgorithm,
                                              int keySize)
                                       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)

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

archiveEncryptedData

public KeyRequestResponse archiveEncryptedData(java.lang.String clientKeyId,
                                               java.lang.String dataType,
                                               java.lang.String keyAlgorithm,
                                               int keySize,
                                               java.lang.String algorithmOID,
                                               byte[] nonceData,
                                               byte[] encryptedData,
                                               byte[] transWrappedSessionKey)

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

symAlgParams - -- storing the value of Utils.base64encode(nonceData)

encryptedData - -- which is the secret wrapped by a session key (168 bit 3DES symmetric key)

transWrappedSessionKey - -- session key wrapped by the transport cert.

Returns:

A KeyRequestResponse object with information about the request.

archivePKIOptions

public KeyRequestResponse archivePKIOptions(java.lang.String clientKeyId,
                                            java.lang.String dataType,
                                            java.lang.String keyAlgorithm,
                                            int keySize,
                                            byte[] pkiArchiveOptions)

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

Returns:

A KeyRequestResponse object with information about the request.

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)

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.

Returns:

a KeyRequestResponse which contains a KeyRequestInfo object that describes the URL for the request and generated key.

generateAsymmetricKey

public KeyRequestResponse generateAsymmetricKey(java.lang.String clientKeyId,
                                                java.lang.String keyAlgorithm,
                                                int keySize,
                                                java.util.List<java.lang.String> usages,
                                                byte[] transWrappedSessionKey)

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 -

transWrappedSessionKey -

Returns: