OASIS PKCS 11 TC

1) C_MessageEncryptInit (5.9.1 in v3.1) does not specify what the
pParameter/ulParameterLen of the pMechanism structure should be, my
understanding is that they should always be NULL because the actual
parameters are always defined on
C_EncryptMessage/C_EncryptMessageBegin/C_MessageEncryptNext but that is
not made explicit in the text and perhaps is not true otherwise I would
have expected the function to take a CKM_MECHANISM_TYPE parameter
instead of CKM_MECHANISM_PTR, some text either way would be nice.

If pParameter can be not null then the specific mechanisms implementing
CKF_MESSAGE_ENCRYPT etc should specify it which brings me to AES GCM
which is the only mechanism I looked into so far.

2) In "6.13 Additional AES Mechanisms"
I think the table should show EncryptMessage/DecryptMessage as
supported Functions in an additional column

Yes.

3) In "6.13.2 AES-GCM Authenticated Encryption / Decryption"
Under the "MessageEncrypt:" section the last bulle point says:
"Call C_MessageEncryptFinal() to close the message decryption.

Two problems:
3.1) decryption should really be encryption

3.2) I think this bulle point should rather say that
C_EncryptMessageNext() should be called with flags=CKF_END_OF_MESSAGE
to complete the message, because C_MessageEncryptFinal() is used to
terminate the whole message encryption operation not a single message.

Hmm that's closes a single message, not the whole stream. Perhaps the wording of the previous bullet should be updated to:

• Call and number of:

• ??C_EncryptMessage(), or??

• C_EncryptMessageBegin() followed by?? one or more?? C_EncryptMessageNext(), the last containing the CKF_END_OF_MESSAGE

• ??The mechanism parameter is passed to all three of these functions.

^{To make it clear you can call multiple messages in the single stream. You do need C_MessageEncryptFinal when you are done with the stream.}

^{Also, to your point 1) we can put the information that the parameter should be NULL for C_MessageEncryptInit here. We should carry these changes to Decrypt and AES_CCM and CHACHA_POLY.}

5) [uncertain] The two sections should probably be renamed:
MessageEncrypt -> EncryptMessage
MessageDecrypt -> DecryptMessage
to aligne with the name of the function used for the individual message
encryptions.

^{Hopefully the changes I suggest should make it clear the original titles are correct. The should describe the entire MessageEncrypt/MessageDecrypt semantics.}

- CKG_GENERATE_COUNTER_XOR means that the non-fixed portion of the IV
is xored with a counter. The value of the non-fixed portion passed must
not vary from call to call.

Does this mean that the fixed portion can vary?

Or should this say that
the input IV should not vary from call to call ? Perhaps it should be
made clear if the generated IV is returned in pIV for these calls
because it would then tell the application developer whether they need
to actively save the IV in a separate buffer for each call (or not).

bob

• Call and number of:

• ??C_EncryptMessage(), or??

• C_EncryptMessageBegin() followed by?? one or more?? C_EncryptMessageNext(), the last containing the CKF_END_OF_MESSAGE

• ??The mechanism parameter is passed to all three of these functions.

bob

1) C_MessageEncryptInit (5.9.1 in v3.1) does not specify what the pParameter/ulParameterLen of the pMechanism structure should be, my understanding is that they should always be NULL because the actual parameters are always defined on C_EncryptMessage/C_EncryptMessageBegin/C_MessageEncryptNext but that is not made explicit in the text and perhaps is not true otherwise I would have expected the function to take a CKM_MECHANISM_TYPE parameter instead of CKM_MECHANISM_PTR, some text either way would be nice.

If pParameter can be not null then the specific mechanisms implementing CKF_MESSAGE_ENCRYPT etc should specify it which brings me to AES GCM which is the only mechanism I looked into so far.

2) In "6.13 Additional AES Mechanisms" I think the table should show EncryptMessage/DecryptMessage as supported Functions in an additional column

Yes.

3) In "6.13.2 AES-GCM Authenticated Encryption / Decryption" Under the "MessageEncrypt:" section the last bulle point says: "Call C_MessageEncryptFinal() to close the message decryption.

Two problems: 3.1) decryption should really be encryption

3.2) I think this bulle point should rather say that C_EncryptMessageNext() should be called with flags=CKF_END_OF_MESSAGE to complete the message, because C_MessageEncryptFinal() is used to terminate the whole message encryption operation not a single message.

Hmm that's closes a single message, not the whole stream. Perhaps the wording of the previous bullet should be updated to:

• Call and number of:

• ??C_EncryptMessage(), or??

• C_EncryptMessageBegin() followed by?? one or more?? C_EncryptMessageNext(), the last containing the CKF_END_OF_MESSAGE

• ??The mechanism parameter is passed to all three of these functions.

^{To make it clear you can call multiple messages in the single stream. You do need C_MessageEncryptFinal when you are done with the stream.}

^{Also, to your point 1) we can put the information that the parameter should be NULL for C_MessageEncryptInit here. We should carry these changes to Decrypt and AES_CCM and CHACHA_POLY.}

5) [uncertain] The two sections should probably be renamed: MessageEncrypt -> EncryptMessage MessageDecrypt -> DecryptMessage to aligne with the name of the function used for the individual message encryptions.

^{Hopefully the changes I suggest should make it clear the original titles are correct. The should describe the entire MessageEncrypt/MessageDecrypt semantics.}

- CKG_GENERATE_COUNTER_XOR means that the non-fixed portion of the IV is xored with a counter. The value of the non-fixed portion passed must not vary from call to call. Does this mean that the fixed portion can vary?

Or should this say that the input IV should not vary from call to call ? Perhaps it should be made clear if the generated IV is returned in pIV for these calls because it would then tell the application developer whether they need to actively save the IV in a separate buffer for each call (or not).

bob