com.unboundid.util.ssl

Class PEMFileKeyManager

java.lang.Object

com.unboundid.util.ssl.PEMFileKeyManager

All Implemented Interfaces:

java.io.Serializable, javax.net.ssl.KeyManager, javax.net.ssl.X509KeyManager

@NotMutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class PEMFileKeyManager
extends java.lang.Object
implements javax.net.ssl.X509KeyManager, java.io.Serializable

This class provides an implementation of an X.509 key manager that can obtain a certificate chain and private key from PEM files. This key manager will only support a single entry, and the alias for that entry will be a SHA-256 fingerprint for the certificate. However, the certificate can be retrieved with any (or no) alias.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
PEMFileKeyManager(java.io.File[] certificateChainPEMFiles, java.io.File privateKeyPEMFile) Creates a new instance of this key manager with the provided PEM files.
PEMFileKeyManager(java.io.File[] certificateChainPEMFiles, java.io.File privateKeyPEMFile, char[] privateKeyEncryptionPassword) Creates a new instance of this key manager with the provided PEM files.
PEMFileKeyManager(java.io.File certificateChainPEMFile, java.io.File privateKeyPEMFile) Creates a new instance of this key manager with the provided PEM files.
PEMFileKeyManager(java.io.File certificateChainPEMFile, java.io.File privateKeyPEMFile, char[] privateKeyEncryptionPassword) Creates a new instance of this key manager with the provided PEM files.
PEMFileKeyManager(java.util.List<java.io.File> certificateChainPEMFiles, java.io.File privateKeyPEMFile) Creates a new instance of this key manager with the provided PEM files.
PEMFileKeyManager(java.util.List<java.io.File> certificateChainPEMFiles, java.io.File privateKeyPEMFile, char[] privateKeyEncryptionPassword) Creates a new instance of this key manager with the provided PEM files.

Method Summary

Modifier and Type	Method and Description
java.lang.String	chooseAlias(java.lang.String[] keyTypes, java.security.Principal[] issuers) Chooses the alias that should be used for the preferred certificate chain with the requested settings.
java.lang.String	chooseClientAlias(java.lang.String[] keyTypes, java.security.Principal[] issuers, java.net.Socket socket) Chooses the alias that should be used for the preferred client certificate chain with the requested settings.
java.lang.String	chooseServerAlias(java.lang.String keyType, java.security.Principal[] issuers, java.net.Socket socket) Chooses the alias that should be used for the preferred server certificate chain with the requested settings.
java.security.cert.X509Certificate[]	getCertificateChain(java.lang.String alias) Retrieves the certificate chain with the specified alias.
java.lang.String[]	getClientAliases(java.lang.String keyType, java.security.Principal[] issuers) Retrieves the aliases that may be used for a client certificate chain with the requested settings.
java.security.PrivateKey	getPrivateKey(java.lang.String alias) Retrieves the private key for the certificate chain with the specified alias.
java.lang.String[]	getServerAliases(java.lang.String keyType, java.security.Principal[] issuers) Retrieves the aliases that may be used for a server certificate chain with the requested settings.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PEMFileKeyManager

public PEMFileKeyManager(@NotNull
                         java.io.File certificateChainPEMFile,
                         @NotNull
                         java.io.File privateKeyPEMFile)
                  throws java.security.KeyStoreException

Creates a new instance of this key manager with the provided PEM files.

Parameters:

certificateChainPEMFile - The file containing the PEM-formatted X.509 representations of the certificates in the certificate chain. This must not be null, the file must exist, and it must contain at least one certificate (the end entity certificate), but may contain additional certificates as needed for the complete certificate chain. Certificates should be ordered such that the first certificate must be the end entity certificate, and each subsequent certificate must be the issuer for the previous certificate. The chain does not need to be complete as long as the peer may be expected to have prior knowledge of any missing issuer certificates.

privateKeyPEMFile - The file containing the PEM-formatted PKCS #8 representation of the private key for the end entity certificate. This must not be null, the file must exist, and it must contain exactly one PEM-encoded private key. The private key must not be encrypted.

Throws:

java.security.KeyStoreException - If there is a problem with any of the provided PEM files.

PEMFileKeyManager

public PEMFileKeyManager(@NotNull
                         java.io.File certificateChainPEMFile,
                         @NotNull
                         java.io.File privateKeyPEMFile,
                         @Nullable
                         char[] privateKeyEncryptionPassword)
                  throws java.security.KeyStoreException

Creates a new instance of this key manager with the provided PEM files.

Parameters:

certificateChainPEMFile - The file containing the PEM-formatted X.509 representations of the certificates in the certificate chain. This must not be null, the file must exist, and it must contain at least one certificate (the end entity certificate), but may contain additional certificates as needed for the complete certificate chain. Certificates should be ordered such that the first certificate must be the end entity certificate, and each subsequent certificate must be the issuer for the previous certificate. The chain does not need to be complete as long as the peer may be expected to have prior knowledge of any missing issuer certificates.

