iaik.x509

Class X509Extensions

java.lang.Object

iaik.x509.X509Extensions

Direct Known Subclasses:

AttributeCertificateExtensions, OCSPExtensions

public class X509Extensions
extends java.lang.Object

This class is used to deal with X.509v3 certificate and X.509v2 CRL extensions.

The X.509v3 certificate format has been introduced by ISO/IEC and ANSI X9 to add the the Extensions field to the X.509v2 certificate format for including some additional information. Extension support for CRLs has been introduced by the X.509v2 CRL format (see RFC 3280). An extension may be a defined standard extension (e.g. certificatePolicies, keyUsage, ...), or it may be a private extension providing some community-specific information. If an extension is marked as critical, but the certificate handling software cannot parse this extension, the appertaining certificate has to be rejected. Non-Critical extensions can be ignored, if they cannot be handled (i.e. of unknown state).

In ASN.1, the Extensions field is defined as a SEQUENCE of Extension:

 Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension
 
 Extension  ::=  SEQUENCE  {
   extnID      OBJECT IDENTIFIER,
   critical    BOOLEAN DEFAULT FALSE,
   extnValue   OCTET STRING  }
 

where critical specifies whether an extension has to be treated as being critical or not; the default value is FALSE. An extension can be identified by its object identifier, given in the extnID field. The value of the extension is represented as ASN.1 encoded OCTET STRING data structure in the extnValue field. Only one instance of a particular extension may be present in a particular certificate.

The X509v3 certificate profile presented in RFC 3280 prescribes that confirming CAs must support the AuthorityKeyIdentifier, SubjectKeyidentifier, BasicConstraints, KeyUsage and CertificatePolicies extensions. The SubjectAltName extensions has to be supported if certificates with empty subject fields are issued.

This class consists of two parts:

• a static part: is responsible for registering implementations of extensions
• a dynamic part: manages the extensions

Every class which implements a specific extension must first register itself, e.g.:

 MyPrivateExtension extends V3Extension {
   ...
   public static final ObjectID oid = ...;
 
 }
 
 X509Extensions.register(MyPrivateExtension.oid, MyPrivateExtension.class);
 

At this time, per default, implementations of the following extensions are registered:

• X.509v3 extensions:
• AuthorityKeyIdentifier
• BasicConstraints
• CertificatePolicies
• CRLDistributionPoints
• ExtendedKeyUsage
• IssuerAltName
• KeyUsage
• NameConstraints
• PolicyConstraints
• PolicyMappings
• PrivateKeyUsagePeriod
• SubjectAltName
• SubjectKeyIdentifier
• SubjectDirectoryAttributes
• InhibitAnyPolicy
• FreshestCRL
• Private Internet extensions:
• AuthorityInfoAccess
• SubjectInfoAccess
• SMIMECapabilities
• Netscape Certificate Extensions:
• NetscapeBaseUrl
• NetscapeCaPolicyUrl
• NetscapeCaRevocationUrl
• NetscapeCertRenewalUrl
• NetscapeCertType
• NetscapeComment
• NetscapeRevocationUrl
• NetscapeSSLServerName
• Qualified Certificate Extensions
:
• BiometricInfo
• QCStatements
• OCSP Certificate Extensions:
  • NoCheck
• IACO MRTD Certificate Extensions:
  • NameChange
  • DocumentTypeList
• Private Certificate Extensions:
• PublicAuthorityIdentifier ("Verwaltungseigenschaft", use in Autrian e-government)
• X.509v2 CRL and CRL entry extensions:
• CRLNumber
• DeltaCRLIndicator
• IssuingDistributionPoint
• ReasonCode
• HoldInstructionCode
• InvalidityDate
• CertificateIssuer
• ITU-T X.509 CRL Extensions:
• ExpiredCertsOnCRL

The dynamic part of this class provides a variety of useful methods for managing extensions. Most of these methods are also provided by classes like X509Certificate or X509CRL, which internally use a X509Extensions object to manage their certificate or crl extensions, respectively. An application can directly call these methods for adding, accessing and removing extensions of a X509Certificate or, for instance, X509CRL object.

