crypto

crypto

Synopsis

#define             GNUTLS_CRYPTO_API_VERSION
                    gnutls_crypto_single_cipher_st;
                    gnutls_crypto_single_mac_st;
                    gnutls_crypto_cipher_st;
                    gnutls_crypto_mac_st;
typedef             gnutls_crypto_single_digest_st;
typedef             gnutls_crypto_digest_st;
enum                gnutls_rnd_level_t;
enum                gnutls_pk_flag_t;
                    gnutls_crypto_rnd_st;
typedef             bigint_t;
enum                gnutls_bigint_format_t;
                    gnutls_crypto_bigint_st;
#define             GNUTLS_MAX_PK_PARAMS
                    gnutls_pk_params_st;
void                gnutls_pk_params_release            (gnutls_pk_params_st *p);
void                gnutls_pk_params_init               (gnutls_pk_params_st *p);
enum                gnutls_direction_t;
                    gnutls_crypto_pk_st;
#define             gnutls_crypto_single_cipher_register(algo, prio, st)
#define             gnutls_crypto_single_mac_register   (algo, prio, st)
#define             gnutls_crypto_single_digest_register(algo, prio, st)
int                 gnutls_crypto_single_cipher_register2
                                                        (gnutls_cipher_algorithm_t algorithm,
                                                         int priority,
                                                         int version,
                                                         gnutls_crypto_single_cipher_st *s);
int                 gnutls_crypto_single_mac_register2  (gnutls_mac_algorithm_t algorithm,
                                                         int priority,
                                                         int version,
                                                         gnutls_crypto_single_mac_st *s);
int                 gnutls_crypto_single_digest_register2
                                                        (gnutls_digest_algorithm_t algorithm,
                                                         int priority,
                                                         int version,
                                                         gnutls_crypto_single_digest_st *s);
#define             gnutls_crypto_cipher_register       (prio, st)
#define             gnutls_crypto_mac_register          (prio, st)
#define             gnutls_crypto_digest_register       (prio, st)
int                 gnutls_crypto_cipher_register2      (int priority,
                                                         int version,
                                                         gnutls_crypto_cipher_st *s);
int                 gnutls_crypto_mac_register2         (int priority,
                                                         int version,
                                                         gnutls_crypto_mac_st *s);
int                 gnutls_crypto_digest_register2      (int priority,
                                                         int version,
                                                         gnutls_crypto_digest_st *s);
#define             gnutls_crypto_rnd_register          (prio, st)
#define             gnutls_crypto_pk_register           (prio, st)
#define             gnutls_crypto_bigint_register       (prio, st)
int                 gnutls_crypto_rnd_register2         (int priority,
                                                         int version,
                                                         gnutls_crypto_rnd_st *s);
int                 gnutls_crypto_pk_register2          (int priority,
                                                         int version,
                                                         gnutls_crypto_pk_st *s);
int                 gnutls_crypto_bigint_register2      (int priority,
                                                         int version,
                                                         gnutls_crypto_bigint_st *s);

Description

Details

GNUTLS_CRYPTO_API_VERSION

#define GNUTLS_CRYPTO_API_VERSION 0x01

gnutls_crypto_single_cipher_st

typedef struct {
  int (*init) (void** ctx);
  int (*setkey) (void* ctx, const void * key, size_t keysize);
  int (*setiv) (void* ctx, const void* iv, size_t ivsize);
  int (*encrypt) (void* ctx, const void* plain, size_t plainsize,
		  void* encr, size_t encrsize);
  int (*decrypt) (void* ctx, const void* encr, size_t encrsize,
		  void* plain, size_t plainsize);
  void (*deinit) (void* ctx);
} gnutls_crypto_single_cipher_st;

gnutls_crypto_single_mac_st

typedef struct {
  int (*init) (void** ctx);
  int (*setkey) (void* ctx, const void * key, size_t keysize);
  int (*hash) (void* ctx, const void * text, size_t textsize);
  int (*copy) (void** dst_ctx, void* src_ctx);
  int (*output) (void* src_ctx, void* digest, size_t digestsize);
  void (*deinit)(void* ctx);
} gnutls_crypto_single_mac_st;