privateKeyPEMFile - The file containing the PEM-formatted PKCS #8 representation of the private key for the end entity certificate. This must not be null, the file must exist, and it must contain exactly one PEM-encoded private key. The private key may optionally be encrypted.

privateKeyEncryptionPassword - The password needed to decrypt the private key if it is encrypted. This may be null if the private key is not encrypted.

Throws:

java.security.KeyStoreException - If there is a problem with any of the provided PEM files.

PEMFileKeyManager

public PEMFileKeyManager(@NotNull
                         java.io.File[] certificateChainPEMFiles,
                         @NotNull
                         java.io.File privateKeyPEMFile)
                  throws java.security.KeyStoreException

Creates a new instance of this key manager with the provided PEM files.

Parameters:

certificateChainPEMFiles - The files containing the PEM-formatted X.509 representations of the certificates in the certificate chain. This must not be null or empty. Each file must exist and must contain at least one certificate. The files will be processed in the order in which they are provided. The first certificate in the first file must be the end entity certificate, and each subsequent certificate must be the issuer for the previous certificate. The chain does not need to be complete as long as the peer may be expected to have prior knowledge of any missing issuer certificates.

privateKeyPEMFile - The file containing the PEM-formatted PKCS #8 representation of the private key for the end entity certificate. This must not be null, the file must exist, and it must contain exactly one PEM-encoded private key. The private key must not be encrypted.

Throws:

java.security.KeyStoreException - If there is a problem with any of the provided PEM files.

PEMFileKeyManager

public PEMFileKeyManager(@NotNull
                         java.io.File[] certificateChainPEMFiles,
                         @NotNull
                         java.io.File privateKeyPEMFile,
                         @Nullable
                         char[] privateKeyEncryptionPassword)
                  throws java.security.KeyStoreException

Creates a new instance of this key manager with the provided PEM files.

Parameters:

certificateChainPEMFiles - The files containing the PEM-formatted X.509 representations of the certificates in the certificate chain. This must not be null or empty. Each file must exist and must contain at least one certificate. The files will be processed in the order in which they are provided. The first certificate in the first file must be the end entity certificate, and each subsequent certificate must be the issuer for the previous certificate. The chain does not need to be complete as long as the peer may be expected to have prior knowledge of any missing issuer certificates.

privateKeyPEMFile - The file containing the PEM-formatted PKCS #8 representation of the private key for the end entity certificate. This must not be null, the file must exist, and it must contain exactly one PEM-encoded private key. The private key may optionally be encrypted.

privateKeyEncryptionPassword - The password needed to decrypt the private key if it is encrypted. This may be null if the private key is not encrypted.

Throws:

java.security.KeyStoreException - If there is a problem with any of the provided PEM files.

PEMFileKeyManager

public PEMFileKeyManager(@NotNull
                         java.util.List<java.io.File> certificateChainPEMFiles,
                         @NotNull
                         java.io.File privateKeyPEMFile)
                  throws java.security.KeyStoreException

Creates a new instance of this key manager with the provided PEM files.

Parameters:

certificateChainPEMFiles - The files containing the PEM-formatted X.509 representations of the certificates in the certificate chain. This must not be null or empty. Each file must exist and must contain at least one certificate. The files will be processed in the order in which they are provided. The first certificate in the first file must be the end entity certificate, and each subsequent certificate must be the issuer for the previous certificate. The chain does not need to be complete as long as the peer may be expected to have prior knowledge of any missing issuer certificates.

privateKeyPEMFile - The file containing the PEM-formatted PKCS #8 representation of the private key for the end entity certificate. This must not be null, the file must exist, and it must contain exactly one PEM-encoded private key. The private key must not be encrypted.

Throws:

java.security.KeyStoreException - If there is a problem with any of the provided PEM files.

PEMFileKeyManager

public PEMFileKeyManager(@NotNull
                         java.util.List<java.io.File> certificateChainPEMFiles,
                         @NotNull
                         java.io.File privateKeyPEMFile,
                         @Nullable
                         char[] privateKeyEncryptionPassword)
                  throws java.security.KeyStoreException

Creates a new instance of this key manager with the provided PEM files.

Parameters:

certificateChainPEMFiles - The files containing the PEM-formatted X.509 representations of the certificates in the certificate chain. This must not be null or empty. Each file must exist and must contain at least one certificate. The files will be processed in the order in which they are provided. The first certificate in the first file must be the end entity certificate, and each subsequent certificate must be the issuer for the previous certificate. The chain does not need to be complete as long as the peer may be expected to have prior knowledge of any missing issuer certificates.

privateKeyPEMFile - The file containing the PEM-formatted PKCS #8 representation of the private key for the end entity certificate. This must not be null, the file must exist, and it must contain exactly one PEM-encoded private key. The private key may optionally be encrypted.

