Package org.opends.server.crypto

Class CryptoManager.CipherService

java.lang.Object

org.opends.server.crypto.CryptoManager.CipherService

Enclosing class:

CryptoManager

public static class CryptoManager.CipherService
extends Object

Provides cryptographic related operations and key management.

Keys are local to each instance and can be exported/imported to the user, but they are not automatically persisted in any way. Only one secret key is considered active for encryption, in some cases previous keys are kept for decryption only.

Users should populate the keys to use by calling useKeysFromEncoding(ByteSequence) and store them off band using the binary representation by calling getEncodedSecretKeys() for all keys (current and all previous keys), or currentKeyAsLdapEntry() for storing only the current key as an LDAP entry. All exported keys are wrapped by the server master key pair, so it is safe to store or transmit them in non secure storage.

One cipher secret key, generated by useNewKeyIfNeeded(String, int), useKeyForDefaultCipher() or set by useKeyFromEntry(Entry) is considered to be the active key and replaces the previous active key. The previous active key is lost except when calling useNewKeyIfNeeded(String, int), which keeps the previous key for decryption.

Method Summary

Modifier and Type	Method	Description
Entry	currentKeyAsLdapEntry()	Return the active cipher key as an LDAP Entry.
byte[]	decrypt(byte[] data)	Decrypts data.
InputStream	decrypt(InputStream inputStream)	Reads encrypted data from the provided input stream.
byte[]	encrypt(byte[] data)	Encrypts data with the configured cipher transformation and key length.
OutputStream	encrypt(OutputStream outputStream)	Writes encrypted data to the provided output stream using the current active cipher.
byte[]	encryptWithoutKeyId(byte[] data)	Encrypts data with the configured cipher transformation and key length.
OutputStream	encryptWithoutKeyId(OutputStream outputStream)	Writes encrypted data to the provided output stream using the current active cipher.
void	ensureCipherKeyIsAvailable(String transformation, int keyLengthBits)	Ensures that a key exists for the provided cipher transformation and key length.
ByteSequence	getEncodedSecretKeys()	Return the list of active and previously used secret keys encoded as an ASN.1 sequence.
String	toString()
CryptoManager.CipherService	useKeyForDefaultCipher()	Generate a new cipher key for the transformation and key length.
CryptoManager.CipherService	useKeyFromEntry(Entry entry)	Use the cipher key from the provided information in the LDAP Entry as active key.
CryptoManager.CipherService	useKeysFromEncoding(ByteSequence wrappedKeys)	Use the provided encoded secret keys for cryptographic operations.
CryptoManager.CipherService	useNewKeyIfNeeded(String transformation, int keyLengthBits)	Generate a new cipher key for the given transformation and key length.

Methods inherited from class java.lang.Object

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

Method Detail

decrypt

public byte[] decrypt(byte[] data)
               throws GeneralSecurityException,
                      CryptoManagerException

Decrypts data.

If the prologue does not contain a key identifier, it is assumed the CryptoManager.CipherService has the correct key, added by calling useKeyFromEntry(Entry) or useKeysFromEncoding(ByteSequence).

Parameters:

data - the cipher-text to be decrypted (contains prologue)

Returns:

a byte array with the clear-text

Throws:

GeneralSecurityException - if a problem occurs while decrypting the data

CryptoManagerException - if a problem occurs during cipher initialization

encrypt

public byte[] encrypt(byte[] data)
               throws GeneralSecurityException,
                      CryptoManagerException

Encrypts data with the configured cipher transformation and key length.

Parameters:

data - the clear-text data to encrypt

Returns:

a byte array with a prologue containing the key identifier followed by cipher-text

Throws:

GeneralSecurityException - if a problem occurs while encrypting the data

CryptoManagerException - if a problem occurs during cipher initialization

encryptWithoutKeyId

public byte[] encryptWithoutKeyId(byte[] data)
                           throws GeneralSecurityException,
                                  CryptoManagerException

Encrypts data with the configured cipher transformation and key length.

The ciphertext does not contain the key identifier needed for decryption, the caller must make sure the CryptoManager.CipherService contains the correct key.

Parameters:

data - the clear-text data to encrypt

Returns:

the byte array of the cipher-text

Throws:

GeneralSecurityException - if a problem occurs while encrypting the data

CryptoManagerException - if a problem occurs during cipher initialization

encrypt

public OutputStream encrypt(OutputStream outputStream)
                     throws CryptoManagerException

Writes encrypted data to the provided output stream using the current active cipher.

Parameters:

outputStream - The output stream to which encrypted data will be written.

Returns:

The encrypted output stream.

Throws:

CryptoManagerException - If a problem occurs managing the encryption key or producing the cipher.

encryptWithoutKeyId

public OutputStream encryptWithoutKeyId(OutputStream outputStream)
                                 throws CryptoManagerException

Writes encrypted data to the provided output stream using the current active cipher.

The output stream does not contain the key identifier needed for decryption, the caller must make sure the CryptoManager.CipherService contains the correct key.

Parameters:

outputStream - The output stream to which encrypted data will be written.

Returns:

The encrypted output stream.

Throws:

CryptoManagerException - If a problem occurs managing the encryption key or producing the cipher.

decrypt

public InputStream decrypt(InputStream inputStream)
                    throws CryptoManagerException

Reads encrypted data from the provided input stream.

If the prologue does not contain a key identifier, it is assumed the CryptoManager.CipherService has the correct key, added by calling useKeyFromEntry(Entry) or useKeysFromEncoding(ByteSequence).

Parameters:

inputStream - The input stream to be decrypted.

Returns:

The decrypted input stream.

Throws:

CryptoManagerException - If there is a problem reading the key ID or initialization vector from the input stream, or using these values to initialize a Cipher.

useKeysFromEncoding

public CryptoManager.CipherService useKeysFromEncoding(ByteSequence wrappedKeys)
                                                throws CryptoManagerException

Use the provided encoded secret keys for cryptographic operations.

The currently active and previously used keys will be set to those provided. Additionally any secret key currently in cn=admin data will be added to the list of previously used keys.

Parameters:

wrappedKeys - the encoded ASN.1 containing the wrapped keys

Returns:

the current CipherService

Throws:

CryptoManagerException - if the provided ASN.1 cannot be decoded

getEncodedSecretKeys

public ByteSequence getEncodedSecretKeys()
                                  throws CryptoManagerException

Return the list of active and previously used secret keys encoded as an ASN.1 sequence.

The encoding follows the following definition.

 WrappedKeys ::= APPLICATION [0] SEQUENCE {
     currentKey  WrappedKey
     wrappedKeys SEQUENCE OF WrappedKey
 }

 WrappedKey ::= SEQUENCE {
     keyType                  KeyType
     wrappingKeyId            OCTET STRING,
     wrappingTransformation   PrintableString,
     keyId                    OCTET STRING,
     transformation           PrintableString,
     keyLengthBits            INTEGER,
     IVLengthBits             INTEGER,
     wrappedKey               OCTET STRING
 }

 KeyType ::= ENUMERATED {
     cipher (0),
     hmac   (1)
 }
 

Returns:

the list of active and previously used secret keys encoded as an ASN.1 sequence

Throws:

CryptoManagerException - if encoding secret keys cannot be performed

useNewKeyIfNeeded

public CryptoManager.CipherService useNewKeyIfNeeded(String transformation,
                                                     int keyLengthBits)
                                              throws CryptoManagerException

Generate a new cipher key for the given transformation and key length. The key will become the active key for encryption and the previously active key will be kept for decryption purposes only.

Parameters:

transformation - cipher transformation string specification

keyLengthBits - length of key in bits

Returns:

the current CipherService

Throws:

CryptoManagerException - If a problem occurs generating a new key

useKeyForDefaultCipher

public CryptoManager.CipherService useKeyForDefaultCipher()
                                                   throws CryptoManagerException

Generate a new cipher key for the transformation and key length. The key will become the active key for encryption and the previously active key will be lost.

Returns:

the current CipherService

Throws:

CryptoManagerException - If a problem occurs generating a new key

useKeyFromEntry

public CryptoManager.CipherService useKeyFromEntry(Entry entry)
                                            throws CryptoManagerException

Use the cipher key from the provided information in the LDAP Entry as active key. The key will become the active key for encryption and the previously active key will be lost.

Parameters:

entry - the LDAP entry

Returns:

this CipherService

Throws:

CryptoManagerException - if an error occurs

currentKeyAsLdapEntry

public Entry currentKeyAsLdapEntry()
                            throws CryptoManagerException

Return the active cipher key as an LDAP Entry.

Returns:

the active cipher key as an LDAP Entry

Throws:

CryptoManagerException - if an error occurs

ensureCipherKeyIsAvailable

public void ensureCipherKeyIsAvailable(String transformation,
                                       int keyLengthBits)
                                throws CryptoManagerException

Ensures that a key exists for the provided cipher transformation and key length. If none exists, a new one will be created.

Parameters:

transformation - cipher transformation string specification

keyLengthBits - length of key in bits

Throws:

CryptoManagerException - If a problem occurs managing the encryption key

toString

public String toString()

Overrides:

toString in class Object