OpenDNSSEC-libhsm  2.1.9
Data Structures | Macros | Typedefs | Functions
libhsm.h File Reference
#include <stdint.h>
#include <ldns/rbtree.h>
#include <pthread.h>

Go to the source code of this file.

Data Structures

struct  hsm_config_t
 
struct  hsm_module_t
 
struct  hsm_session_t
 
struct  libhsm_key_t
 
struct  libhsm_key_info_t
 
struct  hsm_repository_struct
 
struct  hsm_ctx_t
 

Macros

#define HSM_MAX_SESSIONS   100
 
#define HSM_MAX_SESSIONS   100
 
#define HSM_MAX_ALGONAME   16
 
#define HSM_ERROR_MSGSIZE   512
 
#define HSM_MAX_SIGNATURE_LENGTH   512
 
#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
 

Typedefs

typedef struct hsm_repository_struct hsm_repository_t
 

Functions

void hsm_ctx_set_error (hsm_ctx_t *ctx, int error, const char *action, const char *message,...)
 
int hsm_open2 (hsm_repository_t *rlist, char *(pin_callback)(unsigned int, const char *, unsigned int))
 
hsm_repository_thsm_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)
 
char * hsm_prompt_pin (unsigned int id, const char *repository, unsigned int mode)
 
char * hsm_check_pin (unsigned int id, const char *repository, unsigned int mode)
 
int hsm_logout_pin (void)
 
void hsm_close (void)
 
hsm_ctx_thsm_create_context (void)
 
int hsm_check_context ()
 
void hsm_destroy_context (hsm_ctx_t *context)
 
void libhsm_key_free (libhsm_key_t *key)
 
libhsm_key_t ** hsm_list_keys (hsm_ctx_t *context, size_t *count)
 
libhsm_key_t ** hsm_list_keys_repository (hsm_ctx_t *context, size_t *count, const char *repository)
 
libhsm_key_thsm_find_key_by_id (hsm_ctx_t *context, const char *id)
 
libhsm_key_thsm_generate_rsa_key (hsm_ctx_t *context, const char *repository, unsigned long keysize)
 
libhsm_key_thsm_generate_dsa_key (hsm_ctx_t *context, const char *repository, unsigned long keysize)
 
libhsm_key_thsm_generate_gost_key (hsm_ctx_t *context, const char *repository)
 
libhsm_key_thsm_generate_ecdsa_key (hsm_ctx_t *context, const char *repository, const char *curve)
 
libhsm_key_thsm_generate_eddsa_key (hsm_ctx_t *context, const char *repository, const char *curve)
 
int hsm_remove_key (hsm_ctx_t *context, libhsm_key_t *key)
 
void libhsm_key_list_free (libhsm_key_t **key_list, size_t count)
 
char * hsm_get_key_id (hsm_ctx_t *context, const libhsm_key_t *key)
 
libhsm_key_info_thsm_get_key_info (hsm_ctx_t *context, const libhsm_key_t *key)
 
void libhsm_key_info_free (libhsm_key_info_t *key_info)
 
int hsm_random_buffer (hsm_ctx_t *ctx, unsigned char *buffer, unsigned long length)
 
uint32_t hsm_random32 (hsm_ctx_t *ctx)
 
uint64_t hsm_random64 (hsm_ctx_t *ctx)
 
int hsm_attach (const char *repository, const char *token_name, const char *path, const char *pin, const hsm_config_t *config)
 
int hsm_token_attached (hsm_ctx_t *ctx, const char *repository)
 
char * hsm_get_error (hsm_ctx_t *gctx)
 
void hsm_print_session (hsm_session_t *session)
 
void hsm_print_ctx (hsm_ctx_t *ctx)
 
void hsm_print_key (hsm_ctx_t *ctx, libhsm_key_t *key)
 
void hsm_print_error (hsm_ctx_t *ctx)
 
void hsm_print_tokeninfo (hsm_ctx_t *ctx)
 
