IMPORTANT NOTE: The APIs and features described in this document are SUBJECT TO CHANGE.
1. Introduction
This document describes the PKI enhancements that have been made to
J2SE 5.0
and how to use them. Please send feedback on these enhancements to
java-security@sun.com.
The following PKI enhancements were made in version 5.0 of the Java 2 platform:
Property Name Description ocsp.enable This property's value is either true or false. If true, OCSP checking is enabled when doing certificate revocation checking; if false or not set, OCSP checking is disabled. ocsp.responderURL This property's value is a URL that identifies the location of the OCSP responder. Here is an example. ocsp.responderURL=http://ocsp.example.net:80By default, the location of the OCSP responder is determined implicitly from the certificate being validated. The property is used when the Authority Information Access extension (defined in RFC 3280) is absent from the certificate or when it requires overriding.
ocsp.responderCertSubjectName This property's value is the subject name of the OCSP responder's certificate. Here is an example. ocsp.responderCertSubjectName="CN=OCSP Responder, O=XYZ Corp"By default, the certificate of the OCSP responder is that of the issuer of the certificate being validated. This property identifies the certificate of the OCSP responder when the default does not apply. Its value is a string distinguished name (defined in RFC 2253) which identifies a certificate in the set of certificates supplied during cert path validation. In cases where the subject name alone is not sufficient to uniquely identify the certificate, then both the ocsp.responderCertIssuerName and ocsp.responderCertSerialNumber properties must be used instead. When this property is set, then those two properties are ignored.
ocsp.responderCertIssuerName This property's value is the issuer name of the OCSP responder's certificate. Here is an example. ocsp.responderCertIssuerName="CN=Enterprise CA, O=XYZ Corp"By default, the certificate of the OCSP responder is that of the issuer of the certificate being validated. This property identifies the certificate of the OCSP responder when the default does not apply. Its value is a string distinguished name (defined in RFC 2253) which identifies a certificate in the set of certificates supplied during cert path validation. When this property is set then the ocsp.responderCertSerialNumber property must also be set. Note that this property is ignored when the ocsp.responderCertSubjectName property has been set.
ocsp.responderCertSerialNumber This property's value is the serial number of the OCSP responder's certificate Here is an example. ocsp.responderCertSerialNumber=2A:FF:00By default, the certificate of the OCSP responder is that of the issuer of the certificate being validated. This property identifies the certificate of the OCSP responder when the default does not apply. Its value is a string of hexadecimal digits (colon or space separators may be present) which identifies a certificate in the set of certificates supplied during cert path validation. When this property is set then the ocsp.responderCertIssuerName property must also be set. Note that this property is ignored when the ocsp.responderCertSubjectName property has been set.
These properties may be set either staticly in the Java runtime's $JAVA_HOME/jre/lib/security/java.security file, or dynamically using the java.security.Security.setProperty() method.
By default, OCSP checking is not enabled. It is enabled by setting the ocsp.enable property to "true". Use of the remaining properties is optional. Note that enabling OCSP checking only has an effect if revocation checking has also been enabled. Revocation checking is enabled via the PKIXParameters.setRevocationEnabled() method.
OCSP checking works in conjunction with Certificate Revocation Lists (CRLs) during revocation checking. Below is a summary of the interaction of OCSP and CRLs. Failover to CRLs occurs only if an OCSP problem is encountered. Failover does not occur if the OCSP responder confirms either that the certificate has been revoked or that it has not been revoked.
PKIXParameters RevocationEnabled (default=true) ocsp.enabled (default=false) Behavior true true Revocation checking using OCSP,
failover to using CRLstrue false Revocation checking using CRLs only false true No revocation checking false false No revocation checking
See the Java Certification Path API Programming Guide for details about revocation checking and Certificate Revocation Lists.
The java.security.cert.X509CRL class has a method, getRevokedCertificate(BigInteger), for getting a CRL entry given a certificate's serial number. However, for an indirect CRL, the serial number does not uniquely identify a certificate. In J2SE 5, an overloaded form of getRevokedCertificate() was added for getting a CRL entry given a certificate.
Prior to J2SE 5,
the
java.security.cert.X509CRLEntry class did not have
any method for obtaining the issuer of the certificate described by
the CRL entry.
In J2SE 5, a method,
getCertificateIssuer(),
was added to address this gap.
Clarified Distinguished Name Usage in CertPath API
The CertPath API has constructors and methods that accept byte arrays
and strings to represent distinguished names. However, in some
classes, it lacked similar overloaded forms that
accept X500Principal
to represent distinguished names. Use of X500Principal to
represent a distinguished name is preferred because it is more
efficient and suitably typed. The following methods were added
to the CertPath API.
public TrustAnchor(X500Principal caPrincipal, PublicKey pubKey,
byte[] nameConstraints);
public final X500Principal getCA();
public X500Principal getIssuer();
public void setIssuer(X500Principal issuer);
public X500Principal getSubject();
public void setSubject(X500Principal subject);
public void setIssuers(Collection
The methods getSubjectDN() and getIssuerDN() in the X509Certificate class and getIssuerDN() in the X509CRL class are problematic because their specifications say that they return a distinguished name without being specific about its format. Consequently, different implementations may return implementation-specific objects, resulting in applications that have poor interoperability or are non-portable. Use of these methods are strongly discouraged. Instead, applications should use the methods that return an instance of X500Principal.
public final String getPolicyQualifierId() public final byte[] getEncoded() public final byte[] getPolicyQualifier()
Alias name: equifaxsecureebusinessca1
Owner: CN=Equifax Secure eBusiness CA-1, O=Equifax Secure Inc., C=US
Alias name: equifaxsecureca
Owner: OU=Equifax Secure Certificate Authority, O=Equifax, C=US
Alias name: geotrustglobalca
Owner: CN=GeoTrust Global CA, O=GeoTrust Inc., C=US
Alias name: equifaxsecureglobalebusinessca1
Owner: CN=Equifax Secure Global eBusiness CA-1, O=Equifax Secure Inc., C=US
Alias name: equifaxsecureebusinessca2
Owner: OU=Equifax Secure eBusiness CA-2, O=Equifax Secure, C=US
Alias name: verisignclass1g3ca
Owner: CN=VeriSign Class 1 Public Primary Certification Authority - G3, OU="(c)
1999 VeriSign, Inc. - For authorized use only", OU=VeriSign Trust Network,
O="VeriSign, Inc.", C=US
Issuer: CN=VeriSign Class 1 Public Primary Certification Authority - G3, OU="(c)
1999 VeriSign, Inc.
- For authorized use only", OU=VeriSign Trust Network, O="VeriSign, Inc.", C=US
Alias name: verisignclass2g2ca
Owner: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
use only", OU=Class 2
Public Primary Certification Authority - G2, O="VeriSign, Inc.", C=US
Issuer: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
use only", OU=Class 2 Public Primary Certification Authority - G2, O="VeriSign,
Inc.", C=US
Alias name: verisignclass3g3ca
Owner: CN=VeriSign Class 3 Public Primary Certification Authority - G3, OU="(c)
1999 VeriSign, Inc. - For authorized use only", OU=VeriSign Trust Network,
O="VeriSign, Inc.", C=US
Issuer: CN=VeriSign Class 3 Public Primary Certification Authority - G3, OU="(c)
1999 VeriSign, Inc.
- For authorized use only", OU=VeriSign Trust Network, O="VeriSign, Inc.", C=US
Alias name: verisignclass1g2ca
Owner: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
use only", OU=Class 1
Public Primary Certification Authority - G2, O="VeriSign, Inc.", C=US
Issuer: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
use only", OU=Class 1 Public Primary Certification Authority - G2, O="VeriSign,
Inc.", C=US
Alias name: verisignclass2g3ca
Owner: CN=VeriSign Class 2 Public Primary Certification Authority - G3, OU="(c)
1999 VeriSign, Inc. - For authorized use only", OU=VeriSign Trust Network,
O="VeriSign, Inc.", C=US
Issuer: CN=VeriSign Class 2 Public Primary Certification Authority - G3, OU="(c)
1999 VeriSign, Inc.
- For authorized use only", OU=VeriSign Trust Network, O="VeriSign, Inc.", C=US
Alias name: verisignclass3g2ca
Owner: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
use only", OU=Class 3
Public Primary Certification Authority - G2, O="VeriSign, Inc.", C=US
Issuer: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
use only", OU=Class 3 Public Primary Certification Authority - G2, O="VeriSign,
Inc.", C=US