| 1 |
Policy Update |
| 2 |
============= |
| 3 |
|
| 4 |
During development of openCryptoki several updates might be needed to |
| 5 |
the policy code. Places where to update the policy code are marked |
| 6 |
with the comment |
| 7 |
|
| 8 |
POLICY: New |
| 9 |
|
| 10 |
followed by a description of what is added. E.g., if you add a new |
| 11 |
key type, the comment is |
| 12 |
|
| 13 |
POLICY: New CKK |
| 14 |
|
| 15 |
which marks the places where policy-specific code has to be added for |
| 16 |
this key type. Similar places exist for adding new mechanisms where |
| 17 |
the comment is |
| 18 |
|
| 19 |
POLICY: New CKM |
| 20 |
|
| 21 |
For new mechanisms, the comment is also followed by a distinction of |
| 22 |
the kind of mechanism. For example, there are places where only |
| 23 |
digest mechanisms have to be added, or places where mechanisms related |
| 24 |
to signatures and the corresponding verification have to be added. |
| 25 |
|
| 26 |
To make EC curves, MGFs, or KDFs available to the policy |
| 27 |
code, see the corresponding translation.c file in usr/lib/common (i.e., |
| 28 |
ec_curve_translation.c, mgf_translation.c, or kdf_translation.c). |
| 29 |
|
| 30 |
PRFs are special currently since we only support one PRF so far and |
| 31 |
gperf then generates a file that compiles with warnings. So we did |
| 32 |
not use gperf for it, but hard-code the supported PRF string |
| 33 |
comparison in usr/lib/common/stringtranslations.h. |
| 34 |
|
| 35 |
When adding new EC curves, MGFs, KDFs, or PRFs, please also update the |
| 36 |
code in tools/policyexamplegen.c which will generate the policy |
| 37 |
example that should contain everything that is supported by |
| 38 |
OpenCryptoki at this time. The code does not have to be touched if |
| 39 |
new mechanisms are added. |
| 40 |
|
| 41 |
For adding new mechanisms please see the section about the mechanism |
| 42 |
table. The remaining tools will use the mechanism table and will |
| 43 |
automatically be aware of the added mechanism. |
| 44 |
|
| 45 |
Additionally, some code might be needed in the STDLLs to support |
| 46 |
policy checking of the specific mechanism if the mechanism creates |
| 47 |
multiple keys or uses parameters that involve key handles. In the |
| 48 |
latter case, the STDLL first needs to translate the key handle into an |
| 49 |
appropriate struct objstrength which can then be passed to the policy |
| 50 |
code. This became necessary to support different STDLLs that do not |
| 51 |
use the OBJECT structure from openCryptoki common code. |
| 52 |
|
| 53 |
|
| 54 |
Mechanism Table |
| 55 |
=============== |
| 56 |
|
| 57 |
To have a single source for all mechanisms, we added a mechanism table |
| 58 |
to OpenCryptoki. The mechanism table itself is kept as a constant |
| 59 |
structure in the file usr/lib/api/mechtable.inc. You can simply add a |
| 60 |
new mechanism to this structure. Note, however, that the mechanisms |
| 61 |
added to this structure have to be unique w.r.t. the numeric |
| 62 |
representation. This leads to problems if the same mechanism has |
| 63 |
multiple names and thus multiple string representations. You should |
| 64 |
put the string representation you want to see in the output into the |
| 65 |
table. |
| 66 |
|
| 67 |
Also note that the order of the table is important. Tools might rely |
| 68 |
on the index of a specific mechanism to accumulate, e.g., counters. |
| 69 |
So please be careful when changing the order of rows. |
| 70 |
|
| 71 |
The table usage API is defined in usr/lib/api/mechtable.h. This file |
| 72 |
also includes a generated header that provides the MECHTABLE_NUM_ELEMS |
| 73 |
macro. This macro specifies the number of rows in the table. This |
| 74 |
allows users to iterate over the `mechtable_rows`. |
| 75 |
|
| 76 |
While iteration is one basic way to process the table, we also |
| 77 |
generate fast index structures for the string representation and the |
| 78 |
numeric representation. These indices can be accessed via the |
| 79 |
`mechtable_idx_from_numeric`, `mechtable_idx_from_string`, |
| 80 |
`mechrow_from_numeric`, or `mechrow_from_string` functions. These |
| 81 |
functions internally use jump tables to efficiently search for the |
| 82 |
corresponding element. |
| 83 |
|
| 84 |
To keep the table only in one library, the API library passes a |
| 85 |
pointer to a constant `struct mechtable_funcs` to every |
| 86 |
`STDLL_TokData_t`. This structure contains pointers to the above |
| 87 |
mentioned four functions and allows STDLLs to use the table without |
| 88 |
including it in the STDLL (and thus without adding the table multiple |
| 89 |
times to the resident set). |
| 90 |
|
| 91 |
The index functions are automatically generated by |
| 92 |
tools/tableidxgen.c. This file includes usr/lib/api/mechtable.inc and |
| 93 |
produces a file usr/lib/api/mechtable.c and the header |
| 94 |
usr/lib/api/mechtable-gen.h. During generation, it also produces the |
| 95 |
file usr/lib/api/mechtable.log which logs the alphabet mappings and |
| 96 |
the jump table it uses. For strings, the generator has support for |
| 97 |
alias via an internal variable `aliases`. Whenever you have to add an |
| 98 |
alternative string representation for a representation that is already |
| 99 |
in the table, simply add a structure to the `aliases` array. The |
| 100 |
member `string` should be the string to add (which should not already |
| 101 |
be in the table), and the member `alias` should be the string that is |
| 102 |
already in the table and contains the information for this |
| 103 |
alternative. |
| 104 |
|
| 105 |
When trying to interpret the generated log file, keep in mind that the |
| 106 |
generator removes common prefixes. In our case, it removes the prefix |
| 107 |
"CKM_", so the first node in the string match case contains the jump |
| 108 |
table for the letter after "CKM_". Also note that in both cases, |
| 109 |
strings and numeric, the generator performs alphabet compression to |
| 110 |
remove unused character values from the alphabet and thereby |
| 111 |
compressing the jump table. |