CertificateRequest (6.0 API Documentation)

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 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 certification authority will prove 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 34

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

Methods
Modifier and Type	Method and Description
`void`	`addAttribute(Attribute attribute)` Adds one Attribute 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 Attributes of this CertificateRequest.
`Attribute[]`	`getAttributes(ObjectID type)` Gets all the Attributes 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:
`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.
`byte[]`	`getFingerprintSHA()` Get the SHA fingerprint of this certificate.
`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 Attributes for this CertificateRequest.
`void`	`setSignature(AlgorithmID signatureAlgorithm, byte[] signatureValue)` Sets the signature value of this certificate request.
`void`	`sign(AlgorithmID signatureAlgorithm, java.security.PrivateKey issuerPrivateKey)` Signs the certificate request with the private key of the subject.
`void`	`sign(AlgorithmID signatureAlgorithm, java.security.PrivateKey issuerPrivateKey, java.security.spec.AlgorithmParameterSpec signatureParams, java.security.Provider provider)` Signs the certificate request with the private key of the subject.
`void`	`sign(AlgorithmID signatureAlgorithm, java.security.PrivateKey issuerPrivateKey, java.security.spec.AlgorithmParameterSpec signatureParams, java.lang.String providerName)` Signs the certificate request with the private key of the subject.
`void`	`sign(AlgorithmID signatureAlgorithm, java.security.PrivateKey issuerPrivateKey, java.security.Provider provider)` Signs the certificate request with the private key of the subject.
`void`	`sign(AlgorithmID signatureAlgorithm, java.security.PrivateKey issuerPrivateKey, java.lang.String providerName)` 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.
`java.lang.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(java.security.Provider provider)` Verifies the self signed certificate request.
`boolean`	`verify(java.lang.String providerName)` 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
  - 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 CertificationRequestInfo as DER encoded ASN.1 structure
    
    Throws:
    
    PKCSException - if an encoding error occurs
  - addAttribute
```
public void addAttribute(Attribute attribute)
```
    Adds one Attribute to this CertificateRequest.
    
    Parameters:
    attribute - the Attribute to add
  - setAttributes
```
public void setAttributes(Attribute[] attributes)
```
    Sets the Attributes 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 Attributes 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 Attributes matching to a specific type (object identifier). If no Attributes of given type are included, null is returned. Otherwise the matching attributes 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:
    
    PKCSException - if the ASN.1 representation of the attribute value cannot be parsed
  - 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.
    
    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(AlgorithmID signatureAlgorithm,
        java.security.PrivateKey issuerPrivateKey,
        java.lang.String providerName)
          throws java.security.SignatureException,
                 java.security.InvalidKeyException,
                 java.security.NoSuchAlgorithmException
```
    Signs the certificate request with the private key of the subject.
    
    Parameters:
    signatureAlgorithm - the AlgorithmID of the signature algorithm
    issuerPrivateKey - the private key of the subject
    providerName - the name of the provider supplying the Signature engine to used; if null the first available provider will be used the supports the signature algorithm
    
    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(AlgorithmID signatureAlgorithm,
        java.security.PrivateKey issuerPrivateKey,
        java.security.spec.AlgorithmParameterSpec signatureParams,
        java.lang.String providerName)
          throws java.security.SignatureException,
                 java.security.InvalidKeyException,
                 java.security.NoSuchAlgorithmException,
                 java.security.InvalidAlgorithmParameterException
```
    Signs the certificate request with the private key of the subject.
    
    Parameters:
    signatureAlgorithm - the AlgorithmID of the signature algorithm
    issuerPrivateKey - the private key of the subject
    signatureParams - any signature parameters to -- if not null -- be used for initializing the Signature engine; if applicable the parameters are also set for the signatureAlg AlgorithmID (if it does not contain any parameters yet)
    providerName - the name of the provider supplying the Signature engine to used; if null the first available provider will be used the supports the signature algorithm
    
    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
    
    java.security.InvalidAlgorithmParameterException - if an error occurs when trying to set the signature parameters
  - sign
