Debian Codegraph @

doc/README.devel

raw
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.