libhsm.c File Reference
`#include "config.h"`
`#include <stdio.h>`
`#include <string.h>`
`#include <strings.h>`
`#include <stdlib.h>`
`#include <unistd.h>`
`#include <dlfcn.h>`
`#include <ldns/ldns.h>`
`#include <libxml/tree.h>`
`#include <libxml/parser.h>`
`#include <libxml/xpath.h>`
`#include <libxml/xpathInternals.h>`
`#include <libxml/relaxng.h>`
`#include "libhsm.h"`
`#include "libhsmdns.h"`
`#include "compat.h"`
`#include "duration.h"`
`#include <pkcs11.h>`
`#include <pthread.h>`

Go to the source code of this file.

## Macros

#define | HSM_TOKEN_LABEL_LENGTH 32

## Functions

void | hsm_ctx_set_error (hsm_ctx_t *ctx, int error, const char *action, const char *message,...)
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)
int | hsm_open2 (hsm_repository_t *rlist, char *(pin_callback)(unsigned int, const char *, unsigned int))
void | hsm_close ()
hsm_ctx_t * | hsm_create_context ()
int | hsm_check_context ()
void | hsm_destroy_context (hsm_ctx_t *ctx)
hsm_sign_params_t * | hsm_sign_params_new ()
void | hsm_sign_params_free (hsm_sign_params_t *params)
void | libhsm_key_free (libhsm_key_t *key)
libhsm_key_t ** | hsm_list_keys (hsm_ctx_t *ctx, size_t *count)
libhsm_key_t ** | hsm_list_keys_repository (hsm_ctx_t *ctx, size_t *count, const char *repository)
libhsm_key_t * | hsm_find_key_by_id (hsm_ctx_t *ctx, const char *id)
libhsm_key_t * | hsm_generate_rsa_key (hsm_ctx_t *ctx, const char *repository, unsigned long keysize)
libhsm_key_t * | hsm_generate_dsa_key (hsm_ctx_t *ctx, const char *repository, unsigned long keysize)
libhsm_key_t * | hsm_generate_gost_key (hsm_ctx_t *ctx, const char *repository)
libhsm_key_t * | hsm_generate_ecdsa_key (hsm_ctx_t *ctx, const char *repository, const char *curve)
int | hsm_remove_key (hsm_ctx_t *ctx, 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 *ctx, const libhsm_key_t *key)
libhsm_key_info_t * | hsm_get_key_info (hsm_ctx_t *ctx, const libhsm_key_t *key)
void | libhsm_key_info_free (libhsm_key_info_t *key_info)
ldns_rr * | hsm_sign_rrset (hsm_ctx_t *ctx, const ldns_rr_list *rrset, const libhsm_key_t *key, const hsm_sign_params_t *sign_params)
int | hsm_keytag (const char *loc, int alg, int ksk, uint16_t *keytag)
ldns_rr * | hsm_get_dnskey (hsm_ctx_t *ctx, const libhsm_key_t *key, const hsm_sign_params_t *sign_params)
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_label, 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 *gctx)
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_t * | keycache_lookup (hsm_ctx_t *ctx, const char *locator)

## Variables

hsm_ctx_t * | _hsm_ctx
pthread_mutex_t | _hsm_ctx_mutex = PTHREAD_MUTEX_INITIALIZER

## Macro Definition Documentation

## HSM_TOKEN_LABEL_LENGTH

#define HSM_TOKEN_LABEL_LENGTH 32

Fixed length from PKCS#11 specification

Definition at line 53 of file libhsm.c.

## 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

  repository | the name of the repository
  token_label | the name of the token to attach
  path | the path of the shared PKCS#11 library
  pin | the PIN to log into the token
  config | optional configuration

Returns
  0 on success, -1 on error

Definition at line 3177 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

  context | HSM context

Returns
  0 if successful, !0 if failed

Definition at line 2279 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_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 2259 of file libhsm.c.

References _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 2269 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

  ctx | HSM context
  error | error code
  action | action for which the error occured
  message | error message format string

Definition at line 206 of file libhsm.c.

References hsm_ctx_t::error, hsm_ctx_t::error_action, and hsm_ctx_t::error_message.

Referenced by hsm_get_dnskey(), hsm_logout_pin(), and hsm_token_attached().

