com.rsa.certj.crmf

Class Control

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

All Implemented Interfaces:

Cloneable, Serializable

Direct Known Subclasses:

Authenticator, NonStandardControl, OldCertID, PKIArchiveOptions, PKIPublicationInfo, ProtocolEncryptionKey, RegistrationToken

public abstract class Control

extends Object

implements Cloneable, Serializable

This class is the superclass of all Control objects.

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

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

See Also

Serialized Form

Field Summary

static int	AUTHENTICATOR This flag indicates an Authenticator control defined in CRMF.
static int	NON_STANDARD This flag indicates a non-standard control.
static int	OLD_CERT_ID This flag indicates an OldCertID control defined in CRMF.
static int	PKI_ARCHIVE_OPTIONS This flag indicates a PKIArchiveOptions control defined in CRMF.
static int	PKI_PUBLICATION_INFO This flag indicates a PKIPublicationInfo control defined in CRMF.
static int	PROTOCOL_ENCR_KEY This flag indicates a ProtocolEncryptionKey control defined in CRMF.
static int	REG_TOKEN This flag indicates a RegistrationToken control defined in CRMF.

Constructor Summary

Control()

Method Summary

abstract Object	clone() Overrides the default clone method to get a deeper clone.
boolean	compareOID(byte[] oid) Compares the OID of this control to oid.
int	derEncodeControlLen(int special, int valueLen) Returns the number of bytes the DER-encoding of this control will be.
abstract boolean	equals(Object obj) Returns true if this object and obj contain the same control; returns false otherwise.
int	getControlType() Gets the control type.
String	getControlTypeString() Gets the name of the control type.
int	getDEREncoding(byte[] encoding, int offset, int special) Places the DER encoding of the control in this object into encoding, beginning at offset.
int	getDERLen(int special) Returns the number of bytes of the DER encoding of this control.
static Control	getInstance(byte[] controlBER, int offset, int special) Use this constructor, if not using PKIArchiveOptions control.
static Control	getInstance(byte[] controlBER, int offset, int special, CertJ certJ, CertPathCtx pathCtx, com.rsa.jsafe.JSAFE_PublicKey pubKey, com.rsa.jsafe.JSAFE_PrivateKey privKey) Use this constructor, if using PKIArchiveOptions control.
static int	getNextBEROffset(byte[] controlBER, int offset) Given controlBER, the BER encoding of a control beginning at offset, finds the index to the next element in the encoding.
byte[]	getOID() Gets the OID of this control.
boolean	isControlType(int type) Checks to see if this object is of the type represented by the given type, which should be one of the "flags" listed above.
void	setEnvironment(CertJ certJ, CertPathCtx pathCtx, com.rsa.jsafe.JSAFE_PublicKey pubKey, com.rsa.jsafe.JSAFE_PrivateKey privKey) Sets 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

Field Detail

REG_TOKEN

public static final int REG_TOKEN

This flag indicates a RegistrationToken control defined in CRMF.

AUTHENTICATOR

public static final int AUTHENTICATOR

This flag indicates an Authenticator control defined in CRMF.

PKI_PUBLICATION_INFO

public static final int PKI_PUBLICATION_INFO

This flag indicates a PKIPublicationInfo control defined in CRMF.

PKI_ARCHIVE_OPTIONS

public static final int PKI_ARCHIVE_OPTIONS

This flag indicates a PKIArchiveOptions control defined in CRMF.

OLD_CERT_ID

public static final int OLD_CERT_ID

This flag indicates an OldCertID control defined in CRMF.

PROTOCOL_ENCR_KEY

public static final int PROTOCOL_ENCR_KEY

This flag indicates a ProtocolEncryptionKey control defined in CRMF.

NON_STANDARD

public static final int NON_STANDARD

This flag indicates a non-standard control.

Constructor Detail

Control

public Control()

Method Detail

getInstance

public static Control getInstance(byte[] controlBER,
                                  int offset,
                                  int special,
                                  CertJ certJ,
                                  CertPathCtx pathCtx,
                                  com.rsa.jsafe.JSAFE_PublicKey pubKey,
                                  com.rsa.jsafe.JSAFE_PrivateKey privKey)
                           throws CRMFException

Use this constructor, if using PKIArchiveOptions control. Creates a control based on controlBER, the BER encoding of a control. This method will determine which kind of control is represented and instantiate the appropriate subclass.

The ASN.1 definition of Control is as follows:

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

That definition means the tag will be 0x30. However, a Control can be part of some other construct, and it may have a different tag due to IMPLICIT or EXPLICIT. For example, suppose the definition were

   control   [1] EXPLICIT Control
 

To pass in the BER encoding of Control, indicating the special nature of this particular encoding, use the special argument. That is the purpose of special. Set that argument to any special instructions of the BER encoding. For example, to indicate

   control   [1] EXPLICIT Control
 

