Class 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 Detail

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