Generated by
JDiff

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.

Class CRL

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.9 0210 12/0203/0001 @see X509CRL @see CertificateFactory @since 1.2


Class CRLException

CRL (Certificate Revocation List) Exception. @author Hemma Prafullchandra 1.68

Class Certificate

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.18 0020 01/0212/0203


Class Certificate.CertificateRep, Object readResolve()

Resolve the Certificate Object.

@return the resolved Certificate Object. @throws java.io.ObjectStreamException if the Certificate could not be resolved.


Class Certificate, Object writeReplace()

Replace the Certificate to be serialized. @return the alternate Certificate object to be serialized. @throws java.io.ObjectStreamException if a new object representing this certificateCertificate could not be created

Class CertificateEncodingException

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

Class CertificateException

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

Class CertificateExpiredException

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

Class CertificateFactory

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

For encodings consisting of multiple certificates use generateCertificates when you want to parse a collection of possibly unrelated certificates. Otherwise use generateCertPath when you want to generate a CertPath (a certificate chain) and subsequently validate it with a CertPathValidator.

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 ByteArrayInputStreamBufferedInputStream (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); DataInputStreamBufferedInputStream disbis = new DataInputStreamBufferedInputStream(fis); CertificateFactory cf = CertificateFactory.getInstance("X.509"); byte[] bytes = new byte[dis.available()]; dis.readFully(bytes); ByteArrayInputStream bais = new ByteArrayInputStream(bytes); while (baisbis.available() > 0) { Certificate cert = cf.generateCertificate(baisbis); 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 @author Sean Mullan @version 1.15 0223 12/0203/0001 @see Certificate @see X509Certificate @see CertPath @see CRL @see X509CRL @since 1.2
Class CertificateFactory, CRL generateCRL(InputStream)

Generates a certificate revocation list (CRL) object and initializes it with the data read from the input stream inStream.

In order to take advantage of the specialized CRL format supported by this certificate factory the returned CRL object can be typecast to the corresponding CRL class. For example if this certificate factory implements X.509 CRLs the returned CRL object can be typecast to the X509CRL class.

Note that if the given input stream does not support mark and reset this method will consume the entire input stream. Otherwise each call to this method consumes one CRL and the read position of the input stream is positioned to the next available byte after the the inherent end-of-CRL marker. If the data in the input stream does not contain an inherent end-of-CRL marker (other than EOF) and there is trailing data after the CRL is parsed a CRLException is thrown. @param inStream an input stream with the CRL data. @return a CRL object initialized with the data from the input stream. @exception CRLException on parsing errors.

Class CertificateFactory, Certificate generateCertificate(InputStream)

Generates a certificate object and initializes it with the data read from the input stream inStream.

The given input stream inStream must contain a single certificate. In order to take advantage of the specialized certificate format supported by this certificate factory the returned certificate object can be typecast to the corresponding certificate class. For example if this certificate factory implements X.509 certificates the returned certificate object can be typecast to the X509Certificate class.

In the case of a certificate factory for X.509 certificates the certificate provided in inStream must be DER-encoded and may be supplied in binary or printable (Base64) encoding. If the certificate is provided in Base64 encoding it must be bounded at the beginning by -----BEGIN CERTIFICATE----- and must be bounded at the end by -----END CERTIFICATE-----.

Note that if the given input stream does not support mark and reset this method will consume the entire input stream. Otherwise each call to this method consumes one certificate and the read position of the input stream is positioned to the next available byte after the inherent end-of-certificate marker. If the data in the input stream does not contain an inherent end-of-certificate marker (other than EOF) and there is trailing data after the certificate is parsed a CertificateException is thrown. @param inStream an input stream with the certificate data. @return a certificate object initialized with the data from the input stream. @exception CertificateException on parsing errors.


Class CertificateFactorySpi

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 certification path (CertPath) and certificate revocation list (CRL) objects from their encodingencodings.

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 @author Sean Mullan @version 1.9 0214 12/0203/0001 @see CertificateFactory @see Certificate @see X509Certificate @see CertPath @see CRL @see X509CRL @since 1.2

Class CertificateFactorySpi, CRL engineGenerateCRL(InputStream)

Generates a certificate revocation list (CRL) object and initializes it with the data read from the input stream inStream.

In order to take advantage of the specialized CRL format supported by this certificate factory the returned CRL object can be typecast to the corresponding CRL class. For example if this certificate factory implements X.509 CRLs the returned CRL object can be typecast to the X509CRL class.

Note that if the given input stream does not support mark and reset this method will consume the entire input stream. Otherwise each call to this method consumes one CRL and the read position of the input stream is positioned to the next available byte after the the inherent end-of-CRL marker. If the data in the input stream does not contain an inherent end-of-CRL marker (other than EOF) and there is trailing data after the CRL is parsed a CRLException is thrown. @param inStream an input stream with the CRL data. @return a CRL object initialized with the data from the input stream. @exception CRLException on parsing errors.

Class CertificateFactorySpi, Certificate engineGenerateCertificate(InputStream)

Generates a certificate object and initializes it with the data read from the input stream inStream.

The given input stream inStream must contain a single certificate. In order to take advantage of the specialized certificate format supported by this certificate factory the returned certificate object can be typecast to the corresponding certificate class. For example if this certificate factory implements X.509 certificates the returned certificate object can be typecast to the X509Certificate class.

In the case of a certificate factory for X.509 certificates the certificate provided in inStream must be DER-encoded and may be supplied in binary or printable (Base64) encoding. If the certificate is provided in Base64 encoding it must be bounded at the beginning by -----BEGIN CERTIFICATE----- and must be bounded at the end by -----END CERTIFICATE-----.

Note that if the given input stream does not support mark and reset this method will consume the entire input stream. Otherwise each call to this method consumes one certificate and the read position of the input stream is positioned to the next available byte after the the inherent end-of-certificate marker. If the data in the input stream does not contain an inherent end-of-certificate marker (other than EOF) and there is trailing data after the certificate is parsed a CertificateException is thrown. @param inStream an input stream with the certificate data. @return a certificate object initialized with the data from the input stream. @exception CertificateException on parsing errors.


Class CertificateNotYetValidException

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

Class CertificateParsingException

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

Class X509CRL

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 } 

More information can be found in RFC 2459 "Internet X.509 Public Key Infrastructure Certificate and CRL Profile" at http://www.ietf.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.1822 @see CRL @see CertificateFactory @see X509Extension
Class X509CRL, String getSigAlgOID()

Gets the signature algorithm OID string from the CRL. An OID is represented by a set of positivenonnegative 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 RFC 2459.

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


Class X509CRLEntry

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.12 0013 01/0212/0203

Class X509Certificate

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.

More information can be found in RFC 2459 "Internet X.509 Public Key Infrastructure Certificate and CRL Profile" at http://www.ietf.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.2733 @see Certificate @see CertificateFactory @see X509Extension
Class X509Certificate, String getSigAlgOID()

Gets the signature algorithm OID string from the certificate. An OID is represented by a set of positivenonnegative 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 RFC 2459.

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

Class X509Certificate, Principal getSubjectDN()

Gets the subject (subject distinguished name) value from the certificate. If the subject value is empty then the getName() method of the returned Principal object returns an empty string ("").

The ASN.1 definition for this is:

 subject Name 

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


Class X509Extension

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.16 0018 01/0212/0203
Class X509Extension, byte[] getExtensionValue(String)

Gets the DER-encoded OCTET string for the extension value (extnValue) identified by the passed-in oid String. The oid string is represented by a set of positivenonnegative whole numbers separated by periods.

For example:
OID (Object Identifier) Extension Name
2.5.29.14 SubjectKeyIdentifier
2.5.29.15 KeyUsage
2.5.29.16 PrivateKeyUsage
2.5.29.17 SubjectAlternativeName
2.5.29.18 IssuerAlternativeName
2.5.29.19 BasicConstraints
2.5.29.30 NameConstraints
2.5.29.33 PolicyMappings
2.5.29.35 AuthorityKeyIdentifier
2.5.29.36 PolicyConstraints
@param oid the Object Identifier value for the extension. @return the DER-encoded octet string of the extension value or null if it is not present.