org.dataone.client.auth

Class CertificateManager

java.lang.Object

java.util.Observable

org.dataone.client.auth.CertificateManager

public class CertificateManager
extends Observable

Import and manage certificates to be used for authentication against DataONE service providers. It uses the concepts of 'keystores' and 'truststores' to represent, respectively, the client certificate to be used for SSL connections, and the set of CA certificates that are trusted.
For the client keystore, the CertificateManager knows how to locate CILogon certificates downloaded via a browser. Because certificate downloads take place outside of the application using this class, the client keystore is not cached.
For the truststore, the CertificateManager builds and caches a TrustManager that is reused for all SSL connections it builds. It is assumed that these certificate are long-lived and as a whole, the set of them are stable throughout the life of the application. The TrustManager contains all of the CA certificates used by the JVM, and defaults also to include DataONE-trusted CA certificate that ship with d1_libclient_java.jar. For more information, see getSSLConnectionFactory()
Finally, note that the TLS protocol used to establish SSL/TLS connections is configurable using the property 'tls.protocol.preferences'. Success of TLS connections relies on alignment of the chosen TLS protocol with the Security providers determined by your runtime environment. As of May, 2015, te preference list is 'TLSv1.2, TLS'. This allows standard Java6 runtimes to operate at TLSv1.0, and Java7 and 8 runtimes to use the more secure TLSv1.2. This class is a singleton, as in any given application there need only be one collection of certificates.

Author:

Matt Jones, Ben Leinfelder

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	defaultTlsPreferences

Constructor Summary

Constructors

Constructor and Description
CertificateManager() CertificateManager is normally a singleton, but custom instances can be created if needed.

Method Summary

Modifier and Type	Method and Description
void	displayCertificate(X509Certificate cert) Show details of an X509 certificate, printing the information to STDOUT.
boolean	equalsDN(String dn1, String dn2) Compare Subject DNs for equality
X509Certificate	getCACert(String caAlias) Find the supplemental CA certificate to be used to validate user (peer) <
X509Certificate	getCertificate(javax.servlet.http.HttpServletRequest request) Get the client certificate from the request object
String	getCertificateLocation()
protected String	getExtensionValue(X509Certificate X509Certificate, String oid) Retrieves the extension value given by the OID
static CertificateManager	getInstance() Return the singleton instance of this CertificateManager, creating it if needed.
Session	getSession(javax.servlet.http.HttpServletRequest request) extracts the principal from the certificate passed in with the request and creates the dataone Session object.
org.apache.http.conn.ssl.SSLConnectionSocketFactory	getSSLConnectionSocketFactory(String subjectString) For use by clients making requests via SSL connection.
org.apache.http.conn.ssl.SSLConnectionSocketFactory	getSSLConnectionSocketFactory(X509Session x509Session)
org.apache.http.conn.ssl.SSLSocketFactory	getSSLSocketFactory(String subjectString) For use by clients making requests via SSL connection.
org.apache.http.conn.ssl.SSLSocketFactory	getSSLSocketFactory(X509Session x509Session)
String	getSubjectDN(X509Certificate certificate) Returns the RFC2253 string representation for the certificate's subject This is the standard format used in DataONE.
SubjectInfo	getSubjectInfo(X509Certificate certificate) Retrieve the SubjectInfo contained in the given certificate
X509Certificate	loadCertificate() Load the configured certificate into the keystore singleton Follows the logic of first searching the certificate at the setCertificateLocation() location, then using the default location.
X509Certificate	loadCertificateFromFile(String fileName) Load X509Certificate object from given file
PrivateKey	loadKey() Load configured private key from the keystore
PrivateKey	loadPrivateKeyFromFile(String fileName, String password) Load PrivateKey object from given file
File	locateDefaultCertificate() Locate the default certificate.
void	registerCertificate(String subjectString, X509Certificate certificate, PrivateKey key) Register certificates to be used by getSSLSocketFactory(subject) for setting up connections, using the subject as the lookup key
void	registerDefaultCertificate() Registers the default certificate into the registry, using first the setLocation or if null, the default CILogon location.
X509Session	selectSession(String subjectString) Select the X509Session using the provided subjectString to search among the registered certificates.
void	setCertificateLocation(String certificateFilePath) Use this method to set the certificate to point CertificateManager to a certificate at the designated file-path.
String	standardizeDN(String name) Returns D1-wide consistent Subject DN string representations
static boolean	verify(X509Certificate cert, X509Certificate caCert)
static boolean	verify(X509Certificate cert, X509Certificate caCert, boolean logExceptions) Check the validity of a certificate, and be sure that it is verifiable using the given CA certificate.

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

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

Field Detail

defaultTlsPreferences

protected static String defaultTlsPreferences

Constructor Detail

CertificateManager

public CertificateManager()

CertificateManager is normally a singleton, but custom instances can be created if needed. Normally, getInstance() will provide the appropriate interface for certificate management. In cases where the same process needs to act as multiple identities, new custom instances should be created.

Method Detail

getInstance

public static CertificateManager getInstance()

Return the singleton instance of this CertificateManager, creating it if needed.

Returns:

an instance of CertificateManager