gnutls_crypto_cipher_st

typedef struct {
  int (*init) (gnutls_cipher_algorithm_t, void** ctx);
  int (*setkey) (void* ctx, const void * key, size_t keysize);
  int (*setiv) (void* ctx, const void* iv, size_t ivsize);
  int (*encrypt) (void* ctx, const void* plain, size_t plainsize,
		  void* encr, size_t encrsize);
  int (*decrypt) (void* ctx, const void* encr, size_t encrsize,
		  void* plain, size_t plainsize);
  void (*deinit) (void* ctx);
} gnutls_crypto_cipher_st;

gnutls_crypto_mac_st

typedef struct {
  int (*init) (gnutls_mac_algorithm_t, void** ctx);
  int (*setkey) (void* ctx, const void * key, size_t keysize);
  int (*hash) (void* ctx, const void * text, size_t textsize);
  int (*copy) (void** dst_ctx, void* src_ctx);
  int (*output) (void* src_ctx, void* digest, size_t digestsize);
  void (*deinit)(void* ctx);
} gnutls_crypto_mac_st;

gnutls_crypto_single_digest_st

typedef gnutls_crypto_single_mac_st gnutls_crypto_single_digest_st;

gnutls_crypto_digest_st

typedef gnutls_crypto_mac_st gnutls_crypto_digest_st;

enum gnutls_rnd_level_t

typedef enum gnutls_rnd_level
  {
    /* fatal in parts of session if broken, i.e., vulnerable to
       statistical analysis */
    GNUTLS_RND_NONCE = 0,
    /* fatal in session if broken */
    GNUTLS_RND_RANDOM = 1,
    /* fatal in many sessions if broken */
    GNUTLS_RND_KEY = 2
  } gnutls_rnd_level_t;

enum gnutls_pk_flag_t

typedef enum
  {
    GNUTLS_PK_FLAG_NONE = 0
  } gnutls_pk_flag_t;

gnutls_crypto_rnd_st

typedef struct {
  int (*init)( void** ctx);
  int (*rnd) ( void* ctx, int /* gnutls_rnd_level_t */ level,
	       void* data, size_t datasize);
  void (*deinit)( void* ctx);
} gnutls_crypto_rnd_st;

bigint_t

typedef void* bigint_t;

enum gnutls_bigint_format_t

typedef enum
  {
    /* raw unsigned integer format */
    GNUTLS_MPI_FORMAT_USG = 0,
    /* raw signed integer format - always a leading zero when positive */
    GNUTLS_MPI_FORMAT_STD = 1,
    /* the pgp integer format */
    GNUTLS_MPI_FORMAT_PGP = 2
  } gnutls_bigint_format_t;

gnutls_crypto_bigint_st

