Protection Attributes - OASIS | Advancing open standards ...



Date: 1 Oct 2013Target: PKCS11 3.0Status: Slightly less Drafty Draft Author's Note: At this point this is both a clean-up of the existing attributes, and text to cover changes that I think would be useful (e.g. CKA_DERIVE_TEMPLATE). Look for groupings of [[]] to identify text that describes changes. Also lined out text represents some changes that might be necessary if we change the set of key types to deprecate CKK_GENERIC_SECRET.The primary goal of this document is to clarify "stickyness" for the entire set of attributes related specifically to key and object protection.I expect this to interact with proposals related to: CKA_DERIVE_TEMPLATE, CKA_WRAP_WITH_WRAPPING_KEYID/CKA_WRAPPING_KEYID, deprecating CKK_GENERIC_SECRET. It MAY also interact with any proposals for new commands (as the commands affected by things like CKA_DECRYPT are listed by name).Mike StJohnsChanges from "Drafty draft":Removed "trinary" or "unset" implementation discussion for boolean attributes.Fixed the CKA_DESTROYABLE discussion with respect to token and session objects - back to the 2.40 definition for CKA_TOKEN.Fixed the key usage attributes discussion. CK_FALSE is both sticky and the default if not specified - meaning that the attribute can only be set to CK_TRUE at key creation.Protection AttributesThis section describes the set of attributes used to define the protection of storage objects. All of the following attributes have a "stickyness" characteristic. They each have a state where once a specific value is set, the attribute becomes read-only. That state varies for each attribute and is described below either for the attribute or for the general class of attribute. For example, if a description says that "CK_FALSE is sticky for attribute CKA_EXAMPLE" that means that once the CKA_EXAMPLE attribute of an object is set to CK_FALSE, the value of CKA_EXAMPLE may not be further changed and is effectively read-only for the life of the object. In addition, "stickyness" also applies to the process of copying an object. An object copied from another object with sticky attributes will have at least the same sticky attributes and values as the original object.Each attribute also has a "default" value that is imputed if the attribute is not provided at creation, and that is also described below.General Protection AttributesCKA_MODIFIABLECKA_COPYABLECKA_DESTROYABLEThe above boolean attributes apply to all storage objects. Their default value if not specified at creation is CK_TRUE. The sticky value for each of these is CK_FALSE (e.g. once set to CK_FALSE, the attribute becomes read-only and may not be further changed.CKA_MODIFIABLEThis attribute controls the use of the C_AttributeValue command on the containing object. The command may only be used on the object if the value of CKA_MODIFIABLE is set to CK_TRUE. In addition, if an object is non-modifiable, none of the attributes of the object may be modified during a call to C_CopyObject. The resultant object must have exactly the same attribute set as the object from which it was copied. [[question for discussion - are there any attributes that should be exempted for modify on copy? e.g. CKA_LABEL?]] [[Q for discussion related to Stef - interactions between this and CKA_COPYABLE. Attributes say that an object is copyable but not modifiable - should this prevent modification on copy? The above says yes - and I think that is probably the most secure approach]]CKA_COPYABLEThis attribute controls the use of the C_CopyObject command on the containing object. The command may only be used on the object if the value of CKA_COPYABLE of the object being copied is set to CK_TRUE. CKA_DESTROYABLEThis attribute controls the use of the C_DestroyObject command on the containing object. The command may only be used on the object if the value of CKA_DESTROYABLE of the object being destroyed is set to CK_TRUE. If this attribute is set to CK_FALSE, then if the CKA_TOKEN attribute is set to CK_TRUE (e.g. a token object), the object is persistent until the token is reinitialized through a call to C_InitToken, or zeroized through non-PKCS11 means. Otherwise, if the object is a session object, setting the attribute to CK_TRUE causes the object to persist until the session is terminated.If a non-destroyable session object is used to create a token object (e.g. via a C_CopyObject call with the CKA_TOKEN in the copy template set to CK_FALSE), unless the copy template includes a specific setting for CKA_DESTROYABLE, the resultant object will have a CKA_DESTROYABLE attribute of CK_TRUE. This ensures that an implementation will not inadvertently create non-destroyable token objects.General Sensitivity AttributesCKA_PRIVATECKA_SENSITIVEIf not specified at object creation, these boolean attributes take on a value of CKA_TRUE for all CKO_PRIVATE_KEY, CKO_SECRET_KEY, and CKO_DATA objects and take on a value of CKA_FALSE for all CKO_PUBLIC_KEY and CKO_CERTIFICATE objects.An attribute value of CKA_TRUE is sticky; once the object has been set to private, it may not be set to public; once set to sensitive, it may not be set to non-sensitive. CKA_PRIVATEThis attribute controls whether the object is usable/readable when no CKU_USER is logged in to the token. If the value of the CKA_PRIVATE attribute is CK_TRUE, the object may only be used or read by a logged in user.This attribute is mandatory for all storage objects. CKA_SENSITIVEThis attribute controls whether "sensitive" attributes may be read from an object using C_GetAttributeValues. If the value of the CKA_SENSITIVE attribute is CK_TRUE, an attempt to read sensitive attributes from the object returns an error. The specific attributes considered sensitive for each object or key type are defined in the object or key type descriptions.This attribute is mandatory only for CKO_SECRET_KEY and CKO_PRIVATE_KEY objects. An implementation may provide support for it on other storage objects. [[Discussion - would this ever make sense for objects that are not normally defined as sensitive? E.g. is there any way to use this for say protecting a CKO_DATA object in a way that is actually useful?]]Key Usage AttributesCKA_DERIVECKA_SIGNCKA_SIGN_RECOVERCKA_VERIFYCKA_VERIFY_RECOVERCKA_ENCRYPTCKA_DECRYPTCKA_WRAPCKA_UNWRAPThe above boolean attributes apply to different classes of key types. See the descriptions of each attribute for a list of those types. The default value of these attributes, if not specified at creation, is CK_FALSE. The sticky value for each of these is also CK_FALSE. That means that if one of the use of the associated key for one of the above purposes is desired, it must be specified at key creation time. [[ discussion - does this need to be enforced for public keys? If not are we sure there is no threat? E.g. might I want to load a public key and prevent it from being used with C_Encrypt even if I can trivially create another copy of that key with different attributes (because I can extract all the public data attributes and use that to build a public key from scratch)? or leave it as is for consistency?]]CKA_DERIVEThis attribute controls the use of the C_DeriveKey command using the containing key as a key for the derive operation. The command may only be used with the key if the key's CKA_DERIVE attribute is set to CK_TRUE.This attribute is appropriate for the CKO_SECRET_KEY objects of the CKK_GENERIC_SECRET [[ CKK_MASTER_SECRET]] key type.CKA_SIGNThis attribute controls the use of the C_SignInit command with the containing key, and by implication the use of the C_Sign, C_SignUpdate, and C_SignFinal commands. The command may only be used with the key if the key's CKA_SIGN attribute is set to CK_TRUE.This attribute is appropriate for CKO_PRIVATE_KEY objects, and for CKO_SECRET_KEY objects of the CKK_GENERIC_SECRET and CKK_SECRET_KEY [[, CKK_*_HMAC and CKK_*_CMAC]] key types.CKA_SIGN_RECOVERThis attribute controls the use of the C_SignInitRecover command with the containing key, and by implication the use of the C_SignRecover, C_SignRecoverUpdate, and C_SignRecoverFinal commands. The command may only be used with the key if the key's CKA_SIGN_RECOVER attribute is set to CK_TRUE.This attribute is appropriate for the CKO_PRIVATE_KEY type. [[Question - are there hmac or cmac mechanisms with data recovery?]]CKA_VERIFYThis attribute controls the use of the C_VerifyInit command with the containing key, and by implication, the use of the C_Verify, C_VerifyUpdate, and C_VerifyFinal commands. The command may only be used with the key if the key's CKA_VERIFY attribute is set to CK_TRUE.This attribute is appropriate for CKO_PUBLIC_KEY objects, and for CKO_SECRET_KEY objectds of the CKK_GENERIC_SECRET and CKK_SECRET_KEY [[, CKK_*_HMAC and CKK_*_CMAC]] key types.CKA_VERIFY_RECOVERThis attribute controls the use of the C_VerifyInitRecover command with the containing key, and by implication the use of the C_VerifyRecover, C_VerifyUpdateRecover, and C_VerifyFinalRecover commands. The command may only be used with the key if the key's CKA_VERIFY_RECOVER attribute is set to CK_TRUE.This attribute is appropriate for the CKO_PUBLIC_KEY key type.CKA_ENCRYPTThis attribute controls the use of the C_EncryptInit command with the containing key, and by implication the use of the C_Encrypt, C_EncryptUpdate, and C_EncryptFinal commands. The command may only be used with the key if the key's CKA_ENCRYPT attribute is set to CK_TRUE.This attribute is appropriate for CKO_SECRET_KEY and CKO_PUBLIC_KEY object types.CKA_DECRYPTThis attribute controls the use of the C_DecryptInit command with the containing key, and by implication, the use of the C_Decrypt, C_DecryptUpdate, and C_DecryptFinal commands. The command may only be used with a key if the key's CKA_DECRYPT attribute is set to CK_TRUE.This attribute is appropriate for CKO_SECRET_KEY and CKO_PRIVATE_KEY object types.CKA_WRAPThis attribute controls the use of the C_WrapKey command with the containing key. The command may only be used with a wrapping key if the wrapping key's CKA_WRAP attribute is set to CK_TRUE. This attribute is appropriate for CKO_SECRET_KEY and CKO_PUBLIC_KEY key types.CKA_UNWRAPThis attribute controls the use of the C_UnwrapKey command with the containing key. The command may only be used with an unwrapping key if the unwrapping key's CKA_UNWRAP attribute is set to CK_TRUE.This attribute is appropriate for CKO_SECRET_KEY and CKO_PRIVATE_KEY object types.Key Wrapping AttributesCKA_EXTRACTABLECKA_WRAP_WITH_TRUSTEDCKA_WRAP_TEMPLATECKA_UNWRAP_TEMPLATE[[CKA_WRAPPING_KEYID]][[CKA_WRAP_WITH_WRAPPING_KEYID]]CKA_EXTRACTABLEThis boolean attribute controls whether the containing key may be a target of C_WrapKey. It differs from CKA_WRAP in that it applies to the key being wrapped rather than the wrapping key. If the value of CKA_EXTRACTABLE is CK_FALSE, the key may not be wrapped and C_WrapKey should fail with an error.If not specified at object creation time, CKA_EXTRACTABLE takes on the value of CK_FALSE. An attribute value of CK_FALSE is sticky. This attribute must be included for all CKO_PRIVATE_KEY, CKO_SECRET_KEY, [[and CKO_DATA objects]].[[ Question - should C_WrapKey be genericized to permit wrapping of any storage object? If so, above language will change.]]CKA_WRAP_WITH_TRUSTEDThis boolean attribute controls whether the key wrapping this object must have the CKA_TRUSTED attribute set to CK_TRUE. This attribute has a default value of CK_FALSE, and a sticky value of CK_TRUE. If CKA_WRAP_WITH_TRUSTED of the key to be wrapped is set to CK_TRUE, then the wrapping key (hWrappingKey) given as an argument to C_WrapKey must have its CKA_TRUSTED attribute set to CK_TRUE for the wrapping of the target key to be successful.CKA_WRAP_TEMPLATEThis attribute is used to restrict the set of keys that may be wrapped by a particular key. If the key to be wrapped by the key containing this attribute does not match this template, then C_WrapKey will fail with an error.This attribute is an array of CK_ATTRIBUTE. Its default value is a zero-length array. Once set to an array length of greater than zero, it becomes read-only.CKA_UNWRAP_TEMPLATEThis attribute is used to apply policy in the form of a set of mandatory attributes to keys created by C_UnwrapKey using this key as the unwrapping key. The attributes from the template contained in this attribute are applied to the unwrapped key as part of the creation process. If any attributes from this template conflict with the supplied attributes in the command, the unwrapping will fail with an error.This attribute is an array of CK_ATTRIBUTE. Its value is a zero-length array. Once set to an array length of greater than zero, it becomes read-only.[[CKA_WRAPPING_KEYID]][[This attribute is a CK_BYTE[16] read-only attribute that exists on any key that has a CKA_WRAP attribute value of CK_TRUE. It is created whenever the CKA_WRAP attribute is set to CK_TRUE. It is updated whenever any attribute of the associated key changes. How the actual value is selected is implementation dependent. However, the implementer MUST ensure that any two keys on a specific token that differ in any manner (different key values, different usage attributes, label, etc) have distinct values for this attribute. One suggested implementation is to generate a random byte stream of length 16 whenever a new value for this attribute is required as this should provide sufficient uniqueness to meet the requirement.]][[CKA_WRAP_WITH_WRAPPING_KEYID]][[This attribute is used to restrict the set keys that may wrap this particular key. If a key has CKA_WRAP_WITH_WRAPPING_KEYID attribute set to any value other than an empty, zero length array, the wrapping key (hWrappingKey) must have an attribute of CKA_WRAPPING_KEYID whose value exactly matches the value of this attribute, otherwise C_WrapKey will fail with an error.This attribute is a CK_BYTE[] of length 0 or length 16 which has a default value of a zero length array. Once set to an array of length 16, it becomes read-only.]]Miscellaneous Protection AttributesCKA_ALLOWED_MECHANISMSCKA_TRUSTED[[CKA_DERIVE_TEMPLATE]]This section describes protection attributes which do not fit any of the above classes.CKA_ALLOWED_MECHANISMSThis attribute is used to restrict the set of mechanisms that may be used with a particular key. The value of this attribute is an array of CK_MECHANISM_TYPE[] of any length. It has a default value of a zero length array. Once set to an array length of greater than 0, it becomes read-only.In general, any keyed command for which a mechanism is specified shall check the keys provided in the command call (exception - C_WrapKey shall not check the key to be wrapped - hKey) for the presence of this attribute. If any of the CK_MECHANISM_TYPEs provided in the attribute match the mechanism type in the specified mechanism, the command may proceed (barring other failures). Otherwise it should fail with an error.[[***Following text related to Stef's comment locking out all mechanisms, but I don't think it makes sense - why would you have a key that can't be used with ANY mechanism? Remove this if not necessary] [[If it is desired to permanently restrict a key so that no mechanism may be used with the key, specify an attribute value of an array containing a single mechanism that is incompatible with the key. E.g. specify "CKA_ALLOWED_MECHANISMS = { CKM_AES_WRAP }; " when you create a DES secret key.]]CKA_TRUSTEDThis boolean attribute has a default value of CK_FALSE. It may only be set to CK_TRUE by the CKU_SO or by proprietary means external to PKCS11. Note that this implies that CKO_SECRET_KEY objects that require this attribute to be set to CK_TRUE will have to be public objects (CKA_PRIVATE == CK_FALSE) at some point to allow the attribute to be set. The value of CK_FALSE is effectively sticky without the intervention of the security officer.[[CKA_DERIVE_TEMPLATE]][[This attribute is used to force the application of policy to keys derived as a result of a call to C_DeriveKey. The attributes from the template contained in this attribute are applied to the derived key(s) as part of the key creation process. If any attributes from this template conflict with the supplied attributes in the command, the derivation will fail with an error and no keys will be returned. [[more details on CKA_DERIVE_TEMPLATE to be provided elsewhere]]This attribute is an array of CK_ATTRIBUTE. Its default value is a zero-length array. Once set to an array length of greater than 0, it becomes read-only.]] ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download