com.rsa.certj.cert.extensions

Class KeyUsage

java.lang.Object
  |
  +--com.rsa.certj.cert.extensions.X509V3Extension
        |
        +--com.rsa.certj.cert.extensions.KeyUsage

All Implemented Interfaces:

CertExtension, Cloneable, Serializable

public class KeyUsage

extends X509V3Extension

implements Cloneable, Serializable, CertExtension

This class builds, holds, encodes, and decodes the KeyUsage extension. The key usage extension defines the purpose (for example, encipherment, signature, certificate signing) of the key contained in the certificate. The usage restriction might be employed when a key that could be used for more than one operation must be restricted. For example, when an RSA key should be used only for signing, you would assert the digitalSignature or nonRepudiation bits. Likewise, when an RSA key should be used only for key management, you would assert the keyEncipherment bit.

The ASN.1 definition is as follows:

 keyUsage EXTENSION ::= {
	SYNTAX	KeyUsage
	IDENTIFIED BY id-ce-keyUsage }

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

digitalSignature – Asserted when the subject public key is used with a digital signature mechanism to support security services other than non-repudiation (bit 1), certificate signing (bit 5), or revocation information signing (bit 6). Digital signature mechanisms are often used for entity authentication and data-origin authentication with integrity.

nonRepudiation – Verifies digital signatures used in providing a non-repudiation service tjat protects against the signing entity falsely denying some action (excluding certificate or CRL signing, as in keyCertSign or cRLSign).

keyEncipherment – Enciphers keys or other security information; for example, for key transport.

dataEncipherment – Enciphers user data, but not keys or other security information as in keyEncipherment.

keyAgreement – Used as a public key agreement key.

keyCertSign – Verifies a CA's signature on certificates.

cRLSign – Verifies a CA's signature on CRLs.

encipherOnly – Public key agreement key for use only in enciphering data when used with the keyAgreement bit. If this bit is set, the only other bit to set is keyAgreement. If any other key usage bit besides keyAgreement is set when this bit is set, this bit has no meaning.

decipherOnly – Public-key agreement key for use only in deciphering data when used with the keyAgreement bit. If this bit is set, the only other bit to set is keyAgreement. If any other key usage bit besides keyAgreement is set when this bit is set, this bit has no meaning.

The keyCertSign bit is used in CA certificates only. This extension may, at the option of the certificate issuer, be either critical or non-critical. If the extension is flagged critical, then the certificate shall be used only for a purpose for which the corresponding key usage bit is set to one. If the extension is flagged non-critical, then it indicates the intended purpose or purposes of the key, and may be used in finding the correct key or certificate of an entity that has multiple keys or certificates.

Copyright © RSA Security Inc., 1998-2001. All rights reserved.

See Also

Serialized Form

Field Summary

static int	CRL_SIGN Indicates the key is used in verifying the CA's signature on a CRL.
static int	DATA_ENCIPHERMENT Indicates the key is used in encrypting data other than KEY_ENCIPHERMENT.
static int	DECIPHER_ONLY Indicates that the key is used in deciphering data, and that no other bit (except KEY_AGREEMENT) is set.
static int	DIGITAL_SIGNATURE Indicates the key is for use in verifying digital signatures other than NON_REPUDIATION, KEY_CERT_SIGN, or CRL_SIGN.
static int	ENCIPHER_ONLY Indicates the key is used in enciphering data, and any other bit (except KEY_AGREEMENT) is not set.
static int	KEY_AGREEMENT Indicates the key is used in key agreement.
static int	KEY_CERT_SIGN Indicates the key is used in verifying the CA's signature on a certificate.
static int	KEY_ENCIPHERMENT Indicates the key is used in encrypting keys; for example, for key transport.
static int	KEY_USAGE_BITS Indicates the number of possible KeyUsage bits.
static int	KEY_USAGE_MASK Indicates which KeyUsage bits to check.
static int	NON_REPUDIATION Indicates the key is used in verifying digital signatures protecting against falsely denying some action, other than KEY_CERT_SIGN or CRL_SIGN.

Fields inherited from class com.rsa.certj.cert.extensions.X509V3Extension

