com.rsa.certj.cert

Class X509V3Extensions

java.lang.Object
  |
  +--com.rsa.certj.cert.X509V3Extensions

All Implemented Interfaces:

Cloneable, Serializable

public class X509V3Extensions

extends Object

implements Cloneable, Serializable

This class builds and holds the collection of X.509 version 3 extensions. The X509V3Extension class, the superclass of all the individual extension type classes, is where the data is stored, encoded, and decoded. For example, for a KEY_USAGE extension, use the KeyUsageExtension class, which is a subclass of X509V3Extension.

The ASN.1 definition is as follows:

 Extensions ::= SEQUENCE OF Extension

 Extension ::= SEQUENCE {
   extnID      OBJECT IDENTIFIER
   critical    BOOLEAN DEFAULT FALSE
   extnValue   OCTET STRING }

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

See Also

Serialized Form

Field Summary

static int	X509_EXT_TYPE_CERT Specifies the CertExtensions type.
static int	X509_EXT_TYPE_CRL Specifies the CRLExtensions type.
static int	X509_EXT_TYPE_CRL_ENTRY Specifies the CRLEntryExtensions type.
static int	X509_EXT_TYPE_OCSP_REQUEST Specifies the OCSPRequestExtensions type.
static int	X509_EXT_TYPE_OCSP_SINGLE Specifies the OCSPSingleExtensions type.

Constructor Summary

X509V3Extensions(byte[] extensionsBER, int offset, int special, int extType)

Constructs a signed X509V3Extensions object and initializes it with the value given by extensionsBER, beginning at offset, the BER encoding of X.509 v3 extensions.

X509V3Extensions(int extType)

Constructs an empty X509V3Extensions object.

Method Summary

int	addV3Extension(X509V3Extension extension) Adds a new X.509 v3 defined extension.
Object	clone() Overrides the default clone method to get a deeper clone.
int	getDEREncoding(byte[] encoding, int offset, int special) Places the DER encoding of the X.509 extensions in this object into encoding, beginning at offset.
int	getDERLen(int special) Returns the number of bytes of the DER encoding of these X.509 extensions.
X509V3Extension	getExtensionByIndex(int index) Gets the extension at specified index in the list.
X509V3Extension	getExtensionByType(int extensionType) Gets the extension of the given extensionType.
int	getExtensionCount() Gets the number of extensions in this object.
int	getExtensionsType() Gets the extensions type.
static int	getNextBEROffset(byte[] extensionsBER, int offset) Given extensionsBER, the BER encoding of the X.509 extensions, beginning at offset, finds the index to the next element in the encoding.

Methods inherited from class java.lang.Object

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

Field Detail

X509_EXT_TYPE_CERT

public static final int X509_EXT_TYPE_CERT

Specifies the CertExtensions type.

X509_EXT_TYPE_CRL

public static final int X509_EXT_TYPE_CRL

Specifies the CRLExtensions type.

X509_EXT_TYPE_CRL_ENTRY

public static final int X509_EXT_TYPE_CRL_ENTRY

Specifies the CRLEntryExtensions type.

X509_EXT_TYPE_OCSP_SINGLE

public static final int X509_EXT_TYPE_OCSP_SINGLE

Specifies the OCSPSingleExtensions type.

X509_EXT_TYPE_OCSP_REQUEST

public static final int X509_EXT_TYPE_OCSP_REQUEST

Specifies the OCSPRequestExtensions type.

Constructor Detail

X509V3Extensions

public X509V3Extensions(int extType)
                 throws CertificateException

Constructs an empty X509V3Extensions object.

Parameters

extType

An int that specifies the type of these extensions. It must be one of the X509_EXT_TYPE_* fields previously defined in this class.

Throws

CertificateException - If the specified type is invalid.

X509V3Extensions

public X509V3Extensions(byte[] extensionsBER,
                        int offset,
                        int special,
                        int extType)
                 throws CertificateException

Constructs a signed X509V3Extensions object and initializes it with the value given by extensionsBER, beginning at offset, the BER encoding of X.509 v3 extensions.

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

      extensions   [3] EXPLICIT Extensions OPTIONAL

To indicate that the DER encoding of the X509Extensions object should follow any special circumstances, use the special argument. Set special to any special circumstances of the DER encoding. For example, to indicate the following:

      extensions   [3] EXPLICIT Extensions OPTIONAL

Pass in:

      special = (ASN1.CONTEXT_EXPLICIT | 3 | ASN1.OPTIONAL);

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

	extensionsBER		The BER encoding of an X.509 v3 extension.
	offset		The offset into extensionsBER where the encoding begins.
	special		The special BER circumstances of the encoding, if there are any.
	extType		The type of these extensions. It must be one of the X509_EXT_TYPE_* fields previously defined in this class.