An extension is added by calling method addExtension and can be retrieved by calling method getExtension(ObjectID) using an oid to identify an particular extension. If an extension cannot be initialized properly a X509ExtensionInitException is thrown. If the extension just initialized is an unknown extension (i.e. an extension, for which there exists no registered implementation), an UnknownExtension object is created and returned by the getExtension method to be parsed for obtaining as much information as possible from the unknown extension. When using the listExtensions method for obtaining all the extensions included in the actual X509Extensions object, an enumeration is returned containing an UnknownExtension for any included unknown extension, and an ErrorExtension for any extension which cannot be initialized because of some kind of error. Note the difference: Within the IAIK-JCE environment, an unknown extension denotes an extension, for which there exists no registered implementation; whereas an error extension represents an - registered or unknown - erroneous extension which cannot be parsed properly.

Version:

File Revision 70

See Also:

V3Extension, X509Certificate, RevokedCertificate, X509CRL

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Hashtable	critical_extensions Repository for critical extensions.
protected java.util.Hashtable	noncritical_extensions Repository for noncritical extensions.

Constructor Summary

Constructors

Constructor and Description
X509Extensions() Default Constructor.
X509Extensions(ASN1Object extensions) Creates a new X.509Extensions object from an ASN1Object.
X509Extensions(int initialCriticalExtensionsCapacity, int initialNoncriticalExtensionsCapacity) Creates an X509Extensions object with the given initial capacities for the critical_extensions and noncritical_extensions hashtables.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	addExtension(V3Extension e) Adds an extension to this X509Extensions object.
int	countExtensions() Returns the number of extensions included in this X509Extensions object.
static V3Extension	create(ObjectID oid) Returns the implementation of the specified extension defined through an ASN.1 ObjectID.
protected void	createExtensionsTable(boolean critical) Creates the requested extensions repository.
void	decode(ASN1Object asn1Obj) Initializes the extensions from an ASN1Object.
java.util.Set	getCriticalExtensionOIDs() Gets a Set of the OID strings for the extension(s) marked CRITICAL in this X509Extensions object.
V3Extension	getExtension(ObjectID oid) Returns a particular extension, specified by its object ID.
byte[]	getExtensionValue(java.lang.String oid) Returns a byte array representing the DER encoding of the extnValue OCTET STRING field of the extension identified by the given OID string.
java.util.Set	getNonCriticalExtensionOIDs() Gets a Set of the OID strings for the extension(s) marked NON-CRITICAL in this X509Extensions object.
byte[]	getRawExtensionValue(java.lang.String oid) Returns a byte array representing the DER encoding of the extension value identified by the given OID string.
boolean	hasExtensions() Checks, if there are any extensions currently maintained by this X509Extensions object.
boolean	hasUnsupportedCriticalExtension() Returns true if there are unsupported critical extensions.
java.util.Enumeration	listExtensions() Returns an enumeration of all extensions currently maintained by this X509Extensions object.
protected void	parseExtensions(ASN1Object extObj) Initializes the extensions from an ASN1Object.
static void	register(ObjectID oid, java.lang.Class cl) Registers a new implementation for a X.509 certificate or CRL extension.
void	removeAllExtensions() Removes all extensions currently maintained by this X509Extensions object.
boolean	removeExtension(ObjectID oid) Removes an extension, identified by its object ID.
ASN1Object	toASN1Object() Returns this X509Extensions object as (SEQUENCE) ASN1Object.
java.lang.String	toString() Returns a string that represents the contents of the extensions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

critical_extensions

protected volatile java.util.Hashtable critical_extensions

Repository for critical extensions.

noncritical_extensions

protected volatile java.util.Hashtable noncritical_extensions

Repository for noncritical extensions.

Constructor Detail

X509Extensions

public X509Extensions()

Default Constructor. The initial capacity for the critical_extensions hashtable is set to 4, and for the noncritical_extensions hashtable is set to 11. With a load factor of 0.75 this means that 3 extensions can be put into the critical_extensions table before its size is increased, and 8 extensions into the noncritical_extensions table before it is increased.

X509Extensions

public X509Extensions(int initialCriticalExtensionsCapacity,
              int initialNoncriticalExtensionsCapacity)

Creates an X509Extensions object with the given initial capacities for the critical_extensions and noncritical_extensions hashtables.

Parameters:

initialCriticalExtensionsCapacity - the initial capacity of the critical_extensions table

