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.
