Attributes
The following sections describe how PKCS #11 attributes map to the Access Control List (ACL) given to the key by the nCore API. nCore API ACLs are described in the nCore API Documentation (supplied as HTML).
CKA_SENSITIVE
In a FIPS 140 Level 2 world, CKA_SENSITIVE=FALSE
creates a key with an ACL that includes ExportAsPlain
.
Keys are exported using DeriveMech_EncryptMarshalled
even in a FIPS 140 Level 2 world.
The presence of the ExportAsPlain
permission makes the status of the key clear when a FIPS 140 Level 2 ACL is viewed using GetACL
.
CKA_SENSITIVE=FALSE
always creates a key with an ACL that includes DeriveKey
with DeriveRole_BaseKey
and DeriveMech_EncryptMarshalled
.
See also CKA_UNWRAP_TEMPLATE
.
CKA_PRIVATE
If CKA_PRIVATE
is set to TRUE
, keys are protected by the logical token of the OCS.
If it is set to FALSE
, public keys are protected by a well-known module key, and other keys and objects are protected by the Security World module key.
You must set CKA_PRIVATE
to:
-
FALSE
for public keys -
TRUE
for non-extractable keys on card slots.
CKA_EXTRACTABLE
CKA_EXTRACTABLE
creates a key with an ACL including DeriveKey
permissions listed in the following table:
Key Type | Role | Mechanism |
---|---|---|
Secret key |
|
|
Private key |
|
|
CKA_ENCRYPT, CKA_DECRYPT, CKA_SIGN, CKA_VERIFY
These attributes create a key with ACL including Encrypt
, Decrypt
, Sign
, or Verify
permission.
CKA_WRAP, CKA_UNWRAP
CKA_WRAP
creates a key with an ACL including the DeriveKey
permissions listed in the following table:
Key Type | Role | Mechanism |
---|---|---|
Secret key |
|
|
Secret key (AES only) |
|
|
Secret key, public key (RSA only) |
|
|
Public key (elliptic curve only) |
|
|
CKA_UNWRAP
creates a key with an ACL including the DeriveKey
permissions listed in the following table:
Key Type | Role | Mechanism |
---|---|---|
Secret key |
|
|
Secret key (AES only) |
|
|
Secret key, public key (RSA only) |
|
|
Public key (elliptic curve only) |
|
|
CKA_WRAP_TEMPLATE, CKA_UNWRAP_TEMPLATE
CKA_WRAP_TEMPLATE
and CKA_UNWRAP_TEMPLATE
guard against non-compliance of keys by specifying an attribute template.
The CKA_WRAP_TEMPLATE
attribute applies to wrapping keys and specifies the attribute template to match against any of the keys wrapped by the wrapping key.
Keys which do not match the attribute template will not be wrapped.
The CKA_UNWRAP_TEMPLATE
attribute applies to wrapping keys and specifies the attribute template to apply to any of the keys which are unwrapped by the wrapping key.
Keys will not be unwrapped if there is attribute conflict between the CKA_UNWRAP_TEMPLATE
and any user supplied template (pTemplate
).
Nested occurrences of CKA_WRAP_TEMPLATE
or CKA_UNWRAP_TEMPLATE
are not supported.
If CKA_MODIFIABLE
or CKA_SENSITIVE
are defined within the CKA_UNWRAP_TEMPLATE
, the behavior is as follows:
PKCS #11 Attribute Types | Unwrap Template Attribute | C_Unwrap pTemplate Attribute | Attribute Value Comparison | Allowed |
---|---|---|---|---|
All supported |
Defined |
Defined |
Equal |
Yes |
Defined |
Defined |
Not Equal |
Yes |
|
Undefined |
Defined |
N/A |
Yes |
|
Defined |
Undefined |
N/A |
Yes |
PKCS #11 Attribute Types | Unwrap Template Attribute | C_Unwrap pTemplate Attribute | Attribute Value Comparison | Allowed |
---|---|---|---|---|
All supported |
Defined |
Defined |
Equal |
Yes |
Defined |
Defined |
Not Equal |
No |
|
Undefined |
Defined |
N/A |
Yes |
|
Defined |
Undefined |
N/A |
Yes |
PKCS #11 Attribute Types | C_Unwrap pTemplate Attribute | C_Unwrap pTemplate Attribute Value | Allowed |
---|---|---|---|
CKA_SENSITIVE |
Defined |
FALSE |
No |
CKA_EXTRACTABLE |
Defined |
FALSE |
No |
PKCS #11 Attribute Types | C_Unwrap pTemplate Attribute | C_Unwrap pTemplate Attribute Value | Allowed |
---|---|---|---|
CKA_SENSITIVE |
Defined |
TRUE |
Yes |
FALSE |
Yes |
||
CKA_EXTRACTABLE |
Defined |
TRUE |
Yes |
FALSE |
Yes |
See also CKA_ALLOWED_MECHANISMS
for more information about mechanism-specific restrictions applying to the use of CKA_UNWRAP_TEMPLATE
.
CKA_SIGN_RECOVER
C_SignRecover
checks CKA_SIGN_RECOVER
but is otherwise identical to C_Sign
.
Setting CKA_SIGN_RECOVER
creates a key with an ACL that includes Sign
permission.
CKA_VERIFY_RECOVER
Setting CKA_VERIFY_RECOVER
creates a public key with an ACL including Encrypt
permission.
CKA_DERIVE
For Diffie-Hellman private keys, CKA_DERIVE
creates a key with Decrypt
permissions.
For secret keys, CKA_DERIVE
creates a key with an ACL that includes DeriveRole_BaseKey
with one of DeriveMech_DESsplitXOR
, DeriveMech_DES2splitXOR
, DeriveMech_DES3splitXOR
, DeriveMech_RandsplitXOR
, or DeriveMech_CASTsplitXOR
as appropriate if the key is extractable, because this permission would effectively allow the key to be extracted.
The ACL includes DeriveMech_RawEncrypt
whether or not the key is extractable.
CKA_ALLOWED_MECHANISMS
CKA_ALLOWED_MECHANISMS
is available as a full attribute array for all key types.
The number of mechanisms in the array is the ulValueLen
component of the attribute divided by the size of CK_MECHANISM_TYPE
.
The CKA_ALLOWED_MECHANISMS
attribute is set when generating, creating and unwrapping keys.
CKA_ALLOWED_MECHANISMS
is an optional attribute and does not have to be set, except when the key is intended for use with one of the mechanisms described below.
However, if CKA_ALLOWED_MECHANISMS
is set, then the attribute is checked to see if the mechanism you want to use is in the list of allowed mechanisms.
If the mechanism is not present, then an error occurs and a value of CKR_MECHANISM_INVALID
is returned.
CKM_CONCATENATE_BASE_AND_KEY
You must set CKA_ALLOWED_MECHANISMS
with the CKM_CONCATENATE_BASE_AND_KEY
mechanism when generating or creating both of the keys that are used in the C_DeriveKey
operation with the CKM_CONCATENATE_BASE_AND_KEY
mechanism.
If CKA_ALLOWED_MECHANISMS
is not set at creation time then the correct ConcatenateBytes
ACL is not set for the keys.
When CKM_CONCATENATE_BASE_AND_KEY
is used with C_DeriveKey
, CKA_ALLOWED_MECHANISMS
is checked.
If CKM_CONCATENATE_BASE_AND_KEY
is not present, then an error occurs and a value of CKR_MECHANISM_INVALID
is returned.
CKM_RSA_AES_KEY_WRAP
You must set CKA_ALLOWED_MECHANISMS
with the CKM_RSA_AES_KEY_WRAP
mechanism when generating or creating RSA keys that also have CKA_UNWRAP_TEMPLATE
set on the private half if they are to be used in the C_UnwrapKey
operation with the CKM_RSA_AES_KEY_WRAP
mechanism.
When CKM_RSA_AES_KEY_WRAP
is used with C_UnwrapKey
, CKA_ALLOWED_MECHANISMS
is checked.
If CKM_RSA_AES_KEY_WRAP
is not present but the unwrapping key has CKA_UNWRAP_TEMPLATE
, then an error occurs and a value of CKR_MECHANISM_INVALID
is returned.
RSA private keys that have CKA_ALLOWED_MECHANISMS
set with the CKM_RSA_AES_KEY_WRAP
mechanism cannot be copied if they also have both the following attributes set:
-
CKA_TOKEN
with a value ofCK_TRUE
-
CKA_UNWRAP_TEMPLATE
The C_CopyObject
operation returns CKR_ACTION_PROHIBITED
for such keys.
CKA_MODIFIABLE
CKA_MODIFIABLE
only restricts access through the PKCS #11 API: all PKCS #11 keys have ACLs that include the ReduceACL
permission.
See also CKA_UNWRAP_TEMPLATE
.
CKA_START_DATE, CKA_END_DATE
These attributes are ignored, and the PKCS #11 standard states that these attributes do not restrict key usage.
CKA_TRUSTED and CKA_WRAP_WITH_TRUSTED
CKA_TRUSTED
and CKA_WRAP_WITH_TRUSTED
guard against a key being wrapped and removed from the HSM by an untrusted wrapping key.
A key with a CKA_WRAP_WITH_TRUSTED
attribute can only be wrapped by a wrapping key with a CKA_TRUSTED
attribute.
A trusted key can only be given a CKA_TRUSTED
attribute by the PKCS #11 Security officer.
The CKA_WRAP_WITH_TRUSTED
attribute gives a key an ACL whose DeriveRole_BaseKey
exists in a group protected by a certifier.
The ACL therefore requires a certificate generated by the PKCS #11 Security Officer to be able to wrap the key.
The CKA_TRUSTED
attribute stores on a wrapping key a certificate signed by the PKCS #11 Security Officer.
This certificate can then be used to authenticate a wrapping operation.
CKA_TRUSTED
can only be set if the session is logged in as CKU_SO
, and the Security Officer’s token and key has been preloaded.
If not, the operation will return CKR_USER_NOT_LOGGED_IN
.
CKA_WRAP_WITH_TRUSTED
does not require the Security Officer token and key to be preloaded, or to be logged in as CKU_SO
, but it does require that the role exists.
If the role does not exist, the operation returns CKR_USER_NOT_LOGGED_IN
.
When attributes have been set, the PKCS #11 Security Officer is not needed for C_WrapKey
to perform a trusted key wrapping.
If the PKCS #11 Security Officer is deleted, keys with existing CKA_TRUSTED or CKA_WRAP_WITH_TRUSTED attributes continue to be valid.
If the PKCS #11 Security Officer is recreated, any new keys that are given the CKA_TRUSTED attribute will not be trusted by existing keys with CKA_WRAP_WITH_TRUSTED , and vice versa.
|
A CKO_CERTIFICATE
object can also be given a CKA_TRUSTED
attribute, and also requires the PKCS #11 Security Officer to do so.
This includes using ckcerttool
with the -T
option, which sets CKA_TRUSTED
to true.
CKA_COPYABLE and CKA_DESTROYABLE
The CKA_COPYABLE
and CKA_DESTROYABLE
attributes indicate whether an object can be copied using C_CopyObject
or destroyed using C_DestroyObject
.
If the corresponding function is attempted when the attribute is set to false, the function returns CKR_ACTION_PROHIBITED
.
CKA_COPYABLE
and CKA_DESTROYABLE
can be applied to objects through all interfaces that support setting attributes:
-
C_GenerateKey
andC_GenerateKeyPair
-
C_CreateObject
-
C_SetAttributeValue
-
C_CopyObject
Existing and new objects have both attributes set to true by default.
When changing an attribute, CKA_COPYABLE
cannot be changed from false to true.
RSA key values
CKA_PRIVATE_EXPONENT
is not used when importing an RSA private key using C_CreateObject
.
However, it must be in the template, since the PKCS #11 standard requires it.
All the other values are required.
The nCore API allows use of a default public exponent, but the PKCS #11 standard requires CKA_PUBLIC_EXPONENT
.
Except for very small keys, the nShield default is 65537, which as a PKCS #11 big integer is CK_BYTEpublic_exponent[ ] = { 1, 0, 1 };
DSA key values
If CKA_PRIME
is 1024 bits or less, then the KeyType_DSAPrivate_GenParams_flags_Strict
flag is used, because it enforces a 1024 bit limit.
The implementation allows larger values of CKA_PRIME
, but in those cases the KeyType_DSAPrivate_GenParams_flags_Strict
flag is not used.
Vendor specific error codes
Security World Software defines the following vendor specific error codes:
CKR_FIPS_TOKEN_NOT_PRESENT
This error code indicates that an Operator Card is required even though the card slot is not in use.
CKR_FIPS_MECHANISM_INVALID
This error code indicates that the current mechanism is not allowed in FIPS 140 Level 3 mode.
CKR_FIPS_FUNCTION_NOT_SUPPORTED
This error code indicates that the function is not supported in FIPS 140 Level 3 mode (although it is supported in FIPS 140 Level 2 mode).