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 hash software for benchmarking

Are you a hash-function designer, or a hash-function implementor? Would you like your hash function, or your implementation, professionally benchmarked on many computers, producing stable, reliable, verifiable timings that reflect the performance that hash-function users will see? This page explains how to submit your software to the eBASH 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 (SHA-3 excerpt) showing the hash functions submitted to eBASH so far, and another page (SHA-3 excerpt) reporting measurements of those functions.

Example for designers: submitting the MD7 hash function

Let's say you're the designer of a 512-bit hash function MD7, and you want to submit your MD7 software to eBASH. Your submission can be as simple as two files, crypto_hash/md7/ref/api.h and crypto_hash/md7/ref/hash.c. Here is an explanation of what these files contain and what additional options you have.

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

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

After choosing the implementation name crypto_hash/md7/ref, create a directory by that name. Inside the crypto_hash/md7/ref directory, create a file named api.h with one line

     #define CRYPTO_BYTES 64
indicating that your software produces a 64-byte hash output. 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_hash/md7/ref directory, create a file named hash.c that defines a crypto_hash function:

     #include "crypto_hash.h"

     int crypto_hash(
       unsigned char *out,
       const unsigned char *in,
       unsigned long long inlen
     )
     {
       ... 
       ... the code for your MD7 implementation goes here
       ...
       return 0;
     }
Your function must have exactly the prototype shown here: first an unsigned char pointer for the output, then a const unsigned char pointer for the input, then an unsigned long long for the number of bytes of input. Your function must return 0 to indicate success, or a negative number to indicate failure (e.g., out of memory).

The file crypto_hash.h is not something for you to write; it is created automatically by SUPERCOP. It defines a crypto_hash_BYTES macro (converted from your CRYPTO_BYTES macro) and a prototype for the crypto_hash function.

You can use names other than hash.c. You can split your code across several files *.c defining various auxiliary functions; the files will be automatically compiled together. You can, for example, have files md7.c and md7.h using NIST's SHA-3 submission API, along with a file nist.c containing

     #include "crypto_hash.h"
     #include "md7.h"
     
     int crypto_hash(unsigned char *out,const unsigned char *in,unsigned long long inlen)
     {
       if (Hash(crypto_hash_BYTES * 8,in,inlen * 8,out) == SUCCESS) return 0;
       return -1;
     }

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 hash.c you can write hash.cc or hash.cpp in C++ or hash.s or hash.S in assembly language. Assembly-language implementations must define a function crypto_hash_md7_ref instead of a function crypto_hash. (This is also true for C implementations but is handled automatically by a macro in crypto_hash.h.)

Finally, create a tarball such as md7-ref-3.01a.tar.gz that contains your crypto_hash/md7/ref/api.h, crypto_hash/md7/ref/hash.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 SHA-256 implementation

Submitting a new implementation of an existing hash function is just like submitting a new hash function. 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 two SHA-256 implementations. One implementation, crypto_hash/sha256/ref, is a reference implementation written from the SHA-256 specification. Another implementation, crypto_hash/sha256/openssl, is a simple wrapper around OpenSSL. You can submit another SHA-256 implementation such as crypto_hash/sha256/smith/sse3 in the same way that the designer of MD7 can submit crypto_hash/md7/ref; by using the existing name sha256 you indicate that your implementation computes the same SHA-256 hash function.

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.03 of the call-hash.html web page. This web page is in the public domain.