iaik.x509
Class X509Certificate

java.lang.Object
  |
  +--java.security.cert.Certificate
        |
        +--java.security.cert.X509Certificate
              |
              +--iaik.x509.X509Certificate

public class X509Certificate

extends X509Certificate

implements ASN1Type, java.io.Serializable

This class represents a X.509 version 3 certificate, as specified by ISO/IEC and ANSI X9.

A certificate can be imagined as some kind of "digital identity card" attesting that a particular public key belongs to a particular entity. Certificates have a limited period of validity and are digitally signed by some trusted authority. Certificates can be verified by anyone having access to the signing authority´s public key. Each certification authority has to take care to label every handled certificate with a unique serial number for unequivocally identifying it. Certification authorities also have to maintain certification revocation lists of certificates that heve been expired for some reason and are no longer valid. Certification authorities (CAs) are organized in some tree-like structures, where certification authorities also are used for certifying other certification authorities. The certifcation authority being located at the highest level of such a tree, is called top-level or root certification authority and self-signs its public key with its own private key. Publicly available certification policies specify guidelines that may be referred by some entity for querying for the strategy a particular CA may follow for issuing and verifying certificates. Certification policy publishing CAs are called Policy Certification Authorities (PCAs) and prescribe the minimal policy requirements for all CAs located below in the CA-tree.

ITU-T X.509 defines a standard certificate format to be used along with the X.500 naming tree conventions. The first version has been published as X509v1 format in 1988, and has been extended in 1993 by version 2 about two fields for uniquely identifying certificate subject and issuer.

The X.509v3 certificate format extends its predecessor v2 format about the extensions field for including some additional information (see PKIX internet draft draft-ietf-pkix-ipki-part1-07.txt). An extension may be a defined standard extension (e.g. certificatePolicies, keyUsage, ...), or it may be a private extension providing some community-specific information. If an extension is marked as critical, but the certificate handling software cannot parse this extension, the appertaining certifcate has to be rejected. Non-Critical extensions can be ignored, if they cannot be handled (i.e. of unknown state).

X.509 certificates are described platform-independently by using the Abstract Syntax Notation One (ASN.1) language (defined in the ITU-T X.208 standard). X.509 ASN.1 structures are encoded according to the Distinguished Encoding Rules (DER). The X.509v3 certificate format is defined as an ASN.1 SEQUENCE structure containing the following components:

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

where signatureAlgorithm identifies the signature algorithm used by the signing certification authority for computing the digital signature upon the ASN.1 DER encoded TBSCertificate structure, which itself is expressed as ASN.1 SEQUENCE structure specifying the (distinguished) names of subject and issuer, the public key of the subject, validity period, signature algorithm (the same as specified in Certificate above), version and serial numbers, and optionally unique identifiers for subject and issuer:

 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        }
 