initialNoncriticalExtensionsCapacity - the initial capacity of the noncritical_extensions table

X509Extensions

public X509Extensions(ASN1Object extensions)
               throws X509ExtensionException

Creates a new X.509Extensions object from an ASN1Object.

The given ASN1Object has the ASN.1 type "SEQUENCE of Extensions", and may have been created by calling the toASN1Objetct method.

Parameters:

extensions - the extensions as ASN1Object

Throws:

X509ExtensionException - if the extensions cannot be parsed

Method Detail

create

public static V3Extension create(ObjectID oid)
                          throws java.lang.InstantiationException

Returns the implementation of the specified extension defined through an ASN.1 ObjectID.

This method belongs to the static part of this class.

Parameters:

oid - the ObjectID of the extension.

Returns:

the implementation of the extension with this oid

Throws:

java.lang.InstantiationException - if the internal factory couldn't create an instance of requested type

register

public static void register(ObjectID oid,
            java.lang.Class cl)

Registers a new implementation for a X.509 certificate or CRL extension. This method belongs to the static part of this class.

Parameters:

oid - the object id of the extension to be registered

cl - the class which implements this extension

addExtension

public boolean addExtension(V3Extension e)
                     throws X509ExtensionException

Adds an extension to this X509Extensions object.

If an extension with the same object ID already exists, it is replaced. In this case this method returns true, otherwise - if there exists no extension with the same object ID - this method returns false. Use method getExtension(ObjectID) to get some particular extension from the X509Extensions object.

Parameters:

e - the X509v3 extension to add to the list of extensions

Returns:

true, if an extension with the same object id has been replaced, or false if there has yet not been included any extension with the same ObjectID

Throws:

X509ExtensionException - if an error occurs while DER encoding the extension

removeExtension

public boolean removeExtension(ObjectID oid)

Removes an extension, identified by its object ID.

Parameters:

oid - the object ID of the extension to remove

Returns:

true if the extension successfully has been removed, false otherwise

removeAllExtensions

public void removeAllExtensions()

Removes all extensions currently maintained by this X509Extensions object.

listExtensions

public java.util.Enumeration listExtensions()

Returns an enumeration of all extensions currently maintained by this X509Extensions object.

The enumeration returned by this method will contain an UnknownExtension for any included unknown extension, and an ErrorExtension for any extension which cannot be initialized because it is burdened with some kind of error.

Returns:

an enumeration of the extensions

hasExtensions

public boolean hasExtensions()

Checks, if there are any extensions currently maintained by this X509Extensions object.

Returns:

true if there are extensions, false if not

countExtensions

public int countExtensions()

Returns the number of extensions included in this X509Extensions object.

Returns:

the number of extensions

getExtension

public V3Extension getExtension(ObjectID oid)
                         throws X509ExtensionInitException

Returns a particular extension, specified by its object ID.

If the extension is an unknown extension, an UnknownExtension is returned. If the extension cannot be initialized properly because of some error, an X509ExtensionInitException is thrown.

Parameters:

oid - the object ID of the extension

Returns:

the desired extension if it is available, or null if not

Throws:

X509ExtensionInitException - if the extension can not be initialized

getCriticalExtensionOIDs

public java.util.Set getCriticalExtensionOIDs()

Gets a Set of the OID strings for the extension(s) marked CRITICAL in this X509Extensions object.

Returns:

a Set (or an empty Set if none are marked critical) of the extension OID strings for extensions that are marked critical. If there are no extensions present at all, then this method returns null

getNonCriticalExtensionOIDs

public java.util.Set getNonCriticalExtensionOIDs()

Gets a Set of the OID strings for the extension(s) marked NON-CRITICAL in this X509Extensions object.

Returns:

a Set (or an empty Set if none are marked non-critical) of the extension OID strings for extensions that are marked non-critical. If there are no extensions present at all, then this method returns null.

hasUnsupportedCriticalExtension

public boolean hasUnsupportedCriticalExtension()

Returns true if there are unsupported critical extensions.

Returns:

true, if there are unsupported critical extensions

getExtensionValue

public byte[] getExtensionValue(java.lang.String oid)

Returns a byte array representing the DER encoding of the extnValue OCTET STRING field of the extension identified by the given OID string.

