com.ibm.security.pkcs10
Class CertificationRequest

java.lang.Object
  |
  +--com.ibm.security.pkcsutil.PKCSDerObject
        |
        +--com.ibm.security.pkcs10.CertificationRequest

public final class CertificationRequest
extends PKCSDerObject
implements Cloneable

A PKCS #10 certificate request is created and sent to a Certificate Authority, which then creates an X.509 certificate (or perhaps a PKCS #6 extended certificate) and returns it to the entity that requested it.

A certificate request basically consists of the subject's X.500 name, public key, and zero or more attributes, signed using the subject's private key.

The ASN.1 syntax for a Certification Request is:

CertificationRequest ::= SEQUENCE { certificationRequestInfo CertificationRequestInfo, signatureAlgorithm SignatureAlgorithmIdentifier, signature Signature } SignatureAlgorithmIdentifier ::= AlgorithmIdentifier Signature ::= BIT STRING CertificationRequestInfo ::= SEQUENCE { version Version, subject Name, subjectPublicKeyInfo SubjectPublicKeyInfo, attributes [0] IMPLICIT Attributes } Attributes ::= SET OF Attribute

CertificationRequest objects are immutable; they cannot be changed once created.

See Also:
CertificationRequestInfo, AlgorithmId

Fields inherited from class com.ibm.security.pkcsutil.PKCSDerObject
provider
 
Constructor Summary
CertificationRequest(byte[] der)
          Create a CertificationRequest object with a DER byte array.
CertificationRequest(byte[] der, String provname)
          Create a CertificationRequest object with a DER byte array.
CertificationRequest(CertificationRequestInfo info)
          Constructs an unsigned PKCS #10 certificate request.
CertificationRequest(CertificationRequestInfo certReqInfo, PrivateKey privateKey, String digest)
          Constructs a signed PKCS #10 certificate request.
CertificationRequest(CertificationRequestInfo certReqInfo, PrivateKey privateKey, String digest, String provname)
          Constructs a signed PKCS #10 certificate request.
CertificationRequest(CertificationRequestInfo info, String provname)
          Constructs an unsigned PKCS #10 certificate request.
CertificationRequest(String filename, boolean base64)
          Create a CertificationRequest with the filename of the DER-encoded or BASE64-encoded object.
CertificationRequest(String filename, boolean base64, String provname)
          Create a CertificationRequest with the filename of the DER-encoded or BASE64-encoded object.
 
Method Summary
 Object clone()
          Creates a clone of this CertificationRequest object.
protected  void decode(com.ibm.security.pkcs10.DerValue encoding)
          Initializes a CertificationRequest object from a DerValue.
 void encode(OutputStream os)
          Encodes this object to an OutputStream.
 boolean equals(Object other)
          Determines if this CertificationRequest object is equivalent to the input object.
 CertificationRequestInfo getCertRequestInfo()
          Returns a reference to the certification request information.
 byte[] getSignature()
          Returns a copy of the request signature.
 AlgorithmId getSignatureAlgorithm()
          Returns a copy of the request signing algorithm identifier.
 int hashCode()
          Returns a hashcode value for this certificate request from its encoded form.
 void print(PrintStream out)
          Prints an E-Mailable version of the certificate request on the print stream passed.
protected  void readBASE64(String filename)
          Read the BASE64 encoding of a DER-encode object from the input file and decode the contents into the current object.
 CertificationRequest sign(String digest, PrivateKey key)
          Creates a signature for this certificate request.
 String toString()
          Provides a short description of this request.
 void verify()
          Verifies the request's signature.
 void writeBASE64(String filename)
          DER-encode the object and write the encoded bytes to the output file in BASE64 format.
 
Methods inherited from class com.ibm.security.pkcsutil.PKCSDerObject
decode, decode, encode, getObjectIdentifier, read, write, write
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CertificationRequest

public CertificationRequest(byte[] der)
                     throws IOException