## hsm_destroy_context()

void hsm_destroy_context | ( | hsm_ctx_t * | context | ) |

Destroy HSM context

Parameters

  context | HSM context

Also destroys any associated sessions.

Definition at line 2334 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

  context | HSM context
  id | CKA_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 2419 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

  context | HSM context
  repository | repository in where to create the key
  keysize | Size of DSA key

Returns
  return key identifier or NULL if key generation failed

Definition at line 2536 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

  context | HSM context
  repository | repository in where to create the key
  curve | which curve to use

Returns
  return key identifier or NULL if key generation failed

Definition at line 2730 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

  context | HSM context
  repository | repository in where to create the key

Returns
  return key identifier or NULL if key generation failed

Definition at line 2650 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

  context | HSM context
  repository | repository in where to create the key
  keysize | Size of RSA key

Returns
  return key identifier or NULL if key generation failed

Definition at line 2448 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_dnskey()

ldns_rr* hsm_get_dnskey | ( | hsm_ctx_t * | ctx,
|  | const libhsm_key_t * | key,
|  | const hsm_sign_params_t * | sign_params
| ) |  |

Get DNSKEY RR

The returned ldns_rr structure can be freed with ldns_rr_free()

Parameters

  context | HSM context
  key | Key to get DNSKEY RR from
  sign_params | the signing parameters (flags, algorithm, etc)

Returns
  ldns_rr*

Definition at line 3070 of file libhsm.c.

References hsm_ctx_set_error().

Referenced by hsm_keytag().

## 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

  ctx | HSM context

Returns
  error message string

Definition at line 3217 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

  context | HSM context
  key | Key pair to get the ID from

Returns
  id of key pair

Definition at line 2865 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

  context | HSM context
  key | Key pair to get information about

Returns
  key information

Definition at line 2895 of file libhsm.c.

Referenced by hsm_print_key().

## hsm_keytag()

int hsm_keytag | ( | const char * | loc,
|  | int | alg,
|  | int | ksk,
|  | uint16_t * | keytag
| ) |  |

Calculate keytag

Parameters

  | loc | Locator of keydata on HSM
  | alg | Algorithm of key
  | ksk | 0 for zsk, positive int for ksk|csk
  [out] | keytag | the calculated keytag return: non-zero in case of failure

Definition at line 3014 of file libhsm.c.

References hsm_sign_params_t::algorithm, hsm_sign_params_t::flags, hsm_create_context(), hsm_destroy_context(), hsm_find_key_by_id(), hsm_get_dnskey(), hsm_sign_params_free(), hsm_sign_params_new(), libhsm_key_free(), and hsm_sign_params_t::owner.

## 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

  context | HSM context
  count | location to store the number of keys found

Definition at line 2376 of file libhsm.c.

References 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

  context | HSM context
  count | location to store the number of keys found
  repository | repository to list the keys in

Definition at line 2402 of file libhsm.c.

## hsm_open2()

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

Open HSM library

Parameters

  rlist | Repository list.
  pin_callback | This 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 2192 of file libhsm.c.

References _hsm_ctx_mutex, and HSM_OK.

## hsm_print_ctx()

void hsm_print_ctx | ( | hsm_ctx_t * | ctx | ) |

Definition at line 3258 of file libhsm.c.

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

## hsm_print_error()

void hsm_print_error | ( | hsm_ctx_t * | gctx | ) |

Definition at line 3295 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
| ) |  |

Definition at line 3269 of file libhsm.c.

References libhsm_key_info_t::algorithm_name, hsm_get_key_info(), libhsm_key_info_t::id, libhsm_key_info_t::keysize, libhsm_key_info_free(), libhsm_key_t::modulename, libhsm_key_t::private_key, and libhsm_key_t::public_key.

## hsm_print_session()

void hsm_print_session | ( | hsm_session_t * | session | ) |

Definition at line 3248 of file libhsm.c.

References hsm_session_t::module, hsm_module_t::name, hsm_module_t::path, hsm_session_t::session, hsm_module_t::sym, and hsm_module_t::token_label.

Referenced by hsm_print_ctx().

## hsm_print_tokeninfo()

void hsm_print_tokeninfo | ( | hsm_ctx_t * | ctx | ) |

Definition at line 3310 of file libhsm.c.

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

## hsm_random32()

uint32_t hsm_random32 | ( | hsm_ctx_t * | ctx | ) |

Return unsigned 32-bit random number from any attached HSM

Parameters

  context | HSM context

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

Definition at line 3143 of file libhsm.c.

References hsm_random_buffer().

## hsm_random64()

uint64_t hsm_random64 | ( | hsm_ctx_t * | ctx | ) |

Return unsigned 64-bit random number from any attached HSM

Parameters

  context | HSM context

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

Definition at line 3158 of file libhsm.c.

References 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

  context | HSM context
  buffer | Buffer to fill with random data
  length | Size of random buffer

Returns
  0 if successful, !0 if failed

Definition at line 3116 of file libhsm.c.

References CKR_OK, 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

  context | HSM context
  key | Key pair to be removed

Returns
  0 if successful, !0 if failed

Definition at line 2826 of file libhsm.c.

## hsm_repository_free()

void hsm_repository_free | ( | hsm_repository_t * | r | ) |

Free configured repositories.

Parameters

  r | Repository list.

Definition at line 404 of file libhsm.c.

References hsm_repository_free(), hsm_repository_struct::module, hsm_repository_struct::name, hsm_repository_struct::next, hsm_repository_struct::pin, and hsm_repository_struct::tokenlabel.

Referenced by hsm_repository_free().

## 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

  name | Repository name.
  module | PKCS#11 module.
  tokenlabel | PKCS#11 token label.
  pin | PKCS#11 login credentials.
  use_pubkey | Whether to store the public key in the HSM.

Returns
  The created repository.

Definition at line 371 of file libhsm.c.

## hsm_sign_params_free()

void hsm_sign_params_free | ( | hsm_sign_params_t * | params | ) |

Free the signer parameters structure

If params->owner has been set, ldns_rdf_deep_free() will be called on it.

Parameters

  params | The signer parameters to free

Definition at line 2360 of file libhsm.c.

References hsm_sign_params_t::owner.

Referenced by hsm_keytag().

## hsm_sign_params_new()

hsm_sign_params_t* hsm_sign_params_new | ( | void |  | ) |

Returns an allocated hsm_sign_params_t with some defaults

Definition at line 2343 of file libhsm.c.

References hsm_sign_params_t::algorithm, hsm_sign_params_t::expiration, hsm_sign_params_t::flags, hsm_sign_params_t::inception, hsm_sign_params_t::keytag, and hsm_sign_params_t::owner.

Referenced by hsm_keytag().

## hsm_sign_rrset()

ldns_rr* hsm_sign_rrset | ( | hsm_ctx_t * | ctx,
|  | const ldns_rr_list * | rrset,
|  | const libhsm_key_t * | key,
|  | const hsm_sign_params_t * | sign_params
| ) |  |

Sign RRset using key

The returned ldns_rr structure can be freed with ldns_rr_free()

Parameters

  context | HSM context
  rrset | RRset to sign
  key | Key pair used to sign

Returns
  ldns_rr* Signed RRset

Definition at line 2957 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

  ctx | HSM context
  token_name | The name of the token

Returns
  1 if the token is attached, 0 if not found

Definition at line 3200 of file libhsm.c.

References 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 3370 of file libhsm.c.

References hsm_ctx_t::keycache.

## keycache_destroy()

void keycache_destroy | ( | hsm_ctx_t * | ctx | ) |

Definition at line 3378 of file libhsm.c.

References 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 3388 of file libhsm.c.

References 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 2369 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_info | The structure to free

Definition at line 2943 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_list | The array of keys to free
  count | The number of keys in the array

Definition at line 2855 of file libhsm.c.

References libhsm_key_free().

## Variable Documentation

## _hsm_ctx

hsm_ctx_t* _hsm_ctx

Global (initial) context, with mutex to serialize access to it

Definition at line 56 of file libhsm.c.

Referenced by hsm_check_context(), and hsm_get_error().

## _hsm_ctx_mutex

pthread_mutex_t _hsm_ctx_mutex = PTHREAD_MUTEX_INITIALIZER

Definition at line 57 of file libhsm.c.

Referenced by hsm_check_context(), hsm_close(), hsm_create_context(), and hsm_open2().