com.rsa.certj.pkcs7

Class ContentInfo

java.lang.Object
  |
  +--com.rsa.certj.pkcs7.ContentInfo

All Implemented Interfaces:

Cloneable, Serializable

Direct Known Subclasses:

Data, DigestedData, EncryptedData, EnvelopedData, SignedData

public abstract class ContentInfo

extends Object

implements Cloneable, Serializable

This class is the superclass for all PKCS #7 content classes.

The following are the supported PKCS #7 content types and their respective Cert-J classes:

	PKCS #7 Content Type			Cert-J PKCS #7 Class
	Data			Data
	SignedData			SignedData
	EnvelopedData			EnvelopedData
	DigestedData			DigestedData
	EncryptedData			EncryptedData

The ASN.1 definition is as follows:

  ContentInfo ::= SEQUENCE {
     contentType  OBJECT IDENTIFIER
     content      [0] EXPLICIT ANY DEFINED BY contentType OPTIONAL }

Copyright © RSA Security Inc., 1999-2003. All rights reserved.

See Also

Serialized Form

Field Summary

static int	DATA This flag indicates that the ContentType is Data.
static int	DIGESTED_DATA This flag indicates that the ContentType is DigestedData.
static int	ENCRYPTED_DATA This flag indicates that the ContentType is EncryptedData.
static int	ENVELOPED_DATA This flag indicates that the ContentType is EnvelopedData.
static int	NO_CONTENT This flag indicates that there is currently no content in this object, that is, there is no ContentType.
static int	PKCS7_VERSION_NUMBER_0 This indicates that PKCS #7 syntax version is 0.
static int	PKCS7_VERSION_NUMBER_1 This indicates that PKCS #7 syntax version is 1.
static int	SIGNED_DATA This flag indicates that the ContentType is SignedData.

Method Summary

int	bytesRead() Indicates how many bytes were read during the calls to readInit and readUpdate.
void	clearInternalContentBuffer() Clears the internal working buffer that contains the entire ContentInfo encoding of a newly read and parsed message.
void	clearSensitiveData() Clears any sensitive data.
Object	clone() Overrides the default clone method to get a deeper clone.
boolean	endOfMessage() Indicates whether the end of the message has been reached.
ContentInfo	getContent() This method returns a copy of the PKCS7Content object and its contents.
int	getContentInfoDERLen() Gets the total length of the DER-encoded contentInfo of the PKCS #7 message.
int	getContentInfoDERLen(int special) Gets the total length of the DER-encoded contentInfo of the PKCS #7 message.
int	getContentType() This method returns the flag indicating the contentType of the contents of this object.
String	getDevice() Gets the name of the device that actually performed the encrypting or decrypting.
String[]	getDeviceList() Gets a list of names of devices that actually performed the individual elements of the encrypting or decrypting.
static ContentInfo	getInstance(byte[] oid, int offset, int oidLen, CertJ certJ, CertPathCtx pathCtx) Builds the appropriate ContentInfo object with the given object identifier.
static ContentInfo	getInstance(int type, CertJ certJ, CertPathCtx pathCtx) Builds the appropriate ContentInfo object.
static int	getMessageType(byte[] data, int offset, int len) Returns the ContentInfo type, given the PKCS #7 message or the first part of it that contains the PKCS #7 message OID.
static int	getMessageType(byte[] data, int offset, int len, int special) Returns the ContentInfo type, given the PKCS #7 message or the first part of it that contains the PKCS #7 message OID.
int	getUnprocessedDataLen() Returns the number of bytes in the internal buffer that contains the unprocessed data.
boolean	readFinal() Finishes the process of decoding the contentInfo of this object.
boolean	readInit(byte[] input, int inOffset, int maxInputLen) Begins decoding the contentInfo of the given PKCS #7 message.
boolean	readInit(byte[] input, int inOffset, int maxInputLen, int special) Begins decoding the contentInfo of the given PKCS #7 message.
boolean	readInit(byte[] input, int inOffset, int maxInputLen, int special, int maxBufferSize) Begins decoding the contentInfo of the given PKCS #7 message.
int	readUpdate(byte[] input, int inOffset, int maxInputLen) Continues decoding the given contentInfo of a PKCS #7 message, returning the number of bytes that were read.
void	setCertJ(CertJ certJ) Sets the CertJ object.
void	setCertPath(CertPathCtx pathCtx) Sets the CertPathCtx object for path validation.
void	setDevice(String device) Sets the name of the device any cryptographic operations should use.
int	writeMessage(byte[] output, int outOffset) Creates the entire contentInfo of the PKCS #7 message, placing the result into output, beginning at outOffset.
int	writeMessage(byte[] output, int outOffset, int special) Creates the entire contentInfo of the PKCS #7 message, placing the result into output, beginning at outOffset.