where:

 Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
 

 CertificateSerialNumber  ::=  INTEGER   
 

 AlgorithmIdentifier  ::=  SEQUENCE  {
   algorithm               OBJECT IDENTIFIER,
   parameters              ANY DEFINED BY algorithm OPTIONAL  }
 

 Name ::= CHOICE {     RDNSequence }
 

 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
 

 RelativeDistinguishedName ::=     SET OF AttributeTypeAndValue
 

 AttributeTypeAndValue ::= SEQUENCE {     
   type     AttributeType,
   value    AttributeValue }   
 

 AttributeType ::= OBJECT IDENTIFIER
 

 AttributeValue ::= ANY   -- Directory string type --
 

 DirectoryString ::= CHOICE {
    teletexString           TeletexString (SIZE (1..maxSize),
    printableString         PrintableString (SIZE (1..maxSize)),
    universalString         UniversalString (SIZE (1..maxSize)),
    bmpString               BMPString (SIZE(1..maxSIZE))
 }
 

 Validity ::= SEQUENCE {
   notBefore      Time,
   notAfter       Time }   
 

 Time ::= CHOICE {
   utcTime        UTCTime,
   generalTime    GeneralizedTime }
 
      
 UniqueIdentifier  ::=  BIT STRING 
 

 SubjectPublicKeyInfo  ::=  SEQUENCE  {
   algorithm            AlgorithmIdentifier,
   subjectPublicKey     BIT STRING  }
 
      
 Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension
 

 Extension  ::=  SEQUENCE  {        
   extnID      OBJECT IDENTIFIER,
   critical    BOOLEAN DEFAULT FALSE, 
   extnValue   OCTET STRING  }
 

For a detailled description of the several fields refer to PKIX internet draft draft-ietf-pkix-ipki-part1-07.txt.

For each value extists a set<Value> and a get<Value> method. After creating a X509Certificate, the, for instance, validity period may be set to, e.g. 6 month counting from the current date, by using the setValidNotBefore and setValidNotAfter methods:

 X509Certificate X509cert = new X509Certificate();
 GregorianCalendar date = (GregorianCalendar)Calendar.getInstance();
 X509cert.setValidNotBefore(date.getTime());                    
 date.add(Calendar.MONTH, 6);
 X509cert.setValidNotAfter(date.getTime());
 

Manipulating the extensions of a certificate is described in class X509Extensions. For adding some extension to a X509Certificate use the addExtension(V3Extension e) method, e.g:

 BasicConstraints basicConstraints = new BasicConstraints(false);
 X509cert.addExtension(basicConstraints);
 

After creating a new certificate by means of the default constructor, setting issuer and subject names, specifying the subject´s public key, setting validity period and serial number, and adding any extension to be included, finally sign the certificate with the private key of the issuer.

The X509Certificate(byte[]) and X509Certificate(InputStream) constructors may be used for parsing an X509Certificate from its DER encoding.

See Also:

X509Extensions, V3Extension, UnknownExtension, X509CRL, RevokedCertificate, Certificate, X509Certificate, Serialized Form

Constructor Summary

X509Certificate()
Default constructor for creating a new empty X509 certificate.

X509Certificate(byte[] array)
Creates a X509Certificate form a PEM or DER byte array.

X509Certificate(java.io.InputStream is)
Creates a X509Certificate from an input stream.

Method Summary

void	addExtension(V3Extension e) Adds the given X509v3 extension.
void	checkValidity() Checks if this certificate currently is valid.
void	checkValidity(java.util.Date date) Checks if this certificate would be valid at the given date value.
int	countExtensions() Returns the number of extensions included into this certificate.
void	decode(ASN1Object obj) Creates a X509Certificate from an ASN1Object.
void	decode(java.io.InputStream is) Decodes a X509Certificate from an inputstream.
int	getBasicConstraints() Returns the pathLenConstraint value of the BasicConstraints extension, if included in this certificate.
java.util.Set	getCriticalExtensionOIDs() Returns a Set of the OID strings identifying the extension(s) that are marked CRITICAL in this certificate.
byte[]	getEncoded() Returns this X509 certificate as DER encoded ASN.1 data structure
V3Extension	getExtension(ObjectID oid) Returns a specific extension, identified by its object identifier.
byte[]	getExtensionValue(java.lang.String oid) Returns a byte array representing the DER encoding of the extension value identified by the passed-in OID string.
byte[]	getFingerprint() Returns the fingerprint of this certificate.
Principal	getIssuerDN() Returns the Distinguished Name of the issuer of this certificate, as Principal.
boolean[]	getIssuerUniqueID() Returns the issuer unique identifier of this certificate, or null if no IssuerUniqueID is specified by this certificate.
boolean[]	getKeyUsage() Returns the bits representing the getKeyUsage extension, if included in this certificate.
java.util.Set	getNonCriticalExtensionOIDs() Returns a Set of the OID strings for the extension(s) marked NON-CRITICAL in this certificate.
java.util.Date	getNotAfter() Returns the notAfter date of this certificate.
java.util.Date	getNotBefore() Returns the notBefore date of this certificate.
PublicKey	getPublicKey() Returns the public key of this certificate.
java.math.BigInteger	getSerialNumber() Returns the serial number of this certificate as BigInteger.
java.lang.String	getSigAlgName() Returns the name of the signature algorithm used by the issuer for signing this certificate.
java.lang.String	getSigAlgOID() Returns the OID of the signature algorithm used by the issuer for signing this certificate.
byte[]	getSigAlgParams() Returns the algorithm parameters associated with the signature algorithm used by the issuer for signing this certificate.
byte[]	getSignature() Returns the signature of this certificate.
AlgorithmID	getSignatureAlgorithm() Returns the signature algorithm of this certificate.
Principal	getSubjectDN() Returns the Distinguished Name of the subject of this certificate, as Principal.
boolean[]	getSubjectUniqueID() Returns the subject unique identifier of this certificate, or null if no SubjectUniqueID is specified by this certificate.
byte[]	getTBSCertificate() Returns the DER encoded TBSCertificate ASN.1 data structure specifying all subject and issuer related information.
int	getVersion() Returns the version number of this certificate as int.
boolean	hasExtensions() Checks, if there are any extensions included into this certificate.
boolean	hasUnsupportedCriticalExtension() Returns true if there are unsupported critical extensions.
java.util.Enumeration	listExtensions() Returns an enumeration of all extensions included into this certificate.
void	removeAllExtensions() Removes all extensions from this certificate.
boolean	removeExtension(ObjectID oid) Removes the extension specified by its object identifier.
void	setIssuerDN(Principal issuer) Sets the issuer of this certificate.
void	setIssuerUniqueID(boolean[] id) Sets the issuer unique ID for this certificate.
void	setPublicKey(PublicKey publicKey) Sets the public key of this certificate.
void	setSerialNumber(java.math.BigInteger serialNumber) Sets the serial number of this certificate.
void	setSignatureAlgorithm(AlgorithmID signatureAlg) Sets the signature algorithm to be used for signing.
void	setSubjectDN(Principal subject) Sets the subject of this certificate.
void	setSubjectUniqueID(boolean[] id) Sets the subject unique ID for this certificate.
void	setValidNotAfter(java.util.Date validNotAfter) Sets the notAfter date of this certificate.
void	setValidNotBefore(java.util.Date validNotBefore) Sets the notBefore date of this certificate.
void	sign(AlgorithmID signatureAlg, PrivateKey issuerPK) Signs the certificate with the private key of the issuer.
ASN1Object	toASN1Object() Returns the certificate as an ASN1Object.
byte[]	toByteArray() Returns the certificate as DER encoded ASN.1 data structure.
java.lang.String	toString() Returns a string that represents the contents of the certificate.
java.lang.String	toString(boolean detailed) Returns a string that represents the contents of the certificate.
void	verify() Verifies a self signed certificate.
void	verify(DSAPublicKey key, DSAParameterSpec dsaParams) Uses the given public DSA key and DSA parameters to verify this certificate.
void	verify(PublicKey key) Verifies a certificate using the given public key.
void	verify(PublicKey key, java.lang.String sigProvider) Uses the given public key to verify a certificate based on a signature algorithm supplied by the specified provider.
void	writeTo(java.io.OutputStream os) Writes the certificate DER encoded to the given output stream.

Methods inherited from class java.security.cert.Certificate

equals, getType, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

X509Certificate

public X509Certificate(java.io.InputStream is)
                throws java.io.IOException,
                       CertificateException

Creates a X509Certificate from an input stream.

The supplied certificate can be in PEM or DER format. This constructor reads a X509Certificate previously written with method writeTo(OutputStream).

For instance:

 InputStream fis = new FileInputStream("cert.der");
 X509Certificate cert = new X509Certificate(fis);
 fis.close();
 

Parameters:

is - InputStream from which to create the certificate

Throws:

java.io.IOException - if the certificate could not be read

CertificateException - if there is a problem with the certificate

X509Certificate

public X509Certificate(byte[] array)
                throws CertificateException

Creates a X509Certificate form a PEM or DER byte array.

This constructor may be used for parsing an already exisiting X509Certifcate ASN.1 object, supplied as DER encoded byte array, which may have been created by calling the toByteArray or the getEncoded method.

Parameters:

array - the byte array containing the DER encoded certificate

Throws:

CertificateException - if the format of the cert is wrong

X509Certificate

public X509Certificate()

Default constructor for creating a new empty X509 certificate.

Any value may be set using the corrseponding set<Value> method. The version number per default is set to 1 indicating a Version 1 certificate. When including subjectUniqueID or issuerUniqueID, the version automatically will be set to 2, and when adding an extension increased to 3.

Method Detail

decode

public void decode(ASN1Object obj)
            throws CodingException

Creates a X509Certificate from an ASN1Object.

The given ASN1Object represents an already existing X509Certificate which may have been created by calling the toASN1Object method.

Specified by:

decode in interface ASN1Type

Parameters:

obj - the ASN1Object which contains the certificate

Throws:

CodingException - if there is a problem when parsing the certificate

decode

public void decode(java.io.InputStream is)
            throws java.io.IOException,
                   CertificateException

Decodes a X509Certificate from an inputstream. The given inputstream supplies the certificate in DER or PEM encoded format. This method internally is called when creating a X509Certificate from an InputStream.

Parameters:

is - the InputStream from where the certificate should be read

Throws:

java.io.IOException - if something is wrong with the InputStream

CertificateException - if the certificate is not properly initialized, or data is missing, etc.

sign

public void sign(AlgorithmID signatureAlg,
                 PrivateKey issuerPK)
          throws CertificateException,
                 InvalidKeyException,
                 NoSuchAlgorithmException

Signs the certificate with the private key of the issuer. This method creates a PKCS#1 standard signature.

Parameters:

signatureAlg - the AlgorithmID of the signature algorithm

issuerPK - the private key of the issuer

Throws:

CertificateException - if the certificate could not be signed

InvalidKeyException - if the format of the key is wrong

NoSuchAlgorithmException - if there is no implementation for the specified algorithm

checkValidity

public void checkValidity(java.util.Date date)
                   throws CertificateExpiredException,
                          CertificateNotYetValidException

Checks if this certificate would be valid at the given date value. Certificates have a limited period of validity prescribed by the notBefore and notAfter Time values. This method just checks if the given date/time value lies between notBefore and notAfter and throws an exception if this does not come true.

Overrides:

checkValidity in class X509Certificate

Throws:

CertificateExpiredException - if the certificate alreay has expired or the validNotAfter date yet has not been set

CertificateNotYetValidException - if the certificate yet is not valid or the validNotBefore date yet has not been set

See Also:

checkValidity(java.util.Date)

checkValidity

public void checkValidity()
                   throws CertificateExpiredException,
                          CertificateNotYetValidException

Checks if this certificate currently is valid. Certificates have a limited period of validity prescribed by the notBefore and notAfter Time values:

 Validity ::= SEQUENCE {        
    notBefore      Time,        
    notAfter       Time }
 

 Time ::= CHOICE {        
    utcTime        UTCTime,
    generalTime    GeneralizedTime }
 

The X.509 Certificate and CRL Profile specified in the PKIX internet draft draft-ietf-pkix-ipki-part1-07.txt recommends to encode certificate validity dates through the year 2049 as UTCTime, and certificate validity dates in 2050 or later as GeneralizedTime.

The notBefore and notAfter time values can be set by using the setValidNotBefore and setValidNotAfter methods.

This checkValidity method only calls checkValidity(Date) with the current date to check if it lies between the two time values specified by notBefore and notAfter.

Overrides:

checkValidity in class X509Certificate

Throws:

CertificateExpiredException - if the certificate already has expired

CertificateNotYetValidException - if the certificate is yet not valid

See Also:

UTCTime, GeneralizedTime

getEncoded

public byte[] getEncoded()
                  throws CertificateEncodingException

Returns this X509 certificate as DER encoded ASN.1 data structure

Overrides:

getEncoded in class Certificate

Returns:

a byte array holding the DER encoded X509 certificate ASN.1 data structure

Throws:

CertificateEncodingException - if the certificate cannot be encoded correctly

getVersion

public int getVersion()

Returns the version number of this certificate as int. The version number may specify a v1, v2, or v3 certificate.

ASN.1 definition:

 Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
 

Overrides:

getVersion in class X509Certificate

Returns:

version number of the certificate as int, 1 for a v1 cert, 2 for a v2 cert, and 3 for a v3 cert

getSerialNumber

public java.math.BigInteger getSerialNumber()

Returns the serial number of this certificate as BigInteger. Certificates are labelled with serial numbers by the issuing certification authority for unequivocally identifying them:

ASN.1 definition:

 CertificateSerialNumber  ::=  INTEGER 
 

Overrides:

getSerialNumber in class X509Certificate

Returns:

the serial number of this certificate as BigInteger

getIssuerDN

public Principal getIssuerDN()

Returns the Distinguished Name of the issuer of this certificate, as Principal.

A Distinguished Name is used to specify a path within a X.500 directory information tree. A distinguished name is defined as a sequence of relative distinguished names:

 Name ::= CHOICE {     RDNSequence }
 

 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
 

 RelativeDistinguishedName ::=     SET OF AttributeTypeAndValue
 

 AttributeTypeAndValue ::= SEQUENCE {     
    type     AttributeType,
    value    AttributeValue } 
 

 AttributeType ::= OBJECT IDENTIFIER
 

 AttributeValue ::= ANY
 

The AttributeType generally will be of ASN.1 type DirectoryString which either may be a PrintableString, TeletexString, BMPString, or an UniversalString. A name may consist of, for instance, the following Attribute Type/Value "pairs" defining a path through a X.500 directory tree:

 country: "AT"
 locality: "Graz"
 organization: "TU Graz"
 organizationalUnit: "IAIK"
 commonName: "IAIK TestCA"
 

The issuer identity also may be specified by an issuerAltName extension (e.g. as an e-mail address). If the issuer identity only is specified by an issuerAltName extension, the issuer name field may be left an empty SEQUENCE and the issuerAltName extension has to be marked to be critical (see PKIX internet draft draft-ietf-pkix-ipki-part1-07.txt).

Overrides:

getIssuerDN in class X509Certificate

Returns:

the distinguished name of the issuer of this certificate as Principal

See Also:

Name, RDN

getSubjectDN

public Principal getSubjectDN()

Returns the Distinguished Name of the subject of this certificate, as Principal. The subject of the certificate is the entity the certificate belongs to.

A Distinguished Name is used to specify a path within a X.500 directory information tree. A distinguished name is defined as a sequence of relative distinguished names:

 Name ::= CHOICE {     RDNSequence }
 

 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
 

 RelativeDistinguishedName ::=     SET OF AttributeTypeAndValue
 

 AttributeTypeAndValue ::= SEQUENCE {     
    type     AttributeType,
    value    AttributeValue } 
 

 AttributeType ::= OBJECT IDENTIFIER
 

 AttributeValue ::= ANY
 

The AttributeType generally will be of ASN.1 type DirectoryString which either may be a PrintableString, TeletexString, BMPString, or an UniversalString. A name may consist of, for instance, the following Attribute Type/Value "pairs" defining a path through a X.500 directory tree:

 country: "AT"
 locality: "Graz"
 organization: "TU Graz"
 organizationalUnit: "IAIK"
 commonName: "TestUser"
 

The subject identity also may be specified by a subjectAltName extension (e.g. as an e-mail address). If the subject identity only is specified by an subjectAltName extension, the subject name field may be left an empty SEQUENCE and the subjectAltName extension has to be marked to be critical (see PKIX internet draft draft-ietf-pkix-ipki-part1-07.txt).

Overrides:

getSubjectDN in class X509Certificate

Returns:

the distinguished name of the subject of this certificate as Principal

See Also:

Name, RDN

getNotBefore

public java.util.Date getNotBefore()

Returns the notBefore date of this certificate.

The notBefore value denotes the date on which the certificate becomes valid and can be set using the setValidNotBefore method.

Overrides:

getNotBefore in class X509Certificate

Returns:

the date on which this certificate becomes valid, or null if the notBefore date has yet not been set

See Also:

checkValidity(java.util.Date)

getNotAfter

public java.util.Date getNotAfter()

Returns the notAfter date of this certificate.

The notAfter value denotes the date on which the certificate´s validity expires. The notAfter date can be set using the setValidNotAfter method.

Overrides:

getNotAfter in class X509Certificate

Returns:

the date on which the certificate´s validity expires, or null if the notAfter date has yet not been set

See Also:

checkValidity(java.util.Date)

getTBSCertificate

public byte[] getTBSCertificate()
                         throws CertificateEncodingException

Returns the DER encoded TBSCertificate ASN.1 data structure specifying all subject and issuer related information.

 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        }
 