```
public void sign(AlgorithmID signatureAlgorithm,
        java.security.PrivateKey issuerPrivateKey,
        java.security.Provider provider)
          throws java.security.SignatureException,
                 java.security.InvalidKeyException,
                 java.security.NoSuchAlgorithmException
```
    Signs the certificate request with the private key of the subject.
    This method uses a Signature engine from the given provider for signing the request.
    If Provider object based JCA/JCE Signature engine instantiation is not available the Java VM in use (<1.4), this method tries to get an implementation based on the provider name (if the Provider is installed within the Security Provider framework). I.e. if method Signature.getInstance(algorithm,provider) is not available method Signature.getInstance(algorithm,provider.getName()) is tried.
    
    Parameters:
    signatureAlgorithm - the AlgorithmID of the signature algorithm
    issuerPrivateKey - the private key of the subject
    provider - the provider supplying the Signature engine to used; if null the first available provider will be used the supports the signature algorithm
    
    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(AlgorithmID signatureAlgorithm,
        java.security.PrivateKey issuerPrivateKey,
        java.security.spec.AlgorithmParameterSpec signatureParams,
        java.security.Provider provider)
          throws java.security.SignatureException,
                 java.security.InvalidKeyException,
                 java.security.NoSuchAlgorithmException,
                 java.security.InvalidAlgorithmParameterException
```
    Signs the certificate request with the private key of the subject.
    This method uses a Signature engine from the given provider for signing the request.
    If Provider object based JCA/JCE Signature engine instantiation is not available the Java VM in use (<1.4), this method tries to get an implementation based on the provider name (if the Provider is installed within the Security Provider framework). I.e. if method Signature.getInstance(algorithm,provider) is not available method Signature.getInstance(algorithm,provider.getName()) is tried.
    
    Parameters:
    signatureAlgorithm - the AlgorithmID of the signature algorithm
    issuerPrivateKey - the private key of the subject
    signatureParams - any signature parameters to -- if not null -- be used for initializing the Signature engine; if applicable the parameters are also set for the signatureAlg AlgorithmID (if it does not contain any parameters yet)
    provider - the provider supplying the Signature engine to used; if null the first available provider will be used the supports the signature algorithm
    
    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
    
    java.security.InvalidAlgorithmParameterException - if an error occurs when trying to set the signature parameters
  - setSignature
```
public void setSignature(AlgorithmID signatureAlgorithm,
                byte[] signatureValue)
                  throws java.security.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:
    
    java.security.SignatureException - if the certificate request could not be signed
  - verify
```
public boolean verify()
               throws java.security.SignatureException
```
    Verifies the self signed certificate request.
    
    Specified by:
    
    verify in interface CertRequest
    
    Returns:
    true if the signature of the cert request is OK, false if not
    
    Throws:
    
    java.security.SignatureException - if the certificate request could not be verified
  - verify
```
public boolean verify(java.lang.String providerName)
               throws java.security.SignatureException
```
    Verifies the self signed certificate request.
    
    Parameters:
    providerName - the name of the provider supplying the Signature engine to be used; if null the first available provider will be used the supports the signature algorithm
    
    Returns:
    true if the signature of the cert request is OK, false if not
    
    Throws:
    
    java.security.SignatureException - if the certificate request could not be verified
  - verify
```
public boolean verify(java.security.Provider provider)
               throws java.security.SignatureException
```
    Verifies the self signed certificate request.
    This method uses a Signature engine from the given provider for verifying the request.
    If Provider object based JCA/JCE Signature engine instantiation is not available the Java VM in use (<1.4), this method tries to get an implementation based on the provider name (if the Provider is installed within the Security Provider framework). I.e. if method Signature.getInstance(algorithm,provider) is not available method Signature.getInstance(algorithm,provider.getName()) is tried.
    
    Parameters:
    provider - the provider supplying the Signature engine to be used; if null the first available provider will be used the supports the signature algorithm
    
    Returns:
    true if the signature of 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 data structure.
    
    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
  - getFingerprintSHA
```
public byte[] getFingerprintSHA()
```
    Get the SHA fingerprint of this certificate. The result is cached for subsequent calls.
    
    Returns:
    the SHA fingerprint
  - 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
  - toString
```
public java.lang.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

Class CertificateRequest

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CertificateRequest

CertificateRequest

CertificateRequest

Method Detail

getCertificateRequestInfo

addAttribute

setAttributes

getAttributes

getAttributes

getAttribute

getAttributeValue

sign

sign

sign

sign

sign

setSignature

verify

verify

verify

toByteArray

writeTo

getVersion

getSignatureAlgorithmID

getSubject

getPublicKey

getFingerprint

getFingerprint

getFingerprintSHA

toString

toString