= PKCS#11 Definitions =

These are issues that will likely need to be addressed in an PKCS#11 v2.40 amendment.

Items that are shown as --(strike through)-- have been addressed.
Items which could be handled in an errata document (if the TC decides to publish one) are noted as '''errata''' or they may simply be folded into the next minor version of the specification.

== csprd03a Problems ==

pkcs11-base-v2.40-csprd03a.doc

 * CK_HW_FEATURE should be changed to CK_HW_FEATURE_TYPE. '''(errata)''' '''correct in 3.4, incorrect in 4.3.3.1, 4.3.4.1, 4.3.5.1'''
 * Remove #define for CKR_COPY_PROHIBITED  '''(errata)''' '''this should not exist and where it is used it is meant to be CKR_ACTION_PROHIBITED'''

pkcs11-curr-v2.40-csprd03a.doc

 * CK_SEED_CBC_ENCRYPT_DATA_PARAMS is a zero length structure.  '''(errata/nextver)''' '''missing definition combined with typos'''

{{{
typedef struct CK_SEED_CBC_ENCRYPT_DATA_PARAMS {
  CK_BYTE      iv[16];
  CK_BYTE_PTR  pData;
  CK_ULONG     length;
}  CK_SEED_CBC_ENCRYPT_DATA_PARAMS;
typedef CK_SEED_CBC_ENCRYPT_DATA_PARAMS CK_PTR CK_SEED_CBC_ENCRYPT_DATA_PARAMS_PTR;
}}}

 * CK_PARAM_TYPE should be changed to CK_OTP_PARAM_TYPE throughout.  '''(errata)''' '''typographical error that should be corrected'''
 * Missing definition and deprecation of CK_PKCS5_PBKD2_PARAMS in favor of CK_PKCS5_PBKD2_PARAMS2.  '''(nextver)''' '''missing from the specification text - we decided to make this change and deprecate the incorrect version which has the wrong type''' [[http://markmail.org/message/g4rwktabxyfmarsv#query:+page:1+mid:ivsjzbravrywwvvw+state:results|see this mail thread]]

{{{
typedef struct CK_PKCS5_PBKD2_PARAMS2 {
	CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE saltSource;
	CK_VOID_PTR pSaltSourceData;
	CK_ULONG ulSaltSourceDataLen;
	CK_ULONG iterations;
	CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE prf;
	CK_VOID_PTR pPrfData;
	CK_ULONG ulPrfDataLen;
	CK_UTF8CHAR_PTR pPassword;
	CK_ULONG ulPasswordLen; /* CHANGE */
} CK_PKCS5_PBKD2_PARAMS2;
}}}

 * CKM_X9_42_DH_PKCS_PARAMETER_GEN should be changed to CKM_X9_42_DH_PARAMETER_GEN throughout.  '''(errata)''' '''typographical error repeated in multiple locations - contained in the v2.11, v2.20 and v2.30 docs'''
 * CKM_AES_XCBC_MAC-96 is incorrect in 2.8.12  '''(errata)''' '''typo in the one location - should be CKM_AES_XCBC_MAC_96'''
 * In 2.41.5.1 the CKA_OTP_CHALLENGE_REQUIREMENT table entry has an incorrect line break.  '''(errata)'''
 * CKA_OTP_CHALLENGE_REQURIEMENT should be changed to CKA_OTP_CHALLENGE_REQUIREMENT throughout.  '''(errata)''' '''typo'''
 * CK_CBC_ENCRYPT_DATA_PARAMS should be replaced with CK_SEED_CBC_ENCRYPT_DATA_PARAMS throughout.  '''(errata|nextver)'''
 * CK_CBC_ENCRYPT_DATA_PARAMS_PTR should be replaced with CK_SEED_CBC_ENCRYPT_DATA_PARAMS_PTR throughout. '''(errata|nextver)'''
 * 2.2.1 is missing the following text after the description of CK_DSA_PARAMETER_GEN_PARAM: "CK_DSA_PARAMETER_GEN_PARAM_PTR is a pointer to a CK_DSA_PARAMETER_GEN_PARAM".  '''(errata)'''
 * 2.3.8 has an extra space in "CK_ECMQV _DERIVE_PARAMS"  '''(errata)'''
 * 2.45.5 is missing the following text after the description of CK_GOSTR3410_DERIVE_PARAMS: "CK_GOSTR3410_DERIVE_PARAMS_PTR is a pointer to a  CK_GOSTR3410_DERIVE_PARAMS".  '''(errata)'''
 * 2.45.5 is missing the following text after the description of CK_GOSTR3410_KEY_WRAP_PARAMS: "CK_GOSTR3410_KEY_WRAP_PARAMS_PTR is a pointer to a CK_GOSTR3410_KEY_WRAP_PARAMS".  '''(errata)'''
 * CKM_DSA_PROBABALISTIC_PARAMETER_GEN should be changed to CKM_DSA_PROBABLISTIC_PARAMETER_GEN throughout.  '''(errata)'''
 * CKM_GOSTR3410_WITH_GOST3411 should be changed to CKM_GOSTR3410_WITH_GOSTR3411 throughout.  '''(errata)'''
 * CKM_SHA1 should be changed to CKM_SHA_1 throughout. '''(errata)''' '''but only those precise items - not the other items which match that which are not the same - the spec is inconsistent in this area'''
 * CK_OTP_FORMAT should be changed to CK_OTP_OUTPUT_FORMAT throughout. '''(errata|nextver)''' '''this issue is in v2.30 and the v2.20 ammendments - it is correct in the header files but not the specification'''
 * CK_PKCS5_PBKD2_PARAM should be changed to CK_PKCS5_PBKD2_PARAMS throughout.
 * Missing CK_ECDH2_DERIVE_PARAMS and CK_ECDH2_DERIVE_PARAMS_PTR
 * Missing CK_CAMELLIA_CTR_PARAMS and CK_CAMELLIA_CTR_PARAMS_PTR
 * Missing CK_TLS_PRF_PARAMS and CK_TLS_PRF_PARAMS_PTR

pkcs11-hist-v2.40-csprd02a.doc

 * 2.7.1 "CKM_CAST128_CB C" should be changed to CKM_CAST128_CBC '''(errata)''' '''single instance typo - correct in all other usage in the doc'''
 * 2.3.6 CKM_DEA_DERIVE should be changed to CKM_KEA_DERIVE '''(errata)''' '''single instance typo - correct in all other usage in the doc'''
 * 2.16.2 CKM_RIMEMD128 should be changed to CKM_RIPEMD128 '''(errata)''' '''single instance typo - correct in all other usage in the doc'''
 * --(2.8.3.1 CK_PRIVATE_WRAP_PARAMS should be changed to 2.8.3.1 CK_SKIPJACK_PRIVATE_WRAP_PARAMS)-- '''(okay)''' '''was this already fixed as it isn't this way in the current OS documents?'''

== Possibly missing definitions ==

 * CKA_DERIVE_TEMPLATE '''(unclear)''' '''this is in the v2.30 header files but it is not referenced anywhere in the specification text'''
{{{
#define CKA_DERIVE_TEMPLATE      (CKF_ARRAY_ATTRIBUTE|0x00000213)
}}}
 * CKM_CMS_SIG_PARAMS '''(unclear)''' '''there has never been a defined CKM_CMS_SIG_PARAMS mechanism in any header file. There has been references in the specification since v2.20'''
 * CKM_ECDSA_SHA224 '''(unclear)''' '''this has never been defined in the spec. there is a value in the v2.30 header files'''
{{{
#define CKM_ECDSA_SHA224               0x00001043
}}}
 * CKM_ECDSA_SHA256 '''(unclear)''' '''this has never been defined in the spec. there is a value in the v2.30 header files'''
{{{
#define CKM_ECDSA_SHA256               0x00001044
}}}
 * CKM_ECDSA_SHA384 '''(unclear)''' '''this has never been defined in the spec. there is a value in the v2.30 header files'''
{{{
#define CKM_ECDSA_SHA384               0x00001045
}}}
 * CKM_ECDSA_SHA512 '''(unclear)''' '''this has never been defined in the spec. there is a value in the v2.30 header files'''
{{{
#define CKM_ECDSA_SHA512               0x00001046
}}}
 * CKK_MD5_HMAC '''(unclear)''' '''this has never been defined in the spec. there is a value in the v2.30 header files'''
{{{
#define CKK_MD5_HMAC        0x00000027
}}}
 * CKK_RIPEMD128_HMAC '''(unclear)''' '''there is a value in the v2.30 spec and header files but no other reference'''
{{{
#define CKK_RIPEMD128_HMAC  0x00000029
}}}
 * CKK_RIPEMD160_HMAC '''(unclear)''' '''there is a value in the v2.30 spec and header files but no other reference'''
{{{
#define CKK_RIPEMD160_HMAC  0x0000002A
}}}
 * CK_CAMELLIA_CTR_PARAMS '''(unclear)''' '''there is a definition in v2.20a3 and v2.30 header files but no other reference'''
{{{
typedef struct CK_CAMELLIA_CTR_PARAMS {
    CK_ULONG ulCounterBits;
    CK_BYTE cb[16];
} CK_CAMELLIA_CTR_PARAMS;
typedef CK_CAMELLIA_CTR_PARAMS CK_PTR CK_CAMELLIA_CTR_PARAMS_PTR;
}}}
 * CK_ECDH2_DERIVE_PARAMS '''(unclear)''' '''there is a definition in v2.20a3 and v2.30 header files but no other reference'''
{{{
typedef struct CK_ECDH2_DERIVE_PARAMS {
  CK_EC_KDF_TYPE kdf;
  CK_ULONG ulSharedDataLen;
  CK_BYTE_PTR pSharedData;
  CK_ULONG ulPublicDataLen;
  CK_BYTE_PTR pPublicData;
  CK_ULONG ulPrivateDataLen;
  CK_OBJECT_HANDLE hPrivateData;
  CK_ULONG ulPublicDataLen2;
  CK_BYTE_PTR pPublicData2;
} CK_ECDH2_DERIVE_PARAMS;
typedef CK_ECDH2_DERIVE_PARAMS CK_PTR CK_ECDH2_DERIVE_PARAMS_PTR;
}}}
 * CK_TLS_PRF_PARAMS '''(unclear)''' '''there is a definition in v2.20 and v2.30 header files but no other reference'''
{{{
typedef struct CK_TLS_PRF_PARAMS {
  CK_BYTE_PTR  pSeed;
  CK_ULONG     ulSeedLen;
  CK_BYTE_PTR  pLabel;
  CK_ULONG     ulLabelLen;
  CK_BYTE_PTR  pOutput;
  CK_ULONG_PTR pulOutputLen;
} CK_TLS_PRF_PARAMS;
typedef CK_TLS_PRF_PARAMS CK_PTR CK_TLS_PRF_PARAMS_PTR;
}}}

== Definitions that need adding to appendixes ==

'''Note: definition values where they clash with a previously allocated value in v2.30 or earlier have been updated.'''

{{{
#define CKK_GOST28147 0x00000032    /* WAS: 0x00000062 */
#define CKK_GOSTR3410 0x00000030    /* WAS: 0x00000060 */
#define CKK_GOSTR3411 0x00000031    /* WAS: 0x00000061 */
#define CKC_VENDOR_DEFINED 0x80000000
#define CKK_SEED 0x0000002F         /* WAS: 0x00000050 */
#define CKK_SHA_1_HMAC 0x00000028   /* WAS: 0x00000040 */
#define CKK_SHA224_HMAC 0x0000002E  /* WAS: 0x00000041 */
#define CKK_SHA256_HMAC 0x0000002B  /* WAS: 0x00000042 */
#define CKK_SHA384_HMAC 0x0000002C  /* WAS: 0x00000043 */
#define CKK_SHA512_HMAC 0x0000002D  /* WAS: 0x00000044 */
#define CKM_AES_GMAC 0x0000108E
#define CKM_DES3_CMAC 0x00000138
#define CKM_DES3_CMAC_GENERAL 0x00000137
#define CKM_KEA_DERIVE 0x00001012
#define CKM_SEED_CBC 0x00000652
#define CKM_SEED_CBC_ENCRYPT_DATA 0x00000657
#define CKM_SEED_CBC_PAD 0x00000655
#define CKM_SEED_ECB 0x00000651
#define CKM_SEED_ECB_ENCRYPT_DATA 0x00000656
#define CKM_SEED_KEY_GEN 0x00000650
#define CKM_SEED_MAC 0x00000653
#define CKM_SEED_MAC_GENERAL 0x00000654
#define CKM_TLS12_KDF 0x000003D9

/* Flags and values should be defined for completeness */
#define CKC_WTLS 0x00000002
#define CKC_X_509 0x00000000
#define CKC_X_509_ATTR_CERT 0x00000001
#define CKD_CPDIVERSIFY_KDF 0x00000009
#define CKD_NULL 0x00000001
#define CKD_SHA1_KDF 0x00000002
#define CKD_SHA1_KDF_ASN1 0x00000003
#define CKD_SHA1_KDF_CONCATENATE 0x00000004
#define CKD_SHA224_KDF 0x00000005
#define CKD_SHA256_KDF 0x00000006
#define CKD_SHA384_KDF 0x00000007
#define CKD_SHA512_KDF 0x00000008
#define CKF_CLOCK_ON_TOKEN 0x00000040
#define CKF_DECRYPT 0x00000200
#define CKF_DERIVE 0x00080000
#define CKF_DIGEST 0x00000400
#define CKF_DUAL_CRYPTO_OPERATIONS 0x00000200
#define CKF_EC_COMPRESS 0x02000000
#define CKF_EC_ECPARAMETERS 0x00400000
#define CKF_EC_F_2M 0x00200000
#define CKF_EC_F_P 0x00100000
#define CKF_EC_NAMEDCURVE 0x00800000
#define CKF_EC_UNCOMPRESS 0x01000000
#define CKF_ENCRYPT 0x00000100
#define CKF_ERROR_STATE 0x01000000
#define CKF_EXTENSION 0x80000000
#define CKF_GENERATE 0x00008000
#define CKF_GENERATE_KEY_PAIR 0x00010000
#define CKF_HW 0x00000001
#define CKF_HW_SLOT 0x00000004
#define CKF_LIBRARY_CANT_CREATE_OS_THREADS 0x00000001
#define CKF_LOGIN_REQUIRED 0x00000004
#define CKF_OS_LOCKING_OK 0x00000002
#define CKF_PROTECTED_AUTHENTICATION_PATH 0x00000100
#define CKF_REMOVABLE_DEVICE 0x00000002
#define CKF_RESTORE_KEY_NOT_NEEDED 0x00000020
#define CKF_RNG 0x00000001
#define CKF_RW_SESSION 0x00000002
#define CKF_SECONDARY_AUTHENTICATION 0x00000800
#define CKF_SERIAL_SESSION 0x00000004
#define CKF_SIGN 0x00000800
#define CKF_SIGN_RECOVER 0x00001000
#define CKF_SO_PIN_COUNT_LOW 0x00100000
#define CKF_SO_PIN_FINAL_TRY 0x00200000
#define CKF_SO_PIN_LOCKED 0x00400000
#define CKF_SO_PIN_TO_BE_CHANGED 0x00800000
#define CKF_TOKEN_INITIALIZED 0x00000400
#define CKF_TOKEN_PRESENT 0x00000001
#define CKF_UNWRAP 0x00040000
#define CKF_USER_PIN_COUNT_LOW 0x00010000
#define CKF_USER_PIN_FINAL_TRY 0x00020000
#define CKF_USER_PIN_INITIALIZED 0x00000008
#define CKF_USER_PIN_LOCKED 0x00040000
#define CKF_USER_PIN_TO_BE_CHANGED 0x00080000
#define CKF_VERIFY 0x00002000
#define CKF_VERIFY_RECOVER 0x00004000
#define CKF_WRAP 0x00020000
#define CKF_WRITE_PROTECTED 0x00000002
#define CKG_MGF1_SHA1 0x00000001
#define CKG_MGF1_SHA224 0x00000005
#define CKG_MGF1_SHA256 0x00000002
#define CKG_MGF1_SHA384 0x00000003
#define CKG_MGF1_SHA512 0x00000004
#define CKP_PKCS5_PBKD2_HMAC_GOSTR3411 0x00000002
#define CKP_PKCS5_PBKD2_HMAC_SHA1 0x00000001
#define CKP_PKCS5_PBKD2_HMAC_SHA224 0x00000003
#define CKP_PKCS5_PBKD2_HMAC_SHA256 0x00000004
#define CKP_PKCS5_PBKD2_HMAC_SHA384 0x00000005
#define CKP_PKCS5_PBKD2_HMAC_SHA512 0x00000006
#define CKP_PKCS5_PBKD2_HMAC_SHA512_224 0x00000007
#define CKP_PKCS5_PBKD2_HMAC_SHA512_256 0x00000008
#define CKZ_DATA_SPECIFIED 0x00000001
#define CKZ_SALT_SPECIFIED 0x00000001
}}}