Throws

CertificateException - If the BER is not a valid X.509AExtensions certificate or if the specified extensions type is invalid.

Method Detail

getNextBEROffset

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

Given extensionsBER, the BER encoding of the X.509 extensions, beginning at offset, finds the index to the next element in the encoding. In other words, gets the next offset after the extensions.

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

Parameters

	extensionsBER		The BER encoding of the X.509 extensions.
	offset		The offset into extensionsBER 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 these X.509 extensions. If this object is not set with values, then this method returns zero.

The ASN.1 definition is previously defined in this class. An X.509 extensions object can be part of a certificate (or some other construct), and it may have a different tag, caused by IMPLICIT or EXPLICIT. This can affect the length. For example, suppose the definition is as follows:

   extensions   [3] EXPLICIT Extensions OPTIONAL

To indicate that the DER encoding of the X509V3Extentions object should follow any special circumstances, use the special argument. Set special to any special circumstances of the DER encoding. For example, to indicate the following:

   extensions   [3] EXPLICIT Extensions OPTIONAL

Pass in the following:

      special = (ASN1.CONTEXT_EXPLICIT | 3 | ASN1.OPTIONAL);

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

Returns

The number of bytes the DER encoding of these X.509 extensions.

getDEREncoding

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

Places the DER encoding of the X.509 extensions in this object into encoding, beginning at offset. To determine the length of the encoding, call getDERLen. If this object is not yet set with X.509 extensions, then this method places nothing into the array and returns zero. The ASN.1 definition, previously defined in this class, means the tag will be 0x30. However, an extensions object can be part of a certificate (or some other construct), and it might have a different tag caused by IMPLICIT or EXPLICIT. For example, suppose the X.509 definition is as follows:

      extensions   [3] EXPLICIT Extensions OPTIONAL

To indicate that the DER encoding of the X509V3Esxtensions object should follow any special circumstances, use the special argument. Set special to any special circumstances of the DER encoding. For example, to indicate the following:

   extensions   [3] EXPLICIT Extensions OPTIONAL

Pass in:

      special = (ASN1.CONTEXT_EXPLICIT | 3 | ASN1.OPTIONAL);

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

	encoding		The byte array into which the result will be placed.
	offset		The offset into encoding where writing begins.
	special		The special DER circumstances of the encoding, if there are any.

Returns

The number of bytes placed into encoding.

addV3Extension

public int addV3Extension(X509V3Extension extension)
                   throws CertificateException

Adds a new X.509 v3 defined extension. If the method cannot add the extension, this method throws an exception. This can occur if the object is not set with data when this method is called. If this object already contains an extension of the type of the input value, the previous extension is deleted and the new one is added.

Parameters

extension

An object that contains the extension value. See each X509V3Extension class for information about an extension of this type.

Returns

The index into the list for this extension.

Throws

CertificateException - If the extension is of the wrong type or null.

getExtensionCount

public int getExtensionCount()

Gets the number of extensions in this object.

Returns

An int that contains the number of extensions.

getExtensionsType

public int getExtensionsType()

Gets the extensions type. It should be one of the following: Certificate, CRL, or CRLEntry.

Returns

A flag that specifies the extensions type: X509_EXT_TYPE_CERT for Certificate extensions, X509_EXT_TYPE_CRL for CRL extensions, and X509_EXT_TYPE_CRL_ENTRY for CRLEntry extensions.

getExtensionByIndex

public X509V3Extension getExtensionByIndex(int index)
                                    throws CertificateException

Gets the extension at specified index in the list. If there is no extension at that index, this method returns a null.

Parameters

index

The index into the list of the X.509 extension to retrieve.

Returns

A new X509V3Extension object that contains the data.

Throws

CertificateException - If index is invalid.

getExtensionByType

public X509V3Extension getExtensionByType(int extensionType)
                                   throws CertificateException

Gets the extension of the given extensionType. The possible values of extensionType are given in the X509V3Extension class. If this object contains no extension of the desired type, this method returns null.

Parameters

extensionType

The flag indicating the extension type. See the X509V3Extension class for a list of possible values.

Returns

A new X509V3Extension object that contains the data. If there is no extension of specified type, this method returns NULL.

Throws

CertificateException - If there are no extensions.

clone

public Object clone()
             throws CloneNotSupportedException

Overrides the default clone method to get a deeper clone.

Returns

A new X509V3Extensions object, a copy of this object.

Throws

CloneNotSupportedException - If the cloning operation is not successful.