Methods inherited from class java.lang.Object

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

Field Detail

DATA

public static final int DATA

This flag indicates that the ContentType is Data. This is also the last octet of the OID.

SIGNED_DATA

public static final int SIGNED_DATA

This flag indicates that the ContentType is SignedData. This is also the last octet of the OID.

ENVELOPED_DATA

public static final int ENVELOPED_DATA

This flag indicates that the ContentType is EnvelopedData. This is also the last octet of the OID.

DIGESTED_DATA

public static final int DIGESTED_DATA

This flag indicates that the ContentType is DigestedData. This is also the last octet of the OID.

ENCRYPTED_DATA

public static final int ENCRYPTED_DATA

This flag indicates that the ContentType is EncryptedData. This is also the last octet of the OID.

NO_CONTENT

public static final int NO_CONTENT

This flag indicates that there is currently no content in this object, that is, there is no ContentType.

PKCS7_VERSION_NUMBER_0

public static final int PKCS7_VERSION_NUMBER_0

This indicates that PKCS #7 syntax version is 0.

PKCS7_VERSION_NUMBER_1

public static final int PKCS7_VERSION_NUMBER_1

This indicates that PKCS #7 syntax version is 1.

Method Detail

getInstance

public static ContentInfo getInstance(int type,
                                      CertJ certJ,
                                      CertPathCtx pathCtx)
                               throws PKCS7Exception

Builds the appropriate ContentInfo object. The input is one of the fields defined in this class.

Parameters

	type		The PKCS #7 content type.
	certJ		A CertJ object that contains environment information used in signed, encrypted, and enveloped data and contains null for other types of data.
	pathCtx		A CertPathCtx object that contains certificate path validation information used in signed, encrypted, and enveloped data and contains null for other types of data. Most certification path providers require the trusted certificate component of this object to be non-empty to be able to perform certification path validation.

Returns

A new ContentInfo object, which is an instance of the appropriate subclass.

Throws

PKCS7Exception - If the OID is not a valid PKCS #7 ContentInfo.

getInstance

public static ContentInfo getInstance(byte[] oid,
                                      int offset,
                                      int oidLen,
                                      CertJ certJ,
                                      CertPathCtx pathCtx)
                               throws PKCS7Exception

Builds the appropriate ContentInfo object with the given object identifier. The input is one of the object identifiers defined in PKCS #7. For more information about PKCS #7, see the RSA Laboratories Web site (http://www.rsasecurity.com/rsalabs/pkcs/).

Parameters

	oid		The OID of the content type.
	offset		The offset into oid where the information actually begins.
	oidLen		The length of the OID.
	certJ		A CertJ object that contains environment information used in signed, encrypted, and enveloped data and contains null for other types of data.
	pathCtx		A CertPathCtx object that contains certificate-path validation information used in signed, encrypted, and enveloped data and contains null for other types of data. Most certification path providers require the trusted certificate component of this object to be non-empty to be able to perform certification path validation.

Returns

A new ContentInfo object, which is an instance of the appropriate subclass.

Throws

PKCS7Exception - If the OID is not a valid PKCS #7 contentType.

getMessageType