Create a CertificationRequest object with a DER byte array.
Parameters:
der - a DER byte array encoding a CertificationRequest object.
Throws:
IOException - on decoding errors.

CertificationRequest

public CertificationRequest(byte[] der,
                            String provname)
                     throws IOException
Create a CertificationRequest object with a DER byte array.
Parameters:
der - a DER byte array encoding a CertificationRequest object.
provname - a string containing the name of the java security provider that the caller is using
Throws:
IOException - on decoding errors.

CertificationRequest

public CertificationRequest(CertificationRequestInfo certReqInfo,
                            PrivateKey privateKey,
                            String digest)
                     throws NoSuchAlgorithmException,
                            IOException,
                            PKCSException
Constructs a signed PKCS #10 certificate request.
Parameters:
info - the information, including subject name, public key and attributes, to include in the certification request.
privateKey - Private key used in signing.
digest - the digest used in the signing operation. Valid values are MD2, MD5 and SHA when using RSA private keys, or SHA when using DSA private keys.
Throws:
NoSuchAlgorithmException - if the public key algorithm is not supported in this environment.
IOException - on encoding errors.
PKCSException - on signing errors.

CertificationRequest

public CertificationRequest(CertificationRequestInfo certReqInfo,
                            PrivateKey privateKey,
                            String digest,
                            String provname)
                     throws NoSuchAlgorithmException,
                            IOException,
                            PKCSException
Constructs a signed PKCS #10 certificate request.
Parameters:
info - the information, including subject name, public key and attributes, to include in the certification request.
privateKey - Private key used in signing.
digest - the digest used in the signing operation. Valid values are MD2, MD5 and SHA when using RSA private keys, or SHA when using DSA private keys.
provname - a string containing the name of the java security provider that the caller is using
Throws:
NoSuchAlgorithmException - if the public key algorithm is not supported in this environment.
IOException - on encoding errors.
PKCSException - on signing errors.

CertificationRequest

public CertificationRequest(CertificationRequestInfo info)
Constructs an unsigned PKCS #10 certificate request. Before this request may be used, it must be encoded and signed. Then it must be retrieved in some conventional format (e.g. string).
Parameters:
info - the CertificationRequestInfo object containing subject name, public key and attibute information.

CertificationRequest

public CertificationRequest(CertificationRequestInfo info,
                            String provname)
Constructs an unsigned PKCS #10 certificate request. Before this request may be used, it must be encoded and signed. Then it must be retrieved in some conventional format (e.g. string).
Parameters:
info - the CertificationRequestInfo object containing subject name, public key and attibute information.
provname - a string containing the name of the java security provider that the caller is using

CertificationRequest

public CertificationRequest(String filename,
                            boolean base64)
                     throws IOException
Create a CertificationRequest with the filename of the DER-encoded or BASE64-encoded object.
Parameters:
filename - name of the DER-encoded or base64-encoded object
base64 - true if BASE64-encoded, false if DER-encoded
Throws:
IOException - on decoding errors.

CertificationRequest

public CertificationRequest(String filename,
                            boolean base64,
                            String provname)
                     throws IOException
Create a CertificationRequest with the filename of the DER-encoded or BASE64-encoded object.
Parameters:
filename - name of the DER-encoded or base64-encoded object
base64 - true if BASE64-encoded, false if DER-encoded
provname - a string containing the name of the java security provider that the caller is using
Throws:
IOException - on decoding errors.
Method Detail

encode

public void encode(OutputStream os)
            throws IOException
Encodes this object to an OutputStream. The certification request must be signed before it can be encoded.
Overrides:
encode in class PKCSDerObject
Parameters:
os - the OutputStream to write the encoded data to.
Throws:
IOException - on encoding errors.

sign

public CertificationRequest sign(String digest,
                                 PrivateKey key)
                          throws PKCSException,
                                 SignatureException
Creates a signature for this certificate request. This will later be retrieved in either string or binary format.
Parameters:
digest - the digest used in the signing operation. Valid values are MD2, MD5 and SHA when using RSA private keys, or SHA when using DSA private keys.
key - the private key used to sign the certification request information.
Throws:
PKCSException - on signing errors.

