iaik.x509.extensions

Class KeyUsage

java.lang.Object

iaik.x509.V3Extension

iaik.x509.extensions.KeyUsage

public class KeyUsage
extends V3Extension

This class implements the KeyUsage extension.

The KeyUsage extension is a standard X509v3 extension, which shall be marked as being critical when used.

Each extension is associated with a specific certificateExtension object identifier, derived from:

 certificateExtension  OBJECT IDENTIFIER ::=
                            {joint-iso-ccitt(2) ds(5) 29}
 id-ce                 OBJECT IDENTIFIER ::=  certificateExtension
 

The object identifier for the KeyUsage extension is defined as:

id-ce-keyUsage OBJECT IDENTIFIER ::= { id-ce 15 }

which corresponds to the OID string "2.5.29.15".

The X.509 Certificate and CRL profile presented in RFC 3280 specifies the key usage extension for defining the purpose (e.g., encipherment, signature, certificate signing) of the key contained in the certificate:

 KeyUsage ::= BIT STRING {
    digitalSignature        (0),
    nonRepudiation          (1),
    keyEncipherment         (2),
    dataEncipherment        (3),
    keyAgreement            (4),
    keyCertSign             (5),
    cRLSign                 (6),
    encipherOnly            (7),
    decipherOnly            (8) }
 

The usage restriction might be employed when a key that could be used for more than one operation is to be restricted. For example, when a RSA key should be used only for signing, the digitalSignature and nonRepudiation bits would be asserted. Likewise, when a RSA key should be used only for key management, the keyEncipherment bit would be asserted.

More information can be found in RFC 3280, section 4.2.1.3 "Key Usage".

For adding a KeyUsage extension object to a X509Certificate, use the addExtension method of the iaik.x509.X509Certificate class, e.g.:

 X509Certificate cert = new X509Certificate();
  ...
 KeyUsage keyUsage = new KeyUsage( KeyUsage.digitalSignature |
                                   KeyUsage.nonRepudiation|
                                   KeyUsage.keyEncipherment|
                                   KeyUsage.dataEncipherment|
                                   KeyUsage.keyCertSign |
                                   KeyUsage.cRLSign);
 keyUsage.setCritical(true);
 cert.addExtension(keyUsage);
 

Since the KeyUsage extension is a critical extension, critical has to be set to true before adding the KeyUsage extension to a certificate:

 keyUsage.setCritical(true);
 

Version:

File Revision 27

See Also:

X509Certificate, X509Extensions, V3Extension

Field Summary

Fields

Modifier and Type	Field and Description
static int	contentCommitment The contentCommitment keyUsage purpose is used by recent editions of X.509 as synonym for nonRepudiation.
static int	cRLSign The cRLSign keyUsage purpose indicating to use the subject public key for verifying a signature on CRLs.
static int	dataEncipherment The dataEncipherment keyUsage purpose indicating to use the subject public key for enciphering user data, other than cryptographic keys.
static int	decipherOnly The decipherOnly keyUsage purpose indicating that the subject public key may be used only for enciphering data while performing key agreement, if the keyAgreement bit also is set.
static int	digitalSignature The digitalSignature keyUsage purpose indicating to use the subject public key for verifying digital signatures that have purposes other than non-repudiation, certificate signature, and CRL signature.
static int	encipherOnly The encipherOnly keyUsage purpose indicating that the subject public key may be used only for enciphering data while performing key agreement, if the keyAgreement bit also is set.
static int	keyAgreement The keyAgreement keyUsage purpose indicating to use the subject public key for key agreement.
static int	keyCertSign The keyCertSign keyUsage purpose indicating to use the subject public key for verifying a signature on certificates.
static int	keyEncipherment The keyEncipherment keyUsage purpose indicating to use the subject public key for key transport.
static int	nonRepudiation The nonRepudiation keyUsage purpose indicating to use the subject public key for verifying digital signatures used to provide a non- repudiation service which protects against the signing entity falsely denying some action, excluding certificate or CRL signing.
static ObjectID	oid The object identifier of this KeyUsage extension.

