org.dataone.client.auth

Class CertificateManager

java.lang.Object

org.dataone.client.auth.CertificateManager

public class CertificateManager
extends Object

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()
This class is a singleton, as in any given application there need only be one collection of certificates.

Author:

Matt Jones, Ben Leinfelder

Constructor Summary

Constructors

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

Method Summary

Methods

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.
Session	getSession(javax.servlet.http.HttpServletRequest request, boolean lookupSubject) extracts the principal from the certificate passed in with the request and creates the dataone Session object.
org.apache.http.conn.ssl.SSLSocketFactory	getSSLSocketFactory(String subjectString) For use by clients making requests via SSL connection.
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 subject, X509Certificate certificate, PrivateKey key) Register certificates to be used by getSSLSocjetFactory(subject) for setting up connections, using the subject as the lookup key
void	setCertificateLocation(String certificate) 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.lang.Object

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

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 certificate)

Use this method to set the certificate to point CertificateManager to a certificate at the designated file-path. (Call before getKeyStore() or getSSLSocketFactory()

Parameters:

certificate -

registerCertificate

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

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

Parameters:

subject -

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.

Returns:

the loaded X.509 certificate

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,
                                  org.jibx.runtime.JiBXException

Retrieve the SubjectInfo contained in the given certificate

Parameters:

certificate -

Returns:

subjectInfo from DataONE representing subject of the certificate

Throws:

IOException

InstantiationException

IllegalAccessException

org.jibx.runtime.JiBXException

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. The SubjectList is not filled out.

Parameters:

request -

Returns:

Throws:

InvalidToken

getSession

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

extracts the principal from the certificate passed in with the request and creates the dataone Session object. If lookupSubject parameter is true, an http call to the subject authority is made (the CNIdentity service) to populate the SubjectList session property

Parameters:

request -

lookupSubject - - set to true to fill out the subject list from the CNIdentity service

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

UnrecoverableKeyException

KeyStoreException - - thrown if an unknown subject value provided

KeyManagementException

CertificateException

IOException

loadPrivateKeyFromFile

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

Load PrivateKey object from given file

Parameters:

fileName -

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