ARCHIVE_CUTOFF, ARCHIVE_CUTOFF_OID, AUTHORITY_INFO_ACCESS, AUTHORITY_INFO_OID, AUTHORITY_KEY_ID, BASIC_CONSTRAINTS, BIO_INFO, BIO_INFO_OID, CERT_POLICIES, CERTIFICATE_ISSUER, CRL_DISTRIBUTION_POINTS, CRL_NUMBER, CRL_REFERENCE, CRL_REFERENCE_OID, DELTA_CRL_INDICATOR, EXTENDED_KEY_USAGE, HOLD_INSTRUCTION_CODE, INHIBIT_ANY_POLICY, INVALIDITY_DATE, ISSUER_ALT_NAME, ISSUING_DISTRIBUTION_POINT, KEY_USAGE, NAME_CONSTRAINTS, NETSCAPE_BASE_URL, NETSCAPE_BASE_URL_OID, NETSCAPE_CA_POLICY_URL, NETSCAPE_CA_POLICY_URL_OID, NETSCAPE_CA_REVOCATION_URL, NETSCAPE_CA_REVOCATION_URL_OID, NETSCAPE_CERT_RENEWAL_URL, NETSCAPE_CERT_RENEWAL_URL_OID, NETSCAPE_CERT_TYPE, NETSCAPE_CERT_TYPE_OID, NETSCAPE_COMMENT, NETSCAPE_COMMENT_OID, NETSCAPE_REVOCATION_URL, NETSCAPE_REVOCATION_URL_OID, NETSCAPE_SSL_SERVER_NAME, NETSCAPE_SSL_SERVER_NAME_OID, NON_STANDARD_EXTENSION, OCSP_ACCEPTABLE_RESPONSES, OCSP_ACCEPTABLE_RESPONSES_OID, OCSP_NOCHECK, OCSP_NOCHECK_OID, OCSP_NONCE, OCSP_NONCE_OID, OCSP_SERVICE_LOCATOR, OCSP_SERVICE_LOCATOR_OID, POLICY_CONSTRAINTS, POLICY_MAPPINGS, PRIVATE_KEY_USAGE_PERIOD, QC_STATEMENTS, QC_STATEMENTS_OID, REASON_CODE, SUBJECT_ALT_NAME, SUBJECT_DIRECTORY_ATTRIBUTES, SUBJECT_KEY_ID, VERISIGN_CZAG, VERISIGN_CZAG_OID, VERISIGN_FIDELITY_ID, VERISIGN_FIDELITY_ID_OID, VERISIGN_JURISDICTION_HASH, VERISIGN_JURISDICTION_HASH_OID, VERISIGN_NETSCAPE_INBOX_V1, VERISIGN_NETSCAPE_INBOX_V1_OID, VERISIGN_NETSCAPE_INBOX_V2, VERISIGN_NETSCAPE_INBOX_V2_OID, VERISIGN_NON_VERIFIED, VERISIGN_NON_VERIFIED_OID, VERISIGN_SERIAL_NUMBER, VERISIGN_SERIAL_NUMBER_OID, VERISIGN_TOKEN_TYPE, VERISIGN_TOKEN_TYPE_OID

Constructor Summary

KeyUsage()

Constructs an empty KeyUsage object.

KeyUsage(int keyUsage, boolean criticality)

Creates a KeyUsage object and initializes it with the given values.

Method Summary

Object	clone() Overrides the default clone method to get a deeper clone.
void	decodeValue(byte[] valueBER, int offset) Decode the value.
int	derEncodeValue(byte[] encoding, int offset) Place the encoding of the value into encoding, beginning at offset.
int	derEncodeValueInit() Initialize for encoding the value.
int	getKeyUsage() Gets the value of this object, the KeyUsage bits.
boolean	verifyKeyUsage(int usageToVerify) Given usageToVerify, a value set with flags of the proposed usage, verifies that the extension is set with these flags.

Methods inherited from class com.rsa.certj.cert.extensions.X509V3Extension

extend, getCriticality, getDEREncoding, getDERLen, getExtensionType, getExtensionTypeString, getInstance, getNextBEROffset, isExtensionType, setCriticality, setEncoding, setSpecialOID, setStandardOID