Fields inherited from class iaik.x509.V3Extension

critical

Constructor Summary

Constructors

Constructor and Description
KeyUsage() Default constructor.
KeyUsage(int keyUsage) Constructs a KeyUsage extension with a defined key usage parameter.

Method Summary

Methods

Modifier and Type	Method and Description
int	get() Returns the key usage value as an integer.
boolean[]	getBooleanArray() Return the key usage value as a boolean array.
ObjectID	getObjectID() Returns the object ID of this KeyUsage extension
int	hashCode() Returns a hashcode for this identity.
void	init(ASN1Object obj) Inits this KeyUsage implementation with an ASN1Object representing the value of this extension.
boolean	isSet(int keyUsage) Return whether the specified key usage values are set.
void	set(int keyUsage) Sets the purpose of the key (e.g.: cRLSign | digitalSignature).
ASN1Object	toASN1Object() Returns an ASN1Object representing the value of this KeyUsage extension object.
java.lang.String	toString() Returns a string that represents the contents of this KeyUsage extension.

Methods inherited from class iaik.x509.V3Extension

getName, isCritical, setCritical

Methods inherited from class java.lang.Object

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

Field Detail

oid

public static final ObjectID oid

The object identifier of this KeyUsage extension. The corresponding OID string is "2.5.29.15".

digitalSignature

public static final int digitalSignature

The digitalSignature keyUsage purpose indicating to use the subject public key for verifying digital signatures that have purposes other than non-repudiation, certificate signature, and CRL signature.

See Also:

Constant Field Values

nonRepudiation

public static final int nonRepudiation

The nonRepudiation keyUsage purpose indicating to use the subject public key for verifying digital signatures used to provide a non- repudiation service which protects against the signing entity falsely denying some action, excluding certificate or CRL signing. .

See Also:

Constant Field Values

contentCommitment

public static final int contentCommitment

The contentCommitment keyUsage purpose is used by recent editions of X.509 as synonym for nonRepudiation.

See Also:

Constant Field Values

keyEncipherment

public static final int keyEncipherment

The keyEncipherment keyUsage purpose indicating to use the subject public key for key transport.

See Also:

Constant Field Values

dataEncipherment

public static final int dataEncipherment

The dataEncipherment keyUsage purpose indicating to use the subject public key for enciphering user data, other than cryptographic keys.

See Also:

Constant Field Values

keyAgreement

public static final int keyAgreement

The keyAgreement keyUsage purpose indicating to use the subject public key for key agreement.

See Also:

Constant Field Values

keyCertSign

public static final int keyCertSign

The keyCertSign keyUsage purpose indicating to use the subject public key for verifying a signature on certificates.

See Also:

Constant Field Values

cRLSign

public static final int cRLSign

The cRLSign keyUsage purpose indicating to use the subject public key for verifying a signature on CRLs.

See Also:

Constant Field Values

encipherOnly

public static final int encipherOnly

The encipherOnly keyUsage purpose indicating that the subject public key may be used only for enciphering data while performing key agreement, if the keyAgreement bit also is set.

See Also:

Constant Field Values

decipherOnly

public static final int decipherOnly

The decipherOnly keyUsage purpose indicating that the subject public key may be used only for enciphering data while performing key agreement, if the keyAgreement bit also is set.

See Also:

Constant Field Values

Constructor Detail

KeyUsage

public KeyUsage()

Default constructor. Creates an empty KeyUsage object.

Per default the keyUsage value is set to 0 indicating that it is not set. Use set for explicitly setting the key usage value.

