OpenDNSSEC-libhsm  2.1.5
libhsm.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2009 .SE (The Internet Infrastructure Foundation).
3  * Copyright (c) 2009 NLNet Labs.
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  * 1. Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
19  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
21  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
23  * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
25  * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27 
28 #ifndef HSM_H
29 #define HSM_H 1
30 
31 #include <stdint.h>
32 #include <ldns/rbtree.h>
33 #include <pthread.h>
34 
35 #define HSM_MAX_SESSIONS 100
36 /*
37  * Note that currently the MySQL kasp schema limits the number of HSMs to
38  * 127; so to increase it beyond that requires some database changes similar
39  * to when keypairs(id) was increased, see svn r4465.
40  *
41  * Note that this constant also determines the size of the shared PIN memory.
42  * Increasing this size requires any existing memory to be removed and should
43  * be part of a migration script.
44  */
45 #define HSM_MAX_SESSIONS 100
46 
47 #define HSM_MAX_ALGONAME 16
48 
49 #define HSM_ERROR_MSGSIZE 512
50 
51 /* TODO: depends on type and key, or just leave it at current
52  * maximum? */
53 #define HSM_MAX_SIGNATURE_LENGTH 512
54 
55 /* Note that this constant also determines the size of the shared PIN memory.
56  * Increasing this size requires any existing memory to be removed and should
57  * be part of a migration script.
58  */
59 #define HSM_MAX_PIN_LENGTH 255
60 
65 #define HSM_OK 0
66 #define HSM_ERROR 0x10000001
67 #define HSM_PIN_INCORRECT 0x10000002
68 #define HSM_CONFIG_FILE_ERROR 0x10000003
69 #define HSM_REPOSITORY_NOT_FOUND 0x10000004
70 #define HSM_NO_REPOSITORIES 0x10000005
71 #define HSM_MODULE_NOT_FOUND 0x10000006
72 
74 #define HSM_PIN_FIRST 0 /* Used when getting the PIN for the first time. */
75 #define HSM_PIN_RETRY 1 /* Used when we failed to login the first time. */
76 #define HSM_PIN_SAVE 2 /* The latest PIN can be saved for future use. Called
77  after a successful login. */
78 
80 typedef struct {
81  unsigned int use_pubkey;
82  unsigned int allow_extract;
83 } hsm_config_t;
84 
86 typedef struct {
87  unsigned int id;
88  char *name;
89  char *token_label;
90  char *path;
91  void *handle;
92  void *sym;
93  hsm_config_t *config;
94 } hsm_module_t;
95 
97 typedef struct {
98  hsm_module_t *module;
99  unsigned long session;
100 } hsm_session_t;
101 
103 typedef struct {
104  char *modulename;
105  unsigned long private_key;
106  unsigned long public_key;
107 } libhsm_key_t;
108 
110 typedef struct {
111  char *id;
112  unsigned long algorithm;
113  char *algorithm_name;
114  unsigned long keysize;
116 
121  char *name;
122  char *module;
123  char *tokenlabel;
124  char *pin;
125  uint8_t require_backup;
126  uint8_t use_pubkey;
127  unsigned int allow_extract;
128 };
129 
131 typedef struct {
133  size_t session_count;
136  int error;
137 
140  const char *error_action;
141 
143  char error_message[HSM_ERROR_MSGSIZE];
144 
145  ldns_rbtree_t* keycache;
146  pthread_mutex_t *keycache_lock;
147 } hsm_ctx_t;
148 
149 
161 void
162 hsm_ctx_set_error(hsm_ctx_t *ctx, int error, const char *action,
163  const char *message, ...)
164 #ifdef HAVE___ATTRIBUTE__
165  __attribute__ ((format (printf, 4, 5)))
166 #endif
167  ;
168 
184 int
186  char *(pin_callback)(unsigned int, const char *, unsigned int));
187 
188 
199 hsm_repository_new(char* name, char* module, char* tokenlabel, char* pin,
200  uint8_t use_pubkey, uint8_t allowextract, uint8_t require_backup);
201 
206 void
208 
218 char *
219 hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode);
220 
221 
230 char *
231 hsm_check_pin(unsigned int id, const char *repository, unsigned int mode);
232 
233 
240 int
241 hsm_logout_pin(void);
242 
243 
250 void
251 hsm_close(void);
252 
253 
259 hsm_ctx_t *
260 hsm_create_context(void);
261 
262 
271 int
273 
274 
281 void
283 
284 void
286 
299 libhsm_key_t **
300 hsm_list_keys(hsm_ctx_t *context, size_t *count);
301 
302 
316 libhsm_key_t **
318  size_t *count,
319  const char *repository);
320 
321 
322 
332 libhsm_key_t *
334  const char *id);
335 
349 libhsm_key_t *
351  const char *repository,
352  unsigned long keysize);
353 
366 libhsm_key_t *
368  const char *repository,
369  unsigned long keysize);
370 
382 libhsm_key_t *
384  const char *repository);
385 
398 libhsm_key_t *
400  const char *repository,
401  const char *curve);
402 
413 int
414 hsm_remove_key(hsm_ctx_t *context, libhsm_key_t *key);
415 
416 
423 void
424 libhsm_key_list_free(libhsm_key_t **key_list, size_t count);
425 
426 
435 char *
436 hsm_get_key_id(hsm_ctx_t *context,
437  const libhsm_key_t *key);
438 
439 
450 hsm_get_key_info(hsm_ctx_t *context,
451  const libhsm_key_t *key);
452 
453 
458 void
460 
469 int
471  unsigned char *buffer,
472  unsigned long length);
473 
474 
480 uint32_t
482 
483 
489 uint64_t
491 
492 
493 
494 /*
495  * Additional functions for debugging, and non-general use-cases.
496  */
497 
509 int
510 hsm_attach(const char *repository,
511  const char *token_name,
512  const char *path,
513  const char *pin,
514  const hsm_config_t *config);
515 
521 int
523  const char *repository);
524 
533 char *
534 hsm_get_error(hsm_ctx_t *gctx);
535 
536 /* a few debug functions for applications */
537 void hsm_print_session(hsm_session_t *session);
542 
543 /* implementation of a key cache per context, needs changing see
544  * OPENDNSSEC-799.
545  */
546 extern void keycache_create(hsm_ctx_t* ctx);
547 extern void keycache_destroy(hsm_ctx_t* ctx);
548 extern const libhsm_key_t* keycache_lookup(hsm_ctx_t* ctx, const char* locator);
549 
550 #endif /* HSM_H */
keycache_lookup
const libhsm_key_t * keycache_lookup(hsm_ctx_t *ctx, const char *locator)
Definition: libhsm.c:3393
hsm_ctx_set_error
void hsm_ctx_set_error(hsm_ctx_t *ctx, int error, const char *action, const char *message,...)
Definition: libhsm.c:206
hsm_repository_struct::tokenlabel
char * tokenlabel
Definition: libhsm.h:122
hsm_repository_struct::use_pubkey
uint8_t use_pubkey
Definition: libhsm.h:125
hsm_config_t
Definition: libhsm.h:79
libhsm_key_info_free
void libhsm_key_info_free(libhsm_key_info_t *key_info)
Definition: libhsm.c:2943
hsm_repository_struct::next
hsm_repository_t * next
Definition: libhsm.h:119
libhsm_key_t
Definition: libhsm.h:102
hsm_list_keys
libhsm_key_t ** hsm_list_keys(hsm_ctx_t *context, size_t *count)
Definition: libhsm.c:2376
hsm_check_context
int hsm_check_context()
Definition: libhsm.c:2279
hsm_find_key_by_id
libhsm_key_t * hsm_find_key_by_id(hsm_ctx_t *context, const char *id)
Definition: libhsm.c:2419
hsm_random64
uint64_t hsm_random64(hsm_ctx_t *ctx)
Definition: libhsm.c:3158
hsm_print_error
void hsm_print_error(hsm_ctx_t *ctx)
Definition: libhsm.c:3300
hsm_logout_pin
int hsm_logout_pin(void)
Definition: pin.c:413
hsm_check_pin
char * hsm_check_pin(unsigned int id, const char *repository, unsigned int mode)
Definition: pin.c:325
hsm_generate_ecdsa_key
libhsm_key_t * hsm_generate_ecdsa_key(hsm_ctx_t *context, const char *repository, const char *curve)
Definition: libhsm.c:2730
hsm_repository_struct::module
char * module
Definition: libhsm.h:121
algorithm
ldns_algorithm algorithm
Definition: hsmspeed.c:43
hsm_print_tokeninfo
void hsm_print_tokeninfo(hsm_ctx_t *ctx)
Definition: libhsm.c:3315
hsm_print_ctx
void hsm_print_ctx(hsm_ctx_t *ctx)
Definition: libhsm.c:3263
hsm_prompt_pin
char * hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode)
Definition: pin.c:228
hsm_destroy_context
void hsm_destroy_context(hsm_ctx_t *context)
Definition: libhsm.c:2334
HSM_ERROR_MSGSIZE
#define HSM_ERROR_MSGSIZE
Definition: libhsm.h:49
libhsm_key_free
void libhsm_key_free(libhsm_key_t *key)
Definition: libhsm.c:2369
hsm_print_key
void hsm_print_key(hsm_ctx_t *ctx, libhsm_key_t *key)
Definition: libhsm.c:3274
session_count
#define session_count
Definition: pkcs11.h:123
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:371
hsm_generate_gost_key
libhsm_key_t * hsm_generate_gost_key(hsm_ctx_t *context, const char *repository)
Definition: libhsm.c:2650
hsm_random_buffer
int hsm_random_buffer(hsm_ctx_t *ctx, unsigned char *buffer, unsigned long length)
Definition: libhsm.c:3116
hsm_repository_struct::pin
char * pin
Definition: libhsm.h:123
keycache_create
void keycache_create(hsm_ctx_t *ctx)
Definition: libhsm.c:3375
hsm_module_t
Definition: libhsm.h:85
hsm_get_key_id
char * hsm_get_key_id(hsm_ctx_t *context, const libhsm_key_t *key)
Definition: libhsm.c:2865
ctx
hsm_ctx_t * ctx
Definition: hsmutil.c:46
keycache_destroy
void keycache_destroy(hsm_ctx_t *ctx)
Definition: libhsm.c:3383
hsm_repository_struct::allow_extract
unsigned int allow_extract
Definition: libhsm.h:126
HSM_MAX_SESSIONS
#define HSM_MAX_SESSIONS
Definition: libhsm.h:45
hsm_open2
int hsm_open2(hsm_repository_t *rlist, char *(pin_callback)(unsigned int, const char *, unsigned int))
Definition: libhsm.c:2192
hsm_generate_dsa_key
libhsm_key_t * hsm_generate_dsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition: libhsm.c:2536
hsm_get_error
char * hsm_get_error(hsm_ctx_t *gctx)
Definition: libhsm.c:3217
hsm_repository_struct::name
char * name
Definition: libhsm.h:120
hsm_get_key_info
libhsm_key_info_t * hsm_get_key_info(hsm_ctx_t *context, const libhsm_key_t *key)
Definition: libhsm.c:2895
libhsm_key_info_t
Definition: libhsm.h:109
hsm_ctx_t
Definition: libhsm.h:130
hsm_create_context
hsm_ctx_t * hsm_create_context(void)
Definition: libhsm.c:2269
hsm_token_attached
int hsm_token_attached(hsm_ctx_t *ctx, const char *repository)
Definition: libhsm.c:3200
hsm_remove_key
int hsm_remove_key(hsm_ctx_t *context, libhsm_key_t *key)
Definition: libhsm.c:2826
hsm_repository_free
void hsm_repository_free(hsm_repository_t *r)
Definition: libhsm.c:404
hsm_session_t
Definition: libhsm.h:96
hsm_close
void hsm_close(void)
Definition: libhsm.c:2259
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:3177
libhsm_key_list_free
void libhsm_key_list_free(libhsm_key_t **key_list, size_t count)
Definition: libhsm.c:2855
hsm_print_session
void hsm_print_session(hsm_session_t *session)
Definition: libhsm.c:3253
hsm_list_keys_repository
libhsm_key_t ** hsm_list_keys_repository(hsm_ctx_t *context, size_t *count, const char *repository)
Definition: libhsm.c:2402
hsm_repository_struct::require_backup
uint8_t require_backup
Definition: libhsm.h:124
hsm_generate_rsa_key
libhsm_key_t * hsm_generate_rsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition: libhsm.c:2448
hsm_repository_struct
Definition: libhsm.h:118
hsm_random32
uint32_t hsm_random32(hsm_ctx_t *ctx)
Definition: libhsm.c:3143