typedef struct {
  bigint_t (*bigint_new)( int nbits);
  void (*bigint_release)( bigint_t n);
  /* 0 for equality, > 0 for m1>m2, < 0 for m1<m2 */
  int (*bigint_cmp)(const bigint_t m1, const bigint_t m2);
  /* as bigint_cmp */
  int (*bigint_cmp_ui)(const bigint_t m1, unsigned long m2);
  /* ret = a % b */
  bigint_t (*bigint_mod) (const bigint_t a, const bigint_t b);
  /* a = b -> ret == a */
  bigint_t (*bigint_set) (bigint_t a, const bigint_t b);
  /* a = b -> ret == a */
  bigint_t (*bigint_set_ui) (bigint_t a, unsigned long b);
  unsigned int (*bigint_get_nbits)(const bigint_t a);
  /* w = b ^ e mod m */
  bigint_t (*bigint_powm) (bigint_t w, const bigint_t b,
			   const bigint_t e, const bigint_t m);
  /* w = a + b mod m */
  bigint_t (*bigint_addm) (bigint_t w, const bigint_t a,
			   const bigint_t b, const bigint_t m);
  /* w = a - b mod m */
  bigint_t (*bigint_subm) (bigint_t w, const bigint_t a, const bigint_t b,
			   const bigint_t m);
  /* w = a * b mod m */
  bigint_t (*bigint_mulm) (bigint_t w, const bigint_t a, const bigint_t b,
			   const bigint_t m);
  /* w = a + b */bigint_t (*bigint_add) (bigint_t w, const bigint_t a,
					 const bigint_t b);
  /* w = a - b */bigint_t (*bigint_sub) (bigint_t w, const bigint_t a,
					 const bigint_t b);
  /* w = a * b */
  bigint_t (*bigint_mul) (bigint_t w, const bigint_t a, const bigint_t b);
  /* w = a + b */
  bigint_t (*bigint_add_ui) (bigint_t w, const bigint_t a, unsigned long b);
  /* w = a - b */
  bigint_t (*bigint_sub_ui) (bigint_t w, const bigint_t a, unsigned long b);
  /* w = a * b */
  bigint_t (*bigint_mul_ui) (bigint_t w, const bigint_t a, unsigned long b);
  /* q = a / b */
  bigint_t (*bigint_div) (bigint_t q, const bigint_t a, const bigint_t b);
  /* 0 if prime */
  int (*bigint_prime_check) (const bigint_t pp);
  int (*bigint_generate_group) (gnutls_group_st* gg, unsigned int bits);

  /* reads an bigint from a buffer */
  /* stores an bigint into the buffer.  returns
   * GNUTLS_E_SHORT_MEMORY_BUFFER if buf_size is not sufficient to
   * store this integer, and updates the buf_size;
   */
  bigint_t (*bigint_scan) (const void* buf, size_t buf_size,
			   gnutls_bigint_format_t format);
  int (*bigint_print) (const bigint_t a, void* buf, size_t* buf_size,
		       gnutls_bigint_format_t format);
} gnutls_crypto_bigint_st;

GNUTLS_MAX_PK_PARAMS

#define GNUTLS_MAX_PK_PARAMS 6

gnutls_pk_params_st

typedef struct {
  bigint_t params[GNUTLS_MAX_PK_PARAMS];
  unsigned int params_nr; /* the number of parameters */
  unsigned int flags;
} gnutls_pk_params_st;

gnutls_pk_params_release ()

void                gnutls_pk_params_release            (gnutls_pk_params_st *p);

gnutls_pk_params_init ()

void                gnutls_pk_params_init               (gnutls_pk_params_st *p);

enum gnutls_direction_t

typedef enum
{
  GNUTLS_IMPORT,
  GNUTLS_EXPORT
} gnutls_direction_t;

gnutls_crypto_pk_st

typedef struct {
  /* The params structure should contain the private or public key
   * parameters, depending on the operation */
  int (*encrypt)( gnutls_pk_algorithm_t, gnutls_datum_t* ciphertext,
    const gnutls_datum_t* plaintext, const gnutls_pk_params_st* /* public */);
  int (*decrypt)( gnutls_pk_algorithm_t, gnutls_datum_t* plaintext,
		  const gnutls_datum_t* ciphertext,
		  const gnutls_pk_params_st* /* private */);

  int (*sign)( gnutls_pk_algorithm_t, gnutls_datum_t* signature,
	       const gnutls_datum_t* data,
	       const gnutls_pk_params_st* /* private */);
  int (*verify)( gnutls_pk_algorithm_t, const gnutls_datum_t* data,
		 const gnutls_datum_t* signature,
		 const gnutls_pk_params_st* /* public */);

  int (*generate)( gnutls_pk_algorithm_t, unsigned int level /*bits*/,
		   gnutls_pk_params_st*);
  /* this function should convert params to ones suitable
   * for the above functions
   */
  int (*pk_fixup_private_params)( gnutls_pk_algorithm_t, gnutls_direction_t,
				  gnutls_pk_params_st*);
} gnutls_crypto_pk_st;

gnutls_crypto_single_cipher_register()

#define             gnutls_crypto_single_cipher_register(algo, prio, st)

