ExtensionRequest (6.0 API Documentation)

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 requester 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 requester, 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 12
See Also:: Attribute, AttributeValue, CertificateRequest, X509Extensions, V3Extension

Field Summary

Fields
Modifier and Type Field and Description

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

Fields
Modifier and Type	Field and Description
`static ObjectID`	`oid` The attributeType object identifier of the PKCS#9 ExtensionRequest attribute.

Constructor Summary

Constructors
Constructor and Description

ExtensionRequest()
Default constructor.

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

Constructors
Constructor and Description
`ExtensionRequest()` Default constructor.
`ExtensionRequest(ASN1Object obj)` Creates an ExtensionRequest from its ASN.1 representation.

Method Summary

Methods
Modifier and Type	Method and Description
`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.
`java.util.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(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()` Returns a Set of the OID strings for the extension(s) marked NON-CRITICAL in this ExtensionRequest.
`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 included into this ExtensionRequest.
`boolean`	`hasUnsupportedCriticalExtension()` Returns true if there are unsupported critical extensions.
`java.util.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.
`java.lang.String`	`toString()` Returns a string representation of this ExtensionRequest.

Methods inherited from class iaik.asn1.structures.AttributeValue
getName, multipleAllowed

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:
    obj - 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.
    
    Specified by:
    
    getAttributeType in class AttributeValue
    
    Returns:
    the OID identifying the ExtensionRequest attribute type.
  - getCriticalExtensionOIDs
```
public java.util.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 java.util.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(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 in a particular certificate.
    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
  - addExtension
```
public void addExtension(V3Extension e)
                  throws X509ExtensionException
```
    Adds the given X509v3 extension.
    The extension to be added shall be an implemented V3Extension. 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:
    oid - 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 java.util.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:
    oid - 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 java.lang.String toString()
```
    Returns a string representation of this ExtensionRequest.
    
    Specified by:
    
    toString in class AttributeValue
    
    Returns:
    this ExtensionRequest as string

Class ExtensionRequest

Field Summary

Constructor Summary

Method Summary

Methods inherited from class iaik.asn1.structures.AttributeValue

Methods inherited from class java.lang.Object

Field Detail

oid

Constructor Detail

ExtensionRequest

ExtensionRequest

Method Detail

decode

toASN1Object

getAttributeType

getCriticalExtensionOIDs

getNonCriticalExtensionOIDs

getExtensionValue

getRawExtensionValue

addExtension

removeExtension

removeAllExtensions

listExtensions

hasExtensions

hasUnsupportedCriticalExtension

countExtensions

getExtension

toString