OASIS PKCS 11 TC

Looking at WD08 I see that the Byte arrays defined for the two functions differ in their naming although the descriptions are the same.

In C_EncapsulateKey the byte array pointer is called pCiphertext

In C_DecapsulateKey the byte array pointer is called pCiphertextKey

I believe they should have the same name.

It is also a little odd that the ciphertext and template attributes are ordered differently between the two functions, in C_EncapsulateKey the template attributes come before the ciphertext(key) ones, in C_Decapsulate the ciphertextkey attributes come before the template ones.

Is this intentional?

If not I think the template arguments should always come after the ciphertext ones.

Finally the output handle for the resulting key is also in a different position, given that this is actually the output parameter it should always be last, IMO.

Looking at WD08 I see that the Byte arrays defined for the two functions differ in their naming although the descriptions are the same.

In C_EncapsulateKey the byte array pointer is called pCiphertext

In C_DecapsulateKey the byte array pointer is called pCiphertextKey

I believe they should have the same name.

It is also a little odd that the ciphertext and template attributes are ordered differently between the two functions, in C_EncapsulateKey the template attributes come before the ciphertext(key) ones, in C_Decapsulate the ciphertextkey attributes come before the template ones.

Is this intentional?

If not I think the template arguments should always come after the ciphertext ones.

Finally the output handle for the resulting key is also in a different position, given that this is actually the output parameter it should always be last, IMO.

One correction here, because the CiphertextKey attributes are output attributes in the encapsulation case (they are input in the decapsulation case), they should always come after the template ones which are instead always an input attribute, so these are the definition s as I would change them:

CK_DECLARE_FUNCTION(CK_RV, C_EncapsulateKey)(  CK_SESSION_HANDLE hSession,  CK_MECHANISM_PTR pMechanism,  CK_OBJECT_HANDLE hPublicKey,  CK_ATTRIBUTE_PTR pTemplate,  CK_ULONG ulAttributeCount,  CK_BYTE_PTR pCiphertextKey,   CK_ULONG_PTR pulCiphertextLen   CK_OBJECT_HANDLE_PTR phKey,);CK_DECLARE_FUNCTION(CK_RV, C_DecapsulateKey)(  CK_SESSION_HANDLE hSession,  CK_MECHANISM_PTR pMechanism,  CK_OBJECT_HANDLE hPrivateKey,  CK_ATTRIBUTE_PTR pTemplate,  CK_ULONG ulAttributeCount,  CK_BYTE_PTR pCiphertextKey,  CK_ULONG ulCiphertextLen,  CK_OBJECT_HANDLE_PTR phKey,);

Looking at WD08 I see that the Byte arrays defined for the two functions differ in their naming although the descriptions are the same.

In C_EncapsulateKey the byte array pointer is called pCiphertext

In C_DecapsulateKey the byte array pointer is called pCiphertextKey

I believe they should have the same name.

It is also a little odd that the ciphertext and template attributes are ordered differently between the two functions, in C_EncapsulateKey the template attributes come before the ciphertext(key) ones, in C_Decapsulate the ciphertextkey attributes come before the template ones.

Is this intentional?

If not I think the template arguments should always come after the ciphertext ones.

Finally the output handle for the resulting key is also in a different position, given that this is actually the output parameter it should always be last, IMO.

All good points, here's my 2 cents:

• I agree, C_EncapsulateKey and C_DecapsulateKey should use the same name for the ciphered secret key. I'd rather use pCiphertext than pCiphertextKey though, because FIPS 203 also uses the term ciphertext.
• As a general rule, output arguments follow input arguments, and a template (if present at all) is typically the last of all input arguments. See e.g. C_WrapKey and C_UnwrapKey, where pWrappedKey/pulWrappedKeyLen are the last arguments in C_Wrapkey holding the output, while they precede pTemplate as input in C_UnwrapKey. I admit that C_EncapsulateKey is not 100% the same as C_WrapKey because C_WrapKey does not have a Template argument.
• I agree that phkey should be the very last argument for both functions.

With the above, I would declare the functions as follows:

CK_DECLARE_FUNCTION(CK_RV, C_EncapsulateKey)(  CK_SESSION_HANDLE hSession,  CK_MECHANISM_PTR pMechanism,  CK_OBJECT_HANDLE hPublicKey,  CK_ATTRIBUTE_PTR pTemplate,  CK_ULONG ulAttributeCount,  CK_BYTE_PTR pCiphertext,   CK_ULONG_PTR pulCiphertextLen,   CK_OBJECT_HANDLE_PTR phKey);CK_DECLARE_FUNCTION(CK_RV, C_DecapsulateKey)(  CK_SESSION_HANDLE hSession,  CK_MECHANISM_PTR pMechanism,  CK_OBJECT_HANDLE hPrivateKey,  CK_BYTE_PTR pCiphertext,  CK_ULONG ulCiphertextLen,  CK_ATTRIBUTE_PTR pTemplate,  CK_ULONG ulAttributeCount,  CK_OBJECT_HANDLE_PTR phKey);

One correction here, because the CiphertextKey attributes are output attributes in the encapsulation case (they are input in the decapsulation case), they should always come after the template ones which are instead always an input attribute, so these are the definition s as I would change them:

CK_DECLARE_FUNCTION(CK_RV, C_EncapsulateKey)(  CK_SESSION_HANDLE hSession,  CK_MECHANISM_PTR pMechanism,  CK_OBJECT_HANDLE hPublicKey,  CK_ATTRIBUTE_PTR pTemplate,  CK_ULONG ulAttributeCount,  CK_BYTE_PTR pCiphertextKey,   CK_ULONG_PTR pulCiphertextLen   CK_OBJECT_HANDLE_PTR phKey,);CK_DECLARE_FUNCTION(CK_RV, C_DecapsulateKey)(  CK_SESSION_HANDLE hSession,  CK_MECHANISM_PTR pMechanism,  CK_OBJECT_HANDLE hPrivateKey,  CK_ATTRIBUTE_PTR pTemplate,  CK_ULONG ulAttributeCount,  CK_BYTE_PTR pCiphertextKey,  CK_ULONG ulCiphertextLen,  CK_OBJECT_HANDLE_PTR phKey,);

Looking at WD08 I see that the Byte arrays defined for the two functions differ in their naming although the descriptions are the same.

In C_EncapsulateKey the byte array pointer is called pCiphertext

In C_DecapsulateKey the byte array pointer is called pCiphertextKey

I believe they should have the same name.

It is also a little odd that the ciphertext and template attributes are ordered differently between the two functions, in C_EncapsulateKey the template attributes come before the ciphertext(key) ones, in C_Decapsulate the ciphertextkey attributes come before the template ones.

Is this intentional?

If not I think the template arguments should always come after the ciphertext ones.

Finally the output handle for the resulting key is also in a different position, given that this is actually the output parameter it should always be last, IMO.