verify

public void verify()
            throws IOException,
                   SignatureException,
                   NoSuchAlgorithmException
Verifies the request's signature. This method is typically called immediately after constructing or decoding a CertificationRequest with DER-encoded input.
Throws:
IOException - on errors encoding the request information or decoding the stored public key.
SignatureException - if the signature is invalid.
NoSuchAlgorithmException - if the signature algorithm is not supported in this environment.

equals

public boolean equals(Object other)
Determines if this CertificationRequest object is equivalent to the input object.
Overrides:
equals in class PKCSDerObject
Parameters:
other - the object to compare this one to.
Returns:
true, if the two objects are equivalent, false otherwise.

hashCode

public int hashCode()
Returns a hashcode value for this certificate request from its encoded form.
Overrides:
hashCode in class PKCSDerObject
Returns:
the hashcode value.

clone

public Object clone()
Creates a clone of this CertificationRequest object.
Overrides:
clone in class Object
Returns:
clone of this CertificationRequest object.

getCertRequestInfo

public CertificationRequestInfo getCertRequestInfo()
Returns a reference to the certification request information. This consists of a version number, the subject's distinguished name, the subject's public key information and attributes. The certification request information is an immutable object.
Returns:
the certification request information for this object.

getSignatureAlgorithm

public AlgorithmId getSignatureAlgorithm()
Returns a copy of the request signing algorithm identifier.
Returns:
the request signing algorithm for this object.

getSignature

public byte[] getSignature()
Returns a copy of the request signature. The signature is constructed by DER encoding the certification request info into an octet string and then signing the encoded information using the signature algorithm and subject's private key.
Returns:
the signed certification request information.

print

public void print(PrintStream out)
           throws IOException,
                  SignatureException
Prints an E-Mailable version of the certificate request on the print stream passed. The format is a common base64 encoded one, supported by most Certificate Authorities because Netscape web servers have used this for some time. Some certificate authorities expect some more information, in particular contact information for the web server administrator.
Parameters:
out - the print stream where the certificate request will be printed.
Throws:
IOException - when an output operation failed
SignatureException - when the certificate request was not yet signed.

toString

public String toString()
Provides a short description of this request.
Overrides:
toString in class PKCSDerObject
Returns:
a String representation of this object.

writeBASE64

public void writeBASE64(String filename)
                 throws IOException
DER-encode the object and write the encoded bytes to the output file in BASE64 format. File will begin with the following header: -----BEGIN NEW CERTIFICATE REQUEST----- contain the BASE64 DER-encoded CertificationRequest and end with the following footer: -----END NEW CERTIFICATE REQUEST-----
Overrides:
writeBASE64 in class PKCSDerObject
Parameters:
filename - the file to write the BASE64 DER-encoded object to.
Throws:
IOException - if the file cannot be created or written to.

decode

protected void decode(com.ibm.security.pkcs10.DerValue encoding)
               throws IOException
Initializes a CertificationRequest object from a DerValue. The DER encoding must be in the format specified by the CertificationRequest ASN.1 notation. The signature should be verified before using this object.
Parameters:
encoding - a DER-encoded CertificationRequest object.
Throws:
IOException - on parsing error.

readBASE64

protected void readBASE64(String filename)
                   throws IOException
Read the BASE64 encoding of a DER-encode object from the input file and decode the contents into the current object. This method expects the file to be in the following format, beginning with: -----BEGIN NEW CERTIFICATE REQUEST----- containing the BASE64 DER-encoded CertificationRequest and ending with the following footer: -----END NEW CERTIFICATE REQUEST-----

If the file does not contain the header and footer, this method will attempt to decode the entire file.

Overrides:
readBASE64 in class PKCSDerObject
Parameters:
filename - the BASE64 file to read an object's DER encoding from.
Throws:
IOException - if the file cannot be created or read from.