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 functions Stream ciphers Auth ciphers DH functions Public-key encryption Public-key signatures
List of primitives measured: SHA-3 finalists All hash functions Stream ciphers CAESAR candidates All auth ciphers DH functions Public-key encryption Public-key signatures
Measurements indexed by machine: SHA-3 finalists All hash functions Stream ciphers CAESAR candidates All auth ciphers DH functions Public-key encryption Public-key signatures

Call for authenticated-cipher software for benchmarking

Are you a designer or implementor of an authenticated cipher, i.e., a function that uses a secret key to authenticate and encrypt a message? Would you like your cipher, or your implementation, professionally benchmarked on many computers, producing stable, reliable, verifiable timings that reflect the performance that cipher users will see? This page explains how to submit your software to the eBAEAD 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 showing the authenticated ciphers submitted to eBAEAD so far (including software from the CAESAR competition), and another page reporting measurements of those functions.

Example for designers: submitting AEY

Let's say you're the designer of an authenticated cipher AEY that uses a 256-bit key, a 96-bit public message number, and a 128-bit authenticator, and you want to submit your AEY software to eBAEAD. Your submission can be as simple as two files, crypto_aead/aey/ref/api.h and crypto_aead/aey/ref/encrypt.c. Here is an explanation of what these files contain and what additional options you have.

The top-level directory name crypto_aead is required; it distinguishes authenticated encryption from other operations benchmarked by SUPERCOP, such as crypto_stream and crypto_sign.

The second-level directory name aey should be a lowercase version of your cipher 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 ciphers must be placed into different second-level directories, even if they are part of the same "family" of ciphers. For example, crypto_aead/aes128gcmv1 is separate from crypto_aead/aes256gcmv1. One submission tarball can include several ciphers. Directory names may be changed by the eBAEAD 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_aead/aey/ref might be a reference implementation, crypto_aead/aey/smith/little might be John Smith's little-endian implementation, and crypto_aead/aey/smith/sse3 might be John Smith's SSE3-optimized implementation. One submission tarball can include several implementations.

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

     #define CRYPTO_KEYBYTES 32
     #define CRYPTO_NSECBYTES 0
     #define CRYPTO_NPUBBYTES 12
     #define CRYPTO_ABYTES 16
This indicates that the AEY key has 32 bytes, that the secret message number has 0 bytes, that the public message number has 12 bytes, and that the ciphertext is at most 16 bytes longer than the plaintext. (A typical authenticated cipher has a constant gap between plaintext length and ciphertext length, but the requirement here is to have a constant limit on the gap.) 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.

Next, inside the crypto_aead/aey/ref directory, create a file named encrypt.c that defines a crypto_aead_encrypt function and a crypto_aead_decrypt function:

     #include "crypto_aead.h"

     int crypto_aead_encrypt(
       unsigned char *c,unsigned long long *clen,
       const unsigned char *m,unsigned long long mlen,
       const unsigned char *ad,unsigned long long adlen,
       const unsigned char *nsec,
       const unsigned char *npub,
       const unsigned char *k
     )
     {
       ...
       ... the code for the cipher implementation goes here,
       ... generating a ciphertext c[0],c[1],...,c[*clen-1]
       ... from a plaintext m[0],m[1],...,m[mlen-1]
       ... and associated data ad[0],ad[1],...,ad[adlen-1]
       ... and secret message number nsec[0],nsec[1],...
       ... and public message number npub[0],npub[1],...
       ... and secret key k[0],k[1],...
       ...
       return 0;
     }

     int crypto_aead_decrypt(
       unsigned char *m,unsigned long long *mlen,
       unsigned char *nsec,
       const unsigned char *c,unsigned long long clen,
       const unsigned char *ad,unsigned long long adlen,
       const unsigned char *npub,
       const unsigned char *k
     )
     {
       ...
       ... the code for the cipher implementation goes here,
       ... generating a plaintext m[0],m[1],...,m[*mlen-1]
       ... and secret message number nsec[0],nsec[1],...
       ... from a ciphertext c[0],c[1],...,c[clen-1]
       ... and associated data ad[0],ad[1],...,ad[adlen-1]
       ... and public message number npub[0],npub[1],...
       ... and secret key k[0],k[1],...
       ...
       return 0;
     }

The outputs of crypto_aead_encrypt and crypto_aead_decrypt must be determined entirely by the inputs listed above and must not be affected by any randomness or other hidden inputs.

The crypto_aead_decrypt function must return -1 if the ciphertext is not valid, i.e., if the ciphertext does not equal the encryption of any (plaintext,secret message number) pair with this associated data, public message number, and secret key. The crypto_aead_encrypt and crypto_aead_decrypt functions may return other negative numbers to indicate other failures (e.g., memory-allocation failures).

The file crypto_aead.h is not included in the reference implementation; it is created automatically by the benchmarking framework. The file crypto_aead.h is not something for you to write; it is created automatically by SUPERCOP. It defines macros crypto_aead_KEYBYTES, crypto_aead_NSECBYTES, crypto_aead_NPUBBYTES, and crypto_aead_ABYTES (converted from your macros CRYPTO_KEYBYTES etc.), and prototypes for the crypto_aead_encrypt and crypto_aead_decrypt functions.

You can use names other than encrypt.c. You can split your code across several files *.c defining various auxiliary functions; the files will be automatically compiled together.

If you want a 32-bit unsigned integer type, you can

     #include "crypto_uint32.h"
and then use crypto_uint32. This is somewhat more portable then using stdint.h or inttypes.h. SUPERCOP provides similar facilities for uint8, uint16, uint32, uint64, int8, int16, int32, int64.

Instead of encrypt.c you can write encrypt.cc or encrypt.cpp in C++ or encrypt.s or encrypt.S in assembly language. Assembly-language implementations must define functions crypto_aead_aey_ref_encrypt and crypto_aead_aey_ref_decrypt instead of functions crypto_aead_encrypt and crypto_aead_decrypt. (This is also true for C implementations but is handled automatically by a macro in crypto_aead.h.)

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

Example for implementors: submitting a new AES-GCM implementation

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

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.

For example, SUPERCOP already includes several AES-256-GCM implementations. One implementation, crypto_aead/aes256gcmv1/ref, is a (very slow) reference implementation. Another implementation, crypto_aead/aes256gcmv1/openssl, calls the OpenSSL library. You can submit another AES-256-GCM implementation such as crypto_aead/aes256gcmv1/smith/sse3 in the same way that the designer of AEY can submit crypto_aead/aey/ref; by using the existing name aes256gcmv1 you indicate that your implementation computes the same AES-256-GCM cipher.

Version

This is version 2017.07.26 of the call-aead.html web page. This web page is in the public domain.