org.opends.server.types
Interface CryptoManager

All Known Implementing Classes:
CryptoManagerImpl

@PublicAPI(stability=VOLATILE,
           mayInstantiate=false,
           mayExtend=false,
           mayInvoke=true)
public interface CryptoManager

This interface defines the methods to call to access cryptographic services including encryption and hashing; in particular, when the ciphertext or HMAC is produced on one directory server instance and is to be consumed on another.


Method Summary
 int compress(byte[] src, byte[] dst)
          Attempts to compress the data in the provided source array into the given destination array.
 byte[] decrypt(byte[] data)
          Decrypts the data in the provided byte array using cipher specified by the key identifier prologue to the data.
 byte[] digest(byte[] data)
          Retrieves a byte array containing a message digest based on the provided data, using the preferred digest algorithm.
 byte[] digest(java.io.InputStream inputStream)
          Retrieves a byte array containing a message digest based on the data read from the provided input stream, using the preferred digest algorithm.
 byte[] digest(java.lang.String digestAlgorithm, byte[] data)
          Retrieves a byte array containing a message digest based on the provided data, using the requested digest algorithm.
 byte[] digest(java.lang.String digestAlgorithm, java.io.InputStream inputStream)
          Retrieves a byte array containing a message digest based on the data read from the provided input stream, using the requested digest algorithm.
 byte[] encrypt(byte[] data)
          Encrypts the data in the provided byte array using the preferred cipher transformation.
 byte[] encrypt(java.lang.String cipherTransformation, int keyLengthBits, byte[] data)
          Encrypts the data in the provided byte array using the requested cipher algorithm.
 javax.crypto.CipherInputStream getCipherInputStream(java.io.InputStream inputStream)
          Returns a CipherInputStream instantiated with a cipher corresponding to the key identifier prologue to the data.
 javax.crypto.CipherOutputStream getCipherOutputStream(java.io.OutputStream outputStream)
          Writes encrypted data to the provided output stream using the preferred cipher transformation.
 javax.crypto.CipherOutputStream getCipherOutputStream(java.lang.String cipherTransformation, int keyLengthBits, java.io.OutputStream outputStream)
          Writes encrypted data to the provided output stream using the requested cipher transformation.
 javax.crypto.Mac getMacEngine(java.lang.String keyEntryID)
          For the specified key entry identifier, instantiate a MAC engine.
 java.lang.String getMacEngineKeyEntryID()
          For the current preferred MAC algorithm and key length, return the identifier of the corresponding key entry.
 java.lang.String getMacEngineKeyEntryID(java.lang.String macAlgorithm, int keyLengthBits)
          For the specified MAC algorithm and key length, return the identifier of the corresponding key entry.
 java.security.MessageDigest getMessageDigest(java.lang.String digestAlgorithm)
          Retrieves a MessageDigest object that may be used to generate digests using the specified algorithm.
 java.security.MessageDigest getPreferredMessageDigest()
          Retrieves a MessageDigest object that may be used to generate digests using the preferred digest algorithm.
 java.lang.String getPreferredMessageDigestAlgorithm()
          Retrieves the name of the preferred message digest algorithm.
 java.lang.String getSslCertNickname()
          Get the name of the local certificate to use for SSL.
 java.util.SortedSet<java.lang.String> getSslCipherSuites()
          Get the set of enabled SSL cipher suites.
 javax.net.ssl.SSLContext getSslContext(java.lang.String sslCertNickname)
          Create an SSL context that may be used for communication to another ADS component.
 java.util.SortedSet<java.lang.String> getSslProtocols()
          Get the set of enabled SSL protocols.
 boolean isSslEncryption()
          Determine whether SSL encryption is enabled.
 int uncompress(byte[] src, byte[] dst)
          Attempts to uncompress the data in the provided source array into the given destination array.
 

Method Detail

getPreferredMessageDigestAlgorithm

java.lang.String getPreferredMessageDigestAlgorithm()
Retrieves the name of the preferred message digest algorithm.

Returns:
The name of the preferred message digest algorithm

getPreferredMessageDigest

java.security.MessageDigest getPreferredMessageDigest()
                                                      throws java.security.NoSuchAlgorithmException
Retrieves a MessageDigest object that may be used to generate digests using the preferred digest algorithm.

Returns:
A MessageDigest object that may be used to generate digests using the preferred digest algorithm.
Throws:
java.security.NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

getMessageDigest

java.security.MessageDigest getMessageDigest(java.lang.String digestAlgorithm)
                                             throws java.security.NoSuchAlgorithmException
Retrieves a MessageDigest object that may be used to generate digests using the specified algorithm.

Parameters:
digestAlgorithm - The algorithm to use to generate the message digest.
Returns:
A MessageDigest object that may be used to generate digests using the specified algorithm.
Throws:
java.security.NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

digest

byte[] digest(byte[] data)
              throws java.security.NoSuchAlgorithmException
Retrieves a byte array containing a message digest based on the provided data, using the preferred digest algorithm.

Parameters:
data - The data to be digested.
Returns:
A byte array containing the generated message digest.
Throws:
java.security.NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

digest

byte[] digest(java.lang.String digestAlgorithm,
              byte[] data)
              throws java.security.NoSuchAlgorithmException
Retrieves a byte array containing a message digest based on the provided data, using the requested digest algorithm.

Parameters:
digestAlgorithm - The algorithm to use to generate the message digest.
data - The data to be digested.
Returns:
A byte array containing the generated message digest.
Throws:
java.security.NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

digest

byte[] digest(java.io.InputStream inputStream)
              throws java.io.IOException,
                     java.security.NoSuchAlgorithmException
Retrieves a byte array containing a message digest based on the data read from the provided input stream, using the preferred digest algorithm. Data will be read until the end of the stream is reached.

Parameters:
inputStream - The input stream from which the data is to be read.
Returns:
A byte array containing the generated message digest.
Throws:
java.io.IOException - If a problem occurs while reading data from the provided stream.
java.security.NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

digest

byte[] digest(java.lang.String digestAlgorithm,
              java.io.InputStream inputStream)
              throws java.io.IOException,
                     java.security.NoSuchAlgorithmException
Retrieves a byte array containing a message digest based on the data read from the provided input stream, using the requested digest algorithm. Data will be read until the end of the stream is reached.

Parameters:
digestAlgorithm - The algorithm to use to generate the message digest.
inputStream - The input stream from which the data is to be read.
Returns:
A byte array containing the generated message digest.
Throws:
java.io.IOException - If a problem occurs while reading data from the provided stream.
java.security.NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

getMacEngineKeyEntryID

java.lang.String getMacEngineKeyEntryID()
                                        throws CryptoManagerException
For the current preferred MAC algorithm and key length, return the identifier of the corresponding key entry. Note: the result (key identifier) might change across invocations, due to either of the perferred parameters changing, or because the original key was marked compromised and a replacement key generated.

Returns:
A String representation of the identifier of a key entry corresponding to the preferred MAC algorithm and key length.
Throws:
CryptoManagerException - In case one or more of the key parameters is invalid, or there is a problem instantiating the key entry in case it does not already exist.

getMacEngineKeyEntryID

java.lang.String getMacEngineKeyEntryID(java.lang.String macAlgorithm,
                                        int keyLengthBits)
                                        throws CryptoManagerException
For the specified MAC algorithm and key length, return the identifier of the corresponding key entry. Note: the result (key identifier) might change across invocations, due to either of the perferred parameters changing, or because the original key was marked compromised and a replacement key generated.

Parameters:
macAlgorithm - The algorithm to use for the MAC engine.
keyLengthBits - The key length in bits to use with the specified algorithm.
Returns:
A String representation of the identifier of a key entry corresponding to the specified MAC algorithm and key length.
Throws:
CryptoManagerException - In case one or more of the key parameters is invalid, or there is a problem instantiating the key entry in case it does not already exist.

getMacEngine

javax.crypto.Mac getMacEngine(java.lang.String keyEntryID)
                              throws CryptoManagerException
For the specified key entry identifier, instantiate a MAC engine.

Parameters:
keyEntryID - The identifier of the key entry containing the desired MAC algorithm name and key length.
Returns:
The MAC engine instantiated with the parameters from the referenced key entry, or null if no such entry exists.
Throws:
CryptoManagerException - In case the key entry identifier is invalid or there is a problem instantiating the MAC engine from the parameters in the referenced key entry.

encrypt

byte[] encrypt(byte[] data)
               throws java.security.GeneralSecurityException,
                      CryptoManagerException
Encrypts the data in the provided byte array using the preferred cipher transformation.

Parameters:
data - The plain-text data to be encrypted.
Returns:
A byte array containing the encrypted representation of the provided data.
Throws:
java.security.GeneralSecurityException - If a problem occurs while encrypting the data.
CryptoManagerException - If a problem occurs managing the encryption key or producing the cipher.

encrypt

byte[] encrypt(java.lang.String cipherTransformation,
               int keyLengthBits,
               byte[] data)
               throws java.security.GeneralSecurityException,
                      CryptoManagerException
Encrypts the data in the provided byte array using the requested cipher algorithm.

Parameters:
cipherTransformation - The algorithm/mode/padding to use for the cipher.
keyLengthBits - The length in bits of the encryption key this method is to use. Note the specified key length and transformation must be compatible.
data - The plain-text data to be encrypted.
Returns:
A byte array containing the encrypted representation of the provided data.
Throws:
java.security.GeneralSecurityException - If a problem occurs while encrypting the data.
CryptoManagerException - If a problem occurs managing the encryption key or producing the cipher.

getCipherOutputStream

javax.crypto.CipherOutputStream getCipherOutputStream(java.io.OutputStream outputStream)
                                                      throws CryptoManagerException
Writes encrypted data to the provided output stream using the preferred cipher transformation.

Parameters:
outputStream - The output stream to be wrapped by the returned cipher output stream.
Returns:
The output stream wrapped with a CipherOutputStream.
Throws:
CryptoManagerException - If a problem occurs managing the encryption key or producing the cipher.

getCipherOutputStream

javax.crypto.CipherOutputStream getCipherOutputStream(java.lang.String cipherTransformation,
                                                      int keyLengthBits,
                                                      java.io.OutputStream outputStream)
                                                      throws CryptoManagerException
Writes encrypted data to the provided output stream using the requested cipher transformation.

Parameters:
cipherTransformation - The algorithm/mode/padding to use for the cipher.
keyLengthBits - The length in bits of the encryption key this method will generate. Note the specified key length must be compatible with the transformation.
outputStream - The output stream to be wrapped by the returned cipher output stream.
Returns:
The output stream wrapped with a CipherOutputStream.
Throws:
CryptoManagerException - If a problem occurs managing the encryption key or producing the cipher.

decrypt

byte[] decrypt(byte[] data)
               throws java.security.GeneralSecurityException,
                      CryptoManagerException
Decrypts the data in the provided byte array using cipher specified by the key identifier prologue to the data. cipher.

Parameters:
data - The cipher-text data to be decrypted.
Returns:
A byte array containing the clear-text representation of the provided data.
Throws:
java.security.GeneralSecurityException - If a problem occurs while encrypting the data.
CryptoManagerException - If a problem occurs reading the key identifier or initialization vector from the data prologue, or using these values to initialize a Cipher.

getCipherInputStream

javax.crypto.CipherInputStream getCipherInputStream(java.io.InputStream inputStream)
                                                    throws CryptoManagerException
Returns a CipherInputStream instantiated with a cipher corresponding to the key identifier prologue to the data.

Parameters:
inputStream - The input stream be wrapped with the CipherInputStream.
Returns:
The CiperInputStream instantiated as specified.
Throws:
CryptoManagerException - If there is a problem reading the key ID or initialization vector from the input stream, or using these values to inititalize a Cipher.

compress

int compress(byte[] src,
             byte[] dst)
Attempts to compress the data in the provided source array into the given destination array. If the compressed data will fit into the destination array, then this method will return the number of bytes of compressed data in the array. Otherwise, it will return -1 to indicate that the compression was not successful. Note that if -1 is returned, then the data in the destination array should be considered invalid.

Parameters:
src - The array containing the raw data to compress.
dst - The array into which the compressed data should be written.
Returns:
The number of bytes of compressed data, or -1 if it was not possible to actually compress the data.

uncompress

int uncompress(byte[] src,
               byte[] dst)
               throws java.util.zip.DataFormatException
Attempts to uncompress the data in the provided source array into the given destination array. If the uncompressed data will fit into the given destination array, then this method will return the number of bytes of uncompressed data written into the destination buffer. Otherwise, it will return a negative value to indicate that the destination buffer was not large enough. The absolute value of that negative return value will indicate the buffer size required to fully decompress the data. Note that if a negative value is returned, then the data in the destination array should be considered invalid.

Parameters:
src - The array containing the compressed data.
dst - The array into which the uncompressed data should be written.
Returns:
A positive value containing the number of bytes of uncompressed data written into the destination buffer, or a negative value whose absolute value is the size of the destination buffer required to fully decompress the provided data.
Throws:
java.util.zip.DataFormatException - If a problem occurs while attempting to uncompress the data.

getSslContext

javax.net.ssl.SSLContext getSslContext(java.lang.String sslCertNickname)
                                       throws ConfigException
Create an SSL context that may be used for communication to another ADS component.

Parameters:
sslCertNickname - The name of the local certificate to use, or null if none is specified.
Returns:
A new SSL Context.
Throws:
ConfigException - If the context could not be created.

getSslCertNickname

java.lang.String getSslCertNickname()
Get the name of the local certificate to use for SSL.

Returns:
The name of the local certificate to use for SSL.

isSslEncryption

boolean isSslEncryption()
Determine whether SSL encryption is enabled.

Returns:
true if SSL encryption is enabled.

getSslProtocols

java.util.SortedSet<java.lang.String> getSslProtocols()
Get the set of enabled SSL protocols.

Returns:
The set of enabled SSL protocols.

getSslCipherSuites

java.util.SortedSet<java.lang.String> getSslCipherSuites()
Get the set of enabled SSL cipher suites.

Returns:
The set of enabled SSL cipher suites.