iaik.pkcs.pkcs10
Class CertificateRequest

java.lang.Object
  |
  +--iaik.pkcs.pkcs10.CertificateRequest

All Implemented Interfaces:

CertRequest, Serializable

public class CertificateRequest

extends Object

implements Serializable, CertRequest

This class represents a CertificationRequest as described in PKCS#10.

PKCS#10 defines a certification request to consist of a version number, the subject´s distinguished name (where subject denotes the entity claiming for being certified), the subject´s public key (of type subjectPublicKeyInfo including a BIT-STRING representation of the public key together with an identification of the public-key algorithm being used) and an optional set of attributes providing some additional information of the subject entity, all together forming a CertificationRequestInfo value which is signed by the certificate requesting entity using some particular signature algorithm for attesting to being owner of the public key:

 CertificationRequest ::= SEQUENCE {
   certificationRequestInfo CertificationRequestInfo,
   signatureAlgorithm SignatureAlgorithmIdentifier,
   signature Signature  }
 

where:

 CertificationRequestInfo ::= SEQUENCE {
   version Version, -- INTEGER version number (0 for this version)
   subject Name, -- distinguished name of the entity claiming for certification
   subjectPublicKeyInfo SubjectPublicKeyInfo, -- information about the subject´s public key
   attributes [0] IMPLICIT Attributes -- additional information about the subject
 }

 

For creating a certification request to be sent to some certification authority, an application shall use a proper constructor - for instance by directly supplying the subjects´s public key and distinguished name - and subsequently sign the request thereby identifying the signature algorithm and supplying the private key used for signing, e.g:

 CertificateRequest cert_request = new CertificateRequest(public_key, subject_name);
 cert_request.sign(AlgorithmID.sha1WithRSAEncryption, private_key);
 

