base spec review

[Patrick Steuer <psteuer9@gmail.com>]

I have reviewed the latest version of the base spec [1] and header files 
[2].
Here's what i noticed (line numbers refer to [1]) ..

1. Section numbering
- 5.4.1 C_Initialize [193] vs 1.1.2 C_Initialize [2486]
- This messes up the following section numbers..
- 5.4.2 C_Finalize [194] vs 5.4.1 C_Finalize [2540]
- ...

2. Message-based en/de-cryption: naming incosistency

- "C_EncryptMessageFinal"[240,1191(x2),4369,AppendixC(x2)],
- "C_EncryptMessageNext"[4369]
- "C_MessageEncryptFinal" [1332(x2),2058(Table 30),4249,4372,4444].
- The header files use and examples use "C_MessageEncryptFinal"

I think all these occurences should be changed to "C_MessageEncryptFinal",
which would be analogous to message based decryption.

[Remark: I do not get why some message-based functions follow the naming
convention "C_Message<Operation>..." while the others follow
"C_<Operation>Message..."]

3. Message-based en/de-cryption: not part of < 3.0 API [3]

- "C_EncryptMessage*","C_MessageEncrypt*" [1187-1191]
- The header files CK_FUNCTION_LIST structure does not include those

I think those are not part of the < 3.0 APIs and should be removed.

4. C_SessionCancel lacks the "Return values: ..." paragraph which all 
other function provide [~3297]

5. Missing return value or superfluous comma in C_DestroyObjects "Return 
values: ..." paragraph [3800].

6. The docs define CKR_OPERATION_CANCEL_FAILED while the header files do not

7. C_GetInfo example: CK_INFO has no member named âversionâ [2586]

8. C_GetInterfaceList example: i undeclared [2659]

9. C_GetInterface example: CKF_FORK_SAFE_INTERFACE is undefined

- I think it should be changed to CKF_INTERFACE_FORK_SAFE

10. CKF_INTERFACE_FORK_SAFE is defined in the header files but not in 
the doc

11. C_GetSlotList example: passing argument 3 of âC_GetSlotListâ makes 
pointer from integer without a cast [2809]

Change ulSlotWithTokenCount to &ulSlotWithTokenCount

12. C_WaitForSlotEvent example: rv undeclared [2914]

13. C_GetMechanismList example: outer if misses closing bracket [after 2964]

14. C_InitToken example: [3042] should probably re-written as 
"CK_UTF8CHAR pin[] = {"MyPIN"};" (analogous to the other examples and 
produces no warnings).

15. C_LoginUser example: typo (sizoef instead of sizeof) [3584]

16. C_SetOperationState example: pState undeclared [3466]

17. C_LoginUser example: typo: (username instead of userNAME) [3583]

18. C_LoginUser example: == oprator used in assignment (instead of =) [3588]

19. C_Logout example: == oprator used in assignment (instead of =) [3620]

20. C_GetObjectSize example: unused variable dataValue [3829]

21. C_CreateObject example: passing argument ** instead of * (x3)
- Change &dataTemplate to dataTemplate [3701]
- Change &certificateTemplate to certificateTemplate [3709]
- Change &keyTemplate to keyTemplate [3716]

22. C_CopyObjectExample: passing argument ** instead of * (x2)
- Change &keyTemplate to keyTemplate [3781]
- Change &copyTemplate to copyTemplate [3784]

23. C_GetObjectSizeExample: passing argument ** instead of *
- Change &template to template [3843]

24. C_GetAttributeValue example: passing argument ** instead of * (x2)
- Change &template to template [3922]
- Change &template to template [3932]

25. C_SetAttributeValue example: missing braces around initializer [3971]

26. C_SetAttributeValue example: passing argument ** instead of *
- Change &template to template [3977]

27. C_EncryptMessageFinal example: random closing bracket ")" (x2)
- at [4429]
- at [4437]

28. C_EncryptMessageFinal example: using ** instead of * (x2)
- Change &iv to iv [4390]
- Change &tag to tag [4394]

29. C_SignRecover example: last line does not belong here [5092]

30. C_DigestFinal example: hKey undeclared [4888]

31. C_DecryptDigestUpdate example: OOB write [5788]
- second argument of C_DigestUpdate just be just data (without offset)

32. C_DecryptVerifyUpdate example: typo (&uldataLen instead of 
ulDataLen) [6001]

33. C_DecryptVerifyUpdate example: OOB write [6027]
- second argument of C_VerifyUpdate just be just data (without offset)

34. C_DeriveKey example: missing opening brace "{" at [6357]

35. C_DeriveKey example: using ** instead of * [6385]
- Change &pTemplate to pTemplate

[1] 
https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/pkcs11-base-v3.0.docx
[2] 
https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/csprd01/include/pkcs11-v3.0/
[3] 
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html

Best regards,
Patrick