xref: /openbsd-src/lib/libkeynote/HOWTO.add.crypto (revision c459080a59fc0051e18689673d94c473ac29f674)

# $OpenBSD: HOWTO.add.crypto,v 1.3 2000/01/25 09:08:09 angelos Exp $

This document describes how to add support for digital signature algorithms,
hash functions, and ASCII encoding mechanisms in this implementation.

For a signature algorithm:

- Add the appropriate include files in keynote.h
- Create one or more strings describing the signature algorithm
  prefixes, and add those to keynote.h (the SIG_* definitions).
- Add a definition for the algorithm in keynote.h (the
  KEYNOTE_ALGORITHM_* definitions).
- Define the algorithm public key prefixes, and add them to
  signature.h (the *_HEX, *_HEX_LEN, *_BASE64, *_BASE64_LEN
  definitions).
- In auxil.c, function keynote_keyhash(), add to the switch statement
  a case handling the new algorithm; the return value is an integer,
  and is used as an index into a hash table.
- In signature.c:
  - In keynote_free_key(), add code to free any memory allocated for
    storing a key for the new algorithm.
  - In keynote_get_sig_algorithm(), add code that checks whether a
    signature string begins with one of the prefixes for the new
    algorithm that were defined in keynote.h
  - Similarly, in keynote_get_key_algorithm() for key strings, using
    the key prefixes defined in signature.h
  - In kn_decode_key(), add code that converts a bit string to
    the new algorithm's structure for storing a key (use the DSA
    code as a guide).
  - Similarly for kn_encode_key()
  - In kn_keycompare(), add code that compares two keys and
    returns RETURN_TRUE if they are equal, and RETURN_FALSE otherwise.
  - In keynote_signverify_assertion, add code that verifies a
    signature for the new algorithm.
  - Likewise for signature generation in keynote_sign_assertion()
- In keynote-keygen.c, replicate the code for DSA key generation to
  support the new algorithm.

For a hash algorithm:

- Add the necessary include files in keynote.h
- Add a KEYNOTE_HASH_* definition for the algorithm in signature.h
- In signature.h, if the length of the new hash function's result is
  more than LARGEST_HASH_SIZE (currently 20 bytes, for SHA1), then
  replace that value with the new function's hash result length.
- In signature.c:
  - In keynote_sigverify_assertion(), add code in the switch statement
    for generating a hash of the assertion and the signature algorithm
    name (use the SHA1 code as an example).
  - Likewise in keynote_sign_assertion()

For an ASCII-encoding algorithm:

- Add the necessary include files in keynote.h
- Add additional SIG_* definitions in keynote.h
- Add an ENCODING_* definition in keynote.h
- Add additional key prefix string definitions in signature.h
- In signature.c:
  - In keynote_get_sig_algorithm(), add code for detecting signatures
    with this encoding.
  - Likewise for keys in keynote_get_key_algorithm()
  - In kn_decode_key(), add code in the switch statement for decoding
    ASCII-encoded keys.
  - Likewise in kn_encode_key() for encoding keys.
  - Likewise in keynote_sigverify_assertion() for decoding signatures.
  - Add the necessary checks in keynote_sign_assertion() for handling
    the new encoding, and code in the switch statement for doing the
    encoding of the signature.
- Add the necessary checks in keynote-keygen.c for handling the
  new algorithm.