Do not forget to specify this extension as critical before adding it to a certificate, e.g.:

 KeyUsage keyUsage = new KeyUsage();
 keyUsage.set( KeyUsage.digitalSignature |
                KeyUsage.nonRepudiation|
                KeyUsage.keyEncipherment|
                KeyUsage.dataEncipherment|
                KeyUsage.keyCertSign |
                KeyUsage.cRLSign);
 keyUsage.setCritical(true);
 X509Certificate = new X509Certificate();
  ...
 cert.addExtension(bc);
 

See Also:

V3Extension.setCritical(boolean)

KeyUsage

public KeyUsage(int keyUsage)

Constructs a KeyUsage extension with a defined key usage parameter.

Do not forget to specify this extension as critical before adding it to a certificate:

 KeyUsage keyUsage = new KeyUsage(KeyUsage.digitalSignature |
                                  KeyUsage.nonRepudiation|
                                  KeyUsage.keyEncipherment|
                                  KeyUsage.dataEncipherment|
                                  KeyUsage.keyCertSign |
                                  KeyUsage.cRLSign);
 keyUsage.setCritical(true);
 X509Certificate = new X509Certificate();
  ...
 cert.addExtension(bc);
 

Parameters:

keyUsage - the purpose of this key

Method Detail

getObjectID

public ObjectID getObjectID()

Returns the object ID of this KeyUsage extension

Specified by:

getObjectID in class V3Extension

Returns:

the object ID

set

public void set(int keyUsage)

Sets the purpose of the key (e.g.: cRLSign | digitalSignature).

For instance:

 KeyUsage keyUsage = new KeyUsage();
 keyUsage.set( KeyUsage.digitalSignature |
               KeyUsage.cRLSign);
 

Parameters:

keyUsage - the key usage bit string

init

public void init(ASN1Object obj)

Inits this KeyUsage implementation with an ASN1Object representing the value of this extension.

The given ASN1Object indicates the key usage purpose.

The given ASN1Object is the one created by toASN1Object().

This method is used by the X509Extensions class when parsing the ASN.1 representation of a certificate for properly initializing an included KeyUsage extension. This method initializes the extension only with its value, but not with its critical specification. For that reason, this method shall not be explicitly called by an application.

Specified by:

init in class V3Extension

Parameters:

obj - the KeyUsage as ASN1Object

toASN1Object

public ASN1Object toASN1Object()

Returns an ASN1Object representing the value of this KeyUsage extension object.

The returned ASN1Object is an ASN.1 BIT_STRING indicating the key usage purpose:

 KeyUsage ::= BIT STRING {
    digitalSignature        (0),
    nonRepudiation          (1),
    keyEncipherment         (2),
    dataEncipherment        (3),
    keyAgreement            (4),
    keyCertSign             (5),
    cRLSign                 (6),
    encipherOnly            (7),
    decipherOnly            (8) }
 

Specified by:

toASN1Object in class V3Extension

Returns:

the value of this KeyUsage as ASN1Object

hashCode

public int hashCode()

Returns a hashcode for this identity.

Specified by:

hashCode in class V3Extension

Returns:

a hash code for this identity

get

public int get()

Returns the key usage value as an integer.

Note the "big endian" representation of the BIT STRING representing the value of this KeyUsage extension: the least significant bit indicates the purpose with the lowest bit value, meaning that the integer value 1 specifies the "digitalSignature" purpose, and the integer value 256 (binary 100000000, hexadecimal 100) specifies the "decipherOnly" purpose.

Returns:

the key usage value as integer representation

See Also:

set(int)

getBooleanArray

public boolean[] getBooleanArray()

Return the key usage value as a boolean array.

It will always have nine elements, element 0 is digitalSignature, element 1 nonRepudiation, etc.

isSet

public boolean isSet(int keyUsage)

Return whether the specified key usage values are set. For example, keyUsage.isSet(KeyUsage.keyCertSign) returns true if the keyCertSign bit is set.

toString

public java.lang.String toString()

Returns a string that represents the contents of this KeyUsage extension.

Overrides:

toString in class java.lang.Object

Returns:

the string representation