libhsm.h
Go to the documentation of this file.
/*
* Copyright (c) 2009 .SE (The Internet Infrastructure Foundation).
* Copyright (c) 2009 NLNet Labs.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
* DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
* GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
* IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
* IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef HSM_H
#define HSM_H 1
#include <stdint.h>
#include <ldns/rbtree.h>
#include <pthread.h>
#define HSM_MAX_SESSIONS 100
/*
* Note that currently the MySQL kasp schema limits the number of HSMs to
* 127; so to increase it beyond that requires some database changes similar
* to when keypairs(id) was increased, see svn r4465.
*
* Note that this constant also determines the size of the shared PIN memory.
* Increasing this size requires any existing memory to be removed and should
* be part of a migration script.
*/
#define HSM_MAX_SESSIONS 100
#define HSM_MAX_ALGONAME 16
#define HSM_ERROR_MSGSIZE 512
/* TODO: depends on type and key, or just leave it at current
* maximum? */
#define HSM_MAX_SIGNATURE_LENGTH 512
/* Note that this constant also determines the size of the shared PIN memory.
* Increasing this size requires any existing memory to be removed and should
* be part of a migration script.
*/
#define HSM_MAX_PIN_LENGTH 255
#define HSM_OK 0
#define HSM_ERROR 0x10000001
#define HSM_PIN_INCORRECT 0x10000002
#define HSM_CONFIG_FILE_ERROR 0x10000003
#define HSM_REPOSITORY_NOT_FOUND 0x10000004
#define HSM_NO_REPOSITORIES 0x10000005
#define HSM_MODULE_NOT_FOUND 0x10000006
#define HSM_PIN_FIRST 0 /* Used when getting the PIN for the first time. */
#define HSM_PIN_RETRY 1 /* Used when we failed to login the first time. */
#define HSM_PIN_SAVE 2 /* The latest PIN can be saved for future use. Called
after a successful login. */
/*! HSM configuration */
typedef struct {
unsigned int use_pubkey;
unsigned int allow_extract;
} hsm_config_t;
/*! Data type to describe an HSM */
typedef struct {
unsigned int id;
char *name;
char *token_label;
char *path;
void *handle;
void *sym;
hsm_config_t *config;
} hsm_module_t;
/*! HSM Session */
typedef struct {
hsm_module_t *module;
unsigned long session;
} hsm_session_t;
/*! HSM Key Pair */
typedef struct {
char *modulename;
unsigned long private_key;
unsigned long public_key;
} libhsm_key_t;
/*! HSM Key Pair Information */
typedef struct {
char *id;
unsigned long algorithm;
char *algorithm_name;
unsigned long keysize;
} libhsm_key_info_t;
typedef struct hsm_repository_struct hsm_repository_t;
struct hsm_repository_struct {
hsm_repository_t* next;
char *name;
char *module;
char *tokenlabel;
char *pin;
uint8_t require_backup;
uint8_t use_pubkey;
unsigned int allow_extract;
};
/*! HSM context to keep track of sessions */
typedef struct {
hsm_session_t *session[HSM_MAX_SESSIONS];
size_t session_count;
int error;
const char *error_action;
char error_message[HSM_ERROR_MSGSIZE];
ldns_rbtree_t* keycache;
pthread_mutex_t *keycache_lock;
} hsm_ctx_t;
extern void
hsm_ctx_set_error(hsm_ctx_t *ctx, int error, const char *action,
const char *message, ...)
#ifdef HAVE___ATTRIBUTE__
__attribute__ ((format (printf, 4, 5)))
#endif
;
extern int
hsm_open2(hsm_repository_t* rlist,
char *(pin_callback)(unsigned int, const char *, unsigned int));
hsm_repository_t *
hsm_repository_new(char* name, char* module, char* tokenlabel, char* pin,
uint8_t use_pubkey, uint8_t allowextract, uint8_t require_backup);
void
hsm_repository_free(hsm_repository_t* r);
extern char *
hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode);
extern char *
hsm_check_pin(unsigned int id, const char *repository, unsigned int mode);
extern int
hsm_logout_pin(void);
extern void
hsm_close(void);
extern hsm_ctx_t *
hsm_create_context(void);
extern int
hsm_check_context();
extern void
hsm_destroy_context(hsm_ctx_t *context);
extern void
libhsm_key_free(libhsm_key_t *key);
extern libhsm_key_t **
hsm_list_keys(hsm_ctx_t *context, size_t *count);
extern libhsm_key_t **
hsm_list_keys_repository(hsm_ctx_t *context,
size_t *count,
const char *repository);
extern libhsm_key_t *
hsm_find_key_by_id(hsm_ctx_t *context,
const char *id);
extern libhsm_key_t *
hsm_generate_rsa_key(hsm_ctx_t *context,
const char *repository,
unsigned long keysize);
extern libhsm_key_t *
hsm_generate_dsa_key(hsm_ctx_t *context,
const char *repository,
unsigned long keysize);
extern libhsm_key_t *
hsm_generate_gost_key(hsm_ctx_t *context,
const char *repository);
extern libhsm_key_t *
hsm_generate_ecdsa_key(hsm_ctx_t *context,
const char *repository,
const char *curve);
libhsm_key_t *
hsm_generate_eddsa_key(hsm_ctx_t *context,
const char *repository,
const char *curve);
extern int
hsm_remove_key(hsm_ctx_t *context, libhsm_key_t *key);
extern void
libhsm_key_list_free(libhsm_key_t **key_list, size_t count);
extern char *
hsm_get_key_id(hsm_ctx_t *context,
const libhsm_key_t *key);
extern libhsm_key_info_t *
hsm_get_key_info(hsm_ctx_t *context,
const libhsm_key_t *key);
extern void
libhsm_key_info_free(libhsm_key_info_t *key_info);
extern int
hsm_random_buffer(hsm_ctx_t *ctx,
unsigned char *buffer,
unsigned long length);
extern uint32_t
hsm_random32(hsm_ctx_t *ctx);
extern uint64_t
hsm_random64(hsm_ctx_t *ctx);
/*
* Additional functions for debugging, and non-general use-cases.
*/
extern int
hsm_attach(const char *repository,
const char *token_name,
const char *path,
const char *pin,
const hsm_config_t *config);
extern int
hsm_token_attached(hsm_ctx_t *ctx,
const char *repository);
extern char *
hsm_get_error(hsm_ctx_t *gctx);
/* a few debug functions for applications */
extern void hsm_print_session(hsm_session_t *session);
extern void hsm_print_ctx(hsm_ctx_t *ctx);
extern void hsm_print_key(hsm_ctx_t *ctx, libhsm_key_t *key);
extern void hsm_print_error(hsm_ctx_t *ctx);
extern void hsm_print_tokeninfo(hsm_ctx_t *ctx);
/* implementation of a key cache per context, needs changing see
* OPENDNSSEC-799.
*/
extern void keycache_create(hsm_ctx_t* ctx);
extern void keycache_destroy(hsm_ctx_t* ctx);
extern const libhsm_key_t* keycache_lookup(hsm_ctx_t* ctx, const char* locator);
#endif /* HSM_H */
ctx
hsm_ctx_t * ctx
Definition hsmutil.c:46
hsm_repository_new
hsm_repository_t * hsm_repository_new(char *name, char *module, char *tokenlabel, char *pin, uint8_t use_pubkey, uint8_t allowextract, uint8_t require_backup)
Definition libhsm.c:374
hsm_prompt_pin
char * hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode)
Definition pin.c:228
hsm_list_keys_repository
libhsm_key_t ** hsm_list_keys_repository(hsm_ctx_t *context, size_t *count, const char *repository)
Definition libhsm.c:2503
libhsm_key_list_free
void libhsm_key_list_free(libhsm_key_t **key_list, size_t count)
Definition libhsm.c:3052
hsm_generate_ecdsa_key
libhsm_key_t * hsm_generate_ecdsa_key(hsm_ctx_t *context, const char *repository, const char *curve)
Definition libhsm.c:2831
hsm_attach
int hsm_attach(const char *repository, const char *token_name, const char *path, const char *pin, const hsm_config_t *config)
Definition libhsm.c:3373
hsm_ctx_set_error
void hsm_ctx_set_error(hsm_ctx_t *ctx, int error, const char *action, const char *message,...)
Definition libhsm.c:209
hsm_create_context
hsm_ctx_t * hsm_create_context(void)
Definition libhsm.c:2373
keycache_lookup
const libhsm_key_t * keycache_lookup(hsm_ctx_t *ctx, const char *locator)
Definition libhsm.c:3585
hsm_random64
uint64_t hsm_random64(hsm_ctx_t *ctx)
Definition libhsm.c:3354
hsm_get_error
char * hsm_get_error(hsm_ctx_t *gctx)
Definition libhsm.c:3413
hsm_random32
uint32_t hsm_random32(hsm_ctx_t *ctx)
Definition libhsm.c:3339
hsm_generate_rsa_key
libhsm_key_t * hsm_generate_rsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition libhsm.c:2549
hsm_repository_t
struct hsm_repository_struct hsm_repository_t
Definition libhsm.h:117
hsm_token_attached
int hsm_token_attached(hsm_ctx_t *ctx, const char *repository)
Definition libhsm.c:3396
hsm_remove_key
int hsm_remove_key(hsm_ctx_t *context, libhsm_key_t *key)
Definition libhsm.c:3023
hsm_check_pin
char * hsm_check_pin(unsigned int id, const char *repository, unsigned int mode)
Definition pin.c:325
HSM_ERROR_MSGSIZE
#define HSM_ERROR_MSGSIZE
Definition libhsm.h:49
hsm_find_key_by_id
libhsm_key_t * hsm_find_key_by_id(hsm_ctx_t *context, const char *id)
Definition libhsm.c:2520
hsm_print_key
void hsm_print_key(hsm_ctx_t *ctx, libhsm_key_t *key)
Definition libhsm.c:3466
hsm_generate_dsa_key
libhsm_key_t * hsm_generate_dsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition libhsm.c:2637
hsm_print_error
void hsm_print_error(hsm_ctx_t *ctx)
Definition libhsm.c:3492
hsm_generate_eddsa_key
libhsm_key_t * hsm_generate_eddsa_key(hsm_ctx_t *context, const char *repository, const char *curve)
Definition libhsm.c:2927
hsm_close
void hsm_close(void)
Definition libhsm.c:2363
hsm_print_ctx
void hsm_print_ctx(hsm_ctx_t *ctx)
Definition libhsm.c:3455
hsm_repository_free
void hsm_repository_free(hsm_repository_t *r)
Definition libhsm.c:407
hsm_check_context
int hsm_check_context()
Definition libhsm.c:2383
hsm_generate_gost_key
libhsm_key_t * hsm_generate_gost_key(hsm_ctx_t *context, const char *repository)
Definition libhsm.c:2751
libhsm_key_info_free
void libhsm_key_info_free(libhsm_key_info_t *key_info)
Definition libhsm.c:3139
hsm_list_keys
libhsm_key_t ** hsm_list_keys(hsm_ctx_t *context, size_t *count)
Definition libhsm.c:2477
hsm_random_buffer
int hsm_random_buffer(hsm_ctx_t *ctx, unsigned char *buffer, unsigned long length)
Definition libhsm.c:3312
hsm_open2
int hsm_open2(hsm_repository_t *rlist, char *(pin_callback)(unsigned int, const char *, unsigned int))
Definition libhsm.c:2296
hsm_print_session
void hsm_print_session(hsm_session_t *session)
Definition libhsm.c:3445
keycache_create
void keycache_create(hsm_ctx_t *ctx)
Definition libhsm.c:3567
hsm_logout_pin
int hsm_logout_pin(void)
Definition pin.c:413
hsm_print_tokeninfo
void hsm_print_tokeninfo(hsm_ctx_t *ctx)
Definition libhsm.c:3507
hsm_destroy_context
void hsm_destroy_context(hsm_ctx_t *context)
Definition libhsm.c:2438
hsm_get_key_id
char * hsm_get_key_id(hsm_ctx_t *context, const libhsm_key_t *key)
Definition libhsm.c:3062
HSM_MAX_SESSIONS
#define HSM_MAX_SESSIONS
Definition libhsm.h:35
hsm_get_key_info
libhsm_key_info_t * hsm_get_key_info(hsm_ctx_t *context, const libhsm_key_t *key)
Definition libhsm.c:3088
keycache_destroy
void keycache_destroy(hsm_ctx_t *ctx)
Definition libhsm.c:3575
libhsm_key_free
void libhsm_key_free(libhsm_key_t *key)
Definition libhsm.c:2470
hsm_config_t
Definition libhsm.h:79
hsm_config_t::allow_extract
unsigned int allow_extract
Definition libhsm.h:81
hsm_config_t::use_pubkey
unsigned int use_pubkey
Definition libhsm.h:80
hsm_ctx_t
Definition libhsm.h:130
hsm_ctx_t::error
int error
Definition libhsm.h:135
hsm_ctx_t::error_message
char error_message[HSM_ERROR_MSGSIZE]
Definition libhsm.h:142
hsm_ctx_t::error_action
const char * error_action
Definition libhsm.h:139
hsm_ctx_t::session
hsm_session_t * session[HSM_MAX_SESSIONS]
Definition libhsm.h:131
hsm_ctx_t::keycache
ldns_rbtree_t * keycache
Definition libhsm.h:144
hsm_ctx_t::session_count
size_t session_count
Definition libhsm.h:132
hsm_ctx_t::keycache_lock
pthread_mutex_t * keycache_lock
Definition libhsm.h:145
hsm_module_t
Definition libhsm.h:85
hsm_module_t::id
unsigned int id
Definition libhsm.h:86
hsm_module_t::token_label
char * token_label
Definition libhsm.h:88
hsm_module_t::name
char * name
Definition libhsm.h:87
hsm_module_t::handle
void * handle
Definition libhsm.h:90
hsm_module_t::path
char * path
Definition libhsm.h:89
hsm_module_t::sym
void * sym
Definition libhsm.h:91
hsm_module_t::config
hsm_config_t * config
Definition libhsm.h:92
hsm_repository_struct
Definition libhsm.h:118
hsm_repository_struct::module
char * module
Definition libhsm.h:121
hsm_repository_struct::next
hsm_repository_t * next
Definition libhsm.h:119
hsm_repository_struct::name
char * name
Definition libhsm.h:120
hsm_repository_struct::tokenlabel
char * tokenlabel
Definition libhsm.h:122
hsm_repository_struct::allow_extract
unsigned int allow_extract
Definition libhsm.h:126
hsm_repository_struct::require_backup
uint8_t require_backup
Definition libhsm.h:124
hsm_repository_struct::use_pubkey
uint8_t use_pubkey
Definition libhsm.h:125
hsm_repository_struct::pin
char * pin
Definition libhsm.h:123
hsm_session_t
Definition libhsm.h:96
hsm_session_t::session
unsigned long session
Definition libhsm.h:98
hsm_session_t::module
hsm_module_t * module
Definition libhsm.h:97
libhsm_key_info_t
Definition libhsm.h:109
libhsm_key_info_t::algorithm
unsigned long algorithm
Definition libhsm.h:111
libhsm_key_info_t::id
char * id
Definition libhsm.h:110
libhsm_key_info_t::algorithm_name
char * algorithm_name
Definition libhsm.h:112
libhsm_key_info_t::keysize
unsigned long keysize
Definition libhsm.h:113
libhsm_key_t
Definition libhsm.h:102
libhsm_key_t::public_key
unsigned long public_key
Definition libhsm.h:105
libhsm_key_t::private_key
unsigned long private_key
Definition libhsm.h:104
libhsm_key_t::modulename
char * modulename
Definition libhsm.h:103