iaik.pkcs.pkcs9
Class ExtensionRequest

java.lang.Object
  |
  +--iaik.asn1.structures.AttributeValue
        |
        +--iaik.pkcs.pkcs9.ExtensionRequest

All Implemented Interfaces:

ASN1Type

public class ExtensionRequest

extends AttributeValue

The PKCS#9 ExtensionRequest attribute.

PKCS#9 specifies the ExtensionRequest attribute to may be included in a PKCS#10 CertificateRequest if the requestor wishes to indicate that some certificate extension shall be included in the certificate to be issued by the CA in response to the certificate request:

 extensionRequest ATTRIBUTE ::= {
   WITH SYNTAX ExtensionRequest
   SINGLE VALUE TRUE
   ID pkcs-9-at-extensionRequest
 }

 ExtensionRequest ::= Extensions
 

If the requestor, for instance, wishes to indicate to issue a certificate for KeyUsage digitalSignature and nonRepudiation, she/he may include a corresponding KeyUsage extension in the request:

 CertificateRequest request = ...;
 Attribute[] attributes = new Attribute[1];
 // add a ExtensionRequest attribute for KeyUsage 
 KeyUsage keyUsage = new KeyUsage(KeyUsage.digitalSignature | KeyUsage.nonRepudiation);
 ExtensionRequest extensionRequest = new ExtensionRequest();
 extensionRequest.addExtension(keyUsage);
 attributes[0] = new Attribute(extensionRequest);
 // now set the attributes
 request.setAttributes(attributes);
 // sign the request
 request.sign(...);
 ...
 

On the receiving end, the CA may query for an ExtensionRequest attribute included in the certificate request:

 CertificateRequest request = new CertificateRequest(is);
 // verify the request
 if (request.verify()) {
   System.out.println("CertificateRequest verify ok.");
 } else {
   throw new RuntimeException("CertificateRequest verify error.");
 }       
 // look for an ExtensionRequest included
 ExtensionRequest extensionRequest = (ExtensionRequest)request.getAttributeValue(ExtensionRequest.oid);
 if (extensionRequest != null) {
    Enumeration extensions = extensionRequest.listExtensions();
    ...
 }
 

Version:

File Revision 10

See Also:

Attribute, AttributeValue, CertificateRequest, X509Extensions, V3Extension

Field Summary

static ObjectID

oid The attributeType object identifier of the PKCS#9 ExtensionRequest attribute.

Constructor Summary

ExtensionRequest()
Default constructor.

ExtensionRequest(ASN1Object obj)
Creates an ExtensionRequest from its ASN.1 representation.

Method Summary

void	addExtension(V3Extension e) Adds the given X509v3 extension.
int	countExtensions() Returns the number of extensions included in this ExtensionRequest.
void	decode(ASN1Object obj) Decodes the given ASN.1 ExtensionRequest object for parsing the internal structure.
ObjectID	getAttributeType() Returns the OID (1.2.840.113549.1.9.14) identifying the ExtensionRequest attribute type.
Set	getCriticalExtensionOIDs() Returns a Set of the OID strings identifying the extension(s) that are marked CRITICAL in this ExtensionRequest.
V3Extension	getExtension(ObjectID oid) Returns a specific extension, identified by its object identifier.
byte[]	getExtensionValue(String oid) Returns a byte array representing the DER encoding of the extension value identified by the passed-in OID string.
Set	getNonCriticalExtensionOIDs() Returns a Set of the OID strings for the extension(s) marked NON-CRITICAL in this ExtensionRequest.
boolean	hasExtensions() Checks, if there are any extensions included into this ExtensionRequest.
boolean	hasUnsupportedCriticalExtension() Returns true if there are unsupported critical extensions.
Enumeration	listExtensions() Returns an enumeration of all extensions included into this ExtensionRequest.
void	removeAllExtensions() Removes all extensions from this ExtensionRequest.
boolean	removeExtension(ObjectID oid) Removes the extension specified by its object identifier.
ASN1Object	toASN1Object() Returns this ExtensionRequest as ASN1Object.
String	toString() Returns a string representation of this ExtensionRequest.

Methods inherited from class iaik.asn1.structures.AttributeValue

getName

Methods inherited from class java.lang.Object

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

Field Detail

oid

public static final ObjectID oid

The attributeType object identifier of the PKCS#9 ExtensionRequest attribute. The corresponding OID string is "1.2.840.113549.1.9.14".

Constructor Detail

ExtensionRequest

public ExtensionRequest()

Default constructor. Use method addExtension for adding any extension as required.

ExtensionRequest

public ExtensionRequest(ASN1Object obj)
                 throws CodingException