public static int getMessageType(byte[] data,
                                 int offset,
                                 int len)
                          throws PKCS7Exception

Returns the ContentInfo type, given the PKCS #7 message or the first part of it that contains the PKCS #7 message OID. If there is not enough data, then this method returns -1 and can be tried again.

Parameters

	data		A byte array that contains PKCS #7 message or the first part of it that contains the PKCS #7 message OID.
	offset		The offset into data, where the actual message starts.
	len		The length of the data.

Returns

A PKCS #7 message type, one of the fields previously defined in this class.

Throws

PKCS7Exception - If the OID is not a valid PKCS #7 contentType, or if the BER encoding is invalid.

getMessageType

public static int getMessageType(byte[] data,
                                 int offset,
                                 int len,
                                 int special)
                          throws PKCS7Exception

Returns the ContentInfo type, given the PKCS #7 message or the first part of it that contains the PKCS #7 message OID. If there is not enough data, then this method returns -1 and can be tried again.

Parameters

	data		A byte array that contains PKCS #7 message or the first part of it that contains the PKCS #7 message OID.
	offset		The offset into data, where the actual message starts.
	len		The length of the data.
	special		Special ASN.1 info, such as OPTIONAL

Returns

A PKCS #7 message type, one of the fields previously defined in this class.

Throws

PKCS7Exception - If the OID is not a valid PKCS #7 contentType, or if the BER encoding is invalid.

setDevice

public void setDevice(String device)

Sets the name of the device any cryptographic operations should use. If no device is specified, the engine will use the device specified in CertJ object.

Parameters

device

A String that indicates the device to use. The format of device follows the format specified in RSA BSAFE & reg; 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 For more information, see the RSA BSAFE Crypto-J Javadocs.

getDevice

public String getDevice()

Gets the name of the device that actually performed the encrypting or decrypting. If there is no device set or the object does not perform cryptographic operations, this method returns the device specified in CertJ object. If CertJ object is also null, this method returns null.

Returns

A String specifying the device chosen to perform the encrypting or decrypting.

getDeviceList

public String[] getDeviceList()

Gets a list of names of devices that actually performed the individual elements of the encrypting or decrypting. If there is no device set or the object does not perform cryptographic operations, this method returns the device list specified in CertJ object. If CertJ object is also null, this method returns null.

Returns

A String array specifying the devices chosen to perform the encrypting or decrypting.

getContentType

public int getContentType()

This method returns the flag indicating the contentType of the contents of this object. See the list of fields for this class for more information.

Returns

The flag indicating the contentType of the contents of this object. If there is no content, this method returns NO_CONTENT.

setCertJ

public void setCertJ(CertJ certJ)

Sets the CertJ object.

Parameters

certJ

A CertJ object that contains environment information.

setCertPath

public void setCertPath(CertPathCtx pathCtx)

Sets the CertPathCtx object for path validation.

Parameters

pathCtx

A CertPathCtx object that contains certificate-path validation information. Most certification path providers require the trusted certificate component of this object to be non-empty to be able to perform certification path validation.

getContent

public ContentInfo getContent()

This method returns a copy of the PKCS7Content object and its contents. If there are no contents, this method returns null.

Returns

A copy of the object with contents, or null.

getContentInfoDERLen

public int getContentInfoDERLen()
                         throws PKCS7Exception

Gets the total length of the DER-encoded contentInfo of the PKCS #7 message. This method can only be called before any writing begins. This method returns the length of the content of a PKCS #7 message created by calling writeMessage.

Returns

An int, the total length of the contentInfo portion of a message that contains data of length dataLen.

Throws

PKCS7Exception - If the object has already performed some message writing.

getContentInfoDERLen

public int getContentInfoDERLen(int special)
                         throws PKCS7Exception

Gets the total length of the DER-encoded contentInfo of the PKCS #7 message. This method can only be called before any writing begins. This method returns the length of the content of a PKCS #7 message created by calling writeMessage.

