Cryptographic operations: GREP11 API

    message GetMechanismListRequest {
    }
    message GetMechanismListResponse {
      repeated uint64 Mechs = 2;
    }
    

    CK_RV m_GetMechanismList (
      CK_SLOT_ID slot,
      CK_MECHANISM_TYPE_PTR mechs, CK_ULONG_PTR mechslen,
      target_t target
    );
    

C_GetMechanismList is used to obtain a list of mechanism types supported by a token. SlotID is the ID of the token's slot; pulCount points to the location that receives the number of mechanisms.

Two ways are available for an application to call C_GetMechanismList:

1. If pMechanismList is NULL_PTR, then all that C_GetMechanismList does is return (in *pulCount) the number of mechanisms, without returning a list of mechanisms. The contents of *pulCount on entry to C_GetMechanismList has no meaning in this case, and the call returns the value CKR_OK.
2. If pMechanismList is not NULL_PTR, then *pulCount must contain the size (in terms of CK_MECHANISM_TYPE elements) of the buffer pointed to by pMechanismList. If that buffer is large enough to hold the list of mechanisms, then the list is returned in it, and CKR_OK is returned. If not, then the call to C_GetMechanismList returns the value CKR_BUFFER_TOO_SMALL. In either case, the value *pulCount is set to hold the number of mechanisms.

Because C_GetMechanismList does not allocate any space of its own, an application often calls C_GetMechanismList twice. However, this behavior is by no means required.

    CK_DEFINE_FUNCTION(CK_RV, C_GetMechanismList)(
      CK_SLOT_ID slotID,
      CK_MECHANISM_TYPE_PTR pMechanismList,
      CK_ULONG_PTR pulCount
    );
    

    message GetMechanismInfoRequest {
      uint64 Mech = 2;
    }
    message GetMechanismInfoResponse {
      MechanismInfo MechInfo = 3;
    }
    

    CK_RV m_GetMechanismInfo (
      CK_SLOT_ID slot,
      CK_MECHANISM_TYPE mech,
      CK_MECHANISM_INFO_PTR mechInfo,
      target_t target
    );
    

C_GetMechanismInfo obtains information about a particular mechanism that might be supported by a token. slotID is the ID of the token's slot; type is the type of mechanism; pInfo points to the location that receives the mechanism information.

    CK_DEFINE_FUNCTION(CK_RV, C_GetMechanismInfo)(
      CK_SLOT_ID slotID,
      CK_MECHANISM_TYPE type,
      CK_MECHANISM_INFO_PTR pInfo
    );
    

    message GenerateKeyRequest {
      Mechanism Mech = 1;
      map<uint64,AttributeValue> Template = 6;
    }
    message GenerateKeyResponse {
      bytes KeyBytes = 4;
      bytes CheckSum = 5;
    }
    

Implementation of PKCS #11 C_GenerateKey.

TDES keys are generated with proper parity, which is not observable by the host. But it is needed for proper interoperability: other PKCS #11 implementations needs to reject DES keys with parity problems.

If an object is tied to a session, (pin, plen) must be return by Login to that session. Leaving pin NULL creates a public object, one not bound to a login session.

(key, klen) returns the key blob. (csum, clen) contains the key's checksum, that is, the most significant bytes of an all-zero block encrypted by the key. NULL clen is possible, for example for symmetric-key mechanisms without CKA_CHECK_VALUE parameters (such as RC4).

ptempl is used only if the key length (that is, the CKA_VALUE_LEN attribute) is needed by the mechanism. If the mechanism implicitly specifies key size, ptempl is not checked for size.

DSA and DH parameter generation ignores (csum, clen), generating only parameter structures.

DSA, DH parameters (CKM_DSA_PARAMETER_GEN): pass modulus bitcount in CKA_PRIME_BITS of attributes. Writes P,Q,G structure as cleartext output (that is, not a blob).

The pin blob was output from: Login.

PKCS #11 phKey is not mapped to any EP11 parameter. (Host library must bind wrapped key to handle.)

    CK_RV m_GenerateKey (
      CK_MECHANISM_PTR mech,
      CK_ATTRIBUTE_PTR template, CK_ULONG templatelen,
      const unsigned char *pin, size_t pinlen,
      unsigned char *key, size_t *keylen,
      unsigned char *checkSum, size_t *checkSumlen,
      target_t target
      );
    

C_GenerateKey generates a secret key or set of domain parameters, creating a new object. hSession is the session's handle; pMechanism points to the generation mechanism; pTemplate points to the template for the new key or set of domain parameters; ulCount is the number of attributes in the template; phKey points to the location that receives the handle of the new key or set of domain parameters.

If the generation mechanism is for domain parameter generation, the CKA_CLASS attribute has the value CKO_DOMAIN_PARAMETERS; otherwise, it has the value CKO_SECRET_KEY.

Since the type of key or domain parameters to be generated is implicit in the generation mechanism, the template does not need to supply a key type. If it does supply a key type that is inconsistent with the generation mechanism, C_GenerateKey fails and returns the error code CKR_TEMPLATE_INCONSISTENT. The CKA_CLASS attribute is treated in the same way.

If a call to C_GenerateKey cannot support the precise template that is supplied to it, it fails and returns without creating an object.

The object created by a successful call to C_GenerateKey has the CKA_LOCAL attribute set to CK_TRUE.

    CK_DEFINE_FUNCTION(CK_RV, C_GenerateKey)(
      CK_SESSION_HANDLE hSession
      CK_MECHANISM_PTR pMechanism,
      CK_ATTRIBUTE_PTR pTemplate,
      CK_ULONG ulCount,
      CK_OBJECT_HANDLE_PTR phKey
      );
    

    message GenerateKeyPairRequest {
      Mechanism Mech = 1;
      map<uint64,AttributeValue> PrivKeyTemplate = 7;
      map<uint64,AttributeValue> PubKeyTemplate = 8;
      }
    message GenerateKeyPairResponse {
      bytes PrivKeyBytes = 5;
      bytes PubKeyBytes = 6;
    }
    

Implementation of PKCS #11 C_GenerateKeyPair.

Keypair parameters are retrieved from pmech, ppublic, and pprivate parameters. For RSA keys, ppublic specifies the modulus size.

In FIPS mode, only RSA moduluses of 1024+256 n bits are supported (integer n). Non-FIPS mode can generate keys of any even number of bits between the limits in the mechanism parameter list.

Public key is formatted as a standard SPKI (subject public key information), readable by most libraries. It is integrity-protected by a transport-key specific MAC, which is not part of the SPKI itself. DSA parameter generation returns a non-SPKI structure in the public key field.

If you tie an object to a session, (pin, plen) must be returned by Login to that session. Leaving pin NULL creates a public object, one that survives the login session.

Returns wrapped private key to (key, klen), public key as a MACed ASN.1/DER structure in (pubkey, pklen).

The following supported parameter combinations with special notes are beyond what are documented by PKCS #11:

RSA keys reject public exponents below 17 (0x11). Control points can further restrict the accepted minimum. The Fermat4 exponent, 0x10001, is controlled by a specific control point, matching public-exponent restrictions of FIPS 186-3 (section B.3.1).

EC keys (CKM_EC_KEY_PAIR_GEN): curve parameters can be specified as OIDs or symbolic names (our namedCurve variant). Supported symbolic names are "P-nnn" for NIST curves (nnn is a supported prime bitcount, 192 - 521), "BP-nnnR" for regular BP curve. (Names must be supplied as ASCII strings, without zero-termination.)

DSA keys (CKM_DSA_KEY_PAIR_GEN): pass P,Q,G structure as the CKA_IBM_STRUCT_PARAMS attribute of public attributes. Individual P,Q,G parameters might not be passed through regular PKCS #11 parameters, they must be combined to a single structure.

