VAMPIRE

eBACS: ECRYPT Benchmarking of Cryptographic Systems


ECRYPT II
General information: Introduction eBASH eBASC eBAEAD eBATS SUPERCOP XBX Computers
How to submit new software: Tips hash stream aead dh kem encrypt sign
List of primitives measured: sha3 hash stream caesar aead dh kem encrypt sign
Measurements indexed by machine: sha3 hash stream caesar aead dh kem encrypt sign

Call for key-encapsulation software for benchmarking

Are you a designer or implementor of a key-encapsulation mechanism? Would you like your software professionally benchmarked on many computers, producing stable, reliable, verifiable timings that reflect the performance that key-encapsulation users will see? This page explains how to submit your software to the eBATS project. Formal submission requirements have been kept to a minimum, but your software needs to follow a few naming conventions so that it can be benchmarked by SUPERCOP.

There is a separate page listing the key-encapsulation mechanisms submitted so far, and another page reporting measurements of those functions. Note that the eBATS project also includes public-key signature systems, Diffie–Hellman systems, and encryption systems.

Example for designers: submitting the pqRSA-15 system

Let's say you're the designer of pqRSA-15, a key-encapsulation mechanism with a 786432-bit private key, a 262144-bit public key, a 262144-bit key-encapsulation mechanism, and a 256-bit session key, and you want to submit your pqRSA-15 software to eBATS. Your submission can be as simple as two files, crypto_kem/pqrsa15/ref/api.h and crypto_kem/pqrsa15/ref/kem.c. Here is an explanation of what these files contain and what additional options you have.

The top-level directory name crypto_kem is required; it distinguishes key-encapsulation mechanisms from other operations benchmarked by SUPERCOP, such as crypto_hash and crypto_sign.

The second-level directory name pqrsa15 should be a lowercase version of your system's name. Please omit dashes, dots, slashes, and other punctuation marks; the directory name should consist solely of digits (0123456789) and lowercase ASCII letters (abcdefghijklmnopqrstuvwxyz).

Different key-encapsulation mechanisms must be placed into different second-level directories, even if they are part of the same "family" of functions. For example, crypto_kem/pqrsa20 is separate from crypto_kem/pqrsa15. One submission tarball can include several key-encapsulation mechanisms in separate directories. Directory names may be changed by the eBATS managers to resolve conflicts or confusion.

The third-level directory name ref is up to you. Different implementations must be placed into different third-level directories. You can use subdirectories here; for example, crypto_kem/pqrsa15/ref might be a reference implementation, crypto_kem/pqrsa15/smith/little might be John Smith's little-endian implementation, and crypto_kem/pqrsa15/smith/neon might be John Smith's NEON-optimized implementation. One submission tarball can include several implementations.

After choosing the implementation name crypto_kem/pqrsa15/ref, create a directory by that name. Inside the crypto_kem/pqrsa15/ref directory, create a file named api.h with four lines

#define CRYPTO_SECRETKEYBYTES 98304
#define CRYPTO_PUBLICKEYBYTES 32768
#define CRYPTO_CIPHERTEXTBYTES 32768
#define CRYPTO_BYTES 32
indicating that your software uses a 98304-byte (786432-bit) secret key, a 32768-byte (262144-bit) public key, a 32768-byte (262144-bit) ciphertext, and a 32-byte (256-bit) session key. You can also add a line
     #define CRYPTO_VERSION "3.01a"
indicating that this is version 3.01a of your software; SUPERCOP will report this information in its database of measurements. You can also add further lines defining macros and declaring functions with names starting crypto_kem_pqrsa15_ref_.

Next, inside the crypto_kem/pqrsa15/ref directory, create a file named kem.c that defines a crypto_kem_pqrsa15_ref_keypair function, a crypto_kem_pqrsa15_ref_enc function, and a crypto_kem_pqrsa15_ref_dec function:

     int crypto_kem_pqrsa15_ref_keypair(
       unsigned char *pk,
       unsigned char *sk
     )
     {
       ... 
       ... the code for your pqRSA-15 implementation goes here,
       ... generating public key pk[0],pk[1],...
       ... and secret key sk[0],sk[1],...
       ...
       return 0;
     }
     
     int crypto_kem_pqrsa15_ref_enc(
       unsigned char *c,
       unsigned char *k,
       const unsigned char *pk
     )
     {
       ... 
       ... the code for your pqRSA-15 implementation goes here,
       ... generating session key k[0],k[1],...
       ... and ciphertext c[0],c[1],...
       ... from public key pk[0],pk[1],...
       ...
       return 0;
     }

     int crypto_kem_pqrsa15_ref_dec(
       unsigned char *k,
       const unsigned char *c,
       const unsigned char *sk
     )
     {
       ... 
       ... the code for your pqRSA-15 implementation goes here,
       ... generating session key k[0],k[1],...
       ... from ciphertext c[0],c[1],...
       ... and secret key sk[0],sk[1],...
       ...
       return 0;
     }
Your functions must have exactly the prototypes shown here. The keypair function must have an unsigned char pointer for the public-key output and an unsigned char pointer for the secret-key output. The enc function must have an unsigned char pointer for the ciphertext output, an unsigned char pointer for the session-key output, and a const unsigned char pointer for the public-key input. The dec function must have an unsigned char pointer for the session-key output, a const unsigned char pointer for the ciphertext input, and a const unsigned char pointer for the secret-key input. Your functions must return 0 to indicate success, or a negative number to indicate failure (e.g., out of memory).

You can instead define your functions as follows:

     #include "crypto_kem.h"

     int crypto_kem_keypair(
       unsigned char *pk,
       unsigned char *sk
     )
     {
       ... 
     }

     int crypto_kem_enc(
       unsigned char *c,
       unsigned char *k,
       const unsigned char *pk
     )
     {
       ...
     }

     int crypto_kem_dec(
       unsigned char *k,
       const unsigned char *c,
       const unsigned char *sk
     )
     {
       ...
     }
The file crypto_kem.h is not something for you to write; it is created automatically by SUPERCOP. It contains various macros such as
     #define crypto_kem_keypair crypto_kem_pqrsa15_ref_keypair
     #define crypto_kem_enc crypto_kem_pqrsa15_ref_enc
     #define crypto_kem_dec crypto_kem_pqrsa15_ref_dec
     #define crypto_kem_SECRETKEYBYTES crypto_kem_pqrsa15_ref_SECRETKEYBYTES
     #define crypto_kem_PUBLICKEYBYTES crypto_kem_pqrsa15_ref_PUBLICKEYBYTES
     #define crypto_kem_CIPHERTEXTBYTES crypto_kem_pqrsa15_ref_CIPHERTEXTBYTES
     #define crypto_kem_BYTES crypto_kem_pqrsa15_ref_BYTES
and a function declaration that will catch errors in the crypto_kem_keypair, crypto_kem_enc, and crypto_kem_dec prototypes.

You can use names other than kem.c. You can split your code across several files *.c defining various auxiliary functions; the files will be automatically compiled together. Instead of kem.c you can write kem.cc or kem.cpp in C++ or kem.s or kem.S in assembly language. Your implementation is allowed to be unportable; if it doesn't compile on a particular computer, SUPERCOP will skip it and select a different implementation for that computer.

Finally, create a tarball such as pqrsa15-ref-3.01a.tar.gz that contains your crypto_kem/pqrsa15/ref/api.h, crypto_kem/pqrsa15/ref/kem.c, etc. Put the tarball on the web, and send the URL to the eBACS/eBATS/eBASC/eBASH mailing list with a note requesting inclusion in SUPERCOP and subsequent benchmarking.

Example for implementors: submitting a new McEliece implementation

Submitting a new implementation of an existing key-encapsulation mechanism is just like submitting a new key-encapsulation mechanism. You simply have to put the new implementation into a new third-level directory under the same second-level directory.

For example, SUPERCOP already includes crypto_kem/mceliece6960119/mpfq, an implementation of Classic McEliece with the 6960119 parameter set. You can submit another implementation such as crypto_kem/mceliece6960119/smith/neon in the same way that the designer of pqRSA-15 can submit crypto_kem/pqrsa15/ref; by using the existing name mceliece6960119 you indicate that your software implements exactly the same key-encapsulation mechanism.

Version

This is version 2018.08.24 of the call-kem.html web page. This web page is in the public domain.