The OID string is represented by a set of non-negative integers separated by periods, e.g. "2.5.29.15" for the KeyUsage extension.

In ASN.1, the Extensions field is defined as a SEQUENCE of Extension:

 Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension
 
 Extension  ::=  SEQUENCE  {
   extnID      OBJECT IDENTIFIER,
   critical    BOOLEAN DEFAULT FALSE,
   extnValue   OCTET STRING  }
 

where critical specifies whether an extension has to be treated as being critical or not; the default value is FALSE. An extension is identified by its object identifier, specified in the extnID field. The extnValue field is an OCTET STRING which contains the DER encoding of the specific extension's ASN.1 representation itself. Only one instance of a particular extension may be present.

The byte value returned by this method represents the DER encoding of the extnValue (OCTET_STRING) from above, and the value of this OCTET STRING represents the DER encoding of the specific extension's ASN.1 representation itself. If you want to get the DER encoding of the specific extension's ASN.1 representation itself (not wrapped in an OCTET STRING), use method getRawExtensionValue.

Parameters:

oid - the object identifier of the extension to be searched for

Returns:

the DER encoded extnValue OCTET STRING or null if no extension with the specified oid is present

getRawExtensionValue

public byte[] getRawExtensionValue(java.lang.String oid)

Returns a byte array representing the DER encoding of the extension value identified by the given OID string.

The OID string is represented by a set of non-negative integers separated by periods, e.g. "2.5.29.15" for the KeyUsage extension.

In ASN.1, the Extensions field is defined as a SEQUENCE of Extension:

 Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension
 
 Extension  ::=  SEQUENCE  {
   extnID      OBJECT IDENTIFIER,
   critical    BOOLEAN DEFAULT FALSE,
   extnValue   OCTET STRING  }
 

where critical specifies whether an extension has to be treated as being critical or not; the default value is FALSE. An extension is identified by its object identifier, specified in the extnID field. The extnValue field is an OCTET STRING which contains the DER encoding of the specific extension's ASN.1 representation itself. Only one instance of a particular extension may be present.

The byte value returned by this method represents the DER encoding of the specific extension's ASN.1 representation itself (i.e. the value of the extnValue OCTET STRING).

Parameters:

oid - the object identifier of the extension to be searched for

Returns:

the DER encoded ASN.1 representation of the extension or null if no extension with the specified oid is present

parseExtensions

protected void parseExtensions(ASN1Object extObj)
                        throws X509ExtensionException

Initializes the extensions from an ASN1Object.

The ASN1Object must be an ASN.1 data structure "SEQUENCE of Extensions", as can be found in X509v3 certificates or X509v2 CRLs.

The given ASN1Object is parsed for any included extension. For getting an included extension call method getExtension For getting an enumeration of all included extensions, use method listExtensions().

Parameters:

extObj - the ASN.1 data structure "SEQUENCE of Extensions"

Throws:

X509ExtensionException - if there is an error while parsing the extensions

See Also:

UnknownExtension

decode

public void decode(ASN1Object asn1Obj)
            throws X509ExtensionException

Initializes the extensions from an ASN1Object.

The ASN1Object must be an ASN.1 data structure "SEQUENCE of Extensions", as can be found in X509v3 certificates or X509v2 CRLs.

The given ASN1Object is parsed for any included extension. For getting an included extension call method getExtension For getting an enumeration of all included extensions, use method listExtensions().

Parameters:

asn1Obj - the ASN.1 data structure "SEQUENCE of Extensions"

Throws:

X509ExtensionException - if there is an error while parsing the extensions

See Also:

UnknownExtension

toASN1Object

public ASN1Object toASN1Object()
                        throws X509ExtensionException

Returns this X509Extensions object as (SEQUENCE) ASN1Object. The ASN1Object has the ASN.1 type "SEQUENCE of Extensions".

Returns:

the extensions as ASN1Object.

Throws:

X509ExtensionException - if the extensions could not be created

createExtensionsTable

protected void createExtensionsTable(boolean critical)

Creates the requested extensions repository.

Parameters:

critical - whether to create the repository (hashtable) for the critical or the non critical extensions

toString

public java.lang.String toString()

Returns a string that represents the contents of the extensions.

Overrides:

toString in class java.lang.Object

Returns:

the string representation