Creates an ExtensionRequest from its ASN.1 representation.

Parameters:

the - ExtensionRequest as ASN1Object

Throws:

CodingException - if an error occurs when parsing the ASN1Object

Method Detail

decode

public void decode(ASN1Object obj)
            throws CodingException

Decodes the given ASN.1 ExtensionRequest object for parsing the internal structure.

Parameters:

obj - the ExtensionRequest as ASN1Object

Throws:

CodingException - if an error occurs when parsing the ASN1Object

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException

Returns this ExtensionRequest as ASN1Object.

Returns:

this ExtensionRequest as ASN1Object

Throws:

CodingException - if no time value has been set

getAttributeType

public ObjectID getAttributeType()

Returns the OID (1.2.840.113549.1.9.14) identifying the ExtensionRequest attribute type.

Overrides:

getAttributeType in class AttributeValue

Returns:

the OID identifying the ExtensionRequest attribute type.

getCriticalExtensionOIDs

public Set getCriticalExtensionOIDs()

Returns a Set of the OID strings identifying the extension(s) that are marked CRITICAL in this ExtensionRequest.

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 Set getNonCriticalExtensionOIDs()

Returns a Set of the OID strings for the extension(s) marked NON-CRITICAL in this ExtensionRequest.

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.

getExtensionValue

public byte[] getExtensionValue(String oid)

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

The oid string is represented by a set of positive whole numbers 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 can be identified by its object identifier, given in the extnID field. The value of the extension is represented as ASN.1 OCTET STRING data structure in the extnValue field. Only one instance of a particular extension may be present in a particular ExtensionRequest.

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 itsself.

Parameters:

oid - the Object Identifier of the extension to be queried for

Returns:

the DER encoded ASN.1 representation of extension value or null if it is not present

addExtension

public void addExtension(V3Extension e)
                  throws X509ExtensionException

Adds the given X509v3 extension.

The extension to be added shall be an implemented V3Extension. Extensions are managed by the X509Extensions class which maintaines two hashtables, one for recording critical extensions, and the other for non-critical extensions. This method only calls the addExtension method of the X509Extensions class for putting the given extension into the proper hashtable. Note that only the DER encoded extension value is written to the hashtable using the OID of the extension as key. If an extension with the same object ID already exists, it is replaced.

For instance:

 KeyUsage keyUsage = new KeyUsage(KeyUsage.digitalSignature | KeyUsage.nonRepudiation);
 ExtensionRequest extensionRequest = new ExtensionRequest();
 extensionRequest.addExtension(keyUsage);
 

Parameters:

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

Throws:

X509ExtensionException - if an error occurs while DER encoding the extension

removeExtension

public boolean removeExtension(ObjectID oid)

Removes the extension specified by its object identifier.

Parameters:

objectID - the object ID of the extension to remove

Returns:

true if the extension has been successfully removed, false otherwise

removeAllExtensions

public void removeAllExtensions()

Removes all extensions from this ExtensionRequest.

listExtensions

public Enumeration listExtensions()

Returns an enumeration of all extensions included into this ExtensionRequest.

The returned enumeration may contain unknown extensions (instances of UnknownExtension if there are any extensions included in this ExtensionRequest, for which there exists no registered implementation, and it may contain error extensions (instances of ErrorExtension) indicating extensions which cannot be parsed properly because of some kind of error.

Returns:

an enumeration of the extensions, or null if there are no extensions present at all

hasExtensions

public boolean hasExtensions()

Checks, if there are any extensions included into this ExtensionRequest.

Returns:

true if there are extensions, false if not

hasUnsupportedCriticalExtension

public boolean hasUnsupportedCriticalExtension()

Returns true if there are unsupported critical extensions.

Returns:

true, if there are unsupported critical extensions

countExtensions

public int countExtensions()

Returns the number of extensions included in this ExtensionRequest.

Returns:

the number of extensions

getExtension

public V3Extension getExtension(ObjectID oid)
                         throws X509ExtensionInitException

Returns a specific extension, identified by its object identifier.

If the extension identified by the given oid cannot be initialized for some reason, an X509ExtensionInitException is thrown. If the requested extension is an unknown extension, which is not supported by a registered implementation, this method creates and returns an UnknownExtension which may be queried for obtaining as much information as possible about the unknown extension.

Parameters:

objectID - the object ID of the extension

Returns:

the desired extension or null if the requested extension is not present

Throws:

X509ExtensionInitException - if the extension can not be initialized

toString

public String toString()

Returns a string representation of this ExtensionRequest.

Overrides:

toString in class AttributeValue

Returns:

this ExtensionRequest as string