Package org.opends.server.crypto

Class CryptoManager.CipherService

java.lang.Object
org.opends.server.crypto.CryptoManager.CipherService
Enclosing class:
CryptoManager
public static final 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(ByteString) 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 Details

    • 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(ByteString).

      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(ByteString).

      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(ByteString 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 ByteString 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