privateKeyEncryptionPassword - The password needed to decrypt the private key if it is encrypted. This may be null if the private key is not encrypted.

Throws:

java.security.KeyStoreException - If there is a problem with any of the provided PEM files.

Method Detail

getClientAliases

@Nullable
public java.lang.String[] getClientAliases(@Nullable
                                                     java.lang.String keyType,
                                                     @Nullable
                                                     java.security.Principal[] issuers)

Retrieves the aliases that may be used for a client certificate chain with the requested settings.

Specified by:

getClientAliases in interface javax.net.ssl.X509KeyManager

Parameters:

keyType - The key type for the alias to retrieve. It may be null if any key type may be used.

issuers - The set of allowed issuers for the aliases to retrieve. It may be null if any issuers should be allowed.

Returns:

An array of the aliases that may be used for a client certificate chain with the requested settings, or null if the certificate chain does not match the requested criteria.

getServerAliases

@Nullable
public java.lang.String[] getServerAliases(@Nullable
                                                     java.lang.String keyType,
                                                     @Nullable
                                                     java.security.Principal[] issuers)

Retrieves the aliases that may be used for a server certificate chain with the requested settings.

Specified by:

getServerAliases in interface javax.net.ssl.X509KeyManager

Parameters:

keyType - The key type for the alias to retrieve. It may be null if any key type may be used.

issuers - The set of allowed issuers for the aliases to retrieve. It may be null if any issuers should be allowed.

Returns:

An array of the aliases that may be used for a server certificate chain with the requested settings, or null if the certificate chain does not match the requested criteria.

chooseClientAlias

@Nullable
public java.lang.String chooseClientAlias(@Nullable
                                                    java.lang.String[] keyTypes,
                                                    @Nullable
                                                    java.security.Principal[] issuers,
                                                    @Nullable
                                                    java.net.Socket socket)

Chooses the alias that should be used for the preferred client certificate chain with the requested settings.

Specified by:

chooseClientAlias in interface javax.net.ssl.X509KeyManager

Parameters:

keyTypes - The set of allowed key types for the alias to retrieve. It may be null if any key type may be used.

issuers - The set of allowed issuers for the alias to retrieve. It may be null if any issuers should be allowed.

socket - The socket with which the certificate chain will be used. It may be null if no socket should be taken into consideration.

Returns:

The alias that should be used for the preferred client certificate chain with the requested settings, or null if there is no applicable alias.

chooseServerAlias

@Nullable
public java.lang.String chooseServerAlias(@Nullable
                                                    java.lang.String keyType,
                                                    @Nullable
                                                    java.security.Principal[] issuers,
                                                    @Nullable
                                                    java.net.Socket socket)

Chooses the alias that should be used for the preferred server certificate chain with the requested settings.

Specified by:

chooseServerAlias in interface javax.net.ssl.X509KeyManager

Parameters:

keyType - The key type for the alias to retrieve. It may be null if any key type may be u sed.

issuers - The set of allowed issuers for the alias to retrieve. It may be null if any issuers should be allowed.

socket - The socket with which the certificate chain will be used. It may be null if no socket should be taken into consideration.

Returns:

The alias that should be used for the preferred server certificate chain with the requested settings, or null if there is no applicable alias.

chooseAlias

@Nullable
public java.lang.String chooseAlias(@Nullable
                                              java.lang.String[] keyTypes,
                                              @Nullable
                                              java.security.Principal[] issuers)

Chooses the alias that should be used for the preferred certificate chain with the requested settings.

Parameters:

keyTypes - The set of allowed key types for the alias to retrieve. It may be null if any key type may be used.

issuers - The set of allowed issuers for the alias to retrieve. It may be null if any issuers should be allowed.

Returns:

The alias that should be used for the preferred certificate chain with the requested settings, or null if there is no applicable alias.

getCertificateChain

@NotNull
public java.security.cert.X509Certificate[] getCertificateChain(@Nullable
                                                                         java.lang.String alias)

Retrieves the certificate chain with the specified alias. Note that because this key manager implementation can only use a single certificate chain, it will always return the same chain for any alias, even if the requested alias is null.

Specified by:

getCertificateChain in interface javax.net.ssl.X509KeyManager

Parameters:

alias - The alias for the certificate chain to retrieve.

Returns:

The certificate chain for this key manager.

getPrivateKey

@NotNull
public java.security.PrivateKey getPrivateKey(@Nullable
                                                       java.lang.String alias)

Retrieves the private key for the certificate chain with the specified alias. Note that because this key manager implementation can only use a single certificate chain, it will always return the same private key for any alias, even if the requested alias is null.

Specified by:

getPrivateKey in interface javax.net.ssl.X509KeyManager

Parameters:

alias - The alias for the private key to retrieve.

Returns:

The private key for this key manager.