You've already forked opencryptoki
mirror of
https://github.com/opencryptoki/opencryptoki.git
synced 2026-10-24 05:39:17 +03:00
e6aa900049
Closes: https://github.com/opencryptoki/opencryptoki/issues/454 Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com>
112 lines
5.1 KiB
Plaintext
112 lines
5.1 KiB
Plaintext
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.
|