X.509 Java API

Library EARLY access

It is possible to perform an early testing and integration of the java library. To do so you need Maven (at least 2.2.1), OpenJDK 6 and SVN client.

Please note that as of now (14.11.2011) the library is in alpha state: all features are implemented, API should be finalized, however some significant parts are still untested. In particular the proxy generation and proxy CSR generation parts are only minimally tested, and quite likely can contain many errors.

The following commands will retrieve the latest sources from the repository, compile, test, package and install the library to the local Maven's repository:

svn export http://unicore.svn.sourceforge.net/svnroot/unicore/securityFramework/authlib/trunk authlib
cd authlib
mvn install

Note: if you get an error on the test eu.emi.security.authn.x509.ns.OpensslDirTest then it is a known issue related to the risky design of the test (it will be changed after the intensive development is finished). Simply rerun the command or (if you get the error again) add -DskipTests switch the to mvn install command.

For those who do not want to use Maven in project which are going to use the library, the jar file can be found in the target/ directory after building.

Maven dependency:

<dependency>
    <groupId>eu.emi.security</groupId>
    <artifactId>authnlib</artifactId>
    <version>1.0.0-SNAPSHOT</version> 
</dependency>

Please note that this dependency is not deployed yet anywhere, so you need to install it locally first, as it was shown above.

Complete API - for internal review

caNl-javadoc-rc2.zip: Version after internal reviews. Hopefully final.

caNl-javadoc-rc1.zip: caNl-javadoc-rc1.zip

Overview

The API consists of classes allowing for off line certificate validation and SSL socket creation. The latter part heavily depends on validation part and JSSE.

The CertificateChecker interface, its all implementations and ValidationErrorListener interface are supposed to be a low-level API and typically will not be used directly. However those classes are not hidden as sometimes it might be good to have an option to use them to influence the standard validation process.

Examples

• To check a certificate chain using Openssl style directory with trusted CA certificates.

OpensslCertChainValidator v = new OpensslCertChainValidator("/my/certs", 
            OpensslCertChainValidator.CRL.REQUIRE, OpensslCertChainValidator.NAMESPACE.IGNORE, 100);

ValidationResult result = v.validate(toBeChecked);

• To create SSLServerSocket using Keystore with trusted CA certificates.

KeystoreCertChainValidator v = new KeystoreCertChainValidator("/my/truststore.jks", 
            KeystoreCertChainValidator.CRL.REQUIRE, passwd, "JKS", crls, 100);

X509Credential c = new KeystoreCredential("/my/keystore.jks", ksPasswd, keyPasswd, "JKS");
SSLServerSocketFactory sslSsf = SocketFactoryCreator.getServerSocketFactory(c, v);
   
ServerSocket sslSS = sslSsf.createServerSocket();

• Draft of the contents of the SocketFactoryCreator.getServerSocketFactory(X509Credential c, X509CertChainValidator v)

KeyManager km = c.getAsKeyManager();
TrustManager tm = new CommonX509TrustManager(v);
SSLContext sslCtx = SSLContext.getInstance("TLS", "SunJSSE");
sslCtx.init(new KeyManager[] {km}, new TrustManager[] {tm}, new SecureRandom());
SSLServerSocketFactory sslSsf = sslCtx.getServerSocketFactory();

Package eu.emi.security.authn.x509

Certificates validation

• interface CertificateChecker
  Performs low level checks of some certificate properties. Intended to be used internally, as a part of certificate chain validation (so by Validator implementation class). May be stateful, implementations need not to be thread safe - one instance must not be used to check two certificate chains simultaneously. Constructors may need complex arguments.
  • java.util.List<ValidationError> check(java.security.cert.X509Certificate[] cert, int position, java.util.Collection<String> unresolvedCritExts)
    Performs the check(s) on the specified certificate (possibly using its internal state and the rest of chain) and removes any critical extensions that it processes from the specified collection of OIDs).
  • void init()
    Resets this checker so it can be used to check a new certificate chain.

• interface ValidationErrorListener
  Invoked when there is an error in processing returned by any checker.
  • boolean onValidationError(java.security.cert.X509Certificate[] cert, ValidationError error)
    Invoked upon validation error during chain processing. Implementation MAY change the validation error description. Returned value determines whether the error shall be ignored (true) or not (false).

• class ValidationError
  Holds information about a single validation problem.
  • int getPosition()
  • String getMessage()
  • String getErrorCode()
  • void setMessage(String msg)
  • void setErrorCode(String code)

• class ValidationResult
  Wraps a validation result, and optionally error messages list and unresolved certificate extension oids.
  • boolean isValid()
  • java.util.List<ValidationError> getErrors()
  • java.util.Set<String> getUnresolvedExtensions()

• interface X509CertChainValidator
  Implementations are used to perform a manual certificate chain validation. Constructor parameters are expected to be very different. Implementations shall reuse as many of CertificateChecker implementations as possible. Implementations must be thread safe.
  • ValidationResult validate(java.security.cert.CertPath cp)
  • ValidationResult validate(java.security.cert.X509Certificate[] cp)
  • java.security.cert.X509Certificate[] getTrustedIssuers()
  • void addValidationListener(ValidationListener l)
  • ValidationErrorListener removeValidationListener(ValidationListener l)

