org.opends.server.util
Class CertificateManager

java.lang.Object
  extended by org.opends.server.util.CertificateManager

@PublicAPI(stability=VOLATILE,
           mayInstantiate=true,
           mayExtend=false,
           mayInvoke=true)
public final class CertificateManager
extends java.lang.Object

This class provides an interface for generating self-signed certificates and certificate signing requests, and for importing, exporting, and deleting certificates from a key store. It supports JKS, PKCS11, and PKCS12 key store types.

Note that for some operations, particularly those that require updating the contents of a key store (including generating certificates and/or certificate signing requests, importing certificates, or removing certificates), this class relies on the keytool utility provided with Sun's implementation of the Java runtime environment. It will perform the associated operations by invoking the appropriate command. It is possible that the keytool command will not exist in all Java runtime environments, especially those not created by Sun. In those cases, it will not be possible to invoke operations that require altering the contents of the key store. Therefore, it is strongly recommended that any code that may want to make use of this facility should first call mayUseCertificateManager and if it returns false the caller should gracefully degrade and suggest that the user perform the operation manually.


Field Summary
static java.lang.String KEY_STORE_PATH_PKCS11
          The key store path value that must be used in conjunction with the PKCS11 key store type.
static java.lang.String KEY_STORE_TYPE_JKS
          The key store type value that should be used for the "JKS" key store.
static java.lang.String KEY_STORE_TYPE_PKCS11
          The key store type value that should be used for the "PKCS11" key store.
static java.lang.String KEY_STORE_TYPE_PKCS12
          The key store type value that should be used for the "PKCS12" key store.
static java.lang.String KEYTOOL_COMMAND
          The path to the keytool command, which will be required to perform operations that modify the contents of a key store.
 
Constructor Summary
CertificateManager(java.lang.String keyStorePath, java.lang.String keyStoreType, java.lang.String keyStorePIN)
          Creates a new certificate manager instance with the provided information.
 
Method Summary
 void addCertificate(java.lang.String alias, java.io.File certificateFile)
          Adds the provided certificate to the key store.
 boolean aliasInUse(java.lang.String alias)
          Indicates whether the provided alias is in use in the key store.
 java.io.File generateCertificateSigningRequest(java.lang.String alias, java.lang.String subjectDN)
          Generates a certificate signing request (CSR) using the provided information.
 void generateSelfSignedCertificate(java.lang.String alias, java.lang.String subjectDN, int validity)
          Generates a self-signed certificate using the provided information.
 java.security.cert.Certificate getCertificate(java.lang.String alias)
          Retrieves the certificate with the specified alias from the key store.
 java.lang.String[] getCertificateAliases()
          Retrieves the aliases of the certificates in the specified key store.
static boolean mayUseCertificateManager()
          Indicates whether it is possible to use this certificate manager code to perform operations which may alter the contents of a key store.
 void removeCertificate(java.lang.String alias)
          Removes the specified certificate from the key store.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

KEYTOOL_COMMAND

public static final java.lang.String KEYTOOL_COMMAND
The path to the keytool command, which will be required to perform operations that modify the contents of a key store.


KEY_STORE_TYPE_JKS

public static final java.lang.String KEY_STORE_TYPE_JKS
The key store type value that should be used for the "JKS" key store.

See Also:
Constant Field Values

KEY_STORE_TYPE_PKCS11

public static final java.lang.String KEY_STORE_TYPE_PKCS11
The key store type value that should be used for the "PKCS11" key store.

See Also:
Constant Field Values

KEY_STORE_TYPE_PKCS12

public static final java.lang.String KEY_STORE_TYPE_PKCS12
The key store type value that should be used for the "PKCS12" key store.

See Also:
Constant Field Values

KEY_STORE_PATH_PKCS11

public static final java.lang.String KEY_STORE_PATH_PKCS11
The key store path value that must be used in conjunction with the PKCS11 key store type.

See Also:
Constant Field Values
Constructor Detail

CertificateManager

public CertificateManager(java.lang.String keyStorePath,
                          java.lang.String keyStoreType,
                          java.lang.String keyStorePIN)
                   throws java.lang.IllegalArgumentException,
                          java.lang.NullPointerException,
                          java.lang.UnsupportedOperationException
Creates a new certificate manager instance with the provided information.

Parameters:
keyStorePath - The path to the key store file, or "NONE" if the key store type is "PKCS11". For the other key store types, the file does not need to exist if a new self-signed certificate or certificate signing request is to be generated, although the directory containing the file must exist. The key store file must exist if import or export operations are to be performed.
keyStoreType - The key store type to use. It should be one of KEY_STORE_TYPE_JKS, KEY_STORE_TYPE_PKCS11, or KEY_STORE_TYPE_PKCS12.
keyStorePIN - The PIN required to access the key store. It must not be null.
Throws:
java.lang.IllegalArgumentException - If any of the provided arguments is invalid.
java.lang.NullPointerException - If any of the provided arguments is null.
java.lang.UnsupportedOperationException - If it is not possible to use the certificate manager on the underlying platform.
Method Detail

mayUseCertificateManager

public static boolean mayUseCertificateManager()
Indicates whether it is possible to use this certificate manager code to perform operations which may alter the contents of a key store.

