com.rsa.certj.crmf

Class ProofOfPossession

java.lang.Object
  |
  +--com.rsa.certj.crmf.ProofOfPossession

All Implemented Interfaces:

Cloneable, Serializable

public class ProofOfPossession

extends Object

implements Cloneable, Serializable

This class contains the ProofOfPossession field from CertReqMsg defined in "CertificateRequest Message Format" (RFC 2511).

 ProofOfPossession ::= CHOICE {
      raVerified        [0] NULL,
      -- used if the RA has already verified that the requester is in
      -- possession of the private key
      signature         [1] POPOSigningKey,
      keyEncipherment   [2] POPOPrivKey,
      keyAgreement      [3] POPOPrivKey }

  POPOSigningKey ::= SEQUENCE {
      poposkInput         [0] POPOSigningKeyInput OPTIONAL,
      algorithmIdentifier     AlgorithmIdentifier,
      signature               BIT STRING }
      -- The signature (using "algorithmIdentifier") is on the
      -- DER-encoded value of poposkInput.  NOTE: If the CertReqMsg
      -- certReq CertTemplate contains the subject and publicKey values,
      -- then poposkInput MUST be omitted and the signature MUST be
      -- computed on the DER-encoded value of CertReqMsg certReq.  If
      -- the CertReqMsg certReq CertTemplate does not contain the public
      -- key and subject values, then poposkInput MUST be present and
      -- MUST be signed.  This strategy ensures that the public key is
      -- not present in both the poposkInput and CertReqMsg certReq
      -- CertTemplate fields.
 

To set up POPOSigningKey properly, pass a CertRequest message that contains the CertTemplate that has SubjectName and PublicKey set. If the CertTemplate does not have both values set, pass the POPOSigningKeyInput object instead.

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

See Also

Serialized Form

Field Summary

static int	AGREEMENT_POP
static int	ENCIPHERMENT_POP
static int	RA_VERIFIED_POP
static int	SIGNATURE_POP

Constructor Summary

ProofOfPossession()

Empty constructor

ProofOfPossession(CertJ certJContext)

Constructs an object with CertJ context specified.

ProofOfPossession(int type)

Creates an empty ProofOfPossession object of the specified type.

ProofOfPossession(int type, CertJ certJContext)

Creates an empty ProofOfPossession object of the specified type and specified CertJ context.

Method Summary

Object	clone() Overrides the default clone method to get a deeper clone.
void	decodeProofOfPossession(byte[] dataBER, int offset, int special) This method decodes the BER-encoding of ProofOfPossession object, setting it with the value given by dataBER beginning at offset.
boolean	equals(Object obj) Returns true if this object and obj contain the same ProofOfPossession, returns false otherwise.
byte[]	getAlgBER() Gets the signature algorithm ID BER-encoded
String	getAlgTransformation() Gets the signature algorithm ID as a transformation String
CertJ	getCertJ() Gets CertJ context.
int	getDEREncoding(byte[] encoding, int offset, int special) Places the DER encoding of the ProofOfPossession object into encoding, beginning at offset.
int	getDERLen(int special) Returns the number of bytes that will be used by the DER encoding of the ProofOfPossession.
static int	getNextBEROffset(byte[] popBER, int offset) Finds the index of the next element to encode, given popBER, the BER of a ProofOfPossession beginning at offset.
POPOPrivKey	getPOPOPrivKey() Gets the POPOPrivKey object for keyEncipherment or keyAgreement POP.
POPOSigningKeyInput	getPOPOSigningKeyInput() Gets the POPOSigningKeyInput data.
int	getPOPType() Gets the POP type
byte[]	getSignature() Gets the Signature
void	setCertJ(CertJ certJContext) This is a method to set the CertJ context dynamically.
void	setCertRequest(CertRequest request) Pass in the CertRequest object that contains CertTemplate with Subject Name and Public Key values set.
void	setEnvironment(CertJ certJ, com.rsa.jsafe.JSAFE_PublicKey pubKey, com.rsa.jsafe.JSAFE_PrivateKey privKey) Sets the environment variables; use this method only if this POP is for keyEncipherment or keyAgreement.
void	setKeys(com.rsa.jsafe.JSAFE_PublicKey pubKey, com.rsa.jsafe.JSAFE_PrivateKey privKey) Sets the keys: use this method only if this POP is for keyEncipherment or keyAgreement.
void	setPOPOPrivKey(POPOPrivKey privateKey) Sets the POPOPrivKey object for keyEncipherment or keyAgreement POP.
void	setPOPOSigningKeyInput(POPOSigningKeyInput input) Sets the POPOSigningKeyInput data, including public key.
void	setSignatureAlgorithm(byte[] algID, int offset, int len) Sets the signature algorithm ID.
void	setSignatureAlgorithm(String trans) Sets the signature algorithm ID.
void	signPOP(String device, com.rsa.jsafe.JSAFE_PrivateKey signingKey, SecureRandom random) If Subject Name and Public Key are set, sign the DER encoding of the CertRequest.
boolean	verifySignature(String device, SecureRandom random) Verifies the POP's signature.

