com.entrust.toolkit.x509.testlets

Class ExtendedKeyUsageCertTestlet

java.lang.Object

com.entrust.toolkit.x509.testlets.ExtendedKeyUsageCertTestlet

All Implemented Interfaces:

CertTestlet, ExtensionTestlet

public class ExtendedKeyUsageCertTestlet
extends java.lang.Object
implements CertTestlet

This Testlet is used for Processing the ExtendedKeyUsage certificate Extension. It follows the recomendations in RFC 5280:

 4.2.1.12.  Extended Key Usage

  This extension indicates one or more purposes for which the certified
  public key may be used, in addition to or in place of the basic
  purposes indicated in the key usage extension.  In general, this
  extension will appear only in end entity certificates.  This
  extension is defined as follows:

  id-ce-extKeyUsage OBJECT IDENTIFIER ::= { id-ce 37 }

  ExtKeyUsageSyntax ::= SEQUENCE SIZE (1..MAX) OF KeyPurposeId

  KeyPurposeId ::= OBJECT IDENTIFIER

  Key purposes may be defined by any organization with a need.  Object
  identifiers used to identify key purposes MUST be assigned in
  accordance with IANA or ITU-T Recommendation X.660 [X.660].

  This extension MAY, at the option of the certificate issuer, be
  either critical or non-critical.

  If the extension is present, then the certificate MUST only be used
  for one of the purposes indicated.  If multiple purposes are
  indicated the application need not recognize all purposes indicated,
  as long as the intended purpose is present.  Certificate using
  applications MAY require that the extended key usage extension be
  present and that a particular purpose be indicated in order for the
  certificate to be acceptable to that application.

  If a CA includes extended key usages to satisfy such applications,
  but does not wish to restrict usages of the key, the CA can include
  the special KeyPurposeId anyExtendedKeyUsage in addition to the
  particular key purposes required by the applications.  Conforming CAs
  SHOULD NOT mark this extension as critical if the anyExtendedKeyUsage
  KeyPurposeId is present.  Applications that require the presence of a
  particular purpose MAY reject certificates that include the
  anyExtendedKeyUsage OID but not the particular OID expected for the
  application.

  If a certificate contains both a key usage extension and an extended
  key usage extension, then both extensions MUST be processed
  independently and the certificate MUST only be used for a purpose
  consistent with both extensions.  If there is no purpose consistent
  with both extensions, then the certificate MUST NOT be used for any
  purpose.
 

A toolkit application will need to configure this CertTestlet with the ExtendedKeyUsage types that are acceptable for the application context. When processing the extension, at least one of the key purpose ID's must be acceptable, otherwise the certificate will be rejected.

This implementation does not support ExtendedKeyUsage types in a CA certificate, and will reject any CA certificates containing ExtendedKeyUsage. If an application requires use of an ExtendedKeyUsage for a CA certificate, it will need to implement and register an ExtendedKeyUsage CertTestlet that can process CA certificates.

This implementation supports anyExtendedKeyUsage which can be used in place of a specific key usage. An application can decide to ignore anyExtendedKeyUsage by setting the allowAnyExtendedKeyUsage parameter to false (the default).

Since:

7.2 SP2 Patch

Constructor Summary

Constructors

Constructor and Description
ExtendedKeyUsageCertTestlet() This is the default constructor, it registers the default set of ExtendedKeyUsage extensions.
ExtendedKeyUsageCertTestlet(ObjectID[] extendedUsages, boolean allowAnyExtendedKeyUsage) This constructor allows a toolkit application to configure the List of ExtendedKeyUsages that are accepted.

Method Summary

Methods