The certification authority responses a certification request by re-sending a message (e.g. PKCS#7 message) containing a X.509 public-key certificate or a PKCS#6 extended certificate created from the data received with the certification request. However, before actually fulfilling the request, the certifcation authority will proove the correctness of the entity´s digital signature according to its certification policy.

For verifying a self-signed certificate request an entity may use the verify method:

 if (cert_request.verify()) {
   // do something useful
 }
 

Version:

File Revision 31

See Also:

X509Certificate, PublicKeyInfo, Name, AlgorithmID, Serialized Form

Constructor Summary

CertificateRequest(byte[] arr)
Creates a CertificateRequest form a byte array.

CertificateRequest(InputStream is)
Creates a CertificateRequest form an input stream.

CertificateRequest(PublicKey publicKey, Name subject)
Creates a new CertificateRequest from a PublicKeyInfo and a Name.

Method Summary

void	addAttribute(Attribute attribute) Adds one Atribute to this CertificateRequest.
Attribute	getAttribute(ObjectID oid) Returns the first attribute matching to the given ObjectID, if included in this CertificateRequest.
Attribute[]	getAttributes() Gets the Atributes of this CertificateRequest.
Attribute[]	getAttributes(ObjectID type) Gets all the Atributes matching to a specific type (object identifier).
AttributeValue	getAttributeValue(ObjectID oid) Returns the attribute value of a single valued attribute with the given type.
byte[]	getCertificateRequestInfo() Returns the DER encoded CertificateRequestInfo ASN.1 data structure over which the signature is calculated: CertificationRequestInfo ::= SEQUENCE { version Version, -- version number subject Name, -- distinguished name of the entity requesting the certificate subjectPublicKeyInfo SubjectPublicKeyInfo, -- information about the public key to be certified attributes [0] IMPLICIT Attributes -- additional information about the subject }
byte[]	getFingerprint() Returns the fingerprint of this certificate request.
byte[]	getFingerprint(String digestAlgorithm) Returns the fingerprint of this certificate request calculated with the given hash algorithm.
byte[]	getFingerprintSHA() Get the SHA fingerprint of this certificate.
PublicKey	getPublicKey() Returns the public key of this certificate request.
AlgorithmID	getSignatureAlgorithmID() Returns the signature algorithm of this certificate request.
Name	getSubject() Returns the subject of this certificate request.
int	getVersion() Returns the version number of this certificate request.
void	setAttributes(Attribute[] attributes) Sets the Atributes for this CertificateRequest.
void	setSignature(AlgorithmID signatureAlgorithm, byte[] signatureValue) Sets the signature value of this certificate request.
void	sign(AlgorithmID signatureAlgorithm, PrivateKey issuerPrivateKey) Signs the certificate request with the private key of the subject.
void	sign(AlgorithmID signatureAlgorithm, PrivateKey issuerPrivateKey, String provider) Signs the certificate request with the private key of the subject.
byte[]	toByteArray() Returns the certificate request in a byte array in DER format.
String	toString() Returns a string that represents the contents of the certificate request.
String	toString(boolean detailed) Returns a string that represents the contents of the certificate request.
boolean	verify() Verifies the self signed certificate request.
boolean	verify(String provider) Verifies the self signed certificate request.
void	writeTo(OutputStream os) Writes this certificate request to the given output stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CertificateRequest

public CertificateRequest(InputStream is)
                   throws IOException,
                          PKCSParsingException

Creates a CertificateRequest form an input stream.

From the request derived from the input stream an ASN.1 object is created and subsequently parsed for the inherent CertificationRequestInfo to obtain the version number, the subject´s name and public key information, and any supplied attributes.

Parameters:

is - the input stream from where the certificate request shall be read

Throws:

IOException - if an I/O error occurs

PKCSParsingException - if the certificate request cannot be parsed

CertificateRequest

public CertificateRequest(byte[] arr)
                   throws PKCSParsingException

Creates a CertificateRequest form a byte array.

From the request derived from the byte array an ASN.1 object is created and subsequently parsed for the inherent CertificationRequestInfo to obtain the version number, the subject´s name and public key information, and any supplied attributes. This constructor only may be used for creating a certification request from an already existing certification request, supplied as DER encoded ASN.1 object that may have been created by calling the toByteArray method.

Parameters:

arr - the byte array containing the certificate request

Throws:

PKCSParsingException - if the certificate request cannot be parsed

CertificateRequest

public CertificateRequest(PublicKey publicKey,
                          Name subject)
                   throws InvalidKeyException

Creates a new CertificateRequest from a PublicKeyInfo and a Name.

The Name is of ASN.1 type Name specifying a DistinguishedName within the X.500 directory information tree. It may be created and supplied with proper informations (relative distinguished names) as follows:

  Name subject = new Name();
  subject.addRDN(ObjectID.country, "AT");
  subject.addRDN(ObjectID.locality, "Graz");
  subject.addRDN(ObjectID.organization ,"TU Graz");
  subject.addRDN(ObjectID.organizationalUnit ,"IAIK");
  subject.addRDN(ObjectID.commonName ,"TestUser");
 

Parameters:

publicKey - the public key of the subject

subject - the subject of the certificate request as distinguished name

Throws:

InvalidKeyException - if the public key has an invalid encoding

See Also:

Name

Method Detail

getCertificateRequestInfo

public byte[] getCertificateRequestInfo()
                                 throws PKCSException

Returns the DER encoded CertificateRequestInfo ASN.1 data structure over which the signature is calculated:

 CertificationRequestInfo ::= SEQUENCE {
   version Version, -- version number
   subject Name, -- distinguished name of the entity requesting the certificate
   subjectPublicKeyInfo SubjectPublicKeyInfo, -- information about the public key to be certified
   attributes [0] IMPLICIT Attributes  -- additional information about the subject
 }
 

Returns:

the inherent TBSCertificate as DER encoded ASN.1 structure

Throws:

CertificateEncodingException - if an encoding error occurs

addAttribute

public void addAttribute(Attribute attribute)

Adds one Atribute to this CertificateRequest.

Parameters:

attribute - the Attribute to add

setAttributes

public void setAttributes(Attribute[] attributes)

Sets the Atributes for this CertificateRequest. The given attributes have to be an array of iaik.asn1.structures.Attribute objects. To, for instance, add the PKCS#9 attribute challengePassword, use:

 CertificateRequest request = new CertificateRequest(pubKey, subject);
 PrintableString password = new PrintableString("iaik");
 Attribute cPAttribute =
    new Attribute(ObjectID.challengePassword, new ASN1Object[] { password });
 Attribute[] attributes = new Attribute[] { cPAttribute };
 request.setAttributes(attributes);
 

Note that the attributes have to be set before the request is signed with the subject´s private key!

Parameters:

attributes - the Attribute to set

getAttributes

public Attribute[] getAttributes()

Gets the Atributes of this CertificateRequest. If no Attributes are included, null is returned. Otherwise the atributes are returned as an array of iaik.asn1.structures.Attribute objects:

 Attribute[] attributes = request.getAttributes();
 if (attributes != null) {
   for (int i = 0; i < attributes.length; i++) {
     Attribute attr = attributes[i];
     System.out.println(attr.getType());
     ASN1Object[] asn1Obj = attr.getValue();
     for (int j = 0; j < asn1Obj.length; j++) {
       System.out.println(asn1Obj[j].toString());
     }
   }
 }
 

Returns:

the attributes of this request as array of iaik.asn1.structures.Attribute, or null if there are no attributes included

getAttributes

public Attribute[] getAttributes(ObjectID type)

Gets all the Atributes matching to a specific type (object identifier). If no Attributes of given type are included, null is returned. Otherwise the matching atributes are returned as an array of iaik.asn1.structures.Attribute objects. The following sample queries if the challangePassword attribute is included:

 Attribute[] attributes = request.getAttributes(ObjectID.challengePassword);
 if (attributes != null) {
   //expected only one:
   Attribute attr = attributes[0];
   System.out.println(attr.getType());
   ASN1Object[] asn1Obj = attr.getValue();
   //again, only one expected:
   System.out.println(asn1Obj[0].getValue());
 }
 

Returns:

all the attributes of given type as array of iaik.asn1.structures.Attribute, or null if there are no attributes of the given type included

getAttribute

public Attribute getAttribute(ObjectID oid)

Returns the first attribute matching to the given ObjectID, if included in this CertificateRequest.

Parameters:

oid - the attribute type to look for

Returns:

the first attribute belonging to the given ObjectID or null if there is no attribute for the given OID.

getAttributeValue

public AttributeValue getAttributeValue(ObjectID oid)
                                 throws PKCSException

Returns the attribute value of a single valued attribute with the given type.

This method provides the possibility to immediately access the value of an attribute with the given type. This method may be used for getting the value of the first included attribute of requested type or -- more appropriate -- the only one value of a single valued attribute of requested type. In this way, this method can be seen as an alternative to method getAttribute for providing immediate access to the attribute value. To, for instance, query for a ExtensionRequest attribute, you may proceed as follows:

 ExtensionRequest extensionRequest = (ExtensionRequest)request.getAttributeValue(ExtensionRequest.oid);
 if (extensionRequest != null) {
   Enumeration extensions = extensionRequest.listExtensions();
 }
 

Parameters:

oid - the object identifier representing the type of the attribute for which to get the value

Returns:

the attribute value of null if no attribute of given type is included

Throws:

if - the ASN.1 representation of the attribute value cannot be parsed

sign

public void sign(AlgorithmID signatureAlgorithm,
                 PrivateKey issuerPrivateKey)
          throws SignatureException,
                 InvalidKeyException,
                 NoSuchAlgorithmException

Signs the certificate request with the private key of the subject. A PKCS#1 standard signature is created.

Parameters:

signatureAlgorithm - the AlgorithmID of the signature algorithm

issuerPrivateKey - the private key of the subject

Throws:

SignatureException - if the signature could not be created

InvalidKeyException - if the format of the key is wrong

NoSuchAlgorithmException - if there is no implementation for the specified signature algorithm

sign

public void sign(AlgorithmID signatureAlgorithm,
                 PrivateKey issuerPrivateKey,
                 String provider)
          throws SignatureException,
                 InvalidKeyException,
                 NoSuchAlgorithmException

Signs the certificate request with the private key of the subject. A PKCS#1 standard signature is created.

Parameters:

signatureAlgorithm - the AlgorithmID of the signature algorithm

issuerPrivateKey - the private key of the subject

provider - the name of the provider supplying the Signature engine to used

Throws:

SignatureException - if the signature could not be created

InvalidKeyException - if the format of the key is wrong

NoSuchAlgorithmException - if there is no implementation for the specified signature algorithm

setSignature

public void setSignature(AlgorithmID signatureAlgorithm,
                         byte[] signatureValue)
                  throws SignatureException

Sets the signature value of this certificate request.

This method provides an alternative to method sign when it is required to set the signature value from outside (e.g. calculated by means of a smartcard):

 CertificateRequest request = ...;
 ...
 // set subject, public key, ...
 ...
 // get the to-be-signed value
 byte[] tbs = request.getCertificateRequestInfo();
 // now calculate the signature over the certificate request info
 byte[] signatureValue = calculateSignature(tbs);
 // and set the signatureValue
 request.setSignature(AlgorithmID.sha1WithRSAEncryption, signatureValue);
 // encode the request
 byte[] encodedRequest = request.toByteArray();
 

Parameters:

signatureValue - the signature calculated outside

Throws:

CertificateException - if the certificate could not be signed

verify

public boolean verify()
               throws SignatureException

Verifies the self signed certificate request.

Specified by:

verify in interface CertRequest

Returns:

true if the cert request is OK, false if not

Throws:

SignatureException - if the certificate request could not be verified

verify

public boolean verify(String provider)
               throws SignatureException

Verifies the self signed certificate request.

Parameters:

provider - the name of the provider supplying the Signature engine to be used

Returns:

true if the cert request is OK, false if not

Throws:

SignatureException - if the certificate request could not be verified

toByteArray

public byte[] toByteArray()

Returns the certificate request in a byte array in DER format.

The DER format (Distinguished Encoding Rules) defines a binary representation of an abstract ASN.1 datastructure.

Returns:

the certificate request in DER format

writeTo

public void writeTo(OutputStream os)
             throws IOException

Writes this certificate request to the given output stream.

Parameters:

os - the output stream to which the request shall be written

Throws:

IOException - if an I/O error occurs

getVersion

public int getVersion()

Returns the version number of this certificate request.

Returns:

version number of the certificate

getSignatureAlgorithmID

public AlgorithmID getSignatureAlgorithmID()

Returns the signature algorithm of this certificate request.

Returns:

the signature algorithm used to sign this certificate request as AlgorithmID

getSubject

public Name getSubject()

Returns the subject of this certificate request.

Returns:

the subject of the certificate request as ASN.1 structure Name

getPublicKey

public PublicKey getPublicKey()

Returns the public key of this certificate request.

Specified by:

getPublicKey in interface CertRequest

Returns:

the public key of the the certificate request

getFingerprint

public byte[] getFingerprint()

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

Returns:

the fingerprint of the certificate request

getFingerprint

public byte[] getFingerprint(String digestAlgorithm)
                      throws NoSuchAlgorithmException

Returns the fingerprint of this certificate request calculated with the given hash algorithm.

Parameters:

digestAlgorithm - the digest algorithm to be used

Returns:

the fingerprint of the certificate request

Throws:

NoSuchAlgorithmException - if the requested algorithm is not supported

getFingerprintSHA

public byte[] getFingerprintSHA()

Get the SHA fingerprint of this certificate. The result is cached for subsequent calls.

Returns:

the SHA fingerprint

toString

public String toString()

Returns a string that represents the contents of the certificate request.

Overrides:

toString in class Object

Returns:

the string representation

toString

public String toString(boolean detailed)

Returns a string that represents the contents of the certificate request.

Parameters:

detailed - whether to print more detailed information

Returns:

the string representation