OASIS PKCS 11 TC

 View Only

  • 1.  Automated review of our document.

    Posted 09-24-2024 21:08

    In order to make sure I'm not missing anything in the header file, I've made a tools that parses the document in text format that Dieter produces when he posts a new working draft, and compares it to the working snapshot of our header file. I did this to make sure that I'm not missing anything from our new proposals in the headers. In doing so it also discovered some inconsistencies. Within the document. Below is the output of that tool with my commentary below that.

     ./parse_doc.pl verbose
    doc_file=./pkcs11-spec-v3.2-wd05.txt header_file=../headers/pkcs11t.h function_header_file=../headers/pkcs11.h
     $print_doc_defines=0
     $print_doc_structs=0
     $print_doc_typedefs=0
     $print_doc_tables= 0
     $print_header_defines=0
     $print_header_structs=0
     $print_header_typedefs=0
     $print_diff_defines=1
     $print_diff_typedefs=1
     $print_diff_struct=1
    ./pkcs11-spec-v3.2-wd05.txt line 1752: CK_CERTIFICATE_CATEGORY_UNSPECIFIED in unlabelled table.
    ./pkcs11-spec-v3.2-wd05.txt line 1756: CK_CERTIFICATE_CATEGORY_TOKEN_USER in unlabelled table.
    ./pkcs11-spec-v3.2-wd05.txt line 1760: CK_CERTIFICATE_CATEGORY_AUTHORITY in unlabelled table.
    ./pkcs11-spec-v3.2-wd05.txt line 1764: CK_CERTIFICATE_CATEGORY_OTHER_ENTITY in unlabelled table.
    ./pkcs11-spec-v3.2-wd05.txt line 1860: CK_SECURITY_DOMAIN_UNSPECIFIED in unlabelled table.
    ./pkcs11-spec-v3.2-wd05.txt line 1864: CK_SECURITY_DOMAIN_MANUFACTURER in unlabelled table.
    ./pkcs11-spec-v3.2-wd05.txt line 1868: CK_SECURITY_DOMAIN_OPERATOR in unlabelled table.
    ./pkcs11-spec-v3.2-wd05.txt line 1872: CK_SECURITY_DOMAIN_THIRD_PARTY in unlabelled table.
    ./pkcs11-spec-v3.2-wd05.txt line 2762: inconsistent footnote reference ' Refer to Table 11 for footnotes
    ', whould be '- Refer...' after table 12
    ./pkcs11-spec-v3.2-wd05.txt line 3213: inconsistent Table Title(Table 21: WTLS Certificate Object Attributes) in table 21. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 3352: missing ';' in typedef 'typedef CK_ULONG CK_TRUST'
    ./pkcs11-spec-v3.2-wd05.txt line 13659: inconsistent Table Title(Table 76: ECDH: Allowed Key Types) in table 76. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 13717: inconsistent Table Title(Table 77: ECDH with cofactor: Allowed Key Types) in table 77. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 13765: inconsistent Table Title(Table 78: ECDH MQV: Allowed Key Types) in table 78. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 13874: inconsistent Table Title(Table 80: ECDH AES Key Wrap: Allowed Key Types) in table 80. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 13929: inconsistent Table Title(Table 81: CKM_ECDH_COF_AES_KEY_WRAP Mechanisms vs. Functions) in table 81. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 13976: inconsistent Table Title(Table 82: ECDH AES Key Wrap: Allowed Key Types) in table 82. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 14036: inconsistent Table Title(Table 83: CKM_ECDH_X_AES_KEY_WRAP Mechanisms vs. Functions) in table 83. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 14083: inconsistent Table Title(Table 84: ECDH AES Key Wrap: Allowed Key Types) in table 84. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 22697: missing ';' in typedef 'typedef CK_PRF_DATA_PARAM CK_PTR CK_PRF_DATA_PARAM_PTR'
    ./pkcs11-spec-v3.2-wd05.txt line 22736: missing ';' in typedef 'typedef CK_SP800_108_COUNTER_FORMAT CK_PTR CK_SP800_108_COUNTER_FORMAT_PTR'
    ./pkcs11-spec-v3.2-wd05.txt line 22773: missing ';' in typedef 'typedef CK_SP800_108_DKM_LENGTH_FORMAT CK_PTR CK_SP800_108_DKM_LENGTH_FORMAT_PTR'
    ./pkcs11-spec-v3.2-wd05.txt line 22794: missing ';' in typedef 'typedef CK_DERIVED_KEY CK_PTR CK_DERIVED_KEY_PTR'
    ./pkcs11-spec-v3.2-wd05.txt line 25391: inconsistent Table Title(Table 228: Common OTP key attributes) in table 228. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 25512: inconsistent Table Title(Table 229: OTP mechanisms vs. applicable functions) in table 229. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 25665: inconsistent Table Title(Table 231: OTP Mechanism Flags) in table 231. Should have a comma rather than a colon
    ./pkcs11-spec-v3.2-wd05.txt line 26052: inconsistent Table Title(Table 233: CT-KIP Mechanisms vs. applicable functions) in table 233. Should have a comma rather than a colon
    Processing header ../headers/pkcs11t.h...#define CKA_PUBLIC_CRC64_VALUE                   UNDEFINED missing from header ../headers/pkcs11t.h
    #define CKA_VALIDATION_MODUE_ID                  UNDEFINED missing from header ../headers/pkcs11t.h
    #define CKA_XMSSMT_PARAMS                        UNDEFINED missing from header ../headers/pkcs11t.h
    #define CKA_XMSS_PARAMS                          UNDEFINED missing from header ../headers/pkcs11t.h
    #define CKK_ECDSA                                UNDEFINED missing from header ../headers/pkcs11t.h
    #define CKK_FALCON                               UNDEFINED missing from header ../headers/pkcs11t.h
    #define CKK_MONTGOMERY                           UNDEFINED missing from header ../headers/pkcs11t.h
    #define CKM_FALCON                               UNDEFINED missing from header ../headers/pkcs11t.h
    #define CKM_FALCON_KEY_PAIR_GEN                  UNDEFINED missing from header ../headers/pkcs11t.h
    260 defines in header (../headers/pkcs11t.h) and not in doc (./pkcs11-spec-v3.2-wd05.txt)

    typedef diffs from doc(./pkcs11-spec-v3.2-wd05.txt) and header file(../headers/pkcs11t.h)
    missing typedef (typedef CK_ULONG CK_FALCON_PARAMETER_SET_TYPE;) from header ../headers/pkcs11t.h
    typedef (typedef CK_OTP_PARAM_TYPE CK_PARAM_TYPE;) missing from doc ./pkcs11-spec-v3.2-wd05.txt
    typedef (typedef CK_ULONG CK_HSS_LEVELS;) missing from doc ./pkcs11-spec-v3.2-wd05.txt
    typedef (typedef CK_ULONG CK_LMOTS_TYPE;) missing from doc ./pkcs11-spec-v3.2-wd05.txt
    typedef (typedef CK_ULONG CK_LMS_TYPE;) missing from doc ./pkcs11-spec-v3.2-wd05.txt
    typedef (typedef CK_ULONG CK_RC2_PARAMS;) missing from doc ./pkcs11-spec-v3.2-wd05.txt
     108 occurances of (typedef {ID} CK_PTR {ID}_PTR;) missing from ./pkcs11-spec-v3.2-wd05.txt

    mismatched struct entry in struct CK_CCM_PARAMS line 3:
       header 'CK_BYTE_PTR pAAD;' (../headers/pkcs11t.h)
       doc    'CK_ULONG ulNonceFixedBits;' (./pkcs11-spec-v3.2-wd05.txt)
    mismatched struct entry in struct CK_CCM_PARAMS line 4:
       header 'CK_ULONG ulAADLen;' (../headers/pkcs11t.h)
       doc    'CK_GENERATOR_FUNCTION nonceGenerator;' (./pkcs11-spec-v3.2-wd05.txt)
    mismatched struct entry in struct CK_CCM_PARAMS line 5:
       header 'CK_ULONG ulMACLen;' (../headers/pkcs11t.h)
       doc    'CK_BYTE_PTR pAAD;' (./pkcs11-spec-v3.2-wd05.txt)
    mismatched struct entry in struct CK_CCM_PARAMS line 6:
       header '' (../headers/pkcs11t.h)
       doc    'CK_ULONG ulAADLen;' (./pkcs11-spec-v3.2-wd05.txt)
    mismatched struct entry in struct CK_CCM_PARAMS line 7:
       header '' (../headers/pkcs11t.h)
       doc    'CK_ULONG ulMACLen;' (./pkcs11-spec-v3.2-wd05.txt)
    13 structs in header (../headers/pkcs11t.h) and not in doc (./pkcs11-spec-v3.2-wd05.txt)

    • The unlabelled tables are tables that don't have a table number or a name (I found them when trying to match up unidentified identifiers we had in the header file but not in the document).
    • Inconstistent table titles, most tables are Table #, name, but these are Table #: name.
    • missing ; in typedefs are just that, typedefs that are missing the semi colon at the end.
    • Missing defines: These are defines I found in the document that we don't have in the header
      • CKA_PUBLIC_CRC64_VALUE - looks like we added that a while ago, but never allocated it. Is someone using this define, and if so, what ID are you using. If you don't speak up I'll just allocate a new one. You must have it in one of your own header files because it's not in the OASIS header.
      • CKA_VALIDATION_MODUE_ID is just a typo in the document. It should be CKA_VALIDATION_MODULE_ID.
      • CKA_XMSSMT_PARAMS and CKA_XMSS_PARAMS were both changed to CKA_PARAMETER_SET
      • CKK_ECDSA is marked deprecated and is simply CKK_EC
      • CKK_MONTGOMERY should be CKK_EC_MONTGOMERY
      • CKK_FALCON, CKM_FALCON, and CKM_FALCON_KEY_PAIR_GEN was dropped in the last meeting, so we need to drop the whole falcon sections from the spec.
    • 260 missing defines from the document: because there are so many, I've put them under a separate verbose2 option and just summarizes there here. For the most part I find the defines in tables, so it could be these are defines that aren't in tables (I do scan some lists for the error codes, for instance). Many of these are new defines, which we'll have to add. A large number, however, are historical defines. I may go back and mark them in the header as historical and drop them from the comparisons.
    • Missing typedefs:
      • CK_FALCON_PARAMETER_SET_TYPE is missing from the header file because we dropped Falcon. That will be fixed once we removed falcon from the document.
      • CK_HSS_LEVELS,CK_LMOTS_TYPE, and CK_LMS_TYPE appear to just be missing from the document.
      • CK_OTP_PARAM_TYPE. I don't know what the issue is here. I suspect it's just missing from the document.
      • CK_RC2_PARAMS I think this is an historical algorithm.
      • The 108 missing instances of typedef CK_PTR xxxxxx xxxxx_PTR are probably not an issue, so I didn't include them here. In a future scanner we can add the ability to just search that we reference xxxxx_PTR in the doc and that should be sufficient.
    • CK_CCM_PARAMS is a hot mess. The document includes ulNonceFixedBits and nonceGenerator at the top, which aren't in the header. The document is 'correct' (you need these fields), but we've said the headers are normative. We should resolve this before we ship pkcs11 v3.2.
    • There are a few things to look at in the 13 structs that are in the header but aren't in the doc, most are new structs or historical algorithms.

    The current header files and the current version of the document parser are checked into our git repository. If you want to run the parser yourself pull the git repository, got to pkcs11/working/identifier_db/, grab the text version of one of dieter's documents. The repository names it pkcs11-spec-v3.2-wd0x.txt. If you keep that name, the tool will automatically find the text doc. If you grab a newer version (x=x+1) it will automatically use the newest. It will grab the current header from ../headers/pkcs11t.h. You can type ./parse_doc.pl help to get a usage.





  • 2.  RE: Automated review of our document.

    Posted 09-25-2024 08:33

    Hi Bob,

    these are really great findings by your tool. I have updated PKCS#11 v3.2 WD06 with following editorial changes:

    • added table titles for certificate categories and security domain. As a consequence, the numerous references to table 11 become references to table 13
    • replaced colon by comma in table titles
    • added missing ; in typedefs
    • added missing L in CKA_VALIDATION_MODULE_ID
    • replaced CKK_MONTGOMERY by CKK_EC_MONTGOMERY

    To the other findings of your tool:

    • CKA_PUBLIC_CRC64_VALUE: Utimaco has not defined a value for this ID.
    • CKA_XMSSMT_PARAMS and CKA_XMSS_PARAMS were both changed to CKA_PARAMETER_SET for XMSS public keys but not for XMSS private keys. Per XMSS spec draft2, the XMSS and XMSSMT private key objects still consist of CKA_XMSS_PARAMS and CKA_VALUE.
    • I had previously already removed section Falcon from WD06, thus all inconsistencies wrt. Falcon between the specification and header files will be solved with WD06.
    • CK_HSS_LEVELS, CK_LMOTS_TYPE, and CK_LMS_TYPE are indeed not defined in the document. Only CKA_HSS_LEVELS, CKA_LMOTS_TYPE, and CKA_LMS_TYPE are defined. Looking at pkcs11t.h, CK_HSS_LEVELS, CK_LMOTS_TYPE, and CK_LMS_TYPE are members of a structure named specifiedParams. Where, i.e. in which function or which structure, should a (pointer to) structure specifiedParams be used? And how, as there is no typedef defining a PTR to this structure.
    • CK_OTP_PARAM_TYPE was introduced in PKCS#11 v2.40 Errata. This value was previously called CK_PARAM_TYPE and then renamed to CK_OTP_PARAM_TYPE. The definition "typedef CK_OTP_PARAM_TYPE CK_PARAM_TYPE;" thus ensures compatibility for older implementations.
    • CK_RC2_PARAMS is missing in the spec because RC2 has been moved into the Historical mechanisms document while ago.
    • CK_CCM_PARAMS is luckily not a problem. I found that the structure CK_CCM_WRAP_PARAMS was misspelled as CK_CCM_PARAMS, resulting in 2 different typedefs using the same name. I have replaced CK_CCM_PARAMS by CK_CCM_WRAP_PARAMS in the typedef for CK_CCM_WRAP_PARAMS. This fixes the mess found by your tool. Searching the header file for CK_CCM_WRAP_PARAMS, I noticed that CK_CCM_WRAP_PARAMS is missing in the header file (CK_GCM_WRAP_PARAMS is defined though).

    I have not yet looked into the 260 defines in header (../headers/pkcs11t.h) and not in doc (./pkcs11-spec-v3.2-wd05.txt), and the 108 missing instances of typedef CK_PTR xxxxxx xxxxx_PTR.

    Best regards,

    Dieter



    ------------------------------
    Dieter Bong
    Manager Standardization and Strategic Projects
    Utimaco IS GmbH
    ------------------------------

    Original Message


  • 3.  RE: Automated review of our document.

    Posted 09-25-2024 13:17

    these are really great findings by your tool. I have updated PKCS#11 v3.2 WD06 with following editorial changes:

    • added table titles for certificate categories and security domain. As a consequence, the numerous references to table 11 become references to table 13
    • replaced colon by comma in table titles
    • added missing ; in typedefs
    • added missing L in CKA_VALIDATION_MODULE_ID
    • replaced CKK_MONTGOMERY by CKK_EC_MONTGOMERY
    Thanks for your quick response. Part of why I posted the results was so you were aware. Most of the above are trivial, but it's good to keep our spec consistent.

    To the other findings of your tool:

    • CKA_PUBLIC_CRC64_VALUE: Utimaco has not defined a value for this ID.
    • CKA_XMSSMT_PARAMS and CKA_XMSS_PARAMS were both changed to CKA_PARAMETER_SET for XMSS public keys but not for XMSS private keys. Per XMSS spec draft2, the XMSS and XMSSMT private key objects still consist of CKA_XMSS_PARAMS and CKA_VALUE.
    I think that's a mistake in draft2. We should replace all occurrences of CKA_XMSSMT_PARAMS and CKA_XMSS_PARAMS with CKA_PARAMETER_SET. (I see the same mistake in my copy). I'll send you an errata.
    • I had previously already removed section Falcon from WD06, thus all inconsistencies wrt. Falcon between the specification and header files will be solved with WD06.
    • CK_HSS_LEVELS, CK_LMOTS_TYPE, and CK_LMS_TYPE are indeed not defined in the document. Only CKA_HSS_LEVELS, CKA_LMOTS_TYPE, and CKA_LMS_TYPE are defined. Looking at pkcs11t.h, CK_HSS_LEVELS, CK_LMOTS_TYPE, and CK_LMS_TYPE are members of a structure named specifiedParams. Where, i.e. in which function or which structure, should a (pointer to) structure specifiedParams be used? And how, as there is no typedef defining a PTR to this structure.
    Sigh, I know we went back and forth with HSS. unlike XMSS (or even the new PQ signature schemes), HSS has a completely flexible tree structure definition, where each HSS level consists of LMS trees can have it's own number of entries and hash type and sign with it's own LMOTS, so you don't have a single number but a set of descriptors (one for each level). We need to go back and see how these are put together.
    • CK_OTP_PARAM_TYPE was introduced in PKCS#11 v2.40 Errata. This value was previously called CK_PARAM_TYPE and then renamed to CK_OTP_PARAM_TYPE. The definition "typedef CK_OTP_PARAM_TYPE CK_PARAM_TYPE;" thus ensures compatibility for older implementations.
    Ah, so it should show up as a 'missing struct' in the spec. I'll take a look.
    • CK_RC2_PARAMS is missing in the spec because RC2 has been moved into the Historical mechanisms document while ago.
    Yeah, that's what I figured. A large number of the missing defines from the spec falls under the same category.
    • CK_CCM_PARAMS is luckily not a problem. I found that the structure CK_CCM_WRAP_PARAMS was misspelled as CK_CCM_PARAMS, resulting in 2 different typedefs using the same name. I have replaced CK_CCM_PARAMS by CK_CCM_WRAP_PARAMS in the typedef for CK_CCM_WRAP_PARAMS. This fixes the mess found by your tool. Searching the header file for CK_CCM_WRAP_PARAMS, I noticed that CK_CCM_WRAP_PARAMS is missing in the header file (CK_GCM_WRAP_PARAMS is defined though).
    Oh good! That would have been a real issue if they were truly different.

    I have not yet looked into the 260 defines in header (../headers/pkcs11t.h)

    You can get that list with ./parse_doc.pl verbose2 diff_defines . A bunch are historical, a few are new. There may be some real issues that are hidden in the noise, though.

    and not in doc (./pkcs11-spec-v3.2-wd05.txt), and the 108 missing instances of typedef CK_PTR xxxxxx xxxxx_PTR.

    I'm least worried about these. They are pretty straightforward, and a bunch may be historical.

    Best regards,

    Dieter





    Original Message


  • 4.  RE: Automated review of our document.

    Posted 09-25-2024 19:13
    > I have not yet looked into the 260 defines in header
    > (../headers/pkcs11t.h)

    I've marked the historical identifiers and the policy identifiers (which
    should be in the policy document) in the current header and updated
    parse_doc to ignore them. I'm now down to 110 for you.

    I've also updated the header and the decisions we made today in our meeting.


    Original Message


  • 5.  RE: Automated review of our document.

    Posted 09-25-2024 22:46
    I'd argue that after the call we should only have:

    CKM_HASH_ML_DSA
    and
    CKM_ML_DSA

    Rather than the 12 mechanisms for each.

    The parameter set information is already in the mechanism parameters.
    This would then be consistent across all three algorithms.

    That would be the logical conclusion to draw from the discussion we had on the call.

    I would also make the values for the CKA_PARAMETER_SET distinct across the different algorithms so it is a simple mapping table from the attribute enumeration to the value rather than having to look at the key type to then figure out how to interpret things. Alternatively we could have separate attributes for each algorithm.

    I would not define separate typedefs for the CKP_ values across the algorithms - I would just have a generic one - CK_PARAMETER_SET_TYPE - basically we should either have one type if we are having only one attribute. Alternatively we should have multiple attributes for the different types rather than effectively having different enums for the same attribute.

    Separate from that you have three comments with CKA_PARAMETER_SETS which need to be CKA_PARAMETER_SET even if you leave everything as proposed.

    Tim.




    Original Message


  • 6.  RE: Automated review of our document.

    Posted 09-26-2024 11:17
    On 9/25/24 10:16 AM, Robert Relyea wrote:
    8aad0956-c952-4c15-82e3-d6cb3f471200@redhat.com">

    To the other findings of your tool:

    • CKA_PUBLIC_CRC64_VALUE: Utimaco has not defined a value for this ID.
    • CKA_XMSSMT_PARAMS and CKA_XMSS_PARAMS were both changed to CKA_PARAMETER_SET for XMSS public keys but not for XMSS private keys. Per XMSS spec draft2, the XMSS and XMSSMT private key objects still consist of CKA_XMSS_PARAMS and CKA_VALUE.
    I think that's a mistake in draft2. We should replace all occurrences of CKA_XMSSMT_PARAMS and CKA_XMSS_PARAMS with CKA_PARAMETER_SET. (I see the same mistake in my copy). I'll send you an errata.

    Actually it is already in pkcs11_pq_update.pdf




    Original Message


Related Content