VAMPIRE

eBACS: ECRYPT Benchmarking of Cryptographic Systems


ECRYPT II
General information: Introduction eBASH eBASC eBAEAD eBATS SUPERCOP XBX Computers
How to submit new software: 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 stream-cipher software for benchmarking

Are you a stream-cipher designer, or a stream-cipher implementor? Would you like your stream cipher, or your implementation, professionally benchmarked on many computers, producing stable, reliable, verifiable timings that reflect the performance that stream-cipher users will see? This page explains how to submit your software to the eBASC 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 stream ciphers submitted to eBASC so far (including some submitted to eSTREAM and imported to eBASC), and another page reporting measurements of those stream ciphers.

Example for designers: submitting the A5/7 stream cipher

Let's say you're the designer of a stream cipher A5/7 using a 256-bit key and a 64-bit nonce, and you want to submit your A5/7 software to eBASC. Your submission can be as simple as two files, crypto_stream/a57/ref/api.h and crypto_stream/a57/ref/stream.c. Here is an explanation of what these files contain and what additional options you have.

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

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

After choosing the implementation name crypto_stream/a57/ref, create a directory by that name. Inside the crypto_stream/a57/ref directory, create a file named api.h with two lines

     #define CRYPTO_KEYBYTES 32
     #define CRYPTO_NONCEBYTES 8
indicating that your software uses a 32-byte (256-bit) key and an 8-byte (64-bit) nonce. 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_stream_a57_ref_.

Next, inside the crypto_stream/a57/ref directory, create a file named stream.c that defines a crypto_stream_a57_ref function and a crypto_stream_a57_ref_xor function:

     int crypto_stream_a57_ref(
       unsigned char *out,
       unsigned long long outlen,
       const unsigned char *n,
       const unsigned char *k
     )
     {
       ... 
       ... the code for your A5/7 implementation goes here
       ... generating stream out[0],out[1],...,out[outlen-1]
       ... using nonce n and key k
       ...
       return 0;
     }

     int crypto_stream_a57_ref_xor(
       unsigned char *out,
       const unsigned char *in,
       unsigned long long inlen,
       const unsigned char *n,
       const unsigned char *k
     )
     {
       ... 
       ... the code for your A5/7 implementation goes here
       ... generating ciphertext out[0],out[1],...,out[inlen-1]
       ... from plaintext in[0],in[1],...,in[inlen-1]
       ... using nonce n and key k
       ...
       return 0;
     }
Your functions must have exactly the prototype shown here: first an unsigned char pointer for the output, then (for the xor function) a const unsigned char pointer for the input, then an unsigned long long for the number of bytes of output (and input), then an unsigned char pointer for the nonce, then an unsigned char pointer for the key. 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 function as follows:

     #include "crypto_stream.h"

     int crypto_stream(
       unsigned char *out,
       unsigned long long outlen,
       const unsigned char *n,
       const unsigned char *k
     )
     {
       ... 
     }

     int crypto_stream_xor(
       unsigned char *out,
       const unsigned char *in,
       unsigned long long inlen,
       const unsigned char *n,
       const unsigned char *k
     )
     {
       ...
     }
The file crypto_stream.h is not something for you to write; it is created automatically by SUPERCOP. It contains various macros such as
     #define crypto_stream crypto_stream_a57_ref
     #define crypto_stream_xor crypto_stream_a57_ref_xor
     #define crypto_stream_KEYBYTES crypto_stream_a57_ref_KEYBYTES
     #define crypto_stream_NONCEBYTES crypto_stream_a57_ref_NONCEBYTES
and a function declaration that will catch errors in the crypto_stream and crypto_stream_xor prototypes.

You can use names other than stream.c. You can split your code across several files *.c defining various auxiliary functions; the files will be automatically compiled together. Instead of stream.c you can write stream.cc or stream.cpp in C++ or stream.s or stream.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 a57-ref-3.01a.tar.gz that contains your crypto_stream/a57/ref/api.h, crypto_stream/a57/ref/stream.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 AES implementation

Submitting a new implementation of an existing stream cipher is just like submitting a new stream cipher. 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 several implementations of aes128estream (AES with a 128-bit key in a particular counter mode specified by eSTREAM). One implementation is crypto_stream/aes128estream/e/gladman; another implementation is crypto_stream/aes128estream/e/bernstein/amd64-2; etc. You can submit another implementation such as crypto_stream/aes128estream/smith/sse3 in the same way that the designer of A5/7 can submit crypto_stream/a57/ref; by using the existing name aes128estream you indicate that your software implements exactly the same stream cipher.

Additional documentation

Submitters are encouraged to include additional files such as README or documentation.pdf with references, intellectual-property information, descriptions of the software, etc. These files do not interact with SUPERCOP's benchmarking but are often of interest for human readers.

In particular, submitters are encouraged to clearly specify one of the following levels of copyright protection:

Submitters are also encouraged to clearly specify one of the following levels of patent protection: No matter what the copyright status is, and no matter what the patent status is, all software included in SUPERCOP will be distributed to the public to ensure verifiability of benchmark results. The submitter must ensure before submission that publication is legal.

Version

This is version 2010.09.04 of the call-stream.html web page. This web page is in the public domain.