Package 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

Modifier and Type	Method	Description
int	compress(byte[] src, int srcOff, int srcLen, byte[] dst, int dstOff, int dstLen)	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(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(String digestAlgorithm, byte[] data)	Retrieves a byte array containing a message digest based on the provided data, using the requested digest algorithm.
byte[]	digest(String digestAlgorithm, 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(String cipherTransformation, int keyLengthBits, byte[] data)	Encrypts the data in the provided byte array using the requested cipher algorithm.
void	ensureCipherKeyIsAvailable(String cipherTransformation, int cipherKeyLength)	Ensures that a key exists for the provided cipher transformation and key length.
CipherInputStream	getCipherInputStream(InputStream inputStream)	Returns a CipherInputStream instantiated with a cipher corresponding to the key identifier prologue to the data.
CipherOutputStream	getCipherOutputStream(OutputStream outputStream)	Writes encrypted data to the provided output stream using the preferred cipher transformation.
CipherOutputStream	getCipherOutputStream(String cipherTransformation, int keyLengthBits, OutputStream outputStream)	Writes encrypted data to the provided output stream using the requested cipher transformation.
Mac	getMacEngine(String keyEntryID)	For the specified key entry identifier, instantiate a MAC engine.
String	getMacEngineKeyEntryID()	For the current preferred MAC algorithm and key length, return the identifier of the corresponding key entry.
String	getMacEngineKeyEntryID(String macAlgorithm, int keyLengthBits)	For the specified MAC algorithm and key length, return the identifier of the corresponding key entry.
MessageDigest	getMessageDigest(String digestAlgorithm)	Retrieves a MessageDigest object that may be used to generate digests using the specified algorithm.
MessageDigest	getPreferredMessageDigest()	Retrieves a MessageDigest object that may be used to generate digests using the preferred digest algorithm.
String	getPreferredMessageDigestAlgorithm()	Retrieves the name of the preferred message digest algorithm.
SortedSet<String>	getSslCertNicknames()	Get the names of the local certificates to use for SSL.
SortedSet<String>	getSslCipherSuites()	Get the set of enabled SSL cipher suites.
SSLContext	getSslContext(String componentName, SortedSet<String> sslCertNicknames)	Create an SSL context that may be used for communication to another ADS component.
SortedSet<String>	getSslProtocols()	Get the set of enabled SSL protocols.
boolean	isSslEncryption()	Determine whether SSL encryption is enabled.
CryptoSuite	newCryptoSuite(String cipherTransformation, int cipherKeyLength, boolean encrypt)	Return a new CryptoSuite for the cipher and key.
int	uncompress(byte[] src, int srcOff, int srcLen, byte[] dst, int dstOff, int dstLen)	Attempts to uncompress the data in the provided source array into the given destination array.

Method Detail

getPreferredMessageDigestAlgorithm

String getPreferredMessageDigestAlgorithm()

Retrieves the name of the preferred message digest algorithm.

Returns:

The name of the preferred message digest algorithm

getPreferredMessageDigest

MessageDigest getPreferredMessageDigest()
                                 throws 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:

NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

getMessageDigest

MessageDigest getMessageDigest(String digestAlgorithm)
                        throws 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:

NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

digest

byte[] digest(byte[] data)
       throws 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:

NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

digest

byte[] digest(String digestAlgorithm,
              byte[] data)
       throws 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:

NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

digest

byte[] digest(InputStream inputStream)
       throws IOException,
              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:

IOException - If a problem occurs while reading data from the provided stream.

NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

digest

byte[] digest(String digestAlgorithm,
              InputStream inputStream)
       throws IOException,
              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:

IOException - If a problem occurs while reading data from the provided stream.

NoSuchAlgorithmException - If the requested algorithm is not supported or is unavailable.

getMacEngineKeyEntryID

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

String getMacEngineKeyEntryID(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

Mac getMacEngine(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 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:

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(String cipherTransformation,
               int keyLengthBits,
               byte[] data)
        throws 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:

GeneralSecurityException - If a problem occurs while encrypting the data.

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

getCipherOutputStream

CipherOutputStream getCipherOutputStream(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

CipherOutputStream getCipherOutputStream(String cipherTransformation,
                                         int keyLengthBits,
                                         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 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:

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

CipherInputStream getCipherInputStream(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,
             int srcOff,
             int srcLen,
             byte[] dst,
             int dstOff,
             int dstLen)

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.

srcOff - The start offset of the source data.

srcLen - The maximum number of source data bytes to compress.

dst - The array into which the compressed data should be written.

dstOff - The start offset of the compressed data.

dstLen - The maximum number of bytes of compressed data.

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,
               int srcOff,
               int srcLen,
               byte[] dst,
               int dstOff,
               int dstLen)
        throws 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 raw data to compress.

srcOff - The start offset of the source data.

srcLen - The maximum number of source data bytes to compress.

dst - The array into which the compressed data should be written.

dstOff - The start offset of the compressed data.

dstLen - The maximum number of bytes of compressed data.

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:

DataFormatException - If a problem occurs while attempting to uncompress the data.

getSslContext

SSLContext getSslContext(String componentName,
                         SortedSet<String> sslCertNicknames)
                  throws ConfigException

Create an SSL context that may be used for communication to another ADS component.

Parameters:

componentName - Name of the component to which is associated this SSL Context.

sslCertNicknames - The names of the local certificates to use, or null if none is specified.

Returns:

A new SSL Context.

Throws:

ConfigException - If the context could not be created.

getSslCertNicknames

SortedSet<String> getSslCertNicknames()

Get the names of the local certificates to use for SSL.

Returns:

The names of the local certificates to use for SSL.

isSslEncryption

boolean isSslEncryption()

Determine whether SSL encryption is enabled.

Returns:

true if SSL encryption is enabled.

getSslProtocols

SortedSet<String> getSslProtocols()

Get the set of enabled SSL protocols.

Returns:

The set of enabled SSL protocols.

getSslCipherSuites

SortedSet<String> getSslCipherSuites()

Get the set of enabled SSL cipher suites.

Returns:

The set of enabled SSL cipher suites.

newCryptoSuite

CryptoSuite newCryptoSuite(String cipherTransformation,
                           int cipherKeyLength,
                           boolean encrypt)

Return a new CryptoSuite for the cipher and key.

Parameters:

cipherTransformation - cipher transformation string specification

cipherKeyLength - length of key in bits

encrypt - true if the user of the crypto suite needs encryption

Returns:

a new CryptoSuite for the cipher and key

ensureCipherKeyIsAvailable

void ensureCipherKeyIsAvailable(String cipherTransformation,
                                int cipherKeyLength)
                         throws CryptoManagerException

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

Newly created keys will be published and propagated to the replication topology.

Parameters:

cipherTransformation - cipher transformation string specification

cipherKeyLength - length of key in bits

Throws:

CryptoManagerException - If a problem occurs managing the encryption key