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 public-key Diffie–Hellman secret-sharing software for benchmarking

Are you a designer or implementor of a Diffie–Hellman function? Would you like your software professionally benchmarked on many computers, producing stable, reliable, verifiable timings that reflect the performance that Diffie–Hellman 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 Diffie–Hellman functions submitted so far, and another page reporting measurements of those functions. Note that the eBATS project also includes public-key signature systems and encryption systems.

Example for designers: submitting the XTR-512 system

Let's say you're the designer of XTR-512, a Diffie–Hellman system with a 1536-bit private key, a 512-bit public key, and a 512-bit shared secret, and you want to submit your XTR-512 software to eBATS. Your submission can be as simple as two files, crypto_dh/xtr512/ref/api.h and crypto_dh/xtr512/ref/dh.c. Here is an explanation of what these files contain and what additional options you have.

The top-level directory name crypto_dh is required; it distinguishes Diffie–Hellman functions from other operations benchmarked by SUPERCOP, such as crypto_hash and crypto_sign.

The second-level directory name xtr512 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 Diffie–Hellman functions must be placed into different second-level directories, even if they are part of the same "family" of functions. For example, crypto_dh/nistp256 is separate from crypto_dh/nistp224. One submission tarball can include several Diffie–Hellman functions 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_dh/xtr512/ref might be a reference implementation, crypto_dh/xtr512/smith/little might be John Smith's little-endian implementation, and crypto_dh/xtr512/smith/sse3 might be John Smith's SSE3-optimized implementation. One submission tarball can include several implementations.

After choosing the implementation name crypto_dh/xtr512/ref, create a directory by that name. Inside the crypto_dh/xtr512/ref directory, create a file named api.h with three lines

     #define CRYPTO_SECRETKEYBYTES 192
     #define CRYPTO_PUBLICKEYBYTES 64
     #define CRYPTO_BYTES 64
indicating that your software uses a 192-byte (1536-bit) secret key, a 64-byte (512-bit) public key, and a 64-byte (512-bit) shared secret. 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_dh_xtr512_ref_.

Next, inside the crypto_dh/xtr512/ref directory, create a file named dh.c that defines a crypto_dh_xtr512_ref function and a crypto_dh_xtr512_ref_keypair function:

     int crypto_dh_xtr512_ref_keypair(
       unsigned char *pk,
       unsigned char *sk
     )
     {
       ... 
       ... the code for your XTR-512 implementation goes here,
       ... generating public key pk[0],pk[1],...
       ... and secret key sk[0],sk[1],...
       ...
       return 0;
     }
     
     int crypto_dh_xtr512_ref(
       unsigned char *out,
       const unsigned char *pk,
       const unsigned char *sk
     )
     {
       ... 
       ... the code for your XTR-512 implementation goes here,
       ... generating shared secret out[0],out[1],...
       ... from public key pk[0],pk[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 other function must have an unsigned char pointer for the shared-secret output, a const unsigned char pointer for the public-key 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 function as follows:

     #include "crypto_dh.h"

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

     int crypto_dh(
       unsigned char *out,
       const unsigned char *pk,
       const unsigned char *sk
     )
     {
       ...
     }
The file crypto_dh.h is not something for you to write; it is created automatically by SUPERCOP. It contains various macros such as
     #define crypto_dh crypto_dh_xtr512_ref
     #define crypto_dh_keypair crypto_dh_xtr512_ref_keypair
     #define crypto_dh_SECRETKEYBYTES crypto_dh_xtr512_ref_SECRETKEYBYTES
     #define crypto_dh_PUBLICKEYBYTES crypto_dh_xtr512_ref_PUBLICKEYBYTES
     #define crypto_dh_BYTES crypto_dh_xtr512_ref_BYTES
and a function declaration that will catch errors in the crypto_dh and crypto_dh_keypair prototypes.

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

Submitting a new implementation of an existing Diffie–Hellman function is just like submitting a new Diffie–Hellman function. 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_dh/curve25519/mpfq, an implementation of Curve25519. You can submit another implementation such as crypto_dh/curve25519/smith/sse3 in the same way that the designer of XTR-512 can submit crypto_dh/xtr512/ref; by using the existing name curve25519 you indicate that your software implements exactly the same Diffie–Hellman 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.04 of the call-dh.html web page. This web page is in the public domain.