VAMPIRE

eBACS: ECRYPT Benchmarking of Cryptographic Systems


ECRYPT II
General information: Introduction eBASH eBASC eBAEAD eBATS SUPERCOP XBX Computers Arch
How to submit new software: Tips hash stream aead dh kem encrypt sign
List of primitives measured: lwc sha3 hash stream lwc caesar aead dh kem encrypt sign
Measurements: lwc sha3 hash stream lwc caesar aead dh kem encrypt sign
List of subroutines: verify decode encode sort core hashblocks xof scalarmult

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.)

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).

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. You must include crypto_aead.h for any file referring to the crypto_aead_* functions. The file crypto_aead.h is not something for you to write or submit; it is created automatically by SUPERCOP. See the SUPERCOP tips for more advice and options.

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.

Version

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