DH keys (CKM_DH_PKCS_KEY_PAIR_GEN): pass P,G structure as the CKA_IBM_STRUCT_PARAMS attribute of public attributes. Individual P,G parameters might not be passed through regular PKCS #11 parameters, they must be combined to a single structure. When you select a private-key (X) bitcount, use the XCP_U32_VALUE_BITS attribute. If not present, or an explicit 0 is supplied, bitcount is selected based on P bitcount.

Use of session (Login) state replaces standard use of sessions. The mapping is outside library scope.

The pin blob was output from: Login.

PKCS #11 hSession is not mapped to any EP11 parameter. (The call is not directly associated with any session.)

PKCS #11 phPublicKey is not mapped to any EP11 parameter. (Host library must associate pubkey (SPKI) with handle.)

PKCS #11 phPrivateKey is not mapped to any EP11 parameter. (Host library must associate private key with handle.)

    CK_RV m_GenerateKeyPair (
      CK_MECHANISM_PTR mech,
      CK_ATTRIBUTE_PTR pubKeyTemplate, CK_ULONG pubKeyTemplatelen,
      CK_ATTRIBUTE_PTR privKeyTemplate, CK_ULONG privKeyTemplatelen,
      const unsigned char *pin, size_t pinlen,
      unsigned char *privKey, size_t *privKeylen,
      unsigned char *pubKey, size_t *pubKeylen,
      target_t target
      );
    

C_GenerateKeyPair generates a public and private key pair, creating new key objects. hSession is the session's handle; pMechanism points to the key generation mechanism; pPublicKeyTemplate points to the template for the public key; ulPublicKeyAttributeCount is the number of attributes in the public-key template; pPrivateKeyTemplate points to the template for the private key; ulPrivateKeyAttributeCount is the number of attributes in the private-key template; phPublicKey points to the location that receives the handle of the new public key; phPrivateKey points to the location that receives the handle of the new private key.

Since the types of keys to be generated are implicit in the key pair generation mechanism, the templates do not need to supply key types. If one of the templates does supply a key type that is inconsistent with the key generation mechanism, C_GenerateKeyPair fails and returns the error code CKR_TEMPLATE_INCONSISTENT. The CKA_CLASS attribute is treated similarly.

If a call to C_GenerateKeyPair cannot support the precise templates that are supplied to it, it fails and returns without creating any key objects.

A call to C_GenerateKeyPair never creates just one key and returns. A call can fail, and create no keys; or it can succeed, and create a matching public and private key pair.

The key objects created by a successful call to C_GenerateKeyPair have the CKA_LOCAL attributes set to CK_TRUE.

Note carefully the order of the arguments to C_GenerateKeyPair. The last two arguments do not have the same order as they did in the original Cryptoki Version 1.0 document. The order of these two arguments caused some unfortunate confusion.

    CK_DEFINE_FUNCTION(CK_RV, C_GenerateKeyPair)(
      CK_SESSION_HANDLE hSession,
      CK_MECHANISM_PTR pMechanism,
      CK_ATTRIBUTE_PTR pPublicKeyTemplate,
      CK_ULONG ulPublicKeyAttributeCount,
      CK_ATTRIBUTE_PTR pPrivateKeyTemplate,
      CK_ULONG ulPrivateKeyAttributeCount,
      CK_OBJECT_HANDLE_PTR phPublicKey,
      CK_OBJECT_HANDLE_PTR phPrivateKey
      );
    

    message DeriveKeyRequest {
        Mechanism Mech = 1;
        bytes BaseKey = 3;
        bytes Data = 4;
        map<uint64,AttributeValue> Template = 8;
    }
    message DeriveKeyResponse {
        bytes NewKeyBytes = 6;
        bytes CheckSum = 7;
    }
    

Implementation of PKCS #11 C_DeriveKey.

The basekey,bklen blob must be mapped from the PKCS #11 hBaseKey parameter.

PKCS #11 hSession is not mapped to any EP11 parameter. (The call is not directly associated with any session.)

PKCS #11 phKey is not mapped to any EP11 parameter. (Host library must bind returned key to handle.)

    CK_RV m_DeriveKey (
        CK_MECHANISM_PTR mech,
        CK_ATTRIBUTE_PTR template, CK_ULONG templatelen,
        const unsigned char *baseKey, size_t baseKeylen,
        const unsigned char *data, size_t datalen,
        const unsigned char *pin, size_t pinlen,
        unsigned char *newKey, size_t *newKeylen,
        unsigned char *checkSum, size_t *checkSumlen,
        target_t target
    );
    

C_DeriveKey derives a key from a base key, creating a new key object. hSession is the session's handle; pMechanism points to a structure that specifies the key derivation chanism; hBaseKey is the handle of the base key; pTemplate points to the template for the new key; ulAttributeCount is the number of attributes in the template; and phKey points to the location that receives the handle of the derived key.

The values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, CKA_EXTRACTABLE, and KA_NEVER_EXTRACTABLE attributes for the base key affect the values that these attributes can hold for the newly derived key. See the description of each particular key-derivation mechanism in Section 5.16.2 of the PKCS #11 API specification for any constraints of this type.

If a call to C_DeriveKey cannot support the precise template that is supplied to it, it fails and returns without creating any key object.

The key object created by a successful call to C_DeriveKey has the CKA_LOCAL attribute set to CK_FALSE.

    CK_DEFINE_FUNCTION(CK_RV, C_DeriveKey)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hBaseKey,
        CK_ATTRIBUTE_PTR pTemplate,
        CK_ULONG ulAttributeCount,
        CK_OBJECT_HANDLE_PTR phKey
    );
    

    message WrapKeyRequest {
        bytes Key = 1;
        bytes KeK = 2;
        bytes MacKey = 3;
        Mechanism Mech = 4;
    }
    message WrapKeyResponse {
        bytes Wrapped = 5;
    }
    

    CK_RV m_WrapKey (
        const unsigned char *key, size_t keylen,
        const unsigned char *keK, size_t keKlen,
        const unsigned char *macKey, size_t macKeylen,
        const CK_MECHANISM_PTR mech,
        CK_BYTE_PTR wrapped, CK_ULONG_PTR wrappedlen,
        target_t target
    );
    

C_WrapKey wraps (that is, encrypts) a private or secret key. hSession is the session's handle; pMechanism points to the wrapping mechanism; hWrappingKey is the handle of the wrapping key; hKey is the handle of the key to be wrapped; pWrappedKey points to the location that receives the wrapped key; and pulWrappedKeyLen points to the location that receives the length of the wrapped key.

C_WrapKey uses the convention that is described in Section 5.2 of the PKCS #11 API specification on producing output.

The CKA_WRAP attribute of the wrapping key, which indicates whether the key supports wrapping, must be CK_TRUE. The CKA_EXTRACTABLE attribute of the key to be wrapped must also be CK_TRUE.

If the key to be wrapped cannot be wrapped for some token-specific reason, despite its having its CKA_EXTRACTABLE attribute set to CK_TRUE, then C_WrapKey fails with error code CKR_KEY_NOT_WRAPPABLE. If it cannot be wrapped with the specified wrapping key and mechanism solely because of its length, then C_WrapKey fails with error code CKR_KEY_SIZE_RANGE.

C_WrapKey can be used in the following situations:

• To wrap any secret key with a public key that supports encryption and decryption.
• To wrap any secret key with any other secret key. Consideration must be given to key size and mechanism strength or the token might not allow the operation.
• To wrap a private key with any secret key.

Tokens vary in which types of keys can be wrapped with which mechanisms.

To partition the wrapping keys so that they can wrap only a subset of extractable keys, the attribute CKA_WRAP_TEMPLATE can be used on the wrapping key to specify an attribute set that can be compared against the attributes of the key to be wrapped. If all attributes match according to the C_FindObject rules of attribute matching, the wrap operation proceeds. The value of this attribute is an attribute template and the size is the number of items in the template times the size of CK_ATTRIBUTE. If this attribute is not supplied, any template is acceptable. If an attribute is not present, it is not checked. If any attribute mismatch occurs on an attempt to wrap a key, the function returns CKR_KEY_HANDLE_INVALID.

    CK_DEFINE_FUNCTION(CK_RV, C_WrapKey)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hWrappingKey,
        CK_OBJECT_HANDLE hKey,
        CK_BYTE_PTR pWrappedKey,
        CK_ULONG_PTR pulWrappedKeyLen
    );
    

    message UnwrapKeyRequest {
        bytes Wrapped = 1;
        bytes KeK = 2;
        bytes MacKey = 3;
        Mechanism Mech = 5;
        map<uint64,AttributeValue> Template = 9;
    }
    message UnwrapKeyResponse {
        bytes UnwrappedBytes = 7;
        bytes CheckSum = 8;
    }
    

Implementation of PKCS #11 C_UnwrapKey.

uwmech specifies the encryption mechanism that is used to decrypt wrapped data. ptempl is a key(pair) parameter list, specifying how to transform the unwrapped data to a new key (must include CKA_KEY_TYPE).

The generated object is returned under (unwrapped, uwlen) as a blob. Symmetric keys return their key checksum (3 bytes) under (csum, cslen); public-key objects return their public key as an SPKI in (csum, cslen). Both forms are followed by a 4-byte big-endian value, encoding bitcount of the unwrapped key.

When an SPKI is being transformed to a MACed SPKI, one must use CKM_IBM_TRANSPORTKEY as the unwrapping mechanism. This mode supplies the raw SPKI as wrapped data, and ignores the KEK.

UnwrapKey produces parity-adjusted DES keys (within the blobs), but tolerates input with improper parity.

    CK_RV m_UnwrapKey (
        const CK_BYTE_PTR wrapped, CK_ULONG wrappedlen,
        const unsigned char *keK, size_t keKlen,
        const unsigned char *macKey, size_t macKeylen,
        const unsigned char *pin, size_t pinlen,
        const CK_MECHANISM_PTR mech,
        const CK_ATTRIBUTE_PTR template, CK_ULONG templatelen,
        unsigned char *unwrapped, size_t *unwrappedlen,
        CK_BYTE_PTR checkSum, CK_ULONG *checkSumlen,
        target_t target
    );
    

C_UnwrapKey unwraps (that is, decrypts) a wrapped key, creating a new private key or secret key object. hSession is the session's handle; pMechanism points to the unwrapping mechanism; hUnwrappingKey is the handle of the unwrapping key; pWrappedKey points to the wrapped key; ulWrappedKeyLen is the length of the wrapped key; pTemplate points to the template for the new key; ulAttributeCount is the number of attributes in the template; phKey points to the location that receives the handle of the recovered key.

The CKA_UNWRAP attribute of the unwrapping key, which indicates whether the key supports unwrapping, must be CK_TRUE.

The new key has the CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, and the CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE. The CKA_EXTRACTABLE attribute is by default set to CK_TRUE.

Some mechanisms can modify, or attempt to modify. The contents of the pMechanism structure at the same time that the key is unwrapped.

If a call to C_UnwrapKey cannot support the precise template that is supplied to it, it fails and returns without creating any key object.

The key object created by a successful call to C_UnwrapKey has its CKA_LOCAL attribute set to CK_FALSE.

To partition the unwrapping keys so they can unwrap only a subset of keys the attribute CKA_UNWRAP_TEMPLATE can be used on the unwrapping key to specify an attribute set that is added to attributes of the key to be unwrapped. If the attributes do not conflict with the user supplied attribute template, in pTemplate, the unwrap operation proceeds. The value of this attribute is an attribute template and the size is the number of items in the template times the size of CK_ATTRIBUTE. If this attribute is not present on the unwrapping key, then no extra attributes are added. If any attribute conflict occurs on an attempt to unwrap a key, then the function SHALL return CKR_TEMPLATE_INCONSISTENT.

    CK_DEFINE_FUNCTION(CK_RV, C_UnwrapKey)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hUnwrappingKey,
        CK_BYTE_PTR pWrappedKey,
        CK_ULONG ulWrappedKeyLen,
        CK_ATTRIBUTE_PTR pTemplate,
        CK_ULONG ulAttributeCount,
        CK_OBJECT_HANDLE_PTR phKey
    );
    

    message RewrapKeyBlobRequest {
    	bytes WrappedKey = 1;
    }
    message RewrapKeyBlobResponse {
    	bytes RewrappedKey = 1;
    }
    

    message GetAttributeValueRequest {
        bytes Object = 1;
        map<uint64,AttributeValue> Attributes = 3;
    }
    message GetAttributeValueResponse {
        map<uint64,AttributeValue> Attributes = 4;
    }
    

Implementation of PKCS #11 C_GetAttributeValue.

Does not represent or need sessions (part of blob), therefore does not use the hSession parameter.

EP11 uses more straightforward ways to decode, such as enumerating actual values instead of being more generic.

    CK_RV m_GetAttributeValue (
        const unsigned char *object, size_t objectlen,
        CK_ATTRIBUTE_PTR attributes, CK_ULONG attributeslen,
        target_t target
    );
    

C_GetAttributeValue obtains the value of one or more attributes of an object. hSession is the session's handle; hObject is the object's handle; pTemplate points to a template that specifies which attribute values are to be obtained, and receives the attribute values; ulCount is the number of attributes in the template.

For each (type, pValue, ulValueLen) triple in the template, C_GetAttributeValue performs the following algorithm:

1. If the specified attribute (that is, the attribute that is specified by the type field) for the object cannot be revealed because the object is sensitive or unextractable, then the ulValueLen field in that triple is modified to hold the value CK_UNAVAILABLE_INFORMATION.
2. Otherwise, if the specified value for the object is invalid (the object does not possess such an attribute), then the ulValueLen field in that triple is modified to hold the value CK_UNAVAILABLE_INFORMATION.
3. Otherwise, if the pValue field has the value NULL_PTR, then the ulValueLen field is modified to hold the exact length of the specified attribute for the object.
4. Otherwise, if the length specified in ulValueLen is large enough to hold the value of the specified attribute for the object, then that attribute is copied into the buffer that is at pValue, and the ulValueLen field is modified to hold the exact length of the attribute.
5. Otherwise, the ulValueLen field is modified to hold the value CK_UNAVAILABLE_INFORMATION.

If case 1 applies to any of the requested attributes, then the call needs to return the value CKR_ATTRIBUTE_SENSITIVE. If case 2 applies to any of the requested attributes, then the call needs to return the value CKR_ATTRIBUTE_TYPE_INVALID. If case 5 applies to any of the requested attributes, then the call needs to return the value CKR_BUFFER_TOO_SMALL. As usual, if more than one of these error codes is applicable, Cryptoki can return any of them. Only if none of them applies to any of the requested attributes, CKR_OK is returned.

In the special case of an attribute whose value is an array of attributes, for example CKA_WRAP_TEMPLATE, where it is passed in with pValue not NULL, then if the pValue of elements within the array is NULL_PTR then the ulValueLen of elements within the array is set to the required length. If the pValue of elements within the array is not NULL_PTR, then the ulValueLen element of attributes within the array must reflect the space that the corresponding pValue points to, and pValue is filled in if there is sufficient room. Therefore, it is important to initialize the contents of a buffer before C_GetAttributeValue is called to get such an array value. If any ulValueLen within the array isn't large enough, it is set to CK_UNAVAILABLE_INFORMATION and the function returns CKR_BUFFER_TOO_SMALL, as it does if an attribute in the pTemplate argument has ulValueLen too small. Any attribute whose value is an array of attributes is identifiable by the CKF_ARRAY_ATTRIBUTE set of the attribute type.

The error codes CKR_ATTRIBUTE_SENSITIVE, CKR_ATTRIBUTE_TYPE_INVALID, and CKR_BUFFER_TOO_SMALL do not denote true errors for C_GetAttributeValue. If a call to C_GetAttributeValue returns any of these three values, then the call must nonetheless have processed every attribute in the template that is supplied to C_GetAttributeValue. Each attribute in the template whose value can be returned by the call to C_GetAttributeValue is returned by the call to C_GetAttributeValue.

    CK_DEFINE_FUNCTION(CK_RV, C_GetAttributeValue)(
        CK_SESSION_HANDLE hSession,
        CK_OBJECT_HANDLE hObject,
        CK_ATTRIBUTE_PTR pTemplate,
        CK_ULONG ulCount
    );
    

    message SetAttributeValueRequest {
        bytes Object = 1;
        map<uint64,AttributeValue> Attributes = 3;
    }
    message SetAttributeValueResponse {
        bytes Object = 1;
    }
    

Implementation of PKCS #11 C_SetAttributeValue.

Attribute packing: see _GetAttrValue

Currently, Ep11 only sends Boolean attributes, all other attributes are handled by host (and EP11 does not modify arrays, such as WRAP_TEMPLATE).

Does not represent or need sessions (part of blob), therefore does not use the PKCS #11 hSession parameter.

    CK_RV m_SetAttributeValue (
        unsigned char *object, size_t objectlen,
        CK_ATTRIBUTE_PTR attributes, CK_ULONG attributeslen,
        target_t target
    );
    

C_SetAttributeValue modifies the value of one or more attributes of an object. hSession is the session's handle; hObject is the object's handle; pTemplate points to a template that specifies which attribute values are to be modified and their new values; ulCount is the number of attributes in the template.

Certain objects might not be modified. Calling C_SetAttributeValue on such objects results in the CKR_ACTION_PROHIBITED error code. An application can consult the object's CKA_MODIFIABLE attribute to determine whether an object can be modified.

Only session objects can be modified during a read-only session.

The template can specify new values for any attributes of the object that can be modified. If the template specifies a value of an attribute that is incompatible with other existing attributes of the object, the call fails with the return code CKR_TEMPLATE_INCONSISTENT.

Not all attributes can be modified; see Section 4.1.2 of the PKCS #11 API specification for more information.

    CK_DEFINE_FUNCTION(CK_RV, C_SetAttributeValue)(
        CK_SESSION_HANDLE hSession,
        CK_OBJECT_HANDLE hObject,
        CK_ATTRIBUTE_PTR pTemplate,
        CK_ULONG ulCount
    );
    

    message GenerateRandomRequest {
        uint64 Len = 1;
    }
    message GenerateRandomResponse {
        bytes Rnd = 1;
    }
    

Implementation of PKCS #11 C_GenerateRandom.

GenerateRandom is equivalent to the original PKCS #11 function. Internally, hardware-seeded entropy is passed through a FIPS-compliant DRNG (ANSI X9.31/ISO 18031, depending on Clic version).

The host library could generate random numbers without dispatching to the backend, if suitable functionality would be available on the host. This is not done in the current implementation.

This function does not support a size query.

    CK_RV m_GenerateRandom (
        CK_BYTE_PTR rnd, CK_ULONG rndlen,
        target_t target
    );
    

    CK_DEFINE_FUNCTION(CK_RV, C_GenerateRandom)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pRandomData,
        CK_ULONG ulRandomLen
    );
    

    message EncryptInitRequest {
        Mechanism Mech = 2;
        bytes Key = 3;
    }
    message EncryptInitResponse {
        bytes State = 1;
    }
    

Implementation of PKCS #11 C_EncryptInit.

The (key, klen) blob can be a public-key object, or a secret-key blob. Key type must be consistent with pmech.

For public-key mechanisms, (key, klen) must contain an SPKI. This SPKI is integrity-protected with a MAC key, as returned by GenerateKeyPair or alternatively UnwrapKey. The Encrypt state is created without session restrictions.

For secret-key mechanisms, the Encrypt state inherits object session restrictions from (key, klen).

The state,slen blob must be mapped from the PKCS #11 hSession parameter.

(key, klen) must be a key blob.

    CK_RV m_EncryptInit (
        unsigned char *state, size_t *statelen,
        CK_MECHANISM_PTR mech,
        const unsigned char *key, size_t keylen,
        target_t target
    );
    

C_EncryptInit initializes an encryption operation. hSession is the session’s handle; pMechanism points to the encryption mechanism; hKey is the handle of the encryption key.

The CKA_ENCRYPT attribute of the encryption key, which indicates whether the key supports encryption, must be CK_TRUE.

After the application calls C_EncryptInit, the application can either call C_Encrypt to encrypt data in a single part; or call C_EncryptUpdate zero or more times, followed by C_EncryptFinal, to encrypt data in multiple parts. The encryption operation is active until the application uses a call to C_Encrypt or C_EncryptFinal to obtain the final piece of ciphertext. To process extra data (in single or multiple parts), the application must call C_EncryptInit again.

    CK_DEFINE_FUNCTION(CK_RV, C_EncryptInit)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hKey
    );
    

    message EncryptRequest {
        bytes State = 1;
        bytes Plain = 2;
    }
    message EncryptResponse {
        bytes Ciphered = 3;
    }
    

Implementation of PKCS #11 C_Encrypt.

Does not update (state, slen).

The state,slen blob must be mapped from the PKCS #11 hSession parameter.

The state blob was output from: EncryptInit.

    CK_RV m_Encrypt (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR plain, CK_ULONG plainlen,
        CK_BYTE_PTR ciphered, CK_ULONG_PTR cipheredlen,
        target_t target
    );
    

C_Encrypt encrypts single-part data. hSession is the session’s handle; pData points to the data; ulDataLen is the length in bytes of the data; pEncryptedData points to the location that receives the encrypted data; pulEncryptedDataLen points to the location that holds the length in bytes of the encrypted data.

C_Encrypt uses the convention that is described in Section 5.2 of the PKCS #11 API specification on producing output.

The encryption operation must be initialized with C_EncryptInit. A call to C_Encrypt always terminates the active encryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (that is, one that returns CKR_OK) to determine the length of the buffer that is needed to hold the ciphertext.

C_Encrypt cannot be used to terminate a multi-part operation, and must be called after C_EncryptInit without intervening C_EncryptUpdate calls.

For some encryption mechanisms, the input plain text data has certain length constraints (either because the mechanism can encrypt only relatively short pieces of plain text, or because the mechanism’s input data must consist of an integral number of blocks). If these constraints are not satisfied, then C_Encrypt fails with return code CKR_DATA_LEN_RANGE.

The plain text and ciphertext can be in the same place, that is, it is OK if pData and pEncryptedData point to the same location.

For most mechanisms, C_Encrypt is equivalent to a sequence of C_EncryptUpdate operations followed by C_EncryptFinal.

    CK_DEFINE_FUNCTION(CK_RV, C_Encrypt)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pData,
        CK_ULONG ulDataLen,
        CK_BYTE_PTR pEncryptedData,
        CK_ULONG_PTR pulEncryptedDataLen
    );
    

    message EncryptUpdateRequest {
        bytes State = 1;
        bytes Plain = 2;
    }
    message EncryptUpdateResponse {
        bytes State = 1;
        bytes Ciphered = 3;
    }
    

Implementation of PKCS #11 C_EncryptUpdate.

The state, slen blob must be mapped from the PKCS #11 hSession parameter.

The state blob was output from: EncryptInit.

    CK_RV m_EncryptUpdate (
        unsigned char *state, size_t statelen,
        CK_BYTE_PTR plain, CK_ULONG plainlen,
        CK_BYTE_PTR ciphered, CK_ULONG_PTR cipheredlen,
        target_t target
    );
    

C_EncryptUpdate continues a multiple-part encryption operation, processing another data part. hSession is the session’s handle; pPart points to the data part; ulPartLen is the length of the data part; pEncryptedPart points to the location that receives the encrypted data part; pulEncryptedPartLen points to the location that holds the length in bytes of the encrypted data part.

C_EncryptUpdate uses the convention that is described in Section 5.2 of the PKCS #11 API specification on producing output.

The encryption operation must be initialized with C_EncryptInit. This function can be called any number of times in succession. A call to C_EncryptUpdate which results in an error other than CKR_BUFFER_TOO_SMALL terminates the current encryption operation.

The plaintext and ciphertext can be in the same place, that is, it is OK if pPart and pEncryptedPart point to the same location.

    CK_DEFINE_FUNCTION(CK_RV, C_EncryptUpdate)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pPart,
        CK_ULONG ulPartLen,
        CK_BYTE_PTR pEncryptedPart,
        CK_ULONG_PTR pulEncryptedPartLen
    );
    

    message EncryptFinalRequest {
        bytes State = 1;
    }
    message EncryptFinalResponse {
        bytes Ciphered = 2;
    }
    

Implementation of PKCS #11 C_EncryptFinal.

Does not update (state, slen).

The state,slen blob must be mapped from the PKCS #11 hSession parameter.

The state blob was output from: EncryptInit, EncryptUpdate.

    CK_RV m_EncryptFinal (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR ciphered, CK_ULONG_PTR cipheredlen,
        target_t target
    );
    

C_EncryptFinal finishes a multiple-part encryption operation. hSession is the session’s handle; pLastEncryptedPart points to the location that receives the last encrypted data part, if any; pulLastEncryptedPartLen points to the location that holds the length of the last encrypted data part.

C_EncryptFinal uses the convention that is described in Section 5.2 of the PKCS #11 API specification on producing output.

The encryption operation must be initialized with C_EncryptInit. A call to C_EncryptFinal always terminates the active encryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (that is, one that returns CKR_OK) to determine the length of the buffer that is needed to hold the ciphertext.

For some multi-part encryption mechanisms, the input plain text data has certain length constraints because the mechanism’s input data must consist of an integral number of blocks. If these constraints are not satisfied, then C_EncryptFinal fails with return code CKR_DATA_LEN_RANGE.

    CK_DEFINE_FUNCTION(CK_RV, C_EncryptFinal)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pLastEncryptedPart,
        CK_ULONG_PTR pulLastEncryptedPartLen
    );
    

    message EncryptSingleRequest {
        bytes Key = 1;
        Mechanism Mech = 2;
        bytes Plain = 3;
    }
    message EncryptSingleResponse {
        bytes Ciphered = 4;
    }
    

Non-standard variant of Encrypt. Processes data in one pass, with one call. Does not return any state to host, only encrypted data.

This is the preferred method of encrypting data in one pass for XCP-aware applications. Functionally it is equivalent to EncryptInit followed immediately by Encrypt, but it saves roundtrips, wrapping, and unwrapping.

If the backend supports resident keys, the key can be also a resident-key handle.

See also: Encrypt, EncryptInit, DecryptSingle.

The key blob was output from: GenerateKey, UnwrapKey.

    CK_RV m_EncryptSingle (
        const unsigned char *key, size_t keylen,
        CK_MECHANISM_PTR mech,
        CK_BYTE_PTR plain, CK_ULONG plainlen,
        CK_BYTE_PTR ciphered, CK_ULONG_PTR cipheredlen,
        target_t target
    );
    

    message ReencryptSingleRequest {
        bytes DecKey = 1;
        bytes EncKey = 2;
        Mechanism DecMech = 3;
        Mechanism EncMech = 4;
        bytes Ciphered = 5;
    }
    message ReencryptSingleResponse {
        bytes Reciphered = 6;
    }
    

Non-standard variant of Encrypt. Processes data in one pass, with one call. Does not return any state to host, only the reencrypted data.

Decrypts data with the original key and then encrypts the raw data with a different key within the cloud HSM.

    CK_RV m_ReencryptSingle (
        const unsigned char *dkey, size_t dkeylen,
        const unsigned char *ekey, size_t ekeylen,
        CK_MECHANISM_PTR decmech,
        CK_MECHANISM_PTR encmech,
        CK_BYTE_PTR in, CK_ULONG inlen,
        CK_BYTE_PTR ciphered, CK_ULONG_PTR cipheredlen,
        target_t target
    );
    

    message DecryptInitRequest {
        Mechanism Mech = 2;
        bytes Key = 3;
    }
    message DecryptInitResponse {
        bytes State = 1;
    }
    

    CK_RV m_DecryptInit (
        unsigned char *state, size_t *statelen,
        CK_MECHANISM_PTR mech,
        const unsigned char *key, size_t keylen,
        target_t target
    );
    

C_DecryptInit initializes a decryption operation. hSession is the session’s handle; pMechanism points to the decryption mechanism; hKey is the handle of the decryption key.

The CKA_DECRYPT attribute of the decryption key, which indicates whether the key supports decryption, must be CK_TRUE.

After the application calls C_DecryptInit, the application can either call C_Decrypt to decrypt data in a single part; or call C_DecryptUpdate zero or more times, followed by C_DecryptFinal, to decrypt data in multiple parts. The decryption operation is active until the application uses a call to C_Decrypt or C_DecryptFinal to obtain the final piece of plaintext. To process extra data (in single or multiple parts), the application must call C_DecryptInit again.

    CK_DEFINE_FUNCTION(CK_RV, C_DecryptInit)(
        K_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hKey
    );
    

    message DecryptRequest {
        bytes State = 1;
        bytes Ciphered = 2;
    }
    message DecryptResponse {
       bytes Plain = 3;
    }
    

Implementation of PKCS #11 C_Decrypt. It does not update (state, slen).

The state, slen binary large object (BLOB) must be mapped from the PKCS #11 hSession parameter. The state BLOB was output from DecryptInit.

    CK_RV m_Decrypt (const unsigned char *state, size_t slen,
        CK_BYTE_PTR cipher, CK_ULONG clen,
        CK_BYTE_PTR plain, CK_ULONG_PTR plen,
        target_t target
    );
    

C_Decrypt decrypts encrypted data in a single part.

• hSession is the session handle.
• pEncryptedData points to the encrypted data.
• ulEncryptedDataLen is the length of the encrypted data.
• pData points to the location that receives the recovered data.
• pulDataLen points to the location that holds the length of the recovered data.

C_Decrypt uses the convention that is described in Section 5.2 of the PKCS #11 API specification on producing output.

The decryption operation needs to be initialized with C_DecryptInit. A call to C_Decrypt always terminates the active decryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call with CKR_OK returned to determine the length of the buffer that is needed to hold the plain text.

C_Decrypt cannot be used to terminate a multi-part operation, and needs to be called after C_DecryptInit without intervening C_DecryptUpdate calls.

The ciphertext and plain text can be in the same place, which means it is acceptable if pEncryptedData and pData point to the same location.

If the input ciphertext data cannot be decrypted because it has an inappropriate length, either CKR_ENCRYPTED_DATA_INVALID or CKR_ENCRYPTED_DATA_LEN_RANGE can be returned.

    CK_DEFINE_FUNCTION(CK_RV, C_Decrypt)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pEncryptedData,
        CK_ULONG ulEncryptedDataLen,
        CK_BYTE_PTR pData,
        CK_ULONG_PTR pulDataLen
    );
    

    message DecryptUpdateRequest {
        bytes State = 1;
        bytes Ciphered = 2;
    }
    message DecryptUpdateResponse {
        bytes State = 1;
        bytes Plain = 3;
    }
    

Implementation of PKCS #11 C_DecryptUpdate.

The state,slen blob must be mapped from the PKCS #11 hSession parameter.

The state blob was output from: DecryptInit.

    CK_RV m_DecryptUpdate (
        unsigned char *state, size_t statelen,
        CK_BYTE_PTR ciphered, CK_ULONG cipheredlen,
        CK_BYTE_PTR plain, CK_ULONG_PTR plainlen,
        target_t target
    );
    

C_DecryptUpdate continues a multiple-part decryption operation, processing another encrypted data part. hSession is the session’s handle; pEncryptedPart points to the encrypted data part; ulEncryptedPartLen is the length of the encrypted data part; pPart points to the location that receives the recovered data part; pulPartLen points to the location that holds the length of the recovered data part.

C_DecryptUpdate uses the convention that is described in Section 5.2 of the PKCS #11 API specification on producing output.

The decryption operation must be initialized with C_DecryptInit. This function can be called any number of times in succession. A call to C_DecryptUpdate which results in an error other than CKR_BUFFER_TOO_SMALL terminates the current decryption operation.

The ciphertext and plain text can be in the same place, that is, it is OK if pEncryptedPart and pPart point to the same location.

    CK_DEFINE_FUNCTION(CK_RV, C_DecryptUpdate)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pEncryptedPart,
        CK_ULONG ulEncryptedPartLen,
        CK_BYTE_PTR pPart,
        CK_ULONG_PTR pulPartLen
    );
    

    message DecryptFinalRequest {
        bytes State = 1;
    }
    message DecryptFinalResponse {
        bytes Plain = 2;
    }
    

Implementation of PKCS #11 C_DecryptFinal.

Does not update (state, slen).

The state,slen blob must be mapped from the PKCS #11 hSession parameter.

The state blob was output from: DecryptInit, DecryptUpdate.

    CK_RV m_DecryptFinal (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR plain, CK_ULONG_PTR plainlen,
        target_t target
    );
    

C_DecryptFinal finishes a multiple-part decryption operation. hSession is the session’s handle; pLastPart points to the location that receives the last recovered data part, if any; pulLastPartLen points to the location that holds the length of the last recovered data part.

C_DecryptFinal uses the convention that is described in Section 5.2 of the PKCS #11 API specification on producing output.

The decryption operation must be initialized with C_DecryptInit. A call to C_DecryptFinal always terminates the active decryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (that is, one that returns CKR_OK) to determine the length of the buffer that is needed to hold the plain text.

If the input ciphertext data cannot be decrypted because it has an inappropriate length, then either CKR_ENCRYPTED_DATA_INVALID or CKR_ENCRYPTED_DATA_LEN_RANGE can be returned.

    CK_DEFINE_FUNCTION(CK_RV, C_DecryptFinal)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pLastPart,
        CK_ULONG_PTR pulLastPartLen
    );
    

    message DecryptSingleRequest {
        bytes Key = 1;
        Mechanism Mech = 2;
        bytes Ciphered = 3;
    }
    message DecryptSingleResponse {
        bytes Plain = 4;
    }
    

Non-standard variant of Decrypt. Processes data in one pass, with one call. Does not return any state to host, only decrypted data.

This is the preferred method of encrypting data in one pass for XCP-aware applications. Functionally it is equivalent to DecryptInit followed immediately by Decrypt, but it saves roundtrips, wrapping, and unwrapping.

If the backend supports resident keys, the key can be also a resident-key handle.

See also: Decrypt, DecryptInit, EncryptSingle.

The key blob was output from: GenerateKey, UnwrapKey.

    CK_RV m_DecryptSingle (
        const unsigned char *key, size_t keylen,
        CK_MECHANISM_PTR mech,
        CK_BYTE_PTR ciphered, CK_ULONG cipheredlen,
        CK_BYTE_PTR plain, CK_ULONG_PTR plainlen,
        target_t target
    );
    

    message SignInitRequest {
        Mechanism Mech = 2;
        bytes PrivKey = 3;
    }
    message SignInitResponse {
        bytes State = 1;
    }
    

    CK_RV m_SignInit (
        unsigned char *state, size_t *statelen,
        CK_MECHANISM_PTR mech,
        const unsigned char *privKey, size_t privKeylen,
        target_t target
    );
    

C_SignInit initializes a signature operation, where the signature is an appendix to the data. hSession is the session's handle; pMechanism points to the signature mechanism; hKey is the handle of the signature key.

The CKA_SIGN attribute of the signature key, which indicates whether the key supports signatures with appendix, must be CK_TRUE.

After the application calls C_SignInit, the application can either call C_Sign to sign in a single part; or call C_SignUpdate one or more times, followed by C_SignFinal, to sign data in multiple parts. The signature operation is active until the application uses a call to C_Sign or C_SignFinal to obtain the signature. To process extra data (in single or multiple parts), the application must call C_SignInit again.

    CK_DEFINE_FUNCTION(CK_RV, C_SignInit)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hKey
    );
    

    message SignRequest {
        bytes State = 1;
        bytes Data = 2;
    }
    message SignResponse {
        bytes Signature = 3;
    }
    

Implementation of PKCS #11 C_Sign.

Does not update (state, slen).

The state,slen blob must be mapped from the PKCS #11 hSession parameter. (Host library must map session to stored state.)

The state blob was output from: SignInit.

    CK_RV m_Sign (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR signature, CK_ULONG_PTR signaturelen,
        target_t target
    );
    

C_Sign signs data in a single part, where the signature is an appendix to the data. hSession is the session's handle; pData points to the data; ulDataLen is the length of the data; pSignature points to the location that receives the signature; pulSignatureLen points to the location that holds the length of the signature.

C_Sign uses the convention that is described in Section 5.2 of the PKCS #11 API specification on producing output.

The signing operation must be initialized with C_SignInit. A call to C_Sign always terminates the active signing operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (that is, one that returns CKR_OK) to determine the length of the buffer that is needed to hold the signature.

C_Sign cannot be used to terminate a multi-part operation, and must be called after C_SignInit without intervening C_SignUpdate calls.

For most mechanisms, C_Sign is equivalent to a sequence of C_SignUpdate operations followed by C_SignFinal.

    CK_DEFINE_FUNCTION(CK_RV, C_Sign)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pData,
        CK_ULONG ulDataLen,
        CK_BYTE_PTR pSignature,
        CK_ULONG_PTR pulSignatureLen
    );
    

    message SignUpdateRequest {
        bytes State = 1;
        bytes Data = 2;
    }
    message SignUpdateResponse {
        bytes State = 1;
    }
    

The state,slen blob must be mapped from the PKCS #11 hSession parameter. (Host library must map session to stored state.)

The state blob was output from: SignInit.

    CK_RV m_SignUpdate (
        unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        target_t target
    );
    

C_SignUpdate continues a multiple-part signature operation, processing another data part. hSession is the session's handle, pPart points to the data part; ulPartLen is the length of the data part.

The signature operation must be initialized with C_SignInit. This function can be called any number of times in succession. A call to C_SignUpdate which results in an error terminates the current signature operation.

    CK_DEFINE_FUNCTION(CK_RV, C_SignUpdate)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pPart,
        CK_ULONG ulPartLen
    );
    

    message SignFinalRequest {
        bytes State = 1;
    }
    message SignFinalResponse {
        bytes Signature = 2;
    }
    

Implementation of PKCS #11 C_SignFinal.

Does not update (state, slen).

The state,slen blob must be mapped from the PKCS #11 hSession parameter. (Host library must map session to stored state.)

The state blob was output from: SignInit, SignUpdate.

    CK_RV m_SignFinal (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR signature, CK_ULONG_PTR signaturelen,
        target_t target
    );
    

C_SignFinal finishes a multiple-part signature operation, returning the signature. hSession is the session's handle; pSignature points to the location that receives the signature; pulSignatureLen points to the location that holds the length of the signature.

C_SignFinal uses the convention that is described in Section 5.2 of the PKCS #11 API specification on producing output.

The signing operation must be initialized with C_SignInit. A call to C_SignFinal always terminates the active signing operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (that is, one that returns CKR_OK) to determine the length of the buffer that is needed to hold the signature.

    CK_DEFINE_FUNCTION(CK_RV, C_SignFinal)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pSignature,
        CK_ULONG_PTR pulSignatureLen
    );
    

    message SignSingleRequest {
        bytes PrivKey = 1;
        Mechanism Mech = 2;
        bytes Data = 3;
    }
    message SignSingleResponse {
        bytes Signature = 4;
    }
    

Nonstandard extension, combination of SignInit and Sign. Signs or MACs data in one pass, with one call, without constructing intermediate digest state. Does not return any state to host, only result.

This is the preferred way of signing, without an extra roundtrip, encryption, and decryption. Functionally, SignSingle is equivalent to SignInit followed immediately by Sign.

The (key, klen) blob and the pmech mechanism together must be passable to SignInit.

Multi-data requests for HMAC and CMAC signatures are supported (subvariants 2 and 3).

See also: SignInit, Sign, VerifySingle.

    CK_RV m_SignSingle (
        const unsigned char *privKey, size_t privKeylen,
        CK_MECHANISM_PTR mech,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR signature, CK_ULONG_PTR signaturelen,
        target_t target
    );
    

    message VerifyInitRequest {
        Mechanism Mech = 2;
        bytes PubKey = 3;
    }
    message VerifyInitResponse {
        bytes State = 1;
    }
    

Implementation of PKCS #11 C_VerifyInit. Given a key blob (key, klen), initialize a verify session state in (state, slen). The key blob can be a public key object, or HMAC key bytes. Key blob type must be consistent with pmech.

For public-key mechanisms, (key, klen) must contain an SPKI. This SPKI CKA_UNWRAP can be MACed (such as returned earlier by GenerateKeyPair) or just the SPKI itself (if obtained from an external source, such as a certificate).

If an HMAC operation is initialized, session restrictions of the Verify object are inherited from the HMAC key. Since SPKIs are not tied to sessions, public-key Verify states are session-free.

The key,klen blob must be mapped from the PKCS #11 hKey parameter.

Note: SignInit and VerifyInit are internally the same for HMAC and other symmetric/MAC mechanisms.

    CK_RV m_VerifyInit (
        unsigned char *state, size_t *statelen,
        CK_MECHANISM_PTR mech,
        const unsigned char *pubKey, size_t pubKeylen,
        target_t target
    );
    

C_VerifyInit initializes a verification operation, where the signature is an appendix to the data. hSession is the session's handle; pMechanism points to the structure that specifies the verification mechanism; hKey is the handle of the verification key.

The CKA_VERIFY attribute of the verification key, which indicates whether the key supports verification where the signature is an appendix to the data, must be CK_TRUE.

After the application calls C_VerifyInit, the application can either call C_Verify to verify a signature on data in a single part; or call C_VerifyUpdate one or more times, followed by C_VerifyFinal, to verify a signature on data in multiple parts. The verification operation is active until the application calls C_Verify or C_VerifyFinal. To process extra data (in single or multiple parts), the application must call C_VerifyInit again.

    CK_DEFINE_FUNCTION(CK_RV, C_VerifyInit)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism,
        CK_OBJECT_HANDLE hKey
    );
    

    message VerifyRequest {
        bytes State = 1;
        bytes Data = 2;
        bytes Signature = 3;
    }
    message VerifyResponse {
    }
    

Implementation of PKCS #11 C_Verify.

Does not update (state, slen).

The relative order of data and signature are reversed relative to VerifySingle.

The state,slen blob must be mapped from the PKCS #11 hSession parameter. (Host library must map session to stored state.)

The state blob was output from: VerifyInit.

    CK_RV m_Verify (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR signature, CK_ULONG signaturelen,
        target_t target
    );
    

C_Verify verifies a signature in a single-part operation, where the signature is an appendix to the data. hSession is the session's handle; pData points to the data; ulDataLen is the length of the data; pSignature points to the signature; ulSignatureLen is the length of the signature.

The verification operation must be initialized with C_VerifyInit. A call to C_Verify always terminates the active verification operation.

A successful call to C_Verify needs to return either the value CKR_OK (indicating that the supplied signature is valid) or CKR_SIGNATURE_INVALID (indicating that the supplied signature is invalid). If the signature is invalid purely based on its length, then CKR_SIGNATURE_LEN_RANGE needs to be returned. In any of these cases, the active signing operation is terminated.

C_Verify cannot be used to terminate a multi-part operation, and must be called after C_VerifyInit without intervening C_VerifyUpdate calls.

For most mechanisms, C_Verify is equivalent to a sequence of C_VerifyUpdate operations followed by C_VerifyFinal.

    CK_DEFINE_FUNCTION(CK_RV, C_Verify)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pData,
        CK_ULONG ulDataLen,
        CK_BYTE_PTR pSignature,
        CK_ULONG ulSignatureLen
    );
    

    message VerifyUpdateRequest {
        bytes State = 1;
        bytes Data = 2;
    }
    message VerifyUpdateResponse {
        bytes State = 1;
    }
    

Implementation of PKCS #11 C_VerifyUpdate.

The state,slen blob must be mapped from the PKCS #11 hSession parameter. (Host library must map session to stored state.)

The state blob was output from: VerifyInit.

    CK_RV m_VerifyUpdate (
        unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        target_t target
    );
    

C_VerifyUpdate continues a multiple-part verification operation, processing another data part. hSession is the session's handle, pPart points to the data part; ulPartLen is the length of the data part.

The verification operation must be initialized with C_VerifyInit. This function can be called any number of times in succession. A call to C_VerifyUpdate that results in an error terminates the current verification operation.

    CK_DEFINE_FUNCTION(CK_RV, C_VerifyUpdate)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pPart,
        CK_ULONG ulPartLen
    );
    

    message VerifyFinalRequest {
        bytes State = 1;
        bytes Signature = 2;
    }
    message VerifyFinalResponse {
    }
    

Implementation of PKCS #11 C_VerifyFinal.

Does not update (state, slen).

The state,slen blob must be mapped from the PKCS #11 hSession parameter. (Host library must map session to stored state.)

The state blob was output from: VerifyInit, VerifyUpdate.

    CK_RV m_VerifyFinal (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR signature, CK_ULONG signaturelen,
        target_t target
    );
    

C_VerifyFinal finishes a multiple-part verification operation, checking the signature. hSession is the session's handle; pSignature points to the signature; ulSignatureLen is the length of the signature.

The verification operation must be initialized with C_VerifyInit. A call to C_VerifyFinal always terminates the active verification operation.

A successful call to C_VerifyFinal needs to return either the value CKR_OK (indicating that the supplied signature is valid) or CKR_SIGNATURE_INVALID (indicating that the supplied signature is invalid). If the signature is invalid based on its length, then CKR_SIGNATURE_LEN_RANGE needs to be returned. In any of these cases, the active verifying operation is terminated.

    CK_DEFINE_FUNCTION(CK_RV, C_VerifyFinal)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pSignature,
        CK_ULONG ulSignatureLen
    );
    

    message VerifySingleRequest {
        bytes PubKey = 1;
        Mechanism Mech = 2;
        bytes Data = 3;
        bytes Signature = 4;
    }
    message VerifySingleResponse {
    }
    

Nonstandard extension, combination of VerifyInit and Verify. Signs or MACs data in one pass, with one call, without constructing intermediate digest state. Does not return any state to host, only verification result. No size query is available because this function returns a Boolean.

This is the preferred way of verifying a signature, without an extra roundtrip, encryption, decryption. Functionally, VerifySingle is equivalent to VerifyInit followed immediately by a Verify.

The (key, klen) blob and the pmech mechanism together must be passable to VerifyInit.

For public-key mechanisms, (key, klen) must contain an SPKI. This SPKI can be MACed (such as returned as a public key from GenerateKeyPair) or just the SPKI itself (if obtained from an external source, such as a certificate).

See also: VerifyInit, Verify, SignSingle.

    CK_RV m_VerifySingle (
        const unsigned char *pubKey, size_t pubKeylen,
        CK_MECHANISM_PTR mech,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR signature, CK_ULONG signaturelen,
        target_t target
    );
    

    message DigestInitRequest {
        Mechanism Mech = 2;
    }
    message DigestInitResponse {
        bytes State = 1;
    }
    

Implementation of PKCS #11 C_DigestInit.

Create wrapped digest state.

Note: size queries are supported, but the wrapped state is always returned by the backend, unlike most size queries (which return an output size, instead of actual output). Digest states are sufficiently small that they do not introduce noticeable transport overhead.

During size queries, the host just discards the returned state, and reports blob size (in len). When blob is being returned, len is checked against returned size.

The state,len blob must be mapped from the PKCS #11 hSession parameter. (Host library must tie blob to session.)

    CK_RV m_DigestInit (
        unsigned char *state, size_t *len,
        const CK_MECHANISM_PTR mech,
        target_t target
    );
    

C_DigestInit initializes a message-digesting operation. hSession is the session’s handle; pMechanism points to the digesting mechanism.

After the application calls C_DigestInit, the application can either call C_Digest to digest data in a single part; or call C_DigestUpdate zero or more times, followed by C_DigestFinal, to digest data in multiple parts. The message-digesting operation is active until the application uses a call to C_Digest or C_DigestFinal to obtain the message digest. To process extra data (in single or multiple parts), the application must call 1C_DigestInit1 again.

    CK_DEFINE_FUNCTION(CK_RV, C_DigestInit)(
        CK_SESSION_HANDLE hSession,
        CK_MECHANISM_PTR pMechanism
    );
    

    message DigestRequest {
        bytes State = 1;
        bytes Data = 2;
    }
    message DigestResponse {
        bytes Digest = 3;
    }
    

Implementation of PKCS #11 C_Digest.

If a digest object has exactly 0 (zero) bytes that are appended to it after creation, in any combination of zero-byte transfers, it can still perform a one-pass Digest, even if it needs to be rejected by a strict implementation.

Does not update (state, slen).

Implementations might perform DigestUpdate, DigestFinal, or Digest calls on cleartext digest objects in host code, bypassing HSM backends altogether. This choice might or might not be visible to host code, and it does not impact the security of the operation (as clear objects might not digest sensitive data).

The state,slen blob must be mapped from the PKCS #11 hSession parameter. The state blob was output from: DigestInit.

    CK_RV m_Digest (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR digest, CK_ULONG_PTR digestlen,
        target_t target
    );
    

C_Digest digests data in a single part. hSession is the session’s handle, pData points to the data; ulDataLen is the length of the data; pDigest points to the location that receives the message digest; pulDigestLen points to the location that holds the length of the message digest.

C_Digest uses the convention that is described in Section 5.2 of the PKCS #11 API specification on producing output.

The digest operation must be initialized with C_DigestInit. A call to C_Digest always terminates the active digest operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (that is, one that returns CKR_OK) to determine the length of the buffer that is needed to hold the message digest.

C_Digest cannot be used to terminate a multi-part operation, and must be called after C_DigestInit without intervening C_DigestUpdate calls.

The input data and digest output can be in the same place, that is, it is OK if pData and pDigest point to the same location.

C_Digest is equivalent to a sequence of C_DigestUpdate operations followed by C_DigestFinal.

    CK_DEFINE_FUNCTION(CK_RV, C_Digest)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pData,
        CK_ULONG ulDataLen,
        CK_BYTE_PTR pDigest,
        CK_ULONG_PTR pulDigestLen
    );
    

    message DigestUpdateRequest {
        bytes State = 1;
        bytes Data = 2;
    }
    message DigestUpdateResponse {
        bytes State = 1;
    }
    

Implementation of PKCS #11 C_DigestUpdate.

DigestUpdate is polymorphic, accepting both wrapped or clear digest objects, updating state in the same format.

The state,slen blob must be mapped from the PKCS #11 hSession parameter. (Host library must map session to stored state.)

The state blob was output from: DigestInit, DigestUpdate, DigestKey.

See also: DigestInit

    CK_RV m_DigestUpdate (
        unsigned char *state, size_t statelen,
        CK_BYTE_PTR data, CK_ULONG datalen,
        target_t target
    );
    

C_DigestUpdate continues a multiple-part message-digesting operation, processing another data part. hSession is the session’s handle, pPart points to the data part; ulPartLen is the length of the data part.

The message-digesting operation must be initialized with C_DigestInit. Calls to this function and C_DigestKey can be interspersed any number of times in any order. A call to C_DigestUpdate which results in an error terminates the current digest operation.

    CK_DEFINE_FUNCTION(CK_RV, C_DigestUpdate)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pPart,
        CK_ULONG ulPartLen
    );
    

    message DigestFinalRequest {
        bytes State = 1;
    }
    message DigestFinalResponse {
        bytes Digest = 2;
    }
    

Implementation of PKCS #11 C_DigestFinal.

DigestFinal is polymorphic, accepting both wrapped or clear digest objects.

Does not update (state, slen).

The state,slen blob must be mapped from the PKCS #11 hSession parameter.

The state blob was output from: DigestInit, DigestUpdate, DigestKey.

    CK_RV m_DigestFinal (
        const unsigned char *state, size_t statelen,
        CK_BYTE_PTR digest, CK_ULONG_PTR digestlen,
        target_t target
    );
    

C_DigestFinal finishes a multiple-part message-digesting operation, returning the message digest. hSession is the session’s handle; pDigest points to the location that receives the message digest; pulDigestLen points to the location that holds the length of the message digest.

C_DigestFinal uses the convention that is described in Section 5.2 of the PKCS #11 API specification on producing output.

The digest operation must be initialized with C_DigestInit. A call to C_DigestFinal always terminates the active digest operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (that is, one that returns CKR_OK) to determine the length of the buffer that is needed to hold the message digest.

    CK_DEFINE_FUNCTION(CK_RV, C_DigestFinal)(
        CK_SESSION_HANDLE hSession,
        CK_BYTE_PTR pDigest,
        CK_ULONG_PTR pulDigestLen
    );
    

    message DigestSingleRequest {
        Mechanism Mech = 1;
        bytes Data = 2;
    }
    message DigestSingleResponse {
        bytes Digest = 3;
    }
    

Nonstandard extension, combination of DigestInit and Digest. Digests data in one pass, with one call, without constructing an intermediate digest state, and unnecessary roundtrips.

This is the preferred method of digesting cleartext for XCP-aware applications. Functionally, DigestSingle is equivalent to DigestInit followed immediately by Digest.

If a key needs to be digested, one must use DigestInit and DigestKey, since this function does not handle key blobs.

Does not return any state to host, only digest result. There are no non-PKCS #11 parameters, since everything is used directly from the PKCS #11 call.

    CK_RV m_DigestSingle (
        CK_MECHANISM_PTR mech,
        CK_BYTE_PTR data, CK_ULONG datalen,
        CK_BYTE_PTR digest, CK_ULONG_PTR digestlen,
        target_t target
    );