void keycache_create (hsm_ctx_t *ctx)
 
void keycache_destroy (hsm_ctx_t *ctx)
 
const libhsm_key_tkeycache_lookup (hsm_ctx_t *ctx, const char *locator)
 

Macro Definition Documentation

◆ HSM_CONFIG_FILE_ERROR

#define HSM_CONFIG_FILE_ERROR   0x10000003

Definition at line 68 of file libhsm.h.

◆ HSM_ERROR

#define HSM_ERROR   0x10000001

Definition at line 66 of file libhsm.h.

◆ HSM_ERROR_MSGSIZE

#define HSM_ERROR_MSGSIZE   512

Definition at line 49 of file libhsm.h.

◆ HSM_MAX_ALGONAME

#define HSM_MAX_ALGONAME   16

Definition at line 47 of file libhsm.h.

◆ HSM_MAX_PIN_LENGTH

#define HSM_MAX_PIN_LENGTH   255

Definition at line 59 of file libhsm.h.

◆ HSM_MAX_SESSIONS [1/2]

#define HSM_MAX_SESSIONS   100

Definition at line 45 of file libhsm.h.

◆ HSM_MAX_SESSIONS [2/2]

#define HSM_MAX_SESSIONS   100

Definition at line 45 of file libhsm.h.

◆ HSM_MAX_SIGNATURE_LENGTH

#define HSM_MAX_SIGNATURE_LENGTH   512

Definition at line 53 of file libhsm.h.

◆ HSM_MODULE_NOT_FOUND

#define HSM_MODULE_NOT_FOUND   0x10000006

Definition at line 71 of file libhsm.h.

◆ HSM_NO_REPOSITORIES

#define HSM_NO_REPOSITORIES   0x10000005

Definition at line 70 of file libhsm.h.

◆ HSM_OK

#define HSM_OK   0

Return codes for some of the functions

These should be different than the list of CKR_ values defined by pkcs11 (for easier debugging purposes of calling applications)

Definition at line 65 of file libhsm.h.

◆ HSM_PIN_FIRST

#define HSM_PIN_FIRST   0 /* Used when getting the PIN for the first time. */

The mode for the PIN callback functions

Definition at line 74 of file libhsm.h.

◆ HSM_PIN_INCORRECT

#define HSM_PIN_INCORRECT   0x10000002

Definition at line 67 of file libhsm.h.

◆ HSM_PIN_RETRY

#define HSM_PIN_RETRY   1 /* Used when we failed to login the first time. */

Definition at line 75 of file libhsm.h.

◆ HSM_PIN_SAVE

#define HSM_PIN_SAVE
Value:
2 /* The latest PIN can be saved for future use. Called
after a successful login. */

Definition at line 76 of file libhsm.h.

◆ HSM_REPOSITORY_NOT_FOUND

#define HSM_REPOSITORY_NOT_FOUND   0x10000004

Definition at line 69 of file libhsm.h.

Typedef Documentation

◆ hsm_repository_t

HSM Repositories

Definition at line 1 of file libhsm.h.

Function Documentation

◆ hsm_attach()

int hsm_attach ( const char *  repository,
const char *  token_name,
const char *  path,
const char *  pin,
const hsm_config_t config 
)

Attached a named HSM using a PKCS#11 shared library and optional credentials (may be NULL, but then undefined) This function changes the global state, and is not threadsafe

Parameters
repositorythe name of the repository
token_labelthe name of the token to attach
paththe path of the shared PKCS#11 library
pinthe PIN to log into the token
configoptional configuration
Returns
0 on success, -1 on error

Definition at line 3472 of file libhsm.c.

◆ hsm_check_context()

int hsm_check_context ( )

Check HSM context

Check if the associated sessions are still alive. If they are not alive, then try re-open libhsm.

Parameters
contextHSM context
Returns
0 if successful, !0 if failed

Definition at line 2475 of file libhsm.c.

References _hsm_ctx, _hsm_ctx_mutex, ctx, hsm_session_t::module, hsm_session_t::session, hsm_ctx_t::session, hsm_ctx_t::session_count, and hsm_module_t::sym.

◆ hsm_check_pin()

char* hsm_check_pin ( unsigned int  id,
const char *  repository,
unsigned int  mode 
)

Function that will check if there is a PIN in the shared memory and returns it.

Parameters
idUsed for identifying the repository. Will have a value between zero and HSM_MAX_SESSIONS.
repositoryThe repository name will be included in the prompt
modeThe type of mode the function should run in.
Returns
The string the user enters

Definition at line 325 of file pin.c.

References HSM_MAX_PIN_LENGTH, HSM_MAX_SESSIONS, HSM_PIN_FIRST, HSM_PIN_RETRY, and HSM_PIN_SAVE.

◆ hsm_close()

void hsm_close ( void  )

Close HSM library

Log out and detach from all configured HSMs This cleans up all data for libhsm, and should be the last function called.

Definition at line 2455 of file libhsm.c.

References _hsm_ctx, _hsm_ctx_mutex, and keycache_destroy().

◆ hsm_create_context()

hsm_ctx_t* hsm_create_context ( void  )

Create new HSM context

Creates a new session for each attached HSM. The returned hsm_ctx_t * can be freed with hsm_destroy_context()

Definition at line 2465 of file libhsm.c.

References _hsm_ctx_mutex.

Referenced by hsm_keytag().

◆ hsm_ctx_set_error()

void hsm_ctx_set_error ( hsm_ctx_t ctx,
int  error,
const char *  action,
const char *  message,
  ... 
)

Set HSM Context Error

If the ctx is given, and it's error value is still 0, the value will be set to 'error', and the error_message and error_action will be set to the given strings.

Parameters
ctxHSM context
errorerror code
actionaction for which the error occured
messageerror message format string

Definition at line 207 of file libhsm.c.

◆ hsm_destroy_context()

void hsm_destroy_context ( hsm_ctx_t context)

Destroy HSM context

Parameters
contextHSM context

Also destroys any associated sessions.

Definition at line 2530 of file libhsm.c.

Referenced by hsm_keytag().

◆ hsm_find_key_by_id()

libhsm_key_t* hsm_find_key_by_id ( hsm_ctx_t context,
const char *  id 
)

Find a key pair by CKA_ID (as hex string)

The returned key structure can be freed with libhsm_key_free()

Parameters
contextHSM context
idCKA_ID of key to find (null-terminated string of hex characters)
Returns
key identifier or NULL if not found (or invalid input)

Definition at line 2615 of file libhsm.c.

Referenced by hsm_keytag(), and keycache_lookup().

◆ hsm_generate_dsa_key()

libhsm_key_t* hsm_generate_dsa_key ( hsm_ctx_t context,
const char *  repository,
unsigned long  keysize 
)

Generate new key pair in HSM

Keys generated by libhsm will have a 16-byte identifier set as CKA_ID and the hexadecimal representation of it set as CKA_LABEL.

The returned key structure can be freed with libhsm_key_free()

Parameters
contextHSM context
repositoryrepository in where to create the key
keysizeSize of DSA key
Returns
return key identifier or NULL if key generation failed

Definition at line 2732 of file libhsm.c.

References CK_FALSE, and CK_TRUE.

◆ hsm_generate_ecdsa_key()

libhsm_key_t* hsm_generate_ecdsa_key ( hsm_ctx_t context,
const char *  repository,
const char *  curve 
)

Generate new key pair in HSM

Keys generated by libhsm will have a 16-byte identifier set as CKA_ID and the hexadecimal representation of it set as CKA_LABEL.

The returned key structure can be freed with libhsm_key_free()

Parameters
contextHSM context
repositoryrepository in where to create the key
curvewhich curve to use
Returns
return key identifier or NULL if key generation failed

Definition at line 2926 of file libhsm.c.

References CK_FALSE, and CK_TRUE.

◆ hsm_generate_eddsa_key()

libhsm_key_t* hsm_generate_eddsa_key ( hsm_ctx_t context,
const char *  repository,
const char *  curve 
)

Generate new key pair in HSM

Keys generated by libhsm will have a 16-byte identifier set as CKA_ID and the hexadecimal representation of it set as CKA_LABEL.

The returned key structure can be freed with libhsm_key_free()

Parameters
contextHSM context
repositoryrepository in where to create the key
curvewhich curve to use
Returns
return key identifier or NULL if key generation failed

Definition at line 3022 of file libhsm.c.

References CK_FALSE, and CK_TRUE.

◆ hsm_generate_gost_key()

libhsm_key_t* hsm_generate_gost_key ( hsm_ctx_t context,
const char *  repository 
)

Generate new key pair in HSM

Keys generated by libhsm will have a 16-byte identifier set as CKA_ID and the hexadecimal representation of it set as CKA_LABEL.

The returned key structure can be freed with libhsm_key_free()

Parameters
contextHSM context
repositoryrepository in where to create the key
Returns
return key identifier or NULL if key generation failed

Definition at line 2846 of file libhsm.c.

References CK_FALSE, and CK_TRUE.

◆ hsm_generate_rsa_key()

libhsm_key_t* hsm_generate_rsa_key ( hsm_ctx_t context,
const char *  repository,
unsigned long  keysize 
)

Generate new key pair in HSM

Keys generated by libhsm will have a 16-byte identifier set as CKA_ID and the hexadecimal representation of it set as CKA_LABEL. Other stuff, like exponent, may be needed here as well.

The returned key structure can be freed with libhsm_key_free()

Parameters
contextHSM context
repositoryrepository in where to create the key
keysizeSize of RSA key
Returns
return key identifier or NULL if key generation failed

Definition at line 2644 of file libhsm.c.

References CK_FALSE, CK_TRUE, CKK_RSA, CKM_RSA_PKCS_KEY_PAIR_GEN, and NULL_PTR.

Referenced by hsm_test().

◆ hsm_get_error()

char* hsm_get_error ( hsm_ctx_t gctx)

Return the current error message

The returned message is allocated data, and must be free()d by the caller

Parameters
ctxHSM context
Returns
error message string

Definition at line 3512 of file libhsm.c.

References _hsm_ctx, ctx, hsm_ctx_t::error, hsm_ctx_t::error_action, hsm_ctx_t::error_message, and HSM_ERROR_MSGSIZE.

Referenced by hsm_print_error().

◆ hsm_get_key_id()

char* hsm_get_key_id ( hsm_ctx_t context,
const libhsm_key_t key 
)

Get id as null-terminated hex string using key identifier

The returned id is allocated data, and must be free()d by the caller

Parameters
contextHSM context
keyKey pair to get the ID from
Returns
id of key pair

Definition at line 3157 of file libhsm.c.

Referenced by hsm_test().

◆ hsm_get_key_info()

libhsm_key_info_t* hsm_get_key_info ( hsm_ctx_t context,
const libhsm_key_t key 
)

Get extended key information

The returned id is allocated data, and must be freed by the caller With libhsm_key_info_free()

Parameters
contextHSM context
keyKey pair to get information about
Returns
key information

Definition at line 3187 of file libhsm.c.

Referenced by hsm_print_key().

◆ hsm_list_keys()

libhsm_key_t** hsm_list_keys ( hsm_ctx_t context,
size_t *  count 
)

List all known keys in all attached HSMs

After the function has run, the value at count contains the number of keys found.

The resulting key list can be freed with libhsm_key_list_free() Alternatively, each individual key structure in the list could be freed with libhsm_key_free()

Parameters
contextHSM context
countlocation to store the number of keys found

Definition at line 2572 of file libhsm.c.

References ctx, and hsm_ctx_t::session_count.

◆ hsm_list_keys_repository()

libhsm_key_t** hsm_list_keys_repository ( hsm_ctx_t context,
size_t *  count,
const char *  repository 
)

List all known keys in a HSM

After the function has run, the value at count contains the number of keys found.

The resulting key list can be freed with libhsm_key_list_free() Alternatively, each individual key structure in the list could be freed with libhsm_key_free()

Parameters
contextHSM context
countlocation to store the number of keys found
repositoryrepository to list the keys in

Definition at line 2598 of file libhsm.c.

◆ hsm_logout_pin()

int hsm_logout_pin ( void  )

Logout

Function that will logout the user by deleting the shared memory and semaphore. Any authenticated process will still be able to interact with the HSM.

Definition at line 413 of file pin.c.

References _hsm_ctx, hsm_ctx_set_error(), HSM_ERROR, HSM_OK, SEM_KEY, SHM_KEY, and semun::val.

◆ hsm_open2()

int hsm_open2 ( hsm_repository_t rlist,
char *  pin_callback)(unsigned int, const char *, unsigned int 
)

Open HSM library

Parameters
rlistRepository list.
pin_callbackThis function will be called for tokens that have no PIN configured. The default hsm_prompt_pin() can be used. If this value is NULL, these tokens will be skipped.
Returns
0 if successful, !0 if failed

Attaches all HSMs in the repository list, querying for PINs (using the given callback function) if not known. Also creates initial sessions (not part of any context; every API function that takes a context can be passed NULL, in which case the global context will be used) and log into each HSM.

Definition at line 2388 of file libhsm.c.

References _hsm_ctx, _hsm_ctx_mutex, and HSM_OK.

◆ hsm_print_ctx()

void hsm_print_ctx ( hsm_ctx_t ctx)

Definition at line 3558 of file libhsm.c.

References ctx, hsm_print_session(), hsm_ctx_t::session, and hsm_ctx_t::session_count.

◆ hsm_print_error()

void hsm_print_error ( hsm_ctx_t ctx)

Definition at line 3595 of file libhsm.c.

References hsm_get_error().

Referenced by hsm_test().

◆ hsm_print_key()

void hsm_print_key ( hsm_ctx_t ctx,
libhsm_key_t key 
)

◆ hsm_print_session()

void hsm_print_session ( hsm_session_t session)

◆ hsm_print_tokeninfo()

void hsm_print_tokeninfo ( hsm_ctx_t ctx)

Definition at line 3610 of file libhsm.c.

References ctx, hsm_ctx_t::session, hsm_ctx_t::session_count, and slot_id.

◆ hsm_prompt_pin()

char* hsm_prompt_pin ( unsigned int  id,
const char *  repository,
unsigned int  mode 
)

Function that queries for a PIN, can be used as callback for hsm_open(). Stores the PIN in the shared memory.

Parameters
idUsed for identifying the repository. Will have a value between zero and HSM_MAX_SESSIONS.
repositoryThe repository name will be included in the prompt
modeThe type of mode the function should run in.
Returns
The string the user enters

Definition at line 228 of file pin.c.

References HSM_MAX_PIN_LENGTH, HSM_MAX_SESSIONS, HSM_PIN_FIRST, HSM_PIN_RETRY, and HSM_PIN_SAVE.

◆ hsm_random32()

uint32_t hsm_random32 ( hsm_ctx_t ctx)

Return unsigned 32-bit random number from any attached HSM

Parameters
contextHSM context
Returns
32-bit random number, or 0 if no HSM with a random generator is attached

Definition at line 3438 of file libhsm.c.

References ctx, and hsm_random_buffer().

◆ hsm_random64()

uint64_t hsm_random64 ( hsm_ctx_t ctx)

Return unsigned 64-bit random number from any attached HSM

Parameters
contextHSM context
Returns
64-bit random number, or 0 if no HSM with a random generator is attached

Definition at line 3453 of file libhsm.c.

References ctx, and hsm_random_buffer().

◆ hsm_random_buffer()

int hsm_random_buffer ( hsm_ctx_t ctx,
unsigned char *  buffer,
unsigned long  length 
)

Fill a buffer with random data from any attached HSM

Parameters
contextHSM context
bufferBuffer to fill with random data
lengthSize of random buffer
Returns
0 if successful, !0 if failed

Definition at line 3411 of file libhsm.c.

References CKR_OK, ctx, hsm_session_t::module, hsm_session_t::session, hsm_ctx_t::session, hsm_ctx_t::session_count, and hsm_module_t::sym.

Referenced by hsm_random32(), and hsm_random64().

◆ hsm_remove_key()

int hsm_remove_key ( hsm_ctx_t context,
libhsm_key_t key 
)

Remove a key pair from HSM

When a key is removed, the module pointer is set to NULL, and the public and private key handles are set to 0. The structure still needs to be freed.

Parameters
contextHSM context
keyKey pair to be removed
Returns
0 if successful, !0 if failed

Definition at line 3118 of file libhsm.c.

◆ hsm_repository_free()

void hsm_repository_free ( hsm_repository_t r)

Free configured repositories.

Parameters
rRepository list.

Definition at line 405 of file libhsm.c.

References hsm_repository_struct::module, hsm_repository_struct::name, hsm_repository_struct::next, hsm_repository_struct::pin, and hsm_repository_struct::tokenlabel.

◆ 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 
)

Create new repository as specified in conf.xml.

Parameters
nameRepository name.
modulePKCS#11 module.
tokenlabelPKCS#11 token label.
pinPKCS#11 login credentials.
use_pubkeyWhether to store the public key in the HSM.
Returns
The created repository.

Definition at line 372 of file libhsm.c.

◆ hsm_token_attached()

int hsm_token_attached ( hsm_ctx_t ctx,
const char *  repository 
)

Check whether a named token has been initialized in this context

Parameters
ctxHSM context
token_nameThe name of the token
Returns
1 if the token is attached, 0 if not found

Definition at line 3495 of file libhsm.c.

References ctx, hsm_ctx_set_error(), HSM_REPOSITORY_NOT_FOUND, hsm_session_t::module, hsm_module_t::name, hsm_ctx_t::session, and hsm_ctx_t::session_count.

Referenced by hsm_test().

◆ keycache_create()

void keycache_create ( hsm_ctx_t ctx)

Definition at line 3670 of file libhsm.c.

References ctx, and hsm_ctx_t::keycache.

◆ keycache_destroy()

void keycache_destroy ( hsm_ctx_t ctx)

Definition at line 3678 of file libhsm.c.

References ctx, and hsm_ctx_t::keycache.

Referenced by hsm_close().

◆ keycache_lookup()

const libhsm_key_t* keycache_lookup ( hsm_ctx_t ctx,
const char *  locator 
)

Definition at line 3688 of file libhsm.c.

References ctx, hsm_find_key_by_id(), hsm_ctx_t::keycache, and hsm_ctx_t::keycache_lock.

◆ libhsm_key_free()

void libhsm_key_free ( libhsm_key_t key)

Definition at line 2565 of file libhsm.c.

References libhsm_key_t::modulename.

Referenced by hsm_keytag(), and libhsm_key_list_free().

◆ libhsm_key_info_free()

void libhsm_key_info_free ( libhsm_key_info_t key_info)

Frees the libhsm_key_info_t structure

Parameters
key_infoThe structure to free

Definition at line 3238 of file libhsm.c.

References libhsm_key_info_t::algorithm_name, and libhsm_key_info_t::id.

Referenced by hsm_print_key().

◆ libhsm_key_list_free()

void libhsm_key_list_free ( libhsm_key_t **  key_list,
size_t  count 
)

Free the memory of an array of key structures, as returned by hsm_list_keys()

Parameters
key_listThe array of keys to free
countThe number of keys in the array

Definition at line 3147 of file libhsm.c.

References libhsm_key_free().