xref: /openbsd/lib/libkeynote/HOWTO.add.crypto (revision e5dd7070) 
1# $OpenBSD: HOWTO.add.crypto,v 1.3 2000/01/25 09:08:09 angelos Exp $
2
3This document describes how to add support for digital signature algorithms,
4hash functions, and ASCII encoding mechanisms in this implementation.
5
6For a signature algorithm:
7
8- Add the appropriate include files in keynote.h
9- Create one or more strings describing the signature algorithm
10  prefixes, and add those to keynote.h (the SIG_* definitions).
11- Add a definition for the algorithm in keynote.h (the
12  KEYNOTE_ALGORITHM_* definitions).
13- Define the algorithm public key prefixes, and add them to
14  signature.h (the *_HEX, *_HEX_LEN, *_BASE64, *_BASE64_LEN
15  definitions).
16- In auxil.c, function keynote_keyhash(), add to the switch statement
17  a case handling the new algorithm; the return value is an integer,
18  and is used as an index into a hash table.
19- In signature.c:
20  - In keynote_free_key(), add code to free any memory allocated for
21    storing a key for the new algorithm.
22  - In keynote_get_sig_algorithm(), add code that checks whether a
23    signature string begins with one of the prefixes for the new
24    algorithm that were defined in keynote.h
25  - Similarly, in keynote_get_key_algorithm() for key strings, using
26    the key prefixes defined in signature.h
27  - In kn_decode_key(), add code that converts a bit string to
28    the new algorithm's structure for storing a key (use the DSA
29    code as a guide).
30  - Similarly for kn_encode_key()
31  - In kn_keycompare(), add code that compares two keys and
32    returns RETURN_TRUE if they are equal, and RETURN_FALSE otherwise.
33  - In keynote_signverify_assertion, add code that verifies a
34    signature for the new algorithm.
35  - Likewise for signature generation in keynote_sign_assertion()
36- In keynote-keygen.c, replicate the code for DSA key generation to
37  support the new algorithm.
38
39For a hash algorithm:
40
41- Add the necessary include files in keynote.h
42- Add a KEYNOTE_HASH_* definition for the algorithm in signature.h
43- In signature.h, if the length of the new hash function's result is
44  more than LARGEST_HASH_SIZE (currently 20 bytes, for SHA1), then
45  replace that value with the new function's hash result length.
46- In signature.c:
47  - In keynote_sigverify_assertion(), add code in the switch statement
48    for generating a hash of the assertion and the signature algorithm
49    name (use the SHA1 code as an example).
50  - Likewise in keynote_sign_assertion()
51
52For an ASCII-encoding algorithm:
53
54- Add the necessary include files in keynote.h
55- Add additional SIG_* definitions in keynote.h
56- Add an ENCODING_* definition in keynote.h
57- Add additional key prefix string definitions in signature.h
58- In signature.c:
59  - In keynote_get_sig_algorithm(), add code for detecting signatures
60    with this encoding.
61  - Likewise for keys in keynote_get_key_algorithm()
62  - In kn_decode_key(), add code in the switch statement for decoding
63    ASCII-encoded keys.
64  - Likewise in kn_encode_key() for encoding keys.
65  - Likewise in keynote_sigverify_assertion() for decoding signatures.
66  - Add the necessary checks in keynote_sign_assertion() for handling
67    the new encoding, and code in the switch statement for doing the
68    encoding of the signature.
69- Add the necessary checks in keynote-keygen.c for handling the
70  new algorithm.
71
72