CertificateRequest ("Entrust Authority Security Toolkit for the Java Platform")

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

All Implemented Interfaces:

CertRequest, java.io.Serializable
```
public class CertificateRequest
extends java.lang.Object
implements java.io.Serializable, CertRequest
```
This class represents a CertificationRequest as described in PKCS#10.
PKCS #10: Certification Request Syntax Version 1.5 (RFC 2314) 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
 }
 
```
See Also:

X509Certificate, PublicKeyInfo, Name, AlgorithmID, Serialized Form

Constructor Summary

Constructors
Constructor and Description
`CertificateRequest(byte[] arr)` Creates a CertificateRequest form a byte array.
`CertificateRequest(java.io.InputStream is)` Creates a CertificateRequest form an input stream.
`CertificateRequest(java.security.PublicKey publicKey, Name subject)` Creates a new CertificateRequest from a PublicKeyInfo and a Name.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addAttribute(Attribute attribute)` Adds one Atribute to 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).
`byte[]`	`getFingerprint()` Returns the fingerprint of this certificate request.
`byte[]`	`getFingerprint(java.lang.String digestAlgorithm)` Returns the fingerprint of this certificate request calculated with the given hash algorithm.
`java.security.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`	`sign(AlgorithmID signatureAlgorithm, java.security.PrivateKey issuerPrivateKey)` Signs the certificate request with the private key of the subject.
`void`	`sign(java.security.Provider providerObj, AlgorithmID signatureAlgorithm, java.security.PrivateKey issuerPrivateKey)` Signs the certificate request with the private key of the subject.
`byte[]`	`toByteArray()` Returns the certificate request in a byte array in DER format.
`java.lang.String`	`toString()` Returns a string that represents the contents of the certificate request.
`boolean`	`verify()` Verifies the self signed certificate request.
`void`	`writeTo(java.io.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(java.io.InputStream is)
                   throws java.io.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:
    
    java.io.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(java.security.PublicKey publicKey,
                          Name subject)
                   throws java.security.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:
    
    java.security.InvalidKeyException - if the public key has an invalid encoding
    
    See Also:
    
    Name
- Method Detail
  - 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
  - sign
```
public void sign(AlgorithmID signatureAlgorithm,
                 java.security.PrivateKey issuerPrivateKey)
          throws java.security.SignatureException,
                 java.security.InvalidKeyException,
                 java.security.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:
    
    java.security.SignatureException - if the signature could not be created
    
    java.security.InvalidKeyException - if the format of the key is wrong
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the specified signature algorithm
  - sign
```
public void sign(java.security.Provider providerObj,
                 AlgorithmID signatureAlgorithm,
                 java.security.PrivateKey issuerPrivateKey)
          throws java.security.SignatureException,
                 java.security.InvalidKeyException,
                 java.security.NoSuchAlgorithmException
```
    Signs the certificate request with the private key of the subject. A PKCS#1 standard signature is created.
    
    Parameters:
    
    providerObj - the Provider to use for signing (ex: SunPKCS11)
    
    signatureAlgorithm - the AlgorithmID of the signature algorithm
    
    issuerPrivateKey - the private key of the subject
    
    Throws:
    
    java.security.SignatureException - if the signature could not be created
    
    java.security.InvalidKeyException - if the format of the key is wrong
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the specified signature algorithm
  - verify
```
public boolean verify()
               throws java.security.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:
    
    java.security.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(java.io.OutputStream os)
             throws java.io.IOException
```
    Writes this certificate request to the given output stream.
    
    Parameters:
    
    os - the output stream to which the request shall be written
    
    Throws:
    
    java.io.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 java.security.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(java.lang.String digestAlgorithm)
                      throws java.security.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:
    
    java.security.NoSuchAlgorithmException - if the requested algorithm is not supported
  - toString
```
public java.lang.String toString()
```
    Returns a string that represents the contents of the certificate request.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    the string representation

Class CertificateRequest

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CertificateRequest

CertificateRequest

CertificateRequest

Method Detail

addAttribute

setAttributes

getAttributes

getAttributes

sign

sign

verify

toByteArray

writeTo

getVersion

getSignatureAlgorithmID

getSubject

getPublicKey

getFingerprint

getFingerprint

toString