pass in special = (ASN1.CONTEXT_EXPLICIT | 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

	controlBER		The BER-encoding of a control.
	offset		The offset into controlBER where the encoding begins.
	special		The special BER circumstances of the encoding, if there are any.
	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 the EncryptedValue structure (pass null if decoding, or when 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).

Returns

A Control object. Actually, the return is a subclass of Control, an object of the class associated with the control type.

Throws

CRMFException - If the BER encoding is invalid.

getInstance

public static Control getInstance(byte[] controlBER,
                                  int offset,
                                  int special)
                           throws CRMFException

Use this constructor, if not using PKIArchiveOptions control. Creates a control based on controlBER, the BER encoding of a control. This method will determine which kind of control is represented and instantiate the appropriate subclass.

The ASN.1 definition of Control is as follows:

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

That definition means the tag will be 0x30. But a control can be part of some other construct, and it may have a different tag due to IMPLICIT or EXPLICIT. For example, suppose the definition were

   control   [1] EXPLICIT Control
 

To pass in the BER encoding of Control, indicating the special nature of this particular encoding, use the special argument. That is the purpose of special. Set that argument to any special instructions of the BER encoding. For example, to indicate

   control   [1] EXPLICIT Control
 

pass in special = (ASN1.CONTEXT_EXPLICIT | 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

	controlBER		The BER encoding of a control.
	offset		The offset into controlBER where the encoding begins.
	special		The special BER circumstances of the encoding, if there are any.

Returns

A Control object. Actually, the return is a subclass of Control, an object of the class associated with the control type.

Throws

CRMFException - If the BER encoding is invalid.

getControlTypeString

public String getControlTypeString()

Gets the name of the control type.

Returns

A String describing the control type.

getOID

public byte[] getOID()

Gets the OID of this control.

Returns

A new byte array that contains the OID.

compareOID

public boolean compareOID(byte[] oid)

Compares the OID of this control to oid.

Parameters

oid

A byte array that contains the OID to compare.

getControlType

public int getControlType()

Gets the control type. The return value will be one of the flag values listed in this class (one of the static final ints).

Returns

An int specifying which control type is represented in this object.

getDERLen

public int getDERLen(int special)
              throws CRMFException

Returns the number of bytes of the DER encoding of this control. If this object is not set with a control, return 0.

The ASN.1 definition of Control is:

 Control ::= SEQUENCE { . . . }
 

But a control object can be part of a cert (or some other construct), and it may have a different tag due to IMPLICIT or EXPLICIT. This can affect the length. For example, a definition might include Control as:

   control   [1] EXPLICIT Control
 

To request the length of Control, indicating the special nature of this particular encoding, use the special argument. Set that argument to any special instructions of the DER encoding. For example, to indicate

   control   [1] EXPLICIT Control
 

pass in special = (ASN1.CONTEXT_EXPLICIT | 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

special

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

Returns

The number of bytes in the DER encoding of this control.

Throws

CRMFException - If there is an encoding error.

getNextBEROffset

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

Given controlBER, the BER encoding of a control beginning at offset, finds the index to the next element in the encoding. In other words, this method gets the next offset after the control.

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

Parameters

	controlBER		The BER-encoding of a control.
	offset		The offset into controlBER 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.

getDEREncoding

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

Places the DER encoding of the control in this object into encoding, beginning at offset. To determine how long the encoding will be, call getDERLen. If this object is not yet set with a control, this method will throw an exception.

The ASN.1 definition of Control is:

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

This definition means the tag will be 0x30. However, a control can be part of some other construct, and it may have a different tag due to IMPLICIT or EXPLICIT. For example, suppose the definition were

   control   [1] EXPLICIT Control
 

To indicate that the BER encoding of Control should follow special circumstances, use the special argument. Set that argument to any special instructions of the BER encoding. For example, to indicate

   control   [1] EXPLICIT Control
 

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

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.

Returns

The number of bytes actually placed into encoding.

Throws

CRMFException - If the method cannot create the BER encoding.

isControlType

public boolean isControlType(int type)

Checks to see if this object is of the type represented by the given type, which should be one of the "flags" listed above.

Parameters

type

The flag to check.

Returns

A boolean, indicating whether this object is of type.

derEncodeControlLen

public int derEncodeControlLen(int special,
                               int valueLen)
                        throws CRMFException

Returns the number of bytes the DER-encoding of this control will be. If this object is not set with a control, return 0.

The ASN.1 definition of Control is:

 Control ::= SEQUENCE { . . . }
 

But a control object can be part of a cert (or some other construct), and it may have a different tag due to IMPLICIT or EXPLICIT. This can affect the length. For example, a definition might include Control as

   control  [1] EXPLICIT Control
 

To request the length of Control, indicating the special nature of this particular encoding, use the special argument. Set that argument to any special instructions of the DER encoding. For example, to indicate

   control  [1] EXPLICIT Control
 

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

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 in the DER encoding of this control.

Throws

CRMFException - If there is an encoding error.

setEnvironment

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

Sets 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 (for example, PKIArchiveOptions control)

Parameters

	certJ		A 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 when 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 when not using EncryptedValue option in EncryptedKey in PKIArchiveOptions control).

Throws

CRMFException - If the specified values are null.

equals

public abstract boolean equals(Object obj)

Returns true if this object and obj contain the same control; returns false otherwise.

Overrides

equals in class Object

Parameters

obj

The instance of Control object.

Returns

A boolean that indicates whether these objects are equal.

clone

public abstract Object clone()
                      throws CloneNotSupportedException

Overrides the default clone method to get a deeper clone.

Returns

A new object, a copy of this object.

Throws

CloneNotSupportedException - If the cloning operation is not successful.