The ASN.1 definition of contentInfo is as follows:

   ContentInfo ::= SEQUENCE {
     contentType  OBJECT IDENTIFIER
     content      [0] EXPLICIT ANY DEFINED BY contentType OPTIONAL }
 

The content is optional.

Parameters

special

Any special ASN.1 info, such as OPTIONAL.

Returns

An int that contains the total length of the contentInfo portion of a message.

Throws

PKCS7Exception - If the object has already performed some message writing.

writeMessage

public int writeMessage(byte[] output,
                        int outOffset)
                 throws PKCS7Exception

Creates the entire contentInfo of the PKCS #7 message, placing the result into output, beginning at outOffset. The return value is the number of bytes placed into the output buffer.

Parameters

	output		The buffer into which this method will place output.
	outOffset		The offset into output where the method will begin placing data.

Returns

The number of bytes placed into output.

Throws

PKCS7Exception - If the engine cannot execute some of the required functions. For example, if the message is EnvelopedData and the PKCS7EnvelopedData object has not been set with the recipient's public key, then this method would throw an exception.

writeMessage

public int writeMessage(byte[] output,
                        int outOffset,
                        int special)
                 throws PKCS7Exception

Creates the entire contentInfo of the PKCS #7 message, placing the result into output, beginning at outOffset. The return value is the number of bytes placed into the output buffer.

Parameters

	output		The buffer into which this method will place output.
	outOffset		The offset into output where the method will begin placing data.
	special		Any special ASN.1 info, such as OPTIONAL.

Returns

The number of bytes placed into output.

Throws

PKCS7Exception - If the engine cannot execute some of the required functions. For example, if the message is EnvelopedData and the PKCS7EnvelopedData object has not been set with the recipient's public key, then this method would throw an exception.

readInit

public boolean readInit(byte[] input,
                        int inOffset,
                        int maxInputLen)
                 throws PKCS7Exception

Begins decoding the contentInfo of the given PKCS #7 message. This method will read the header information of the ContentInfo. If the input data contains all the necessary information, this method returns true. If this method needs more of the message, it returns false. Calling the readUpdate method before the readInit method will result in an exception.

This method creates the necessary content objects and stores any data beyond the PKCS #7 header information.

• Call the endOfMessage method to determine whether there is more message to input to this object.
• Call the bytesRead method to determine how many of the bytes of the input buffer this object actually read in the calls to readInit and readUpdate.

Parameters

	input		The content of a PKCS #7 message, or part of it.
	inOffset		The offset into input where the input begins.
	maxInputLen		The maximum number of bytes of input to examine with this method.

Returns

A boolean that indicates whether this method was given enough of the message to read all the header information.

• If the return value is true, do not call the readInit method again; call the readUpdate method instead.
• If the return value is false, do not call the readUpdate method; call the readInit method again with a larger part of the message.

  Throws

  PKCS7Exception - If the input is invalid or null.

readInit

public boolean readInit(byte[] input,
                        int inOffset,
                        int maxInputLen,
                        int special)
                 throws PKCS7Exception

Begins decoding the contentInfo of the given PKCS #7 message. This method will read the header information of the ContentInfo. If the input data contains all the necessary information, then this method returns true. If this method needs more of the message, then it returns false. Calling the readUpdate method before the readInit method will result in an exception.

This method creates the necessary content objects and stores any data beyond the PKCS #7 header information.

• Call the endOfMessage method to determine whether there is more message text to input to this object.
• Call the bytesRead method to determine how many of the bytes of the input buffer this object actually read in the calls to readInit and readUpdate.

Parameters

	input		The content of a PKCS #7 message, or part of it.
	inOffset		The offset into input where the input begins.
	maxInputLen		The maximum number of bytes of input to examine with this method.
	special		Any special ASN.1 info, such as OPTIONAL.

Returns

A boolean that indicates whether this method was given enough of the message to read all the header information.

• If the return value is true, do not call the readInit method again; call the readUpdate method instead.
• If the return value is false, do not call the readUpdate method; call the readInit method again with a larger part of the message.

  Throws

  PKCS7Exception - If the input is invalid or null.

