perftest: Document the `-q' option for disabling checking.

[u/mdw/catacomb] / keysz.h

/* -*-c-*-
 *
 * Key size management
 *
 * (c) 2007 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of Catacomb.
 *
 * Catacomb is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * Catacomb is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with Catacomb; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

#ifndef CATACOMB_KEYSZ_H
#define CATACOMB_KEYSZ_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <stddef.h>

#include <mLib/bits.h>

/*----- Data structures ---------------------------------------------------*/

/* --- Key size type constants --- *
 *
 * A key size limitation is an array of bytes.  The first byte describes the
 * kind of limitation on the key size %$k$%; the rest are argument bytes
 * %$a_i$%, for %$i \ge 0$%.  In all cases, %$a_0$% is the `recommended' key
 * size.
 *
 *   * @KSZ_ANY@ means there is no restriction.
 *
 *   * @KSZ_RANGE@ requires that %$k \ge a_1$%, %$k \equiv 0 \pmod{a_3}$%,
 *     and, if %$a_2 \ne 0$%, %$k \le a_2$%.
 *
 *   * @KSZ_SET@ requires that %$k \in {\,a_i\,}$%.
 */

enum {
  KSZ_ANY,				/* Allows any key at all */
  KSZ_RANGE,				/* Allows keys within a range */
  KSZ_SET				/* Allows specific sizes of keys */
};

/*----- Key sizes for symmetric algorithms --------------------------------*/

/* --- @keysz@ --- *
 *
 * Arguments:	@size_t sz@ = a proposed key size, or zero
 *		@const octet *ksz@ = pointer to key size table
 *
 * Returns:	See below.
 *
 * Use:		Returns a sensible key size.  If @sz@ is nonzero, it is
 *		interpreted as an amount (in bytes) of key material which the
 *		caller has available, and the return value is either the
 *		largest allowable key size less than or equal to the caller's
 *		size, or zero if there is no valid key length small enough.
 *		If @sz@ is zero, the function returns a `recommended' key
 *		size.
 */

extern size_t keysz(size_t /*sz*/, const octet */*ksz*/);

#define KSZ_CHECK(pre, sz) (keysz((sz), pre##_keysz) == (sz))
#define KSZ_ASSERT(pre, sz)						\
  assert(((void)"Bad key size for " #pre, KSZ_CHECK(pre, sz)))

/*----- Key size conversions ----------------------------------------------*/

/* --- @keysz_fromdl@, @_fromschnorr@, @_fromif@, @_fromec@ --- *
 *
 * Arguments:	@double nbits@ = key size
 *
 * Returns:	Equivalent symmetric key size.
 *
 * Use:		Converts key lengths of various kinds of reference problems
 *		to (roughly) equivalent symmetric key sizes.
 *
 *		  * Given the bit length of %$p$%, @keysz_fromdl@ returns a
 *		    key size representing the difficulty of computing
 *		    discrete logarithms in %$\gf{p}$%, for %$p$% prime or a
 *		    small power of a prime.
 *
 *		  * Given the bit length of %$r$%, @keysz_fromschnorr@
 *		    returns a key size representing the difficulty of
 *		    computing discrete logarithms in a subgroup of %$\gf{q}$%
 *		    of order %$r$%.
 *
 *		  * Given the bit length of %$n$%, @keysz_fromif@ returns a
 *		    key size representing the difficulty of factoring a
 *		    `hard' number %$n = p q$%, where %$p$% and %$q$% are
 *		    primes of (near enough) the same length.
 *
 *		  * Given the bit length of %$r$%, @keysz_fromec@ returns a
 *		    key size representing the difficulty of computing
 *		    discrete logarithms in a subgroup of order-%$r$% of an
 *		    elliptic curve over a finite field.
 *
 *		These functions take and return @double@ rather than an
 *		integer type in order to preserve precision between
 *		conversions.
 */

extern double keysz_fromdl(double /*nbits*/);
extern double keysz_fromschnorr(double /*nbits*/);
extern double keysz_fromif(double /*nbits*/);
extern double keysz_fromec(double /*nbits*/);

/* --- @keysz_todl@, @_toschnorr@, @_toif@, @_toec@ --- *
 *
 * Arguments:	@unsigned long nbits@ = symmetric key size
 *
 * Returns:	Equivalent key size.
 *
 * Use:		Converts symmetric key sizes to (roughly) equivalent key
 *		sizes for various kinds of reference problems.  These are the
 *		approximate inverses of the functions above.
 */

extern double keysz_todl(double /*nbits*/);
extern double keysz_toschnorr(double /*nbits*/);
extern double keysz_toif(double /*nbits*/);
extern double keysz_toec(double /*nbits*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif