Some notes on using libntruencrypt.

Providing a source of randomness
================================

  libntruencrypt needs a cryptographically secure source of random bits!

  The library contains an internal deterministic random bit generator (DRBG)
  that can be used to whiten an external random bit source that is of low
  entropy. However, if a source of cryptographically random bits is available
  (such as /dev/urandom on Linux) it can be used directly without whitening.

  The mechanism is selected by calling one of two instantiation functions:

    DRBG_HANDLE handle;
    ntru_crypto_drbg_instantiate(..., &handle); /* HMAC based DRBG */
    --or--
    ntru_crypto_drbg_external_instantiate(..., &handle); /* External Source */

  The later interface is substantially simpler, and is preferable on most
  platforms. The following two sections describe how to use the interfaces.

  Regardless of the instantiation method, a DRBG handle is destroyed by calling
    ntru_crypto_drbg_uninstantiate(&handle);


  Note: If you use NTRU for quantum resistance and use an external DRBG, make sure
  it is instantiated with sufficient entropy! For security of k bits you should
  instantiate your DRBG with 2*k bits of entropy from the external source. The
  internal DRBG does this for you.


HMAC-DRBG
=========

  One of the inputs to ntru_crypto_drbg_instantiate is an ENTROPY_FN. If you use
  the internal HMAC-DRBG it is imperative that you write your entropy function
  correctly. ENTROPY_FN is typedef'd as

  typedef uint8_t (*ENTROPY_FN)(ENTROPY_CMD cmd, uint8_t *out);

  and an ENTROPY_CMD is one of
      INIT,
      GET_NUM_BYTES_PER_BYTE_OF_ENTROPY
      GET_BYTE_OF_ENTROPY.

  On input INIT your entropy function must perform any initialization of your
  external source that is necessary and return 1 on success or 0 on failure.

  On GET_NUM_BYTES_PER_BYTE_OF_ENTROPY your entropy function must output (by
  setting `out') a value between 1 and 8 representing the entropy of your
  random source.  A value of k indicates that the one cryptographically random
  byte can be extracted from k bytes of output from your source. For instance
  an output of 1 indicates that the source is perfectly random, and an output
  of 8 indicates that you can only extract one bit of randomness from each byte
  of your source's output. Your entropy function should return 1 indicating
  success.

  On GET_BYTE_OF_ENTROPY your function must put one byte of output from your
  random source in `out' and return 1 on success, 0 on failure.

  Example: Suppose your platform provides a getrandombyte function
    int getrandombyte(void *out);
  that outputs 1 perfectly random byte at out and returns 0 on success. The
  following is a reasonable ENTROPY_FN:

  uint8_t
  get_entropy(
      ENTROPY_CMD  cmd,
      uint8_t     *out)
  {
      if (cmd == INIT)
          return 1;

      if (out == NULL)
          return 0;

      if (cmd == GET_NUM_BYTES_PER_BYTE_OF_ENTROPY)
      {
          *out = 1;
          return 1;
      }

      if (cmd == GET_BYTE_OF_ENTROPY)
      {
          if(0 == getrandombyte(out))
            return 1;
      }
      return 0;
  }

  To use your get_entropy function:

    uint32_t rc;
    DRBG_HANDLE handle;
    uint32_t sec_strength = 256;

    rc = ntru_crypto_drbg_instantiate(sec_strength, NULL, 0,
                                      &get_entropy, &handle);
    if(rc != DRBG_RESULT(DRBG_OK))
    { ...  }

  The internal HMAC-DRBG is seeded with 3/2 * sec_strength * k bits of input
  from get_entropy where k is the value returned by
  get_entropy(GET_NUM_BYTES_PER...).
  The maximum value of sec_strength is 256.
  The second and third arguments are for specifying an optional
  'personalization string' of up to 32 bytes of non-secret data that are to be
  used in conjunction with the entropy source to seed the DRBG (see NIST SP
  900-80A for details).


External random sources
=======================

  If you trust an external random source, for example because you are using
  libntruencrypt inside of a larger crypto suite that provides a random source,
  then you can use that source directly.

  One of the inputs to ntru_crypto_drbg_external_instantiate is a pointer to
  a RANDOM_BYTES_FN, typedef'd as

  typedef uint32_t (*RANDOM_BYTES_FN)(uint8_t *out, uint32_t num_bytes);

  To use an external random source you simply wrap it in an RANDOM_BYTES_FN.

  Example: Suppose your platform provides a getrandom function
    int getrandom(void *buf, size_t buflen);
  that accepts a buflen between 1 and 256 and returns either the number of
  bytes output or -1 on failure.

  #include "ntru_crypto_drbg.h"
  ...
  uint32_t randombytes(uint8_t *out, uint32_t num_bytes)
  {
    size_t i;
    while(num_bytes > 0)
    {
      if(num_bytes > 256) {
        i = 256;
      } else {
        i = num_bytes;
      }

      i = getrandom(out, i);
      if(i == -1)
        DRBG_RET(DRBG_ENTROPY_FAIL);

      num_bytes -= i;
      out += i;
    }
    DRBG_RET(DRBG_OK);
  }

  Note the use of DRBG_RET. This is required.

  To use your randombytes function:

    uint32_t rc;
    DRBG_HANDLE handle;
    rc = ntru_crypto_drbg_external_instantiate(&randombytesfn, &handle);
    if(rc != DRBG_RESULT(DRBG_OK))
    { ...  }


Parameter sets
==============

  libntruencrypt provides all of the NTRUEncrypt parameter sets defined in the
  IEEE 1363.1 standard -- a superset of those defined in X9.98.  In the table
  below the line labeled Product contains the parameter sets that are unique to
  1363.1. These parameter sets are also faster and more compact than the other
  sets in their respective columns, and these sets are preferable unless X9.98
  compatibility is required. The column headers denote estimated bit security.

           112             128             192              256
  Product  NTRU_EES401EP2  NTRU_EES439EP1  NTRU_EES593EP1   NTRU_EES743EP1

  Size     NTRU_EES401EP1  NTRU_EES449EP1  NTRU_EES677EP1   NTRU_EES1087EP2
  Balanced NTRU_EES541EP1  NTRU_EES613EP1  NTRU_EES887EP1   NTRU_EES1171EP1
  Speed    NTRU_EES659EP1  NTRU_EES761EP1  NTRU_EES1087EP1  NTRU_EES1499EP1


Cryptographic functions
=======================

  All of the cryptographic functions support two calling mechanisms. One to
  obtain the lengths of any buffers that need to be allocated before performing
  the operation, and a second to actually perform the operation

  The DRBG inputs to keygen and encrypt are ignored when getting the buffer
  lengths, and the DRBG need not be initialized at that time.



  Keygen
    NULL public_key requests public_key_len, NULL private_key requests
    private_key_len. drbg argument is ignored.

    Example:
      /* Get public/private key buffer sizes */
      rc = ntru_crypto_ntru_encrypt_keygen(drbg, NTRU_EES401EP2,
                                           &public_key_len, NULL,
                                           &private_key_len, NULL);
      if(rc != NTRU_RESULT(NTRU_OK)) {...}

      /* Allocate memory for keys */
      ...
      /* Perform the key generation */
      rc = ntru_crypto_ntru_encrypt_keygen(drbg, NTRU_EES401EP2,
                                           &public_key_len, public_key,
                                           &private_key_len, private_key);
      if(rc != NTRU_RESULT(NTRU_OK)) {...}

  Encrypt
    NULL ciphertext requests length, drbg, plaintext_len and plaintext arguments
    are ignored.

    Example:
      /* Get the ciphertext buffer size */
      rc = ntru_crypto_ntru_encrypt(drbg, public_key_len, public_key,
                                    0, NULL,
                                    &ciphertext_len, NULL);
      if(rc != NTRU_RESULT(NTRU_OK)) {...}

      /* Allocate memory for ciphertext */
      ...
      /* Perform the encryption */
      rc = ntru_crypto_ntru_encrypt(drbg, public_key_len, public_key,
                                    message_len, message,
                                    &ciphertext_len, ciphertext);
      if(rc != NTRU_RESULT(NTRU_OK)) {...}


  Decrypt
    NULL plaintext requests length, ciphertext_len and ciphertext arguments
    are ignored.

    Example:
      /* Get maximum plaintext length */
      rc = ntru_crypto_ntru_decrypt(private_key_len, private_key,
                                    0, NULL,
                                    &max_msg_len, NULL);

      /* Allocate memory for plaintext */
      ...
      /* Perform the encryption.
       * Note that plaintext_len will contain the actual output length
       * on success
       */
      rc = ntru_crypto_ntru_decrypt(private_key_len, private_key,
                                    ciphertext_len, ciphertext,
                                    &plaintext_len, plaintext);
      if(rc != NTRU_RESULT(NTRU_OK)) {...}