#

# Public Key Infrastructure (PKI) Enhancements
for J2SE 5

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:

- On-Line Certificate Service Protocol (OCSP)
- API support for indirect certificate revocation lists (CRLs)
- Clarified distinguished name usage in CertPath API
- Passed PKIX RFC 3280 compliance test suite
- Made java.security.cert.PolicyQualifierInfo non-final
- Added more CA certificates
- PKCS#11 Support
- Enhanced PKCS#12 implementation
- Enhanced TrustManager support

## On-Line Certificate Service Protocol (OCSP)

Client-side support for the On-Line Certificate Status Protocol (OCSP) as defined in RFC 2560 has been added in this release. OCSP checking is controlled by the following five, new security properties:

> 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:80
> By 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:00
> 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 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 CRLs
> true | 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.

## API Support for Indirect Certificate Revocation Lists (CRLs)

Indirect CRLs are certificate revocation lists that include entries for certificates from issuers other than the CRL issuer. In J2SE 5, two changes were made to the CertPath API to better support indirect CRLs.

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. `

- java.security.cert.TrustAnchor

  >     public TrustAnchor(X500Principal caPrincipal, PublicKey pubKey,
  >         byte[] nameConstraints);
  >     public final X500Principal getCA();

- java.security.cert.X509CertSelector

  >     public X500Principal getIssuer();
  >     public void setIssuer(X500Principal issuer);
  >     public X500Principal getSubject();
  >     public void setSubject(X500Principal subject);

- java.security.cert.X509CRLSelector

  >     public void setIssuers(Collection issuers);
  >     public void addIssuer(X500Principal issuer);
  >     public Collection getIssuers();

`

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`.

- `getSubjectX500Principal()`
- `getIssuerX500Principal()`
- `getIssuerX500Principal()`.

## Passed PKIX Complaince Test Suite

The CertPath implementation in the SUN provider in J2SE 5 passed the Public Key Interoperability Test Suite (PKITS).

## Made java.security.cert.PolicyQualifierInfo non-final

Prior to J2SE 5, `java.security.cert.PolicyQualifierInfo` was a final class. This prevented users from creating subclasses and adding methods that return fields of different types of policy qualifiers. In J2SE 5, this class was made non-final, but the following methods were made final to preserve the class' immutability contract.

>     public final String getPolicyQualifierId()
>     public final byte[] getEncoded()
>     public final byte[] getPolicyQualifier()

## Added More CA Certificates

The following CA (Certification Authority) certificates were added to the `cacerts` file in the `lib/security` directory of the Java installation.

      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

## PKCS#11 Support

The Cryptographic Token Interface Standard, PKCS#11, is a standard that defines native programming interfaces to cryptographic tokens, such as hardware cryptographic accelerators and Smartcards. In J2SE 5, support was added for PKCS#11. This means that PKI applications can use PKCS#11 tokens (such as Smartcards) as keystores. See the PKCS#11 Guide for more information on how to use PKCS#11 tokens as keystores.

## Enhanced PKCS#12 Implementation

PKCS#12 (Personal Information Exchange Syntax Standard) specifies a portable format for storage and/or transport of a user's private keys, certificates, miscellaneous secrets, and other items. J2SE 1.4.x provided read-only support for PKCS#12 keystores, and only for a small number of protection algorithms. The enhanced PKCS#12 keystore in J2SE 5 supports more protection algorithms (such as those supported by popular browsers) and also writing/updates to the keystore. This improves interoperability of PKCS#12 keystores imported/exported by J2SE, browsers, and other security applications.

## Enhanced TrustManager Support

By default, the SunJSSE provider in J2SE 5 uses a X509 PKIX-compliant trust manager. See the What's New in the JSSE Reference Guide for details.