Overrides:

getTBSCertificate in class X509Certificate

Returns:

the inherent TBSCertificate as DER encoded ASN.1 structure

Throws:

CertificateEncodingException - if an encoding error occurs

setSignatureAlgorithm

public void setSignatureAlgorithm(AlgorithmID signatureAlg)

Sets the signature algorithm to be used for signing. This method only provides a way for setting the signature algorithm if an application wants to call getTBSCertificate before signing the cert. When using this fearure an application itsself is responsible to ensure that the signature algorithm specified by this method is equal to that supplied to the sign(AlgorithmID, PrivateKey) method when finally signing the certificate.

Parameters:

signatureAlg - the signature algorithm to be used for signing

getSignature

public byte[] getSignature()

Returns the signature of this certificate. The signature is defined as an ASN.1 BIT STRING structure. This method returns the inherent signature value as byte array.

Overrides:

getSignature in class X509Certificate

Returns:

the signature value as byte array

getSigAlgName

public java.lang.String getSigAlgName()

Returns the name of the signature algorithm used by the issuer for signing this certificate.

Overrides:

getSigAlgName in class X509Certificate

Returns:

the name of the signature algorithm, e.g. "md5WithRSAEncryption", or null if the signature algorithm yet has not been set

getSigAlgOID

public java.lang.String getSigAlgOID()