Methods inherited from class java.lang.Object

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

Field Detail

KEY_USAGE_BITS

public static final int KEY_USAGE_BITS

Indicates the number of possible KeyUsage bits.

KEY_USAGE_MASK

public static final int KEY_USAGE_MASK

Indicates which KeyUsage bits to check.

DIGITAL_SIGNATURE

public static final int DIGITAL_SIGNATURE

Indicates the key is for use in verifying digital signatures other than NON_REPUDIATION, KEY_CERT_SIGN, or CRL_SIGN.

NON_REPUDIATION

public static final int NON_REPUDIATION

Indicates the key is used in verifying digital signatures protecting against falsely denying some action, other than KEY_CERT_SIGN or CRL_SIGN.

KEY_ENCIPHERMENT

public static final int KEY_ENCIPHERMENT

Indicates the key is used in encrypting keys; for example, for key transport.

DATA_ENCIPHERMENT

public static final int DATA_ENCIPHERMENT

Indicates the key is used in encrypting data other than KEY_ENCIPHERMENT.

KEY_AGREEMENT

public static final int KEY_AGREEMENT

Indicates the key is used in key agreement.

KEY_CERT_SIGN

public static final int KEY_CERT_SIGN

Indicates the key is used in verifying the CA's signature on a certificate.

CRL_SIGN

public static final int CRL_SIGN

Indicates the key is used in verifying the CA's signature on a CRL.

ENCIPHER_ONLY

public static final int ENCIPHER_ONLY

Indicates the key is used in enciphering data, and any other bit (except KEY_AGREEMENT) is not set.

DECIPHER_ONLY

public static final int DECIPHER_ONLY

Indicates that the key is used in deciphering data, and that no other bit (except KEY_AGREEMENT) is set.

Constructor Detail

KeyUsage

public KeyUsage()

Constructs an empty KeyUsage object.

KeyUsage

public KeyUsage(int keyUsage,
                boolean criticality)

Creates a KeyUsage object and initializes it with the given values.

Parameters

	keyUsage		The value of keyUsage is the logical bitwise-ORing of the fields previously defined in this class.
	criticality		The user-specified criticality.

Method Detail

decodeValue

public void decodeValue(byte[] valueBER,
                        int offset)
                 throws CertificateException

Decode the value. The input is the BER encoding that was wrapped in the OCTET STRING.

Overrides

decodeValue in class X509V3Extension

Parameters

	valueBER		The BER encoding of the extension's value.
	offset		The offset into valueBER where the encoding begins.

Throws

CertificateException - If the encoding is invalid for this extension.

getKeyUsage

public int getKeyUsage()

Gets the value of this object, the KeyUsage bits. If this object does not have key usage bits, this method returns zero.

Returns

An int that contains the KeyUsage bits.

verifyKeyUsage

public boolean verifyKeyUsage(int usageToVerify)

Given usageToVerify, a value set with flags of the proposed usage, verifies that the extension is set with these flags.

Parameters

usageToVerify

An int that contains the logical bitwise-ORing of one or more proposed key usage field values, previously defined in this class.

Returns

A boolean that indicates whether the fields in this extension, corresponding to the proposed usage, are set.

derEncodeValueInit

public int derEncodeValueInit()

Initialize for encoding the value.

Overrides

derEncodeValueInit in class X509V3Extension

Returns

How many bytes the encoding will be.

derEncodeValue

public int derEncodeValue(byte[] encoding,
                          int offset)

Place the encoding of the value into encoding, beginning at offset. This is the actual contents that are wrapped in the OCTET STRING (not the surrounding OCTET STRING tag and length).

Overrides

derEncodeValue in class X509V3Extension

Parameters

	encoding		The byte array into which the result will be placed.
	offset		The offest into encoding where the writing is to begin.

Returns

The number of bytes actually placed into encoding.

clone

public Object clone()
             throws CloneNotSupportedException

Overrides the default clone method to get a deeper clone.

Overrides

clone in class X509V3Extension

Returns

A new KeyUsage object, a copy of this object.

Throws

CloneNotSupportedException - If the cloning operation is not successful.