getCertificateLocation

public String getCertificateLocation()

setCertificateLocation

public void setCertificateLocation(String certificateFilePath)

Use this method to set the certificate to point CertificateManager to a certificate at the designated file-path. (Call before getKeyStore() or getSSLSocketFactory(). Triggers CertificateManager to call Observer.update() method on registered observers unless the file is the same file as the previous set location (as determined by comparing the checksums of the current one with the new one).

Parameters:

certificateFilePath -

registerDefaultCertificate

public void registerDefaultCertificate()
                                throws IOException

Registers the default certificate into the registry, using first the setLocation or if null, the default CILogon location. Supports the use of the default certificate in Session parameters of DataONE API calls.

Throws:

IOException

registerCertificate

public void registerCertificate(String subjectString,
                                X509Certificate certificate,
                                PrivateKey key)

Register certificates to be used by getSSLSocketFactory(subject) for setting up connections, using the subject as the lookup key

Parameters:

subjectString -

certificate -

key -

getCACert

public X509Certificate getCACert(String caAlias)

Find the supplemental CA certificate to be used to validate user (peer) <

Returns:

X509Certificate for the root CA

loadCertificate

public X509Certificate loadCertificate()

Load the configured certificate into the keystore singleton Follows the logic of first searching the certificate at the setCertificateLocation() location, then using the default location. If a setCertificateLocation() has been previously set and can't be found, a WARN is logged and null is returned.

Returns:

the loaded X.509 certificate or null if a certificate isn't found

loadKey

public PrivateKey loadKey()

Load configured private key from the keystore

getExtensionValue

protected String getExtensionValue(X509Certificate X509Certificate,
                                   String oid)
                            throws IOException

Retrieves the extension value given by the OID

Parameters:

X509Certificate -

oid -

Returns:

Throws:

IOException

See Also:

http://stackoverflow.com/questions/2409618/how-do-i-decode-a-der-encoded-string-in-java

getSubjectInfo

public SubjectInfo getSubjectInfo(X509Certificate certificate)
                           throws IOException,
                                  InstantiationException,
                                  IllegalAccessException,
                                  MarshallingException

Retrieve the SubjectInfo contained in the given certificate

Parameters:

certificate -

Returns:

subjectInfo from DataONE representing subject of the certificate

Throws:

IOException

InstantiationException

IllegalAccessException

MarshallingException

getSubjectDN

public String getSubjectDN(X509Certificate certificate)

Returns the RFC2253 string representation for the certificate's subject This is the standard format used in DataONE.

Parameters:

certificate -

Returns:

subject DN using RFC2253 format

standardizeDN

public String standardizeDN(String name)

Returns D1-wide consistent Subject DN string representations

Parameters:

name - - the [reasonable] DN representation

Returns:

the standard D1 representation

See Also:

http://www.ietf.org/rfc/rfc2253.txt

equalsDN

public boolean equalsDN(String dn1,
                        String dn2)

Compare Subject DNs for equality

Parameters:

dn1 - the DN representation

dn2 - the other DN representation

Returns:

the true if they are "equal"

verify

public static boolean verify(X509Certificate cert,
                             X509Certificate caCert)

verify

public static boolean verify(X509Certificate cert,
                             X509Certificate caCert,
                             boolean logExceptions)

Check the validity of a certificate, and be sure that it is verifiable using the given CA certificate.

Parameters:

cert - the X509Certificate to be verified

caCert - the X509Certificate of the trusted CertificateAuthority (CA)

getSession

public Session getSession(javax.servlet.http.HttpServletRequest request)
                   throws InvalidToken

extracts the principal from the certificate passed in with the request and creates the dataone Session object.

Parameters:

request -

Returns:

Throws:

InvalidToken

getCertificate

public X509Certificate getCertificate(javax.servlet.http.HttpServletRequest request)

Get the client certificate from the request object

Parameters:

request -

Returns:

getSSLSocketFactory

public org.apache.http.conn.ssl.SSLSocketFactory getSSLSocketFactory(String subjectString)
                                                              throws NoSuchAlgorithmException,
                                                                     UnrecoverableKeyException,
                                                                     KeyStoreException,
                                                                     KeyManagementException,
                                                                     CertificateException,
                                                                     IOException

For use by clients making requests via SSL connection. It prepares and returns an SSL socket factory loaded with the certificate determined by the subjectString (see parameter details).
It also configures a TrustManager that uses a supplemental trust-store of DataONE trusted CAs in addition to the default set of CAs registered to the local system (exposed via Java Security).
One can turn off the supplemental DataONE trusted CAs by setting the property 'certificate.truststore.includeD1CAs=false'
The process of loading DataONE-trusted CA certificates is first to try to find them in a default auxiliary location determined by 'certificate.truststore.aux.location'. Failing to find either the directory or any certificates in the directory, it will load a set of CA certificates that ship with d1_libclient_java. This auxiliary location is to allow libclient applications to keep up with any updates to the trust-list without having to update libclient_java itself. Please note, however, that the CA certificates that ship with libclient_java will not be loaded if any certificates are found in the auxiliary location (it uses one or the other)

Parameters:

subjectString - - used to determine which certificate to use for the connection. If null, it auto-discovers the certificate, using the setCertificate() location, (if not set, uses the default location) Otherwise, looks up the certificate from among those registered with registerCertificate().

Returns:

an SSLSockectFactory object configured with the specified certificate

Throws:

NoSuchAlgorithmException - - thrown if the default or configured TLS protocol is not supported by the java runtime. To change the configured value to align with your runtime, see 'tls.protocol.preferences' in auth.properties file.

UnrecoverableKeyException

KeyStoreException - - thrown if an unknown subject value provided

KeyManagementException

CertificateException

IOException

getSSLSocketFactory

public org.apache.http.conn.ssl.SSLSocketFactory getSSLSocketFactory(X509Session x509Session)
                                                              throws NoSuchAlgorithmException,
                                                                     UnrecoverableKeyException,
                                                                     KeyStoreException,
                                                                     KeyManagementException,
                                                                     CertificateException,
                                                                     IOException

Throws:

NoSuchAlgorithmException

UnrecoverableKeyException

KeyStoreException

KeyManagementException

CertificateException

IOException

getSSLConnectionSocketFactory

public org.apache.http.conn.ssl.SSLConnectionSocketFactory getSSLConnectionSocketFactory(String subjectString)
                                                                                  throws NoSuchAlgorithmException,
                                                                                         UnrecoverableKeyException,
                                                                                         KeyStoreException,
                                                                                         KeyManagementException,
                                                                                         CertificateException,
                                                                                         IOException

For use by clients making requests via SSL connection. It prepares and returns an SSL socket factory loaded with the certificate determined by the subjectString (see parameter details).
It also configures a TrustManager that uses a supplemental trust-store of DataONE trusted CAs in addition to the default set of CAs registered to the local system (exposed via Java Security).
One can turn off the supplemental DataONE trusted CAs by setting the property 'certificate.truststore.includeD1CAs=false'
The process of loading DataONE-trusted CA certificates is first to try to find them in a default auxiliary location determined by 'certificate.truststore.aux.location'. Failing to find either the directory or any certificates in the directory, it will load a set of CA certificates that ship with d1_libclient_java. This auxiliary location is to allow libclient applications to keep up with any updates to the trust-list without having to update libclient_java itself. Please note, however, that the CA certificates that ship with libclient_java will not be loaded if any certificates are found in the auxiliary location (it uses one or the other)

Parameters:

subjectString - - used to determine which certificate to use for the connection. If null, it auto-discovers the certificate, using the setCertificate() location, (if not set, uses the default location) Otherwise, looks up the certificate from among those registered with registerCertificate().

Returns:

an SSLSockectFactory object configured with the specified certificate

Throws:

NoSuchAlgorithmException - - thrown if the default or configured TLS protocol is not supported by the java runtime. To change the configured value to align with your runtime, see 'tls.protocol.preferences' in auth.properties file.

UnrecoverableKeyException

KeyStoreException - - thrown if an unknown subject value provided

KeyManagementException

CertificateException

IOException

getSSLConnectionSocketFactory

public org.apache.http.conn.ssl.SSLConnectionSocketFactory getSSLConnectionSocketFactory(X509Session x509Session)
                                                                                  throws NoSuchAlgorithmException,
                                                                                         UnrecoverableKeyException,
                                                                                         KeyStoreException,
                                                                                         KeyManagementException,
                                                                                         CertificateException,
                                                                                         IOException

Throws:

NoSuchAlgorithmException

UnrecoverableKeyException

KeyStoreException

KeyManagementException

CertificateException

IOException

selectSession

public X509Session selectSession(String subjectString)
                          throws IOException

Select the X509Session using the provided subjectString to search among the registered certificates. If the subjectString parameter is null, finds the certificate first using the set certificate location, and then the default location for CILogon certificate downloads (the user's tmp directory). If no certificate file is found, null is returned, signifying that a public connection (certificate-less) will be used. NOTE: this implementation uses Bouncy Castle security provider

Parameters:

subjectString -

Returns:

Throws:

IOException - - if there was trouble reading the PEM file.

loadPrivateKeyFromFile

public PrivateKey loadPrivateKeyFromFile(String fileName,
                                         String password)
                                  throws IOException

Load PrivateKey object from given file

Parameters:

fileName -

password -

Returns:

Throws:

IOException

loadCertificateFromFile

public X509Certificate loadCertificateFromFile(String fileName)
                                        throws IOException

Load X509Certificate object from given file

Parameters:

fileName -

Returns:

Throws:

IOException

locateDefaultCertificate

public File locateDefaultCertificate()
                              throws FileNotFoundException

Locate the default certificate. The default location is constructed based on user environment properties, so this method constructs a path and tests whether or not the resulting path exists. see also http://www.cilogon.org/cert-howto#TOC-Finding-CILogon-Certificates

Returns:

File object of known-to-exist location

Throws:

FileNotFoundException - if no default certificate can be located

displayCertificate

public void displayCertificate(X509Certificate cert)

Show details of an X509 certificate, printing the information to STDOUT.

Parameters:

cert - the certificate to be displayed