iaik.x509

Class V3Extension

java.lang.Object

iaik.x509.V3Extension

Direct Known Subclasses:

AcceptableResponses, ArchiveCutoff, AuthorityKeyIdentifier, BasicConstraints, BiometricInfo, CertificateIssuer, CertificateIssuer, CertificatePolicies, CertificateTransparencyPoison, CertificateTransparencyRedaction, CRLDistPointsSyntax, CrlID, CRLNumber, DeltaCRLIndicator, DeltaCRLIndicator, EntrustVersInfo, ErrorExtension, ExtendedKeyUsage, HoldInstructionCode, HoldInstructionCode, InfoAccess, InhibitAnyPolicy, InhibitAnyPolicy, InvalidityDate, InvalidityDate, IssuerAltName, IssuingDistributionPoint, IssuingDistributionPoint, KeyAttributes, KeyUsage, NameConstraints, NetscapeBaseUrl, NetscapeCaPolicyUrl, NetscapeCaRevocationUrl, NetscapeCertRenewalUrl, NetscapeCertType, NetscapeComment, NetscapeRevocationUrl, NetscapeSSLServerName, Nonce, OldIssuingDistributionPoint, PKCS12ExportPermission, PolicyConstraints, PolicyMappings, PrivateKeyUsagePeriod, QCStatements, ReasonCode, ServiceLocator, SignedCertificateTimestampList, SubjectAltName, SubjectDirectoryAttributes, SubjectKeyIdentifier, UnknownExtension

public abstract class V3Extension
extends java.lang.Object

This class is the basic implementation for X.509v3 certificate and X.509v2 CRL extensions. Every class, which implements an extension must be derived from this class.

ITU-T X.509 defines a standard certificate format to be used along with the X.500 naming tree conventions. The first version has been published as X509v1 format in 1988, and has been extended in 1993 by version 2 about two fields for uniquely identifying certificate subject and issuer.

The X.509v3 certificate format - introduced by ISO/IEC and ANSI X9 - extends its predecessor v2 format about the Extensions field 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 certifcate has to be rejected (respectively CRL validation must fail). 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 certiifcate.

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

Note, that this class per default sets the critical value to false indicating a non-critical extension. When including a critical extension into a certificate (or CRL) do not forget to set critical to true using the setCritical method before adding the particular extension to the certificate (or CRL):

 <Extension_extending_V3Extension>.setCritical(true);
 cert.addExtension(<Extension_extending_V3Extension>);
 

See Also:

X509Extensions, X509Certificate

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	critical Specifies, if the actual V3Extension is critical or not.

Constructor Summary

Constructors

Constructor and Description
V3Extension()

Method Summary

Modifier and Type	Method and Description
java.lang.String	getName() Returns the name of the extension.
abstract ObjectID	getObjectID() Returns the object ID of the extension.
abstract int	hashCode() Returns the hash code of the extension.
abstract void	init(ASN1Object obj) Inits the implementation with an ASN1Object.
boolean	isCritical() Returns true, if this extension is critical.
V3Extension	setCritical(boolean critical) Set the critical value of this extension.
abstract ASN1Object	toASN1Object() Returns an ASN.1 representation of a particular extension.

Methods inherited from class java.lang.Object

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

Field Detail

critical

protected boolean critical

Specifies, if the actual V3Extension is critical or not. If this field is set to true, the extension is a critical one; if the value of this field is false (default), the extension is non-critical.

Constructor Detail

V3Extension

public V3Extension()

Method Detail

init

public abstract void init(ASN1Object obj)
                   throws X509ExtensionException

Inits the implementation with an ASN1Object. This method is used by the X509Extensions class when parsing the ASN.1 representation of a certificate (or a CRL) for properly initializing any included extension. This method initilaizes a specific extension only with its value, but not with its critical specification. For that reason, this method shall not be explicitly called by an application.

Parameters:

obj - the extension value as ASN1Object

Throws:

X509ExtensionException - if the extension could not parse the ASN1Object

toASN1Object

public abstract ASN1Object toASN1Object()
                                 throws X509ExtensionException

Returns an ASN.1 representation of a particular extension.

The genearal ASN.1 definition of an X.509 extension looks like:

 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.

Attention! The ASN1Object returned by this method does not represent the extnValue (OCTET_STRING) from above; rather it represents the specific extension's ASN.1 representation itself. So, for example, when implementig the BasicConstraints extension, the corresponding ASN.1 Sequence will be returned:

  BasicConstraints ::= SEQUENCE {
      cA                      BOOLEAN DEFAULT FALSE,
      pathLenConstraint       INTEGER (0..MAX) OPTIONAL }
 

Returns:

the value of the extension as ASN1Object

Throws:

X509ExtensionException - if the extension could not be created

getObjectID

public abstract ObjectID getObjectID()

Returns the object ID of the extension.

Returns:

the object ID from the extension this class implements

hashCode

public abstract int hashCode()

Returns the hash code of the extension.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code for this extension

getName

public java.lang.String getName()

Returns the name of the extension.

Returns:

the name of the extension

setCritical

public V3Extension setCritical(boolean critical)

Set the critical value of this extension. It returns the extension object itself to allow chained constructions like caCert.addExtension(new KeyUsage(KeyUsage.keyCertSign).setCritical(true));

Parameters:

critical - true if the extension is critical, false if not

isCritical

public boolean isCritical()

Returns true, if this extension is critical.

Returns:

true if the extension is critical, false if not