readInit

public boolean readInit(byte[] input,
                        int inOffset,
                        int maxInputLen,
                        int special,
                        int maxBufferSize)
                 throws PKCS7Exception

Begins decoding the contentInfo of the given PKCS #7 message. This method will read the header information of the ContentInfo. If the input data contains all the necessary information, then this method returns true. If this method needs more of the message, then it returns false. Calling the readUpdate method before the readInit method will result in an exception.

This method creates the necessary content objects and stores any data beyond the PKCS #7 header information.

• Call the endOfMessage method to determine whether there is more message text to input to this object.
• Call the bytesRead method to determine how many of the bytes of the input buffer this object actually read in the calls to readInit and readUpdate.

Parameters

	input		The content of a PKCS #7 message, or part of it.
	inOffset		The offset into input where the input begins.
	maxInputLen		The maximum number of bytes of input to examine with this method.
	special		Any special ASN.1 info, such as OPTIONAL.
	maxBufferSize		the total size of the data to decode. The buffer of this size will be allocated to avoid future incremental increase of the buffer and copying data into it during the decoding of the data. This value must be equal or bigger than the size of the data!! If you don't know the size of the message or it is small, use different readInit().

Returns

A boolean that indicates whether this method was given enough of the message to read all the header information.

• If the return value is true, do not call the readInit method again; call the readUpdate method instead.
• If the return value is false, do not call the readUpdate method; call the readInit method again with a larger part of the message.

  Throws

  PKCS7Exception - If the input is invalid or null.

readUpdate

public int readUpdate(byte[] input,
                      int inOffset,
                      int maxInputLen)
               throws PKCS7Exception

Continues decoding the given contentInfo of a PKCS #7 message, returning the number of bytes that were read.

This method processes as much data as it can and places the rest into the internal buffer. Call getUnprocessedDataLen to find out the quantity of data in the internal buffer.

Parameters

	input		The content of a PKCS #7 message.
	inOffset		The offset into input where the data begins.
	maxInputLen		The maximum number of bytes of input to examine.

Returns

The number of bytes read.

Throws

PKCS7Exception - If the engine cannot execute some of the required functions. For example, if the message is EnvelopedData, this method will try to decrypt the session key with the private key. If the private key has not been loaded yet, or decrypting the envelope does not work, an exception will be thrown.

readFinal

public boolean readFinal()
                  throws PKCS7Exception

Finishes the process of decoding the contentInfo of this object. This method will verify that all the information was passed.

If the return value is false, it means that either an insufficient amount of data was passed or that the BER encoding is invalid.

Returns

A boolean indicating whether the user passed complete and valid BER encoding.

Throws

PKCS7Exception - If BER encoding is invalid.

bytesRead

public int bytesRead()

Indicates how many bytes were read during the calls to readInit and readUpdate.

endOfMessage

public boolean endOfMessage()

Indicates whether the end of the message has been reached.

Returns

A boolean that indicates whether the end of the message has been reached.

getUnprocessedDataLen

public int getUnprocessedDataLen()

Returns the number of bytes in the internal buffer that contains the unprocessed data.

Returns

The number of bytes of unprocessed data.

clone

public Object clone()
             throws CloneNotSupportedException

Overrides the default clone method to get a deeper clone.

Returns

A new ContentInfo object, a copy of this object.

Throws

CloneNotSupportedException - If the cloning operation is not successful.

clearInternalContentBuffer

public void clearInternalContentBuffer()

Clears the internal working buffer that contains the entire ContentInfo encoding of a newly read and parsed message. A subsequent write operation (with the writeMessage() method) will cause the encoding to be re-generated from the component parts. For virtually all uses of reading and writing messages you do not need this method and its use is discouraged.

clearSensitiveData

public void clearSensitiveData()

Clears any sensitive data. The finalizer will clear the data, but it is not known when the garbage collector will call the finalizer. This method clears all sensitive data as soon as possible.