Modifier and Type	Method and Description
void	enforceAnyExtendedKeyUsageNotCritical(boolean enforceAnyEKUNotCritical) This API allows the caller to enforce whether the anyExtendedKeyUsage is allowed to be critical.
boolean	getAllowAnyExtendedKeyUsage()
static ObjectID[]	getDefaultToolkitUsage() This adds the default ExtendedKeyUsages for use with the toolkit.
static ObjectID[]	getRFC5280Usages() Return a List of ObjectID that represents a list of the ExtendedKeyUsages defined in RFC 5280.
void	init(X509Certificate[] chain, TestletDataSet dataSet) Initializes this CertTestlet.
void	notify(V3Extension extension, TestletDataSet dataSet) The notify method passes the extension to this CertTestlet for Use.
void	reset(TestletDataSet dataSet) This reset method does nothing since nothing needs to be reset
void	validate(X509Certificate cert, TestletDataSet dataSet) This is the method that validates the ExtendedKeyUsage.

Methods inherited from class java.lang.Object

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

Constructor Detail

ExtendedKeyUsageCertTestlet

public ExtendedKeyUsageCertTestlet(ObjectID[] extendedUsages,
                           boolean allowAnyExtendedKeyUsage)

This constructor allows a toolkit application to configure the List of ExtendedKeyUsages that are accepted. When ExtendedKeyusage is critical and the ExtendedKeyUsage.anyExtendedKeyUsage is allowed to be used, but has not been set in the certificate being processed, the usage specified in the extension is checked against a list of allowed usages, and if it does not exist the CertTestlet will fail.

The allowAnyExtendedKeyUsage is used to determine whether an application will allow the ExtendedKeyUsage.anyExtendedKeyUsage to be used in place of a specific ExtendedKeyUsage for the application context. If the allowAnyExtendedKeyUsage is set to false, and the ExtendedKeyUsage.anyExtendedKeyUsage is contained in the certificate being validated, the anyExtendedKeyUsage extension will be ignored. This is to meet the criteria from RFC 5280 that states:

 Applications that require the presence of a particular purpose MAY 
 reject certificates that include the anyExtendedKeyUsage OID but not the 
 particular OID expected for the application.
 

This constructor allows an application to decide which ExtendedKeyUsages are acceptable. By default, the toolkit does not register any key purpose id's.

Parameters:

extendedUsages - The array of ObjectID's for acceptable extendedKeyUsages.

allowAnyExtendedKeyUsage - true to indicate whether the ExtendedKeyUsage.anyExtendedKeyUsage will be used if contained in the certificate being processed, false to indicate it should not be used.

ExtendedKeyUsageCertTestlet

public ExtendedKeyUsageCertTestlet()

This is the default constructor, it registers the default set of ExtendedKeyUsage extensions.

See Also:

#getDefaultToolkitUsage()}

Method Detail

init

public void init(X509Certificate[] chain,
        TestletDataSet dataSet)

Initializes this CertTestlet. Get the End-Entity certificate

Specified by:

init in interface CertTestlet

Parameters:

chain - the certificate chain

dataSet - a set in which the testlet can store temporary data for validation

notify

public void notify(V3Extension extension,
          TestletDataSet dataSet)

The notify method passes the extension to this CertTestlet for Use.

Specified by:

notify in interface ExtensionTestlet

Parameters:

extension - the extension found in the certificate

dataSet - a set in which the testlet can store temporary data for validation

validate

public void validate(X509Certificate cert,
            TestletDataSet dataSet)
              throws ExtensionException

This is the method that validates the ExtendedKeyUsage. It follows the guidelines from RFC 5280.

If the ExtendedKeyUsage is critical, it must be processed unless it contains the anyExtendedKeyUsage purposeID which indicates any ExtendedKeyUsage is acceptable. If the enforceAnyExtendedKeyUsageNotCritical(boolean) is set to true, and the extension is critical and contains the ExtendedKeyUsage.anyExtendedKeyUsage then the anyExtendedKeyUsage will be ignored. The anyExtendedKeyUsage must also be an allowed keyPurposeID otherwise it will be ignored.

When the extension is processed, the KeyPurposeId's are checked against the accepted list of KeyPurposeId's that have been configured in this CertTestlet. At least one of the key purpose ID's in the certificate must be acceptable, otherwise the certificate will be rejected.

This implementation does not support ExtendedKeyUsage types in a CA certificate, and will reject any CA certificates containing ExtendedKeyUsage.