Methods inherited from class java.lang.Object

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

Field Detail

RA_VERIFIED_POP

public static final int RA_VERIFIED_POP

SIGNATURE_POP

public static final int SIGNATURE_POP

ENCIPHERMENT_POP

public static final int ENCIPHERMENT_POP

AGREEMENT_POP

public static final int AGREEMENT_POP

Constructor Detail

ProofOfPossession

public ProofOfPossession()

Empty constructor

ProofOfPossession

public ProofOfPossession(CertJ certJContext)

Constructs an object with CertJ context specified.

Parameters

certJContext

CertJ is a CertJ context.

ProofOfPossession

public ProofOfPossession(int type)
                  throws CRMFException

Creates an empty ProofOfPossession object of the specified type.

Parameters

type

One of the POP types, specified as constants in this class

Throws

CRMFException - If specified type is invalid or not supported

ProofOfPossession

public ProofOfPossession(int type,
                         CertJ certJContext)
                  throws CRMFException

Creates an empty ProofOfPossession object of the specified type and specified CertJ context.

Parameters

	type		One of the POP types, specified as constants in this class
	certJContext		CertJ is a CertJ context.

Throws

CRMFException - If specified type is invalid or not supported

Method Detail

decodeProofOfPossession

public void decodeProofOfPossession(byte[] dataBER,
                                    int offset,
                                    int special)
                             throws CRMFException

This method decodes the BER-encoding of ProofOfPossession object, setting it with the value given by dataBER beginning at offset.

This method only reads the ProofOfPossession data, it does not perform any verification. If you have "Signature" type of POP and you want to verify signature, call verifySignature() method after this method.

If this POP is for key agreement or key encripherment, user may need to set Recipient's information (public key and / or private key) and environment information (CertJ object) before calling this method.

Parameters

	dataBER		The BER encoding of a ProofOfPossession data
	offset		The offset into dataBER where the encoding begins
	special		That contains any special ASN.1 info, such as OPTIONAL

Throws

CRMFException - If the BER is not a valid ProofOfPossession data

verifySignature

public boolean verifySignature(String device,
                               SecureRandom random)
                        throws CRMFException

Verifies the POP's signature. Use it only for Signature keys. If POPOSigningKeyInput is not present, use setCertRequest method to set CertTemplate that contains the public key

Parameters

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

Returns

true if the signature is verified; otherwise, false.

Throws

If - This POP is not of the POPOSigningKey type, or if not all required values are set.

getPOPType

public int getPOPType()

Gets the POP type

Returns

The POP type, one of the constants defined in this class.

getPOPOSigningKeyInput

public POPOSigningKeyInput getPOPOSigningKeyInput()

Gets the POPOSigningKeyInput data. It returns the actual object, and not a clone.

Returns

