com.rsa.certj.cert

Class PKCS10CertRequest

java.lang.Object
  |
  +--com.rsa.certj.cert.CertRequest
        |
        +--com.rsa.certj.cert.PKCS10CertRequest

All Implemented Interfaces:

Cloneable, Serializable

public class PKCS10CertRequest

extends CertRequest

implements Cloneable, Serializable

This class builds and holds PKCS #10 certificate requests. A PKCS #10 certificate request consists of three elements: the CertificationRequestInfo, the signatureAlgorithm in the form of an AlgorithmIdentifier, and the signature.

The ASN.1 definition is as follows:

 CertificationRequest ::= SEQUENCE {
   certificationRequestInfo  CertificationRequestInfo,
   signatureAlgorithm        AlgorithmIdentifier,
   signature                 BIT STRING }

 CertificationRequestInfo ::= SEQUENCE {
   version                   INTEGER,
   subject                   Name,
   subjectPublicKeyInfo      SubjectPublicKeyInfo,
   attributes                [0] IMPLICIT Attributes }

See the X500Name class for further descriptions of Name. See the RSA BSAFE Crypto-J Javadocs for further descriptions of SubjectPublicKeyInfo. See the X501Attributes class for a more detailed description of Attributes.

Copyright © RSA Security Inc., 1998-2001. All rights reserved.

See Also

Serialized Form

Field Summary

static int

PKCS10_VERSION_1 Use this value when setting the certificate request to be PKCS #10 version 1, or when you want to get the version of an existing certificate.

Fields inherited from class com.rsa.certj.cert.CertRequest

DSA_WITH_SHA1_X930, DSA_WITH_SHA1_X957, RSA_WITH_SHA1_ISO_OIW, RSA_WITH_SHA1_PKCS

Constructor Summary

PKCS10CertRequest()

Constructs an empty PKCS10CertRequest object.

PKCS10CertRequest(byte[] pkcs10CertRequestBER, int offset, int special)

Constructs a signed PKCS10CertRequest object and initializes it with the values given by pkcs10CertRequestBER, beginning at offset, the BER encoding of a PKCS #10 signed certificate request.

PKCS10CertRequest(byte[] pkcs10CertRequestBER, int offset, int special, CertJ certJContext)

PKCS10CertRequest(CertJ certJContext)

Constructs an empty PKCS10CertRequest object with CertJ context specified.

Method Summary

void	addAttribute(X501Attribute attribute) Adds attribute to the list of attributes for the certificate request.
X501Attributes	getAttributes() Gets the attributes in this certificate request.
int	getCertRequestInfoDEREncoding(byte[] encoding, int offset, int special) Places the DER encoding of the certificate request information in this object into encoding, beginning at offset.
int	getCertRequestInfoDERLen(int special) Returns the number of bytes of the DER encoding of the certifice request information.
int	getDEREncoding(byte[] encoding, int offset, int special) Places the DER encoding of the certificate request in this object into encoding, beginning at offset.
int	getDERLen(int special) Returns the number of bytes of the DER encoding of this request.
static int	getNextBEROffset(byte[] pkcs10CertRequestBER, int offset) Given pkcs10CertRequestBER, the BER of a PKCS #10 certificate request, beginning at offset, finds the index to the next element in the encoding.
byte[]	getSignature() Gets the signature octets.
X500Name	getSubjectName() Gets the subject name of this certificate request.
int	getVersion() Gets the version of this certificate request.
void	setAttributes(X501Attributes attributes) Sets the attributes of this certificate request to attributes.
void	setCertRequestInfo(byte[] pkcs10CertRequestInfo, int offset, int special) Sets this object to be the unsigned certificate request represented by pkcs10CertRequestInfo, beginning at offset, the BER encoding of the PKCS #10 certificate request.
void	setSubjectName(X500Name subjectName) Sets the subject name of this certificate request to be subjectName.
void	setVersion(int version) Sets the version of this certificate request to version.
void	signCertRequest(String transformation, String device, com.rsa.jsafe.JSAFE_PrivateKey signingKey, SecureRandom random) Signs the certificate request, using transformation and signingKey on the specified device.
boolean	verifyCertRequestSignature(String device, SecureRandom random) Verifies the signature on the certificate request, using the public key of the request on the specified device.

Methods inherited from class com.rsa.certj.cert.CertRequest

getCertJ, getDevice, getDeviceList, getSignatureAlgorithm, getSignatureAlgorithmDER, getSignatureFormat, getSignatureStandard, getSubjectPublicKey, setCertJ, setSignatureStandard, setSubjectPublicKey, setSubjectPublicKey

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PKCS10_VERSION_1

public static final int PKCS10_VERSION_1

Use this value when setting the certificate request to be PKCS #10 version 1, or when you want to get the version of an existing certificate.

Constructor Detail

PKCS10CertRequest

public PKCS10CertRequest()

Constructs an empty PKCS10CertRequest object.

PKCS10CertRequest

public PKCS10CertRequest(CertJ certJContext)

Constructs an empty PKCS10CertRequest object with CertJ context specified.

Parameters

certJContext

CertJ is a CertJ context.

PKCS10CertRequest

public PKCS10CertRequest(byte[] pkcs10CertRequestBER,
                         int offset,
                         int special)
                  throws CertificateException

Constructs a signed PKCS10CertRequest object and initializes it with the values given by pkcs10CertRequestBER, beginning at offset, the BER encoding of a PKCS #10 signed certificate request. This constructor only reads the certificate request, it does not perform any verification.

The ASN.1 definition of the request (previously defined in this class) means that the tag will be 0x30. However, a certificate request object can be part of a PKCS #7 message (or some other construct), and it might have a different tag caused by IMPLICIT or EXPLICIT. For example, suppose the definition is as follows:

      certRequest   [1] IMPLICIT CertificationRequest

In this case, the tag will change from 0x30 to 0xa1. To indicate that the BER encoding of the request should follow any special circumstances, use the special argument. Set special to any special circumstances of the BER encoding. For example, to indicate the following:

      certRequest   [1] IMPLICIT CertificationReques

Pass in the following:

 
   special = (ASN1.CONTEXT_IMPLICIT | 1);

If there are no special circumstances, pass in the following:

      special = 0

The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Parameters

	pkcs10CertRequestBER		The BER encoding of a PKCS #10 signed certificate request.
	offset		The offset into pkcs10CertRequestBER where the encoding begins.
	special		The special BER circumstances of the encoding, if there are any.

Throws

CertificateException - If the BER is not a valid PKCS #10 certificate request.

PKCS10CertRequest

public PKCS10CertRequest(byte[] pkcs10CertRequestBER,
                         int offset,
                         int special,
                         CertJ certJContext)
                  throws CertificateException

Method Detail

getNextBEROffset

public static int getNextBEROffset(byte[] pkcs10CertRequestBER,
                                   int offset)
                            throws CertificateException

Given pkcs10CertRequestBER, the BER of a PKCS #10 certificate request, beginning at offset, finds the index to the next element in the encoding. In other words, gets the next offset after the certificate request.

For example, if the offset is 120 and the request's BER encoding is 1819 bytes, this method returns 1939, the index immediately following the request. That is, pkcs10CertRequestBER[120] is the first byte in the encoding of the request, pkcs10CertRequestBER[1938] is the last byte in the encoding of the request, and the next element begins at index 1939.

Parameters

	pkcs10CertRequestBER		The BER encoding of a PKCS #10 certificate request.
	offset		The offset into pkcs10CertRequestBER where the encoding begins.

Returns

An int that contains the index to the next element in the BER encoding.

Throws

CertificateException - If the method cannot read the BER encoding.

getDERLen

public int getDERLen(int special)

Returns the number of bytes of the DER encoding of this request. If this object is not set with values, this method returns zero.

The ASN.1 definition of the request (previously defined in this class) means that the tag will be 0x30. However, a certificate request object can be part of a PKCS #7 message (or some other construct), and it might have a different tag caused by IMPLICIT or EXPLICIT. For example, suppose the definition is as follows:

      certRequest   [1] IMPLICIT CertificationRequest

In this case, the tag will change from 0x30 to 0xa1. To indicate that the BER encoding of the request should follow any special circumstances, use the special argument. Set special to any special circumstances of the BER encoding. For example, to indicate the following:

      certRequest   [1] IMPLICIT CertificationRequest

Pass in the following:

 
   special = (ASN1.CONTEXT_IMPLICIT | 1);

If there are no special circumstances, pass in the following:

      special = 0

The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Parameters

special

The special circumstances of the DER encoding, if there are any.

Returns

The number of bytes of the DER encoding of this certificate request.

getDEREncoding

public int getDEREncoding(byte[] encoding,
                          int offset,
                          int special)
                   throws CertificateException

Places the DER encoding of the certificate request in this object into encoding, beginning at offset. To determine how long the encoding will be, call getDERLen. If this object is not set with a request, this method places nothing into the array and returns zero. The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Parameters

	encoding		The byte array into which the encoding will be placed.
	offset		The offset into encoding where writing begins.
	special		The special DER circumstances of the encoding, if there are any. If there are no special circumstances, pass in special = 0.

Returns

The length of the DER encoding of the certificate request.

Throws

CertificateException - If the object is not set with a valid signed PKCS #10 certificate request.

setCertRequestInfo

public void setCertRequestInfo(byte[] pkcs10CertRequestInfo,
                               int offset,
                               int special)
                        throws CertificateException

Sets this object to be the unsigned certificate request represented by pkcs10CertRequestInfo, beginning at offset, the BER encoding of the PKCS #10 certificate request. If this object is already set with certificate request information, then calling this method deletes any internal copy of that data and replaces it with the new certificate request.

Parameters

	pkcs10CertRequestInfo		The DER encoding of the request information, an unsigned certificate request.
	offset		The offset into pkcs10CertRequestInfo where the encoding begins.
	special		The special BER circumstances of the encoding, if there are any. If there are no special circumstances, pass in special = 0. The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Throws

CertificateException - If the DER is not valid PKCS #10 certificate request information.

getCertRequestInfoDERLen

public int getCertRequestInfoDERLen(int special)

Returns the number of bytes of the DER encoding of the certifice request information. If this object is not set with values, this method returns zero. The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Parameters

special

The special DER circumstances of the encoding, if there are any. If there are no special circumstances, pass in special = 0.

getCertRequestInfoDEREncoding

public int getCertRequestInfoDEREncoding(byte[] encoding,
                                         int offset,
                                         int special)
                                  throws CertificateException

Places the DER encoding of the certificate request information in this object into encoding, beginning at offset. To determine the length of the encoding, call getCertRequestInfoDERLen. If this object is not set with a request, this method places nothing into the array and returns zero.

The following ASN.1 constants are possible values for special: APP_IMPLICIT, APP_EXPLICIT, PRIVATE_IMPLICIT, PRIVATE_EXPLICIT, OPTIONAL, DEFAULT, CONTEXT_IMPLICIT, or CONTEXT_EXPLICIT.

Parameters

	encoding		The byte array into which the encoding will be placed.
	offset		The offset into encoding where writing begins.
	special		The special DER circumstances of the encoding, if there are any. If there are no special circumstances, pass in special = 0.

Throws

CertificateException - If the object is not set with a valid signed PKCS #10 certificate request.

getSignature

public byte[] getSignature()
                    throws CertificateException

Gets the signature octets. A PKCS #10 request wraps the signature in a BIT STRING.

Overrides

getSignature in class CertRequest

Returns

A new byte array that contains the signature octets.

Throws

CertificateException - If the certificate request has not been signed.

setVersion

public void setVersion(int version)
                throws CertificateException

Sets the version of this certificate request to version. The input should be PKCS10_VERSION_1, previously defined in this class. If later versions of PKCS #10 are created, then this method will have more use. If this method is not called, then the request will still be labeled version 1. If the certificate request object possesses a signature, then calling this method causes the signature to be deleted.

Parameters

version

The PKCS #10 version number of this certificate request.

Throws

CertificateException - If the input value is an unsupported version number.

getVersion

public int getVersion()

Gets the version of this certificate request. The result will be PKCS10_VERSION_1, previously defined in this class. If later versions of PKCS #10 are created, then this method will have more use.

Returns

An int that contains the PKCS #10 version number.

setSubjectName

public void setSubjectName(X500Name subjectName)
                    throws CertificateException

Sets the subject name of this certificate request to be subjectName. If the certificate request object possesses a signature, then calling this method causes the signature to be deleted.

Parameters

subjectName

An X500Name object that contains the name.

Throws

CertificateException - If the subjectName is invalid.

getSubjectName

public X500Name getSubjectName()

Gets the subject name of this certificate request. If this object does not yet have a subject name, this method returns null.

Returns

A new X500Name object that contains the name.

addAttribute

public void addAttribute(X501Attribute attribute)

Adds attribute to the list of attributes for the certificate request.

Parameters

attribute

An X501Attribute attribute object.

setAttributes

public void setAttributes(X501Attributes attributes)
                   throws CertificateException

Sets the attributes of this certificate request to attributes. If the certificate object possesses a signature, then calling this method causes the signature to be deleted. It will reset the value of the attributes field.

Parameters

attributes

An X501Attributes object that contains the attributes.

Throws

CertificateException - If the attributes are not valid.

getAttributes

public X501Attributes getAttributes()

Gets the attributes in this certificate request. If there are no attributes, this method returns null.

Returns

An X501Attributes object that contains the attributes.

signCertRequest

public void signCertRequest(String transformation,
                            String device,
                            com.rsa.jsafe.JSAFE_PrivateKey signingKey,
                            SecureRandom random)
                     throws CertificateException

Signs the certificate request, using transformation and signingKey on the specified device. The format of transformation follows the format specified in the Crypto-J class JSAFE_Signature. The following are examples of transformations:

   "MD5/RSA/PKCS1Block01Pad"
   "SHA1/DSA"

The format of device follows the format specified in Crypto-J. The following are examples of device arguments:

   Java         --Perform signature using Java code
   Native       --Perform signature using the native link
   Native/Java  --Use native if possible, if not, use Java

Overrides

signCertRequest in class CertRequest

Parameters

	transformation		A String specifying the algorithm to use to sign the certificate request.
	device		A String specifying the device or choice of devices to use in computing the signature.
	signingKey		A JSAFE_PrivateKey used to compute the signature.
	random		Random bytes. If the signature algorithm needs random bytes, get them from this object.

Throws

CertificateException - If the code cannot perform the specified transformation on the specified device, if the certificate request is not set correctly, or if the certificate request is already signed.

verifyCertRequestSignature

public boolean verifyCertRequestSignature(String device,
                                          SecureRandom random)
                                   throws CertificateException

Verifies the signature on the certificate request, using the public key of the request on the specified device.

The format of device follows the format specified in Crypto-J. The following are examples of device arguments:

   Java         --Perform verification using Java code
   Native       --Perform verification using the native link
   Native/Java  --Use native if possible, if not, use Java

Overrides

verifyCertRequestSignature in class CertRequest

Parameters

	device		A String that specifies the device or choice of devices to use in computing the signature.
	random		Random bytes. If the signature algorithm needs random bytes, get them from this object.

Returns

A boolean indicating whether the signature on the certificate request is valid.

Throws

CertificateException - If this method cannot perform the signature algorithm on the specified device.