gnutls_crypto_single_mac_register()

#define             gnutls_crypto_single_mac_register(algo, prio, st)

gnutls_crypto_single_digest_register()

#define             gnutls_crypto_single_digest_register(algo, prio, st)

gnutls_crypto_single_cipher_register2 ()

int                 gnutls_crypto_single_cipher_register2
                                                        (gnutls_cipher_algorithm_t algorithm,
                                                         int priority,
                                                         int version,
                                                         gnutls_crypto_single_cipher_st *s);

This function will register a cipher algorithm to be used by gnutls. Any algorithm registered will override the included algorithms and by convention kernel implemented algorithms have priority of 90. The algorithm with the lowest priority will be used by gnutls.

This function should be called before gnutls_global_init().

For simplicity you can use the convenience gnutls_crypto_single_cipher_register() macro.

algorithm :

is the gnutls algorithm identifier

priority :

is the priority of the algorithm

version :

should be set to GNUTLS_CRYPTO_API_VERSION

s :

is a structure holding new cipher's data

Returns :

GNUTLS_E_SUCCESS on success, otherwise an error.

Since 2.6.0


gnutls_crypto_single_mac_register2 ()

int                 gnutls_crypto_single_mac_register2  (gnutls_mac_algorithm_t algorithm,
                                                         int priority,
                                                         int version,
                                                         gnutls_crypto_single_mac_st *s);

This function will register a MAC algorithm to be used by gnutls. Any algorithm registered will override the included algorithms and by convention kernel implemented algorithms have priority of 90. The algorithm with the lowest priority will be used by gnutls.

This function should be called before gnutls_global_init().

For simplicity you can use the convenience gnutls_crypto_single_mac_register() macro.

algorithm :

is the gnutls algorithm identifier

priority :

is the priority of the algorithm

version :

should be set to GNUTLS_CRYPTO_API_VERSION

s :

is a structure holding new algorithms's data

Returns :

GNUTLS_E_SUCCESS on success, otherwise an error.

Since 2.6.0


gnutls_crypto_single_digest_register2 ()

int                 gnutls_crypto_single_digest_register2
                                                        (gnutls_digest_algorithm_t algorithm,
                                                         int priority,
                                                         int version,
                                                         gnutls_crypto_single_digest_st *s);

This function will register a digest (hash) algorithm to be used by gnutls. Any algorithm registered will override the included algorithms and by convention kernel implemented algorithms have priority of 90. The algorithm with the lowest priority will be used by gnutls.

This function should be called before gnutls_global_init().

For simplicity you can use the convenience gnutls_crypto_single_digest_register() macro.

algorithm :

is the gnutls algorithm identifier

priority :

is the priority of the algorithm

version :

should be set to GNUTLS_CRYPTO_API_VERSION

s :

is a structure holding new algorithms's data

Returns :

GNUTLS_E_SUCCESS on success, otherwise an error.

Since 2.6.0


gnutls_crypto_cipher_register()

#define             gnutls_crypto_cipher_register(prio, st)

gnutls_crypto_mac_register()

#define             gnutls_crypto_mac_register(prio, st)

gnutls_crypto_digest_register()

#define             gnutls_crypto_digest_register(prio, st)

gnutls_crypto_cipher_register2 ()

int                 gnutls_crypto_cipher_register2      (int priority,
                                                         int version,
                                                         gnutls_crypto_cipher_st *s);

This function will register a cipher interface to be used by gnutls. Any interface registered will override the included engine and by convention kernel implemented interfaces should have priority of 90. The interface with the lowest priority will be used by gnutls.

This function should be called before gnutls_global_init().

For simplicity you can use the convenience gnutls_crypto_cipher_register() macro.

priority :

is the priority of the cipher interface

version :

should be set to GNUTLS_CRYPTO_API_VERSION

s :

is a structure holding new interface's data

Returns :

GNUTLS_E_SUCCESS on success, otherwise an error.

Since 2.6.0


gnutls_crypto_mac_register2 ()