If this POP is of POPOSigningKey type, returns POPOSigningKeyInput data, NULL otherwise.

setPOPOSigningKeyInput

public void setPOPOSigningKeyInput(POPOSigningKeyInput input)
                            throws CRMFException

Sets the POPOSigningKeyInput data, including public key. Use this method only if CertTemplate is missing the subject name or the public key. If this method is called after calling the setCertRequest method, the POPOSigningKeyInput data this is passed in is ignored.

Parameters

input

The POPOSigningKeyInput structure.

Throws

CRMFException - If this POP is not of the POPOSigningKey type, or if input is null.

getAlgTransformation

public String getAlgTransformation()

Gets the signature algorithm ID as a transformation String

Returns

A transformation String representing the signature algorithm ID for example, "SHA1/RSA/PKCS1Block01Pad". returns null if it is not set, or if this POP is not of POPOSigningKey type

getAlgBER

public byte[] getAlgBER()

Gets the signature algorithm ID BER-encoded

Returns

The BER-encoding of the Signature Algorithm. returns null if it is not set, or if this POP is not of POPOSigningKey type.

setSignatureAlgorithm

public void setSignatureAlgorithm(String trans)
                           throws CRMFException

Sets the signature algorithm ID.

Parameters

trans

A transformation String representing the signature algorithm ID; for example, "SHA1/RSA/PKCS1Block01Pad".

Throws

CRMFException - If this POP is not of the POPOSigningKey type, or if input is null.

setSignatureAlgorithm

public void setSignatureAlgorithm(byte[] algID,
                                  int offset,
                                  int len)
                           throws CRMFException

Sets the signature algorithm ID.

Parameters

	algID		A byte array that contains BER encoding of the signature algorithm ID.
	offset		The offset into algID array.
	len		The length of algID array.

Throws

CRMFException - If this POP is not of the POPOSigningKey type, or if input is null.

getSignature

public byte[] getSignature()

Gets the Signature

Returns

The signature; returns null if it is not set, or if this POP is not of POPOSigningKey type

setCertRequest

public void setCertRequest(CertRequest request)
                    throws CRMFException

Pass in the CertRequest object that contains CertTemplate with Subject Name and Public Key values set. This CertRequest will be signed to generate POP. Use this method ONLY if CertTemplate contains both subject name and public key. If CertTemplate is missing any of those two values, use setPOPOSigningKeyInput) method to pass in public key and name. If you passed in CertTemplate with both values set, do not call setPOPOSigningKeyInput method, it will be ignored.

Parameters

certRequest

Contains CertTemplate with Subject Name and Public Key values set.

Throws

CRMFException - If CertRequest is invalid, or CertTemplate does not contain both Subject Name and Public Key values, or if this POP is not of the POPOSigningKey type.

signPOP

public void signPOP(String device,
                    com.rsa.jsafe.JSAFE_PrivateKey signingKey,
                    SecureRandom random)
             throws CRMFException

If Subject Name and Public Key are set, sign the DER encoding of the CertRequest. Otherwise, sign POPOSigningKeyInput value. It sets the signature field in POPOSigningKey structure. To get later the actual signature, use getSignature() method.

Parameters

	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		If the signature algorithm needs random bytes, get them from this object.

Throws

CRMFException - If we cannot sign the data, or if this POP is not of POPOSigningKey type

setEnvironment

public void setEnvironment(CertJ certJ,
                           com.rsa.jsafe.JSAFE_PublicKey pubKey,
                           com.rsa.jsafe.JSAFE_PrivateKey privKey)

Sets the environment variables; use this method only if this POP is for keyEncipherment or keyAgreement.

Parameters

	certJ		CertJ object that contains environment information
	pubKey		Public key used to encrypt the Secret key in EncryptedValue structure (pass NULL if decoding, or not using EncryptedValue option in EncryptedKey in PKIArchiveOptions control)
	privKey		Private key used to decrypt the Secret key in EncryptedValue structure (pass NULL if encoding, or not using EncryptedValue option in EncryptedKey in PKIArchiveOptions control)

setCertJ

public void setCertJ(CertJ certJContext)

This is a method to set the CertJ context dynamically. Applications either call this method or instantiate ProofOfPossession object with CertJ context specified to initialize CertJ context. The value is checked when it is used.

Parameters

certJContex

CertJ

getCertJ

public CertJ getCertJ()

Gets CertJ context.

Returns

certJ CertJ reference

setKeys

public void setKeys(com.rsa.jsafe.JSAFE_PublicKey pubKey,
                    com.rsa.jsafe.JSAFE_PrivateKey privKey)

Sets the keys: use this method only if this POP is for keyEncipherment or keyAgreement.

Parameters

	pubKey		Public key used to encrypt the Secret key in EncryptedValue structure (pass NULL if decoding, or not using EncryptedValue option in EncryptedKey in PKIArchiveOptions control)
	privKey		Private key used to decrypt the Secret key in EncryptedValue structure (pass NULL if encoding, or not using EncryptedValue option in EncryptedKey in PKIArchiveOptions control)

setPOPOPrivKey

public void setPOPOPrivKey(POPOPrivKey privateKey)
                    throws CRMFException

Sets the POPOPrivKey object for keyEncipherment or keyAgreement POP.

Parameters

privateKey

The POPOPrivKey object that contains data for keyEncipherment or keyAgreement POP.

Throws

CRMFException - If there is a clone error, or if this object is not ENCIPHERMENT_POP or AGREEMENT_POP POP.

getPOPOPrivKey

public POPOPrivKey getPOPOPrivKey()
                           throws CRMFException

Gets the POPOPrivKey object for keyEncipherment or keyAgreement POP. It returns the actual object, and not a clone.

Returns

The POPOPrivKey object that contains data for keyEncipherment or keyAgreement POP; returns null if this object is not set.

Throws

CRMFException - If there is a clone error.

clone

public Object clone()
             throws CloneNotSupportedException

Overrides the default clone method to get a deeper clone.

Returns

A new ProofOfPossession object, a copy of this object

Throws

CloneNotSupportedException - If the cloning operation is not successful.

equals

public boolean equals(Object obj)

Returns true if this object and obj contain the same ProofOfPossession, returns false otherwise.

Overrides

equals in class Object

Parameters

obj

The instance of ProofOfPossession object

Returns

A boolean that indicates whether these objects are equal.

getNextBEROffset

public static int getNextBEROffset(byte[] popBER,
                                   int offset)
                            throws CRMFException

Finds the index of the next element to encode, given popBER, the BER of a ProofOfPossession beginning at offset. In other words, gets the next offset after the POP.

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

Parameters

	popBER		The BER encoding of a ProofOfPossession
	offset		The offset into popBER where the encoding begins

Returns

An int that indicates the index to the next element in the BER encoding

Throws

CRMFException - If the method cannot read the BER encoding

getDERLen

public int getDERLen(int special)
              throws CRMFException

Returns the number of bytes that will be used by the DER encoding of the ProofOfPossession. If this object is not set with values, returns 0.

Parameters

special

That contains any special ASN.1 info, such as OPTIONAL

Returns

The number of bytes that will be used by the DER encoding of the ProofOfPossession.

getDEREncoding

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

Places the DER encoding of the ProofOfPossession object into encoding, beginning at offset. To determine how long the encoding will be, call getDERLen. If this object is not yet set with values, this method places nothing into the array and returns 0. To indicate that the DER encoding should follow any special instructions, use the special argument. For instance, to indicate

   data   [1] IMPLICIT INTEGER
 

pass in special = (ASN1.CONTEXT_IMPLICIT | 1);

Of course, 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.

Parameters

	encoding		The byte array into which the result will be placed.
	offset		The offset into encoding where the writing is to begin.
	special		That contains any special ASN.1 info, such as OPTIONAL

Returns

The number of bytes actually placed into encoding.