Returns:
true if it appears that the keytool utility is available and may be used to execute commands that may alter the contents of a key store, or false if not.

aliasInUse

public boolean aliasInUse(java.lang.String alias)
                   throws java.security.KeyStoreException,
                          java.lang.NullPointerException
Indicates whether the provided alias is in use in the key store.

Parameters:
alias - The alias for which to make the determination. It must not be null or empty.
Returns:
true if the key store exist and already contains a certificate with the given alias, or false if not.
Throws:
java.security.KeyStoreException - If a problem occurs while attempting to interact with the key store.
java.lang.NullPointerException - If the provided alias is null or a zero-length string.

getCertificateAliases

public java.lang.String[] getCertificateAliases()
                                         throws java.security.KeyStoreException
Retrieves the aliases of the certificates in the specified key store.

Returns:
The aliases of the certificates in the specified key store, or null if the key store does not exist.
Throws:
java.security.KeyStoreException - If a problem occurs while attempting to interact with the key store.

getCertificate

public java.security.cert.Certificate getCertificate(java.lang.String alias)
                                              throws java.security.KeyStoreException,
                                                     java.lang.NullPointerException
Retrieves the certificate with the specified alias from the key store.

Parameters:
alias - The alias of the certificate to retrieve. It must not be null or empty.
Returns:
The requested certificate, or null if the specified certificate does not exist.
Throws:
java.security.KeyStoreException - If a problem occurs while interacting with the key store, or the key store does not exist.
java.lang.NullPointerException - If the provided alias is null or a zero-length string.

generateSelfSignedCertificate

public void generateSelfSignedCertificate(java.lang.String alias,
                                          java.lang.String subjectDN,
                                          int validity)
                                   throws java.security.KeyStoreException,
                                          java.lang.IllegalArgumentException,
                                          java.lang.NullPointerException,
                                          java.lang.UnsupportedOperationException
Generates a self-signed certificate using the provided information.

Parameters:
alias - The nickname to use for the certificate in the key store. For the server certificate, it should generally be "server-cert". It must not be null or empty.
subjectDN - The subject DN to use for the certificate. It must not be null or empty.
validity - The length of time in days that the certificate should be valid, starting from the time the certificate is generated. It must be a positive integer value.
Throws:
java.lang.IllegalArgumentException - If the validity is not positive.
java.security.KeyStoreException - If a problem occurs while actually attempting to generate the certificate in the key store.
java.lang.NullPointerException - If either the alias or subject DN is null or a zero-length string.
java.lang.UnsupportedOperationException - If it is not possible to use the keytool utility to alter the contents of the key store.

generateCertificateSigningRequest

public java.io.File generateCertificateSigningRequest(java.lang.String alias,
                                                      java.lang.String subjectDN)
                                               throws java.security.KeyStoreException,
                                                      java.io.IOException,
                                                      java.lang.NullPointerException,
                                                      java.lang.UnsupportedOperationException
Generates a certificate signing request (CSR) using the provided information.

Parameters:
alias - The nickname to use for the certificate in the key store. For the server certificate, it should generally be "server-cert". It must not be null or empty.
subjectDN - The subject DN to use for the certificate. It must not be null or empty.
Returns:
The file containing the generated certificate signing request.
Throws:
java.security.KeyStoreException - If a problem occurs while actually attempting to generate the private key in the key store or generate the certificate signing request based on that key.
java.io.IOException - If a problem occurs while attempting to create the file to which the certificate signing request will be written.
java.lang.NullPointerException - If either the alias or subject DN is null or a zero-length string.
java.lang.UnsupportedOperationException - If it is not possible to use the keytool utility to alter the contents of the key store.

addCertificate

public void addCertificate(java.lang.String alias,
                           java.io.File certificateFile)
                    throws java.lang.IllegalArgumentException,
                           java.security.KeyStoreException,
                           java.lang.NullPointerException,
                           java.lang.UnsupportedOperationException
Adds the provided certificate to the key store. This may be used to associate an externally-signed certificate with an existing private key with the given alias.

Parameters:
alias - The alias to use for the certificate. It must not be null or empty.
certificateFile - The file containing the encoded certificate. It must not be null, and the file must exist.
Throws:
java.lang.IllegalArgumentException - If the provided certificate file does not exist.
java.security.KeyStoreException - If a problem occurs while interacting with the key store.
java.lang.NullPointerException - If the provided alias is null or a zero-length string, or the certificate file is null.
java.lang.UnsupportedOperationException - If it is not possible to use the keytool utility to alter the contents of the key store.

removeCertificate

public void removeCertificate(java.lang.String alias)
                       throws java.lang.IllegalArgumentException,
                              java.security.KeyStoreException,
                              java.lang.NullPointerException,
                              java.lang.UnsupportedOperationException
Removes the specified certificate from the key store.

Parameters:
alias - The alias to use for the certificate to remove. It must not be null or an empty string, and it must exist in the key store.
Throws:
java.lang.IllegalArgumentException - If the specified certificate does not exist in the key store.
java.security.KeyStoreException - If a problem occurs while interacting with the key store.
java.lang.NullPointerException - If the provided alias is null or a zero-length string, or the certificate file is null.
java.lang.UnsupportedOperationException - If it is not possible to use the keytool utility to alter the contents of the key store.