If there are no acceptable key purpose ID's configured (as in the default configuration), the toolkit will remain backward compatible with previous versions; an exception will only be thrown if the ExtendedKeyUsage extension is critical.

Specified by:

validate in interface CertTestlet

Parameters:

the - certificate being checked for ExtendedKeyUsage

dataSet - the CertTestlet data set (which is not used by this CertTestlet)

Throws:

ExtensionException - thrown if validation fails

reset

public void reset(TestletDataSet dataSet)

This reset method does nothing since nothing needs to be reset

Specified by:

reset in interface ExtensionTestlet

Parameters:

dataSet - a set in which the testlet can store temporary data for validation

getRFC5280Usages

public static ObjectID[] getRFC5280Usages()

Return a List of ObjectID that represents a list of the ExtendedKeyUsages defined in RFC 5280. These are the following:

 anyExtendedKeyUsage OBJECT IDENTIFIER ::= { id-ce-extKeyUsage 0 }

 id-kp OBJECT IDENTIFIER ::= { id-pkix 3 }

 id-kp-serverAuth             OBJECT IDENTIFIER ::= { id-kp 1 }
 -- TLS WWW server authentication
 -- Key usage bits that may be consistent: digitalSignature,
 -- keyEncipherment or keyAgreement

 id-kp-clientAuth             OBJECT IDENTIFIER ::= { id-kp 2 }
 -- TLS WWW client authentication
 -- Key usage bits that may be consistent: digitalSignature
 -- and/or keyAgreement

 id-kp-codeSigning             OBJECT IDENTIFIER ::= { id-kp 3 }
 -- Signing of downloadable executable code
 -- Key usage bits that may be consistent: digitalSignature

 id-kp-emailProtection         OBJECT IDENTIFIER ::= { id-kp 4 }
 -- Email protection
 -- Key usage bits that may be consistent: digitalSignature,
 -- nonRepudiation, and/or (keyEncipherment or keyAgreement)

 id-kp-timeStamping            OBJECT IDENTIFIER ::= { id-kp 8 }
 -- Binding the hash of an object to a time
 -- Key usage bits that may be consistent: digitalSignature
 -- and/or nonRepudiation

 id-kp-OCSPSigning            OBJECT IDENTIFIER ::= { id-kp 9 }
 -- Signing OCSP responses
 -- Key usage bits that may be consistent: digitalSignature
 -- and/or nonRepudiation

 

Returns:

a List of ObjectID for the ExtendedKeyUsages defined by RFC 5280

getDefaultToolkitUsage

public static ObjectID[] getDefaultToolkitUsage()

This adds the default ExtendedKeyUsages for use with the toolkit.

By default, there are no ExtendedKeyUsages set by the toolkit. It is up to the application to decide which ExtendedKeyUsage purposeID's will be used for the application. When the default usage is set, the toolkit will throw an Exception if it is critical, otherwise it will return if it is non-critical. This is to remain backward compatible with previous versions of the toolkit.

Returns:

the default list of acceptable ExtendedKeyUsage by the toolkit

enforceAnyExtendedKeyUsageNotCritical

public void enforceAnyExtendedKeyUsageNotCritical(boolean enforceAnyEKUNotCritical)

This API allows the caller to enforce whether the anyExtendedKeyUsage is allowed to be critical. RFC 5280 says it SHOULD not be critical, but because it is a SHOULD rather than a MUST, it is possible that implementations will be using it as a critical extension. If this method is set to true, and a critical ExtendedKeyUsage containing the ExtendedKeyUsage.anyExtendedKeyUsage is found, the anyExtendedKeyUsage will be ignored.

The default setting is false.

Parameters:

enforceAnyEKUNotCritical - true to enforce that the ExtendedKeyUsage.anyExtendedKeyUsage is not a critical extension, false to indicate it can be critical or non-critical.

getAllowAnyExtendedKeyUsage

public boolean getAllowAnyExtendedKeyUsage()

Returns:

true if the usage is allowed to be used, or false if it is not allowed.