JSSE integration (TLS socket creation)

• class CommonX509TrustManager implements javax.net.ssl.X509TrustManager
  This class wraps X509CertChainValidator so it can be easily used in standard Java SSL API.
  • CommonX509TrustManager(X509CertChainValidator validator)
    The constructor.

• interface X509Credential
  Implementations are used to wrap credentials (private key and certificate) in various formats. Methods allow for converting the wrapped credentials into a format usable by the Java API.
  • java.security.KeyStore getKeyStore()
  • javax.net.ssl.KeyManager getKeyManager()

Package eu.emi.security.authn.x509.impl

Certificates validation

• class ProxyCertificateChecker implements CertificateChecker
  Handles all checks related to the proxy certificate.

• class BasicCertificateChecker implements CertificateChecker
  Handles all generic checks of a certificate (e.g. signatures, time validity etc). NOTE: it is likely that this checker will be split into many to have a cleaner implementation.

• class OpensslCertChainValidator implements X509CertChainValidator
  The certificate validator which uses OpenSSL directory as a truststore.
  • OpensslCertChainValidator(String directory, CrlMode crlMode, NamespaceMode namespaceMode, int updateInterval, boolean allowProxy)
    The constructor. crlMode enum defines what type of CRL checking shall by used (REQUIRE, IF_AVAILABLE, NONE). The namespaceMode enum defines what type of namespace handling shall be used (REQUIRE, IF_AVAILABLE, NONE). NOTE: other constructors are expected along with setters and getters.

• class KeystoreCertChainValidator implements X509CertChainValidator
  The certificate validator which uses Java KeyStore as a truststore.
  • KeystoreCertChainValidator(String keystorePath, char[] password, String type, List<String> crls, CrlMode crlMode, int updateInterval, boolean allowProxy)
    The constructor.

JSSE integration (TLS socket creation)

• class HostnameToCertificateChecker implements javax.net.ssl.HandshakeCompletedListener
  Implementation which can be registered on a SSLSocket to verify if target hostname is matching a DN of its certificate.

• class SocketFactoryCreator
  Simple utility allowing programmers to quickly create SSLSocket factories.
  • static javax.net.ssl.SSLServerSocketFactory getServerSocketFactory(X509Credential c, X509CertChainValidator v)
  • static javax.net.ssl.SSLSocketFactory getSocketFactory(X509Credential c, X509CertChainValidator v)

• class PEMFileCredential implements X509Credential
  Wraps certificate and private key stored in two PEM files.
  • PEMFileCredential(String keyPath, String certFile, char[] keyPasswd)
    The constructor.

• class KeystoreCredential implements X509Credential
  Dummy wrapper over keystore.
  • KeystoreCredential(String keystorePath, char[] storePasswd, char[] keyPasswd, String storeType)
    The constructor.

Utilities

• class X500NameUtils
  Utility class with methods simplifying typical Distinguished Name related operations.
  • public static boolean equal(String rfc2253dn1, String rfc2253dn2) throws ParseException
    Uses the standard JDK algorithm, see X500Principial.equal() for details.
  • public static boolean equal(X500Principal dn, String rfc2253dn2) throws ParseException
    Uses the standard JDK algorithm, see X500Principial.equal() for details.
  • public static boolean equal(X500Principal dn, X500Principal dn2)
    Uses the strict RFC 3820 algorithm. Note(!) that in certain situations it is possible to get a false answer when comparing DNs with this method, while other DN equality tests from this class (operating on String DN representations) return true.
  • static String getReadableForm(String srcDn) throws java.text.ParseException
  • static String getReadableForm(X500Principal srcDn)
  • static String[] getAttributeVals(String srcDn) throws java.text.ParseException
  • static String[] getAttributeVals(X500Principal srcDn)

• class CertificateUtils
  Utility class with methods simplifying typical certificate related operations.
  • enum PrintMode {COMPACT, FULL}
  • enum FileFormat {PEM, DER}
  • static X509Certificate[] convertToX509Chain(Certificate []chain)
  • static String getReadableForm(X509Certificate cert, PrintMode mode)
  • static String getReadableForm(X509Certificate[] cert, PrintMode mode)
  • static X509Certificate loadCertificate(InputStream is, FileFormat format) throws IOException
  • static PrivateKey loadPrivateKey(InputStream is, FileFormat format) throws IOException
  • static X509Certificate[] loadCertificateChain(InputStream is, FileFormat format) throws IOException
  • static KeyStore loadPEMKeystore(InputStream is) throws IOException
  • static void saveCertificate(OutputStream is, X509Certificate cert, FileFormat format) throws IOException
  • static void savePrivateKey(OutputStream is, PrivateKey pk, FileFormat format) throws IOException
  • static void saveCertificateChain(OutputStream is, X509Certificate[] chain, FileFormat format) throws IOException
  • static void savePEMKeystore(KeyStore is, OutputStream os) throws IOException

Package eu.emi.security.authn.x509.proxy

The first proposition is attached.

canl-proxies-java-0.1.zip: canl-proxies-java-0.1.zip

canl-proxies-java-0.2.zip: canl-proxies-java-0.2.zip

-- KrzysztofBenedyczak - 06-Nov-2010

• caNl-javadoc-rc2.zip: caNl-javadoc-rc2.zip