int                 gnutls_crypto_mac_register2         (int priority,
                                                         int version,
                                                         gnutls_crypto_mac_st *s);

This function will register a mac interface to be used by gnutls. Any interface registered will override the included engine and by convention kernel implemented interfaces should have priority of 90. The interface with the lowest priority will be used by gnutls.

This function should be called before gnutls_global_init().

For simplicity you can use the convenience gnutls_crypto_mac_register() macro.

priority :

is the priority of the mac interface

version :

should be set to GNUTLS_CRYPTO_API_VERSION

s :

is a structure holding new interface's data

Returns :

GNUTLS_E_SUCCESS on success, otherwise an error.

Since 2.6.0


gnutls_crypto_digest_register2 ()

int                 gnutls_crypto_digest_register2      (int priority,
                                                         int version,
                                                         gnutls_crypto_digest_st *s);

This function will register a digest interface to be used by gnutls. Any interface registered will override the included engine and by convention kernel implemented interfaces should have priority of 90. The interface with the lowest priority will be used by gnutls.

This function should be called before gnutls_global_init().

For simplicity you can use the convenience gnutls_crypto_digest_register() macro.

priority :

is the priority of the digest interface

version :

should be set to GNUTLS_CRYPTO_API_VERSION

s :

is a structure holding new interface's data

Returns :

GNUTLS_E_SUCCESS on success, otherwise an error.

Since 2.6.0


gnutls_crypto_rnd_register()

#define             gnutls_crypto_rnd_register(prio, st)

gnutls_crypto_pk_register()

#define             gnutls_crypto_pk_register(prio, st)

gnutls_crypto_bigint_register()

#define             gnutls_crypto_bigint_register(prio, st)

gnutls_crypto_rnd_register2 ()

int                 gnutls_crypto_rnd_register2         (int priority,
                                                         int version,
                                                         gnutls_crypto_rnd_st *s);

This function will register a random generator to be used by gnutls. Any generator registered will override the included generator and by convention kernel implemented generators have priority of 90. The generator with the lowest priority will be used by gnutls.

This function should be called before gnutls_global_init().

For simplicity you can use the convenience gnutls_crypto_rnd_register() macro.

priority :

is the priority of the generator

version :

should be set to GNUTLS_CRYPTO_API_VERSION

s :

is a structure holding new generator's data

Returns :

GNUTLS_E_SUCCESS on success, otherwise an error.

Since 2.6.0


gnutls_crypto_pk_register2 ()

int                 gnutls_crypto_pk_register2          (int priority,
                                                         int version,
                                                         gnutls_crypto_pk_st *s);

This function will register an interface for gnutls to operate on public key operations. Any interface registered will override the included interface. The interface with the lowest priority will be used by gnutls.

Note that the bigint interface must interoperate with the bigint interface. Thus if this interface is updated the gnutls_crypto_bigint_register() should also be used.

This function should be called before gnutls_global_init().

For simplicity you can use the convenience gnutls_crypto_pk_register() macro.

priority :

is the priority of the interface

version :

should be set to GNUTLS_CRYPTO_API_VERSION

s :

is a structure holding new interface's data

Returns :

GNUTLS_E_SUCCESS on success, otherwise an error.

Since 2.6.0


gnutls_crypto_bigint_register2 ()

int                 gnutls_crypto_bigint_register2      (int priority,
                                                         int version,
                                                         gnutls_crypto_bigint_st *s);

This function will register an interface for gnutls to operate on big integers. Any interface registered will override the included interface. The interface with the lowest priority will be used by gnutls.

Note that the bigint interface must interoperate with the public key interface. Thus if this interface is updated the gnutls_crypto_pk_register() should also be used.

This function should be called before gnutls_global_init().

For simplicity you can use the convenience gnutls_crypto_bigint_register() macro.

priority :

is the priority of the interface

version :

should be set to GNUTLS_CRYPTO_API_VERSION

s :

is a structure holding new interface's data

Returns :

GNUTLS_E_SUCCESS on success, otherwise an error.

Since 2.6.0