Returns the OID of the signature algorithm used by the issuer for signing this certificate. An object identifier consists of a sequence of integer components and is used for identifying, e.g. the signature algorithm used for this certificate. This method returns the OID in String representation, e.g. "1.2.840.113549.1.1.4"

Overrides:

getSigAlgOID in class X509Certificate

Returns:

the OID of the signature algorithm as String representation, or null if the signature algorithm yet has not been set

See Also:

ObjectID, AlgorithmID

getSigAlgParams

public byte[] getSigAlgParams()

Returns the algorithm parameters associated with the signature algorithm used by the issuer for signing this certificate. The parameters are returned as DER encoded ASN.1 data structure.

Overrides:

getSigAlgParams in class X509Certificate

Returns:

the signature algorithm parameters as DER encoded ASN.1 data structure, or null if there are no parameters used or the signature algorithm yet has been not set

getIssuerUniqueID

public boolean[] getIssuerUniqueID()

Returns the issuer unique identifier of this certificate, or null if no IssuerUniqueID is specified by this certificate. Together with the SubjectUniqueID the issuer unique identifier field has been introduced by the X.509v2 certificate format for providing the possibility of reusing subject and/or issuer names over time. The PKIX internet draft draft-ietf-pkix-ipki-part1-07.txt recommends that names should not be reused and that Internet certificates should not use unique identifiers. Issuer and subject unique identifiers are defined as ASN.1 BIT STRING structure:

UniqueIdentifier ::= BIT STRING

This method scans the issuer unique identifier and returns it as an array of boolean values.

Overrides:

getIssuerUniqueID in class X509Certificate

Returns:

the IssuerUniqueID of this certificate as array of booleans, or null if no issuer unique identifier is speciifed

getSubjectUniqueID

public boolean[] getSubjectUniqueID()

Returns the subject unique identifier of this certificate, or null if no SubjectUniqueID is specified by this certificate. Together with the IssuerUniqueID the subject unique identifier field has been introduced by the X.509v2 certificate format for providing the possibility of reusing issuer and/or subject names over time. The PKIX internet draft draft-ietf-pkix-ipki-part1-07.txt recommends that names should not be reused and that Internet certificates should not use unique identifiers. Issuer and subject unique identifiers are defined as ASN.1 BIT STRING structure:

UniqueIdentifier ::= BIT STRING

This method scans the subject unique identifier and returns it as an array of boolean values.

Overrides:

getSubjectUniqueID in class X509Certificate

Returns:

the SubjectUniqueID of this certificate as array of booleans, or null if no subject unique identifier is speciifed

getKeyUsage

public boolean[] getKeyUsage()

Returns the bits representing the getKeyUsage extension, if included in this certificate.

The KeyUsage extension is a standard extension and defines the purpose (e.g., encipherment, signature, certificate signing) of the key contained in this certificate.

The PKIX internet draft draft-ietf-pkix-ipki-part1-07.txt recommends that when using this extension, it should be marked as being a critical one.

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

The bits representing the KeyUsage extension are returned as an array of boolean values.

Overrides:

getKeyUsage in class X509Certificate

Returns:

an array of boolean values representing the bits of the KeyUsage extension, or null if this extension included in this certificate.

getBasicConstraints

public int getBasicConstraints()

Returns the pathLenConstraint value of the BasicConstraints extension, if included in this certificate. The BasicConstraints extension is a standard extension specifying whether the subject of this certificate is a CA and how deep a certification path may exist through that CA.

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

The pathLenConstraint field 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.

If the pathLenConstraint value is set, it has to be greater than or equal to zero. If it is not set, the certification path may be of any length.

The PKIX internet draft draft-ietf-pkix-ipki-part1-07.txt recommends to use the BasicConstraint extension, which always should be marked as being critical for CA certificates (cA is set to TRUE).

Overrides:

getBasicConstraints in class X509Certificate

Returns:

the pathLenConstraint value, specifying the maximum number of CA certificates that may follow this certificate in a certification path if the BasicConstraint extension is included in this certitifcate and cA (true) and pathLenConstraint values are set; if only the cA value is set to true, but the pathLenConstraint value is not specified, this method returns -1 indicating that the certification path may have any length; if the the BasicConstraint extension is not included into this certificate, this method also returns -1

verify

public void verify()
            throws CertificateException,
                   NoSuchAlgorithmException,
                   InvalidKeyException,
                   NoSuchProviderException,
                   SignatureException

Verifies a self signed certificate.

This method only calls verify(PublicKey) with the public key certified by this certificate. Since this certificate would be a self-signed certificate, issuer and subject would be the same entities.

Throws:

CertificateException - if the certificate could not be verified

NoSuchAlgorithmException - if there is no implementation for the algorithm used to sign this cert

InvalidKeyException - if the format of the public key is wrong

NoSuchProviderException - if there is no such provider

SignatureException - if the signature not verifies

verify

public void verify(PublicKey key,
                   java.lang.String sigProvider)
            throws CertificateException,
                   NoSuchAlgorithmException,
                   InvalidKeyException,
                   NoSuchProviderException,
                   SignatureException

Uses the given public key to verify a certificate based on a signature algorithm supplied by the specified provider.

Overrides:

verify in class Certificate

Parameters:

key - the public key (of the issuer) to verify the cert

sigProvider - the name of the provider supplying the signature algorithm

Throws:

CertificateException - if the certificate could not be verified

NoSuchAlgorithmException - if there is no implementation for the algorithm used to sign this cert

InvalidKeyException - if the format of the public key is wrong

NoSuchProviderException - if there is no such provider

SignatureException - if the signature not verifies

verify

public void verify(PublicKey key)
            throws CertificateException,
                   NoSuchAlgorithmException,
                   InvalidKeyException,
                   NoSuchProviderException,
                   SignatureException

Verifies a certificate using the given public key.

This method only calls verify(PublicKey, String) setting the provider name to null for relying on the default provider signature architecture.

Overrides:

verify in class Certificate

Parameters:

key - the public key of the issuer

Throws:

CertificateException - if the certificate could not be verified

NoSuchAlgorithmException - if there is no implementation for the algorithm used to sign this cert

InvalidKeyException - if the format of the public key is wrong

NoSuchProviderException - if there is no default provider

SignatureException - if the signature not verifies

verify

public void verify(DSAPublicKey key,
                   DSAParameterSpec dsaParams)
            throws CertificateException,
                   NoSuchAlgorithmException,
                   InvalidKeyException,
                   NoSuchProviderException,
                   SignatureException

Uses the given public DSA key and DSA parameters to verify this certificate.

Attention! This method only may be used to verify a certificate that has been signed with the DSA algorithm and the public DSA key now used for verification does not contain the DSA parameters. Additionally this method only can be used with the IAIK provider.

Parameters:

key - the public DSA key (of the issuer) to verify the cert

dsaParams - the DSA parameters provided by other means

Throws:

CertificateException - if the certificate could not be verified

NoSuchAlgorithmException - if there is no implementation for the algorithm used to sign this cert

InvalidKeyException - if the format of the public key is wrong

NoSuchProviderException - if there is no such provider

SignatureException - if the signature not verifies

toASN1Object

public ASN1Object toASN1Object()

Returns the certificate as an ASN1Object.

Specified by:

toASN1Object in interface ASN1Type

Returns:

the certificate as ASN1Object

toByteArray

public byte[] toByteArray()

Returns the certificate as DER encoded ASN.1 data structure. The DER format (Distinguished Encoding Rules) defines a binary representation of an abstract ASN.1 datastructure.

Returns:

the certificate in a byte array in DER format

writeTo

public void writeTo(java.io.OutputStream os)
             throws java.io.IOException

Writes the certificate DER encoded to the given output stream. For instance:

 try {
     OutputStream fos = new FileOutputStream("Cert.der");
     cert.writeTo(fos);
     fos.close();      
 } catch (IOException ex) {
        System.out.println("IOException: " + ex.getMessage());  
 } 
 

Parameters:

os - the output stream where the certifiacte shall be written to

Throws:

java.io.IOException - if an I/O error occurs

setSerialNumber

public void setSerialNumber(java.math.BigInteger serialNumber)

Sets the serial number of this certificate.

For instance:

 cert.setSerialNumber(BigInteger.valueOf(0x1234L));
 

Parameters:

serialNumber - the serial number of the certificate as BigInteger

See Also:

getSerialNumber()

setIssuerDN

public void setIssuerDN(Principal issuer)
                 throws java.lang.IllegalArgumentException

Sets the issuer of this certificate.

The issuer is the identity which signs the certificate. It is specified by its X.500 distinguished name.

For instance:

 Name issuer = new Name();
 issuer.addRDN(ObjectID.country, "AT");
 issuer.addRDN(ObjectID.organization ,"TU Graz");
 issuer.addRDN(ObjectID.organizationalUnit ,"IAIK");
 issuer.addRDN(ObjectID.commonName ,"IAIK Test CA");
 cert.setIssuerDN(issuer);
 

Parameters:

issuer - the Distinguished Name of issuer of the certificate

Throws:

java.lang.IllegalArgumentException - if the issuer is not an instance of name

See Also:

getIssuerDN()

setValidNotBefore

public void setValidNotBefore(java.util.Date validNotBefore)

Sets the notBefore date of this certificate.

For instance:

 GregorianCalendar date = (GregorianCalendar)Calendar.getInstance();
 cert.setValidNotBefore(date.getTime());   
 

The certificate is not valid before this Date.

Parameters:

validNotBefore - Date when cert will become valid

See Also:

getNotBefore()

setValidNotAfter

public void setValidNotAfter(java.util.Date validNotAfter)

Sets the notAfter date of this certificate.

For instance:

 GregorianCalendar date = (GregorianCalendar)Calendar.getInstance();
 date.add(Calendar.MONTH, 6);
 cert.setValidNotAfter(date.getTime());   
 

The certificate will expire at this Date.

Parameters:

validNotAfter - Date on which the certificate will expire

See Also:

getNotAfter()

setSubjectDN

public void setSubjectDN(Principal subject)
                  throws java.lang.IllegalArgumentException

Sets the subject of this certificate.

For instance:

 Name subject = new Name();
 subject.addRDN(ObjectID.country, "AT");
 subject.addRDN(ObjectID.organization ,"IAIK");
 subject.addRDN(ObjectID.emailAddress ,"user@iaik.tu-graz.ac.at");
 subject.addRDN(ObjectID.commonName ,"Test User");
 cert.setSubjectDN(subject);
 

The subject is the entity claiming for certification of its public key.

Parameters:

subject - the Distinguished Name of the subject of the certificate

Throws:

java.lang.IllegalArgumentException - if the subject is not an instance of name

See Also:

getSubjectDN()

setPublicKey

public void setPublicKey(PublicKey publicKey)
                  throws InvalidKeyException

Sets the public key of this certificate.

Parameters:

publicKey - the public key of the subject

Throws:

InvalidKeyException - if the public key has an invalid encoding

See Also:

getPublicKey()

setIssuerUniqueID

public void setIssuerUniqueID(boolean[] id)

Sets the issuer unique ID for this certificate.

Parameters:

id - the unique identifier of the issuer as array of boolean values

See Also:

getIssuerUniqueID()

setSubjectUniqueID

public void setSubjectUniqueID(boolean[] id)

Sets the subject unique ID for this certificate.

Parameters:

id - the unique identifier of the subject as array of boolean values

See Also:

getSubjectUniqueID()

getSignatureAlgorithm

public AlgorithmID getSignatureAlgorithm()

Returns the signature algorithm of this certificate.

Returns:

the AlgorithmID of the signature algorithm used for signing this certificate

See Also:

AlgorithmID

getPublicKey

public PublicKey getPublicKey()

Returns the public key of this certificate. This is the public key which belongs to the subject of the certificate.

Overrides:

getPublicKey in class Certificate

Returns:

the public key of the certificate

getFingerprint

public byte[] getFingerprint()

Returns the fingerprint of this certificate. This is a MD5 hash of the DER encoded certificate.

Returns:

the fingerprint of the certificate

toString

public java.lang.String toString()

Returns a string that represents the contents of the certificate.

Overrides:

toString in class Certificate

Returns:

the string representation

getCriticalExtensionOIDs

public java.util.Set getCriticalExtensionOIDs()

Returns a Set of the OID strings identifying the extension(s) that are marked CRITICAL in this certificate. Extensions can be marked as being critical. If the certificate handling software cannot parse such an extension, the appertaining certifcate has to be rejected. Non-Critical extensions can be ignored, if they cannot be handled (i.e. of unknown state).

Returns:

a Set (or an empty Set if none are marked critical) of the extension OID strings for extensions that are marked critical. If there are no extensions present at all, then this method returns null

See Also:

getNonCriticalExtensionOIDs()

getNonCriticalExtensionOIDs

public java.util.Set getNonCriticalExtensionOIDs()

Returns a Set of the OID strings for the extension(s) marked NON-CRITICAL in this certificate.

