This page explains how cryptographers can submit implementations of public-key-secret-sharing systems (DH, LUC, XTR, ECDH, etc.) to eBATS.
You can also provide additional functions that document additional features of your system:
The eBATS secret-sharing API is described below in more detail. There's a separate page on BATMAN, the eBATS benchmarking software; you will be able to download and use BATMAN before submission to check that your implementation works properly. There's also a separate page discussing security evaluations in more detail.
The directory name is the BAT name followed by a dash and a version number: e.g., ronald-1 for a BAT named ronald, version 1. eBATS will rename BATs if there is a conflict in names.
The file sizes.h defines various macros discussed below: SECRETKEY_BYTES, PUBLICKEY_BYTES, and SHAREDSECRET_BYTES.
BATMAN will automatically decide whether the BAT is a C BAT, providing the eBATS API functions in C, or a C++ BAT, providing the eBATS API functions in C++. Either way, the BAT can call C functions in its *.c files and assembly-language functions in its *.S files. BATs written in other languages have to be compiled to C++, C, or assembly language.
The eBATS API can support BATs of either type. A parametrized BAT includes, in the same directory as sizes.h, a parameters file with several lines; each line specifies compilation options that select a particular parameter choice. A parameter choice is specified by BAT-specific macros, which are used by sizes.h etc., and by a PARAMETERS macro (without white space), which is used to identify parameters in the eBATS results.
For example, version 1 of the RONALD BAT has a 29-line parameters file starting
-DMODULUS_BITS=768 -DPARAMETERS="768"
-DMODULUS_BITS=832 -DPARAMETERS="832"
-DMODULUS_BITS=896 -DPARAMETERS="896"
-DMODULUS_BITS=960 -DPARAMETERS="960"
-DMODULUS_BITS=1024 -DPARAMETERS="1024"
and continuing (in roughly geometric progression) until
-DMODULUS_BITS=4096 -DPARAMETERS="4096"
The MODULUS_BITS macro controls PUBLICKEY_BYTES etc.
through the lines
#define MODULUS_BYTES (MODULUS_BITS / 8)
#define PUBLICKEY_BYTES (MODULUS_BYTES)
in the sizes.h file.
The PARAMETERS macro is printed in the eBATS measurements.
The parameters file can omit -DPARAMETERS=... if sizes.h defines PARAMETERS. For example, version 2 of the RONALD BAT has a 29-line parameters file starting
-DMODULUS_BITS=768
-DMODULUS_BITS=832
-DMODULUS_BITS=896
-DMODULUS_BITS=960
-DMODULUS_BITS=1024
and the following lines in sizes.h:
#define XSTRINGIFY(N) #N
#define STRINGIFY(N) XSTRINGIFY(N)
#define PARAMETERS (STRINGIFY(MODULUS_BITS))
BATMAN will automatically try each tuning and select the tuning where sharedsecret runs most quickly. A BAT can define a TUNETARGET macro in sizes.h; in that case BATMAN will select the tuning where TUNETARGET() runs most quickly.
Any particular tuning is allowed to be unportable, failing to compile on most platforms. BATMAN will skip tunings that don't compile or that flunk some simple tests.
Functions are permitted, but not encouraged, to generate randomness in other ways, such as by opening /dev/urandom. These functions won't be benchmarkable on systems that don't have /dev/urandom, and they won't be suitable for black-box regression testing.
const unsigned char m[...]; unsigned long long mlen;
unsigned char h[32];
hash256(h,m,mlen);
hash256 hashes bytes m[0], m[1], ..., m[mlen-1]
and puts the output into h[0], h[1], ..., h[31].
Currently hash256 is implemented as SHA-256.
To simplify comparisons of public-key systems, eBATS recommends that BATs use hash256 for all necessary hashing. This is not a recommendation of SHA-256 for any purpose other than public-key benchmarking. Public-key systems may be able to gain speed and security by choosing different hash functions.
To the extent that eBATS considers security of public-key systems, it focuses on generic attacks, i.e., attacks that work with any hash function. Any security problems in SHA-256 are outside the scope of eBATS, although obviously they should be discussed elsewhere.
const unsigned char m[...]; unsigned long long mlen;
unsigned char c[...];
const unsigned char k[32];
const unsigned char n[8];
stream256(c,m,mlen,k,n);
stream256 encrypts (or decrypts) bytes m[0], m[1], ..., m[mlen-1]
and puts the output into c[0], c[1], ..., c[mlen-1].
It uses a 32-byte key k[0], k[1], ..., k[31]
and an 8-byte nonce n[0], n[1], ..., n[7].
Currently stream256 is implemented as Salsa20.
To simplify comparisons of public-key systems, eBATS recommends that BATs use stream256 for all necessary stream generation. This is not a recommendation of Salsa20 for any purpose other than public-key benchmarking. Public-key systems may be able to gain speed and security by choosing different ciphers.
To the extent that eBATS considers security of public-key systems, it focuses on generic attacks, i.e., attacks that work with any stream cipher. Any security problems in Salsa20 are outside the scope of eBATS, although obviously they should be discussed elsewhere.
#include "sizes.h"
unsigned char sk[SECRETKEY_BYTES]; unsigned long long sklen;
unsigned char pk[PUBLICKEY_BYTES]; unsigned long long pklen;
keypair(sk,&sklen,pk,&pklen);
The keypair function
generates a new secret key and a new public key.
It puts the number of bytes of the secret key into sklen;
puts the number of bytes of the public key into pklen;
puts the secret key into
sk[0], sk[1], ..., sk[sklen-1];
and puts the public key into
pk[0], pk[1], ..., pk[pklen-1].
It then returns 0.
keypair guarantees that sklen is at most SECRETKEY_BYTES, and that pklen is at most PUBLICKEY_BYTES, so that the caller can allocate enough space.
If key generation is impossible for some reason (e.g., not enough memory), keypair returns a negative number, possibly after modifying sk[0], sk[1], etc. Current implementations should return -1; other return values with special meanings may be defined in the future.
#include "sizes.h"
const unsigned char sk[PUBLICKEY_BYTES]; unsigned long long sklen;
const unsigned char pk[PUBLICKEY_BYTES]; unsigned long long pklen;
unsigned char s[SHAREDSECRET_BYTES]; unsigned long long slen;
sharedsecret(s,&slen,sk,sklen,pk,pklen);
The sharedsecret function
uses a secret key
sk[0], sk[1], ..., sk[sklen-1]
and another user's public key
pk[0], pk[1], ..., pk[pklen-1]
to compute a shared secret.
It puts the length of the shared secret into slen
and puts the shared secret into
s[0], s[1], ..., s[slen-1].
It then returns 0.
The sharedsecret function guarantees that slen is at most SHAREDSECRET_BYTES. The SHAREDSECRET_BYTES macro is defined in sizes.h.
The sharedsecret function is free to assume that the secret key sk[0], sk[1], ..., sk[sklen-1] was generated by a successful call to the keypair function.
If shared-secret generation is impossible for some reason, sharedsecret returns a negative number, possibly after modifying s[0], s[1], etc. Current implementations should return -1; other return values with special meanings may be defined in the future.
#include "sizes.h"
double e;
double s;
double p = cdhchance(e,s);
The cdhchance function
returns a number between 0 and 1,
namely the probability
that an attacker spending e euros and s seconds
can deduce a shared secret given two public keys.
Here e and s
are powers of 2 between 2^0 and 2^40.
The cdhchance function is free to ignore attacks that merely distinguish the shared secret from uniform (DDH) without computing the shared secret (CDH); shared secrets are presumed to be hashed before they are used.
There is a separate page with more information on security evaluations.
#include "sizes.h"
double e;
double s;
double k;
double p = multiplekeycdhchance(e,s,k);
The multiplekeycdhchance function
returns a number between 0 and 1,
namely the probability
that an attacker spending e euros and s seconds
can deduce at least one shared secret
given k public keys.
(More precisely, there are public keys key_1, key_2, ..., key_k;
the attack is successful if it prints a vector i, j, z
where 1<=i<j<=k and
z is the secret shared between key_i and key_j.)
Here e, s, and k
are powers of 2 between 2^0 and 2^40.
The result of multiplekeycdhchance can be larger than the result of cdhchance by a factor as large as k(k-1)/2.
#include "sizes.h"
int x = fakekeyattacks();
The fakekeyattacks function
returns 100 if an active attacker can save time by providing fake keys
(in applications that do not go to any extra effort to validate keys).
It returns 0 if an active attacker obtains no benefit from fake keys
(for example, if the sharedsecret function includes all necessary key validation).
#include "sizes.h"
int x = timingattacks();
The timingattacks function
returns 0 if the software
does not leak any secret information through timing
(variable time for branching, variable time for memory access, etc.):
i.e., if the best attack known that sees timings
is as difficult as the best attack known that does not see timings.
It returns 100 if the software leaks secret information through timing.
#include "sizes.h"
int x = copyrightclaims();
The copyrightclaims function returns
one of the following numbers:
No matter what the BAT's copyright status is, eBATS will publicly distribute copies of the BAT for benchmarking. The submitter must ensure before submission that publication is legal.
#include "sizes.h"
int x = patentclaims();
The patentclaims function returns
one of the following numbers:
No matter what the BAT's patent status is, eBATS will publicly distribute copies of the BAT for benchmarking.