Policy Update ============= During development of openCryptoki several updates might be needed to the policy code. Places where to update the policy code are marked with the comment POLICY: New followed by a description of what is added. E.g., if you add a new key type, the comment is POLICY: New CKK which marks the places where policy-specific code has to be added for this key type. Similar places exist for adding new mechanisms where the comment is POLICY: New CKM For new mechanisms, the comment is also followed by a distinction of the kind of mechanism. For example, there are places where only digest mechanisms have to be added, or places where mechanisms related to signatures and the corresponding verification have to be added. To make EC curves, MGFs, or KDFs available to the policy code, see the corresponding translation.c file in usr/lib/common (i.e., ec_curve_translation.c, mgf_translation.c, or kdf_translation.c). PRFs are special currently since we only support one PRF so far and gperf then generates a file that compiles with warnings. So we did not use gperf for it, but hard-code the supported PRF string comparison in usr/lib/common/stringtranslations.h. When adding new EC curves, MGFs, KDFs, or PRFs, please also update the code in tools/policyexamplegen.c which will generate the policy example that should contain everything that is supported by OpenCryptoki at this time. The code does not have to be touched if new mechanisms are added. For adding new mechanisms please see the section about the mechanism table. The remaining tools will use the mechanism table and will automatically be aware of the added mechanism. Additionally, some code might be needed in the STDLLs to support policy checking of the specific mechanism if the mechanism creates multiple keys or uses parameters that involve key handles. In the latter case, the STDLL first needs to translate the key handle into an appropriate struct objstrength which can then be passed to the policy code. This became necessary to support different STDLLs that do not use the OBJECT structure from openCryptoki common code. Mechanism Table =============== To have a single source for all mechanisms, we added a mechanism table to OpenCryptoki. The mechanism table itself is kept as a constant structure in the file usr/lib/api/mechtable.inc. You can simply add a new mechanism to this structure. Note, however, that the mechanisms added to this structure have to be unique w.r.t. the numeric representation. This leads to problems if the same mechanism has multiple names and thus multiple string representations. You should put the string representation you want to see in the output into the table. Also note that the order of the table is important. Tools might rely on the index of a specific mechanism to accumulate, e.g., counters. So please be careful when changing the order of rows. The table usage API is defined in usr/lib/api/mechtable.h. This file also includes a generated header that provides the MECHTABLE_NUM_ELEMS macro. This macro specifies the number of rows in the table. This allows users to iterate over the `mechtable_rows`. While iteration is one basic way to process the table, we also generate fast index structures for the string representation and the numeric representation. These indices can be accessed via the `mechtable_idx_from_numeric`, `mechtable_idx_from_string`, `mechrow_from_numeric`, or `mechrow_from_string` functions. These functions internally use jump tables to efficiently search for the corresponding element. To keep the table only in one library, the API library passes a pointer to a constant `struct mechtable_funcs` to every `STDLL_TokData_t`. This structure contains pointers to the above mentioned four functions and allows STDLLs to use the table without including it in the STDLL (and thus without adding the table multiple times to the resident set). The index functions are automatically generated by tools/tableidxgen.c. This file includes usr/lib/api/mechtable.inc and produces a file usr/lib/api/mechtable.c and the header usr/lib/api/mechtable-gen.h. During generation, it also produces the file usr/lib/api/mechtable.log which logs the alphabet mappings and the jump table it uses. For strings, the generator has support for alias via an internal variable `aliases`. Whenever you have to add an alternative string representation for a representation that is already in the table, simply add a structure to the `aliases` array. The member `string` should be the string to add (which should not already be in the table), and the member `alias` should be the string that is already in the table and contains the information for this alternative. When trying to interpret the generated log file, keep in mind that the generator removes common prefixes. In our case, it removes the prefix "CKM_", so the first node in the string match case contains the jump table for the letter after "CKM_". Also note that in both cases, strings and numeric, the generator performs alphabet compression to remove unused character values from the alphabet and thereby compressing the jump table.