Returns:

a Set (or an empty Set if none are marked non-critical) of the extension OID strings for extensions that are marked non-critical. If there are no extensions present at all, then this method returns null.

See Also:

getCriticalExtensionOIDs()

getExtensionValue

public byte[] getExtensionValue(java.lang.String oid)

Returns a byte array representing the DER encoding of the extension value identified by the passed-in OID string.

The oid string is represented by a set of positive whole numbers separated by periods, e.g. "2.5.29.15" for the KeyUsage extension.

In ASN.1, the Extensions field is defined as a SEQUENCE of Extension:

 Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension
 

 Extension  ::=  SEQUENCE  {        
   extnID      OBJECT IDENTIFIER,
   critical    BOOLEAN DEFAULT FALSE, 
   extnValue   OCTET STRING  }
 

where critical specifies whether an extension has to be treated as being critical or not; the default value is FALSE. An extension can be identified by its object identifier, given in the extnID field. The value of the extension is represented as ASN.1 OCTET STRING data structure in the extnValue field. Only one instance of a particular extension may be present in a particular certificate.

Attention! The byte value returned by this method does not represent the DER encoding of the extnValue (OCTET_STRING) from above; rather it represents the DER encoding of the specific extension´s ASN.1 representation itsself. So, for example, when asking for a BasicConstraints extension, the corresponding DER encoded ASN.1 Sequence value will be returned:

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

Parameters:

oid - the Object Identifier of the extension to be queried for

Returns:

the DER encoded ASN.1 representation of extension value or null if it is not present

addExtension

public void addExtension(V3Extension e)
                  throws X509ExtensionException

Adds the given X509v3 extension.

The extension to be added shall be an implemented V3Extension. Extensions are managed by the X509Extensions class which maintaines two hashtables, one for recording critical extensions, and the other for non-critical extensions. This method only calls the addExtension method of the X509Extensions class for putting the given extension into the proper hashtable. Note that only the DER encoded extension value is written to the hashtable using the OID of the extension as key. If an extension with the same object ID already exists, it is replaced.

For instance:

 BasicConstraints bc = new BasicConstraints(true, 1);
 bc.setCritical(true);
 cert.addExtension(bc);
 

For reading back some extension from one of the hashtables, use the getExtension(ObjectID) method. Only at this time actually the appropriate implementation class is created and initialized through the DER encoded extension value derived from the corresponding hashtable.

Parameters:

e - the X509v3 extension to add to the list of extensions

Throws:

X509ExtensionException - if an error occurs while DER encoding the extension

See Also:

V3Extension, getBasicConstraints()

removeExtension

public boolean removeExtension(ObjectID oid)

Removes the extension specified by its object identifier.

Parameters:

objectID - the object ID of the extension to remove

Returns:

true if the extension has been successfully removed, false otherwise

removeAllExtensions

public void removeAllExtensions()

Removes all extensions from this certificate.

listExtensions

public java.util.Enumeration listExtensions()

Returns an enumeration of all extensions included into this certificate.

The returned enumeration may contain unknown extensions (instances of UnknownExtension if there are any extensions included in this certificate, for which there exists no registered implementation, and it may contain error extensions (instances of ErrorExtension) indicating extensions which cannot be parsed properly because of some kind of error.

Notice that this method only calls the listExtensions() method of the X509Extensions class for actually instantiating implementations for the included extensions and initializing them with the appertaining extension values previously written to proper hashtables. If any extension cannot be parsed properly, an ErrorExtension is created from it and written to the enumeration list returned by this method.

Returns:

an enumeration of the extensions, or null if there are no extensions present at all

hasExtensions

public boolean hasExtensions()

Checks, if there are any extensions included into this certificate.

Returns:

true if there are extensions, false if not

hasUnsupportedCriticalExtension

public boolean hasUnsupportedCriticalExtension()

Returns true if there are unsupported critical extensions.

Returns:

true, if there are unsupported critical extensions

countExtensions

public int countExtensions()

Returns the number of extensions included into this certificate.

Returns:

the number of extensions

getExtension

public V3Extension getExtension(ObjectID oid)
                         throws X509ExtensionInitException

Returns a specific extension, identified by its object identifier.

This method only calls the getExtension(ObjectID) method of the X509Extensions class for actually instantiating an implementation for the requested extension and initializing it with the appertaining extension value previously written to a proper hashtable. If the extension cannot be initialized for some reason, an X509ExtensionInitException is thrown. If the requested extension is an unknown extension, which is not supported by a registered implementation, this method creates and returns an UnknownExtension which may be queried for obtaining as much information as possible about the unknown extension.

Parameters:

objectID - the object ID of the extension

Returns:

the desired extension or null if the requested extension is not present

Throws:

X509ExtensionInitException - if the extension can not be initialized

See Also:

X509Extensions.getExtension(iaik.asn1.ObjectID)

toString

public java.lang.String toString(boolean detailed)

Returns a string that represents the contents of the certificate.

Parameters:

detailed - whether or not to give detailed information about the certificate.

Returns:

the string representation