com.rsa.certj.crmf

Class Controls

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

All Implemented Interfaces:

Cloneable, Serializable

public class Controls

extends Object

implements Cloneable, Serializable

This class builds and holds Controls defined in CRMF (RFC-2511). It holds the collection of controls, the Control class is where the data is stored, encoded and decoded.

In CRMF, Controls are defined as follows.

 Controls ::= SEQUENCE SIZE(1...MAX) OF Control

 Control ::= SEQUENCE {
   type        OBJECT IDENTIFIER
   value       ANY DEFINED BY type }
 

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

See Also

Serialized Form

Constructor Summary

Controls()

Constructs an empty Controls object.

Method Summary

int	addControl(Control control) Adds a new CRMF defined control.
Object	clone() Overrides the default clone method to get a deeper clone.
void	decodeControls(byte[] controlsBER, int offset, int special) This method decodes controlsBER encoding and sets the values in this object.
boolean	equals(Object obj) Returns true if this object and obj contain the same Controls, returns false otherwise.
Control	getControlByIndex(int index) Gets the control at the indexth position in the list.
Control	getControlByOID(byte[] oid) Gets the control that is of the given oid.
Control	getControlByType(int controlType) Gets the control that is of the given controlType.
int	getControlCount() Determines the number of controls in this object.
int	getDEREncoding(byte[] encoding, int offset, int special) Places the DER encoding of the Controls into encoding, beginning at offset.
int	getDERLen(int special) Returns the number of bytes the DER encoding these Controls will be.
static int	getNextBEROffset(byte[] controlsBER, int offset) Finds the index of the next element in the encoded data, given controlsBER, the BER of CRMF controls beginning at offset.
void	setEnvironment(CertJ certJ, CertPathCtx pathCtx, com.rsa.jsafe.JSAFE_PublicKey pubKey, com.rsa.jsafe.JSAFE_PrivateKey privKey) Sets the a reference to the object that contains the database and certification path processing information.

Methods inherited from class java.lang.Object

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

Constructor Detail

Controls

public Controls()

Constructs an empty Controls object.

Method Detail

decodeControls

public void decodeControls(byte[] controlsBER,
                           int offset,
                           int special)
                    throws CRMFException

This method decodes controlsBER encoding and sets the values in this object. If one of the controls may need database access, set environment values (CertJ / CertPathCtx objects) and IssuerAndSerialNumber before calling this method.

The ASN.1 definition of Controls is

 Controls ::= SEQUENCE SIZE(1...MAX) OF AttributeTypeAndValue
 

That definition means the tag will be 0x30, But an Controls object can be part of a certificate request (or some other construct), and it may have a different tag due to IMPLICIT or EXPLICIT tag. For example, Controls can be defined as

   controls  [0] IMPLICIT Controls
 

then the tag will change from 0x30 to 0xa0 Hence, there needs to be a way to pass in the BER encoding of Controls, indicating the special nature of this particular encoding. That is the purpose of special. Set that argument to any special instructions of the BER encoding. For instance, to indicate

   controls  [0] IMPLICIT Controls
 

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

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

	controlsBER		A byte array that contains the BER encoding of Controls
	offset		The offset into controlsBER where the encoding begins
	special		The special BER circumstances of the encoding, if there are any

Throws

CRMFException - If the encoding is invalid

getNextBEROffset

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

Finds the index of the next element in the encoded data, given controlsBER, the BER of CRMF controls beginning at offset. In other words, gets the next offset after the controls.

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

Parameters

	controlsBER		The BER encoding of an X.501 controls
	offset		The offset into controlsBER where the encoding begins

Returns

An int, 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 the DER encoding these Controls will be. If this object is not set with values, returns 0.

The ASN.1 definition of Controls is

 Controls ::= SEQUENCE SIZE(1...MAX) OF AttributeTypeAndValue
 

That definition means the tag will be 0x30, But a Controls object can be part of a certificate request (or some other construct), and it may have a different tag due to IMPLICIT or EXPLICIT tag. For example, Controls can be defined as

   controls  [0] IMPLICIT Controls
 

then the tag will change from 0x30 to 0xa0 Hence, there needs to be a way to pass in the BER encoding of Controls, indicating the special nature of this particular encoding. That is the purpose of special. Set that argument to any special instructions of the BER encoding. For instance, to indicate

   controls  [0] IMPLICIT Controls
 

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

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

special

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

Returns

The number of bytes the DER encoding of these Controls will be

Throws

CRMFException - If there is an error while encoding

getDEREncoding

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

Places the DER encoding of the Controls into encoding, beginning at offset. Returns the number of bytes actually placed into the array. If there are no controls, places nothing intot the array and returns 0.

The ASN.1 definition of Controls is

 Controls ::= SEQUENCE SIZE(1...MAX) OF AttributeTypeAndValue
 

That definition means the tag will be 0x30, But a Controls object can be part of a certificate request (or some other construct), and it may have a different tag due to IMPLICIT or EXPLICIT tag. For example, Controls can be defined as

   controls  [0] IMPLICIT Controls
 

then the tag will change from 0x30 to 0xa0 Hence, there needs to be a way to pass in the BER encoding of Controls, indicating the special nature of this particular encoding. That is the purpose of special. Set that argument to any special instructions of the BER encoding. For instance, to indicate

   controls  [0] IMPLICIT Controls
 

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

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		The special DER circumstances of the encoding, if there are any

Returns

A byte array that contains the DER-encoding of the Controls

Throws

CRMFException - If the DER cannot be computed

addControl

public int addControl(Control control)
               throws CRMFException

Adds a new CRMF defined control.

Parameters

control

An object that contains the control type and value or values. See the Control class and its subclasses for information on building them.

Returns

The index into the list this control will be, returns -1 if passed in control is null.

Throws

CRMFException - If specified Control is null.

getControlCount

public int getControlCount()

Determines the number of controls in this object.

Returns

An int, the number of controls

getControlByIndex

public Control getControlByIndex(int index)
                          throws CRMFException

Gets the control at the indexth position in the list. If there is no control at the index given, throws an exception.

Parameters

index

The index into the list of the controls to retrieve

Returns

A new Control object that contains the data

Throws

CRMFException - If the specified index is invalid, or if

getControlByType

public Control getControlByType(int controlType)

Gets the control that is of the given controlType. The possible values of controlType are given in the Control class. If this object does not contain a control of the given type, return a null.

Parameters

controlType

The flag indicating which type. See the Control class for a list of possible values

Returns

A new Control object that contains the data

getControlByOID

public Control getControlByOID(byte[] oid)

Gets the control that is of the given oid. If this object does not contain a control of the given oid, returns a null.

Parameters

oid

The byte array that contains the OID to compare

Returns

A new Control object that contains the data

setEnvironment

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

Sets the a reference to the object that contains the database and certification path processing information. Use this method only if one of the controls needs database / certificate verification operations (e.g., PKIArchiveOptions control)

Parameters

	certJ		CertJ object that contains environment information
	pathCtx		The CertPathCtx object that contains certificate path validation information (pass NULL if not using EnvelopedData option in EncryptedKey in PKIArchiveOptions control)
	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)

clone

public Object clone()
             throws CloneNotSupportedException

Overrides the default clone method to get a deeper clone.

Returns

A new Controls 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 Controls, returns false otherwise.

Overrides

equals in class Object

Parameters

obj

The instance of Controls object

Returns

A boolean that indicates whether these objects are equal.