java.security.cert Documentation Differences

This file contains all the changes in documentation in the package java.security.cert as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

This class is an abstraction of certificate revocation lists (CRLs) that have different formats but important common uses. For example all CRLs share the functionality of listing revoked certificates and can be queried on whether or not they list a given certificate.

Specialized CRL types can be defined by subclassing off of this abstract class. @author Hemma Prafullchandra @version 1.5 989 02/1202/0300 @see X509CRL @see CertificateFactory @since JDK11.2

CRL (Certificate Revocation List) Exception @author Hemma Prafullchandra 1.46

Abstract class for managing a variety of identity certificates. An identity certificate is a binding of a principal to a public key which is vouched for by another principal. (A principal represents an entity such as an individual user a group or a corporation.)

This class is an abstraction for certificates that have different formats but important common uses. For example different types of certificates such as X.509 and PGP share general certificate functionality (like encoding and verifying) and some types of information (like a public key).

X.509 PGP and SDSI certificates can all be implemented by subclassing the Certificate class even though they contain different sets of information and they store and retrieve the information in different ways. @see X509Certificate @see CertificateFactory @author Hemma Prafullchandra @version 1.14 9818 00/1202/0302

Returns the encoded form of this certificate. It is assumed that each certificate type would have only a single form of encoding; for example X.509 certificates would be encoded as ASN.1 DER. @return the encoded form of this certificate @exception CertificateEncodingException if an encoding error occurs.

Certificate Encoding Exception. This is thrown whenever an error occurs while attempting to encode a certificate. @author Hemma Prafullchandra 1.57

This exception indicates one of a variety of certificate problems. @author Hemma Prafullchandra @version 1.2527 @see Certificate

Certificate Expired Exception. This is thrown whenever the current Date or the specified Date is after the notAfter date/time specified in the validity period of the certificate. @author Hemma Prafullchandra 1.46

This class defines the functionality of a certificate factory which is used to generate certificate and certificate revocation list (CRL) objects from their encodings.

A certificate factory for X.509 must return certificates that are an instance of java.security.cert.X509Certificate and CRLs that are an instance of java.security.cert.X509CRL.

The following example reads a file with Base64 encoded certificates which are each bounded at the beginning by -----BEGIN CERTIFICATE----- and bounded at the end by -----END CERTIFICATE-----. We convert the FileInputStream (which does not support mark and reset) to a ByteArrayInputStream (which supports those methods) so that each call to generateCertificate consumes only one certificate and the read position of the input stream is positioned to the next certificate in the file:

 FileInputStream fis = new FileInputStream(filename); DataInputStream dis = new DataInputStream(fis); CertificateFactory cf = CertificateFactory.getInstance("X.509"); byte[] bytes = new byte[dis.available()]; dis.readFully(bytes); ByteArrayInputStream bais = new ByteArrayInputStream(bytes); while (bais.available() > 0) { Certificate cert = cf.generateCertificate(bais); System.out.println(cert.toString()); } 

The following example parses a PKCS#7-formatted certificate reply stored in a file and extracts all the certificates from it:

 FileInputStream fis = new FileInputStream(filename); CertificateFactory cf = CertificateFactory.getInstance("X.509"); Collection c = cf.generateCertificates(fis); Iterator i = c.iterator(); while (i.hasNext()) { Certificate cert = (Certificate)i.next(); System.out.println(cert); } 

@author Hemma Prafullchandra @author Jan Luehe @version 1.1115 02/02/00 @see Certificate @see X509Certificate @see CRL @see X509CRL @since JDK11.2

This class defines the Service Provider Interface (SPI) for the CertificateFactory class. All the abstract methods in this class must be implemented by each cryptographic service provider who wishes to supply the implementation of a certificate factory for a particular certificate type e.g. X.509.

Certificate factories are used to generate certificate and certificate revocation list (CRL) objects from their encoding.

A certificate factory for X.509 must return certificates that are an instance of java.security.cert.X509Certificate and CRLs that are an instance of java.security.cert.X509CRL. @author Hemma Prafullchandra @author Jan Luehe @version 1.49 02/02/00 @see CertificateFactory @see Certificate @see X509Certificate @see CRL @see X509CRL @since JDK11.2

Returns a (possibly empty) collection view of the certificates read from the given input stream inStream.

In order to take advantage of the specialized certificate format supported by this certificate factory each element in the returned collection view can be typecast to the corresponding certificate class. For example if this certificate factory implements X.509 certificates the elements in the returned collection can be typecast to the X509Certificate class.

In the case of a certificate factory for X.509 certificates inStream may contain a single DER-encoded certificate in the formats described for generateCertificate In addition inStream may contain a PKCS#7 certificate chain. This is a PKCS#7 SignedData object with the only significant field being certificates. In particular the signature and the contents are ignored. This format allows multiple certificates to be downloaded at once. If no certificates are present an empty collection is returned.

Note that if the given input stream does not support mark and reset this method will consume the entire input stream. @param inStream the input stream with the certificates. @return a (possibly empty) collection view of java.security.cert.Certificate objects initialized with the data from the input stream. @exception CertificateException on parsing errors.

Certificate is not yet valid exception. This is thrown whenever the current Date or the specified Date is before the notBefore date/time in the Certificate validity period. @author Hemma Prafullchandra 1.46

Certificate Parsing Exception. This is thrown whenever an invalid DER-encoded certificate is parsed or unsupported DER features are found in the Certificate. @author Hemma Prafullchandra 1.57

Abstract class for an X.509 Certificate Revocation List (CRL). A CRL is a time-stamped list identifying revoked certificates. It is signed by a Certificate Authority (CA) and made freely available in a public repository.

Each revoked certificate is identified in a CRL by its certificate serial number. When a certificate-using system uses a certificate (e.g. for verifying a remote user's digital signature) that system not only checks the certificate signature and validity but also acquires a suitably- recent CRL and checks that the certificate serial number is not on that CRL. The meaning of "suitably-recent" may vary with local policy but it usually means the most recently-issued CRL. A CA issues a new CRL on a regular periodic basis (e.g. hourly daily or weekly). Entries are added to CRLs as revocations occur and an entry may be removed when the certificate expiration date is reached.

The X.509 v2 CRL format is described below in ASN.1:

 CertificateList ::= SEQUENCE { tbsCertList TBSCertList signatureAlgorithm AlgorithmIdentifier signature BIT STRING } 

A goodMore decription andinformation profiling is providedcan be found in the IETFRFC PKIX2459 WG draft Part I:"Internet X.509 Public Key Infrastructure Certificate and CRL Profile" <draft-at http://www.ietf-pkix-ipki-part1-07.org/rfc/rfc2459.txt> .

The ASN.1 definition of tbsCertList is:

 TBSCertList ::= SEQUENCE { version Version OPTIONAL -- if present must be v2 signature AlgorithmIdentifier issuer Name thisUpdate ChoiceOfTime nextUpdate ChoiceOfTime OPTIONAL revokedCertificates SEQUENCE OF SEQUENCE { userCertificate CertificateSerialNumber revocationDate ChoiceOfTime crlEntryExtensions Extensions OPTIONAL -- if present must be v2 } OPTIONAL crlExtensions [0] EXPLICIT Extensions OPTIONAL -- if present must be v2 } 

CRLs are instantiated using a certificate factory. The following is an example of how to instantiate an X.509 CRL:

 InputStream inStream = new FileInputStream("fileName-of-crl"); CertificateFactory cf = CertificateFactory.getInstance("X.509"); X509CRL crl = (X509CRL)cf.generateCRL(inStream); inStream.close(); 

@author Hemma Prafullchandra @version 1.1318 @see CRL @see CertificateFactory @see X509Extension

Returns the ASN.1 DER-encoded form of this CRL. @return the encoded form of this certificate @exception CRLException if an encoding error occurs.

Gets the CRL entry if any with the given certificate serialNumber. from@param thisserialNumber the serial number of the certificate for which a CRL. entry is to be looked up @return the entry with the given serial number or null if no such entry exists in this CRL. @see X509CRLEntry

Gets the signature algorithm OID string from the CRL. An OID is represented by a set of positive whole numbers separated by periods. For example the string "1.2.840.10040.4.3" identifies the SHA-1 with DSA signature algorithm as per the PKIX partRFC I2459.

See getSigAlgName()#getSigAlgName for relevant ASN.1 definitions. @return the signature algorithm OID string.

Abstract class for a revoked certificate in a CRL (Certificate Revocation List). The ASN.1 definition for revokedCertificates is:

 revokedCertificates SEQUENCE OF SEQUENCE { userCertificate CertificateSerialNumber revocationDate ChoiceOfTime crlEntryExtensions Extensions OPTIONAL -- if present must be v2 } OPTIONAL 
 CertificateSerialNumber ::= INTEGER 
 Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension 
 Extension ::= SEQUENCE { extnId OBJECT IDENTIFIER critical BOOLEAN DEFAULT FALSE extnValue OCTET STRING -- contains a DER encoding of a value -- of the type registered for use with -- the extnId object identifier value } 

@see X509CRL @see X509Extension @author Hemma Prafullchandra @version 1.9 9812 00/1202/0302

Returns the ASN.1 DER-encoded form of this CRL Entry that is the inner SEQUENCE. @return the encoded form of this certificate @exception CRLException if an encoding error occurs.

Abstract class for X.509 certificates. This provides a standard way to access all the attributes of an X.509 certificate.

In June of 1996 the basic X.509 v3 format was completed by ISO/IEC and ANSI X9 which is described below in ASN.1:

 Certificate ::= SEQUENCE { tbsCertificate TBSCertificate signatureAlgorithm AlgorithmIdentifier signature BIT STRING } 

These certificates are widely used to support authentication and other functionality in Internet security systems. Common applications include Privacy Enhanced Mail (PEM) Transport Layer Security (SSL) code signing for trusted software distribution and Secure Electronic Transactions (SET).

These certificates are managed and vouched for by Certificate Authorities (CAs). CAs are services which create certificates by placing data in the X.509 standard format and then digitally signing that data. CAs act as trusted third parties making introductions between principals who have no direct knowledge of each other. CA certificates are either signed by themselves or by some other CA such as a "root" CA.

A good decriptionMore information can and profiling isbe providedfound in the IETF PKIX WGRFC draft2459 Part I:"Internet X.509 Public Key Infrastructure Certificate and CRL Profile" <draft-at http://www.ietf-pkix-ipki-part1-07.org/rfc/rfc2459.txt> .

The ASN.1 definition of tbsCertificate is:

 TBSCertificate ::= SEQUENCE { version [0] EXPLICIT Version DEFAULT v1 serialNumber CertificateSerialNumber signature AlgorithmIdentifier issuer Name validity Validity subject Name subjectPublicKeyInfo SubjectPublicKeyInfo issuerUniqueID [1] IMPLICIT UniqueIdentifier OPTIONAL -- If present version must be v2 or v3 subjectUniqueID [2] IMPLICIT UniqueIdentifier OPTIONAL -- If present version must be v2 or v3 extensions [3] EXPLICIT Extensions OPTIONAL -- If present version must be v3 } 

Certificates are instantiated using a certificate factory. The following is an example of how to instantiate an X.509 certificate:

 InputStream inStream = new FileInputStream("fileName-of-cert"); CertificateFactory cf = CertificateFactory.getInstance("X.509"); X509Certificate cert = (X509Certificate)cf.generateCertificate(inStream); inStream.close(); 

@author Hemma Prafullchandra @version 1.2127 @see Certificate @see CertificateFactory @see X509Extension

Gets the certificate constraints path length from the critical BasicConstraints extension (OID = 2.5.29.19).

The basic constraints extension identifies whether the subject of the certificate is a Certificate Authority (CA) and how deep a certification path may exist through that CA. The pathLenConstraint field (see below) is meaningful only if cA is set to TRUE. In this case it gives the maximum number of CA certificates that may follow this certificate in a certification path. A value of zero indicates that only an end-entity certificate may follow in the path.

Note that for the PKIXRFC profile2459 this extension is always marked critical if cA is TRUE meaning this certificate belongs to a Certificate Authority.

The ASN.1 definition for this is:

 BasicConstraints ::= SEQUENCE { cA BOOLEAN DEFAULT FALSE pathLenConstraint INTEGER (0..MAX) OPTIONAL } 

@return the lengthvalue of the constraintpathLenConstraint if the BasicConstraints extension is present in the certificate and the cAsubject valueof the certificate is TRUE.a Otherwise returnsCA otherwise -1. If the subject of the certificate is a CA and pathLenConstraint does not appear Integer.MAX_VALUE is returned to indicate that there is no limit to the allowed length of the certification path.

Gets the issuerUniqueID value from the certificate. The issuer unique identifier is present in the certificate to handle the possibility of reuse of issuer names over time. The PKIX PartRFC I2459 recommends that names not be reused and that conforming certificates not make use of unique identifiers. Applications conforming to that profile should be capable of parsing unique identifiers and making comparisons.

The ASN.1 definition for this is:

 issuerUniqueID [1] IMPLICIT UniqueIdentifier OPTIONAL
 UniqueIdentifier ::= BIT STRING 

@return the issuer unique identifier or null if it is not present in the certificate.

Gets a boolean array representing bits of the KeyUsage extension (OID = 2.5.29.15). The key usage extension defines the purpose (e.g. encipherment signature certificate signing) of the key contained in the certificate. The ASN.1 definition for this is:

 KeyUsage ::= BIT STRING { digitalSignature (0) nonRepudiation (1) keyEncipherment (2) dataEncipherment (3) keyAgreement (4) keyCertSign (5) cRLSign (6) encipherOnly (7) decipherOnly (8) } 

The PKIX part IRFC draft2459 recommends that when used this be marked as a critical extension. @return the bitKeyUsage valuesextension of thethis KeyUsage extensioncertificate represented as an array of booleans. or nullThe order ifof KeyUsage values in the array is the same as in the above ASN.1 definition. The array will contain a value for each KeyUsage defined above. If the KeyUsage extensionlist encoded in the certificate is longer than the above list it will not presentbe intruncated. theReturns null if this certificate does not contain a KeyUsage extension.

Gets the notAfter date from the validity period of the certificate. See getNotBefore()#getNotBefore for relevant ASN.1 definitions. @return the end date of the validity period. @see #checkValidity

Gets the signature algorithm OID string from the certificate. An OID is represented by a set of positive whole numbers separated by periods. For example the string "1.2.840.10040.4.3" identifies the SHA-1 with DSA signature algorithm as per the PKIXRFC part I2459.

See getSigAlgName()#getSigAlgName for relevant ASN.1 definitions. @return the signature algorithm OID string.

Gets the DER-encoded signature algorithm parameters from this certificate's signature algorithm. In most cases the signature algorithm parameters are null; the parameters are usually supplied with the certificate's public key. If access to individual parameter values is needed then use java.security.AlgorithmParameters#AlgorithmParameters and instantiate with the name returned by getSigAlgName()#getSigAlgName

See getSigAlgName()#getSigAlgName for relevant ASN.1 definitions. @return the DER-encoded signature algorithm parameters or null if no parameters are present.

Gets the subject (subject distinguished name) value from the certificate. The ASN.1 definition for this is:

 subject Name 

See getIssuerDN()#getIssuerDN for Name and other relevant definitions. @return a Principal whose name is the subject name.

Interface for an X.509 extension.

The extensions defined for X.509 v3 Certificates and v2 CRLs (Certificate Revocation Lists) provide methods for associating additional attributes with users or public keys for managing the certification hierarchy and for managing CRL distribution. The X.509 extensions format also allows communities to define private extensions to carry information unique to those communities.

Each extension in a certificate/CRL may be designated as critical or non-critical. A certificate/CRL-using system (an application validating a certificate/CRL) must reject the certificate/CRL if it encounters a critical extension it does not recognize. A non-critical extension may be ignored if it is not recognized.

The ASN.1 definition for this is:

 Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension Extension ::= SEQUENCE { extnId OBJECT IDENTIFIER critical BOOLEAN DEFAULT FALSE extnValue OCTET STRING -- contains a DER encoding of a value -- of the type registered for use with -- the extnId object identifier value } 

Since not all extensions are known the getExtensionValue method returns the DER-encoded OCTET STRING of the extension value (i.e. the extnValue). This can then be handled by a Class that understands the extension. @author Hemma Prafullchandra @version 1.13 9816 00/1202/0302

ReturnCheck if there is a critical extension that is not supported. @return true if a critical extension is found that is not supported otherwise return false.