OpenDNSSEC-libhsm  2.0.4
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 
34 #define HSM_MAX_SESSIONS 100
35 /*
36  * Note that currently the MySQL kasp schema limits the number of HSMs to
37  * 127; so to increase it beyond that requires some database changes similar
38  * to when keypairs(id) was increased, see svn r4465.
39  *
40  * Note that this constant also determines the size of the shared PIN memory.
41  * Increasing this size requires any existing memory to be removed and should
42  * be part of a migration script.
43  */
44 #define HSM_MAX_SESSIONS 100
45 
46 #define HSM_MAX_ALGONAME 16
47 
48 #define HSM_ERROR_MSGSIZE 512
49 
50 /* TODO: depends on type and key, or just leave it at current
51  * maximum? */
52 #define HSM_MAX_SIGNATURE_LENGTH 512
53 
54 /* Note that this constant also determines the size of the shared PIN memory.
55  * Increasing this size requires any existing memory to be removed and should
56  * be part of a migration script.
57  */
58 #define HSM_MAX_PIN_LENGTH 255
59 
64 #define HSM_OK 0
65 #define HSM_ERROR 0x10000001
66 #define HSM_PIN_INCORRECT 0x10000002
67 #define HSM_CONFIG_FILE_ERROR 0x10000003
68 #define HSM_REPOSITORY_NOT_FOUND 0x10000004
69 #define HSM_NO_REPOSITORIES 0x10000005
70 #define HSM_MODULE_NOT_FOUND 0x10000006
71 
73 #define HSM_PIN_FIRST 0 /* Used when getting the PIN for the first time. */
74 #define HSM_PIN_RETRY 1 /* Used when we failed to login the first time. */
75 #define HSM_PIN_SAVE 2 /* The latest PIN can be saved for future use. Called
76  after a successful login. */
77 
79 typedef struct {
80  unsigned int use_pubkey;
81 } hsm_config_t;
82 
84 typedef struct {
85  unsigned int id;
86  char *name;
87  char *token_label;
88  char *path;
89  void *handle;
90  void *sym;
92 } hsm_module_t;
93 
95 typedef struct {
97  unsigned long session;
99 
101 typedef struct {
102  const char * modulename;
103  unsigned long private_key;
104  unsigned long public_key;
105 } libhsm_key_t;
106 
108 typedef struct {
109  char *id;
110  unsigned long algorithm;
112  unsigned long keysize;
114 
119  char *name;
120  char *module;
121  char *tokenlabel;
122  char *pin;
123  uint8_t require_backup;
124  uint8_t use_pubkey;
125 };
126 
128 typedef struct {
130  size_t session_count;
133  int error;
134 
137  const char *error_action;
138 
140  char error_message[HSM_ERROR_MSGSIZE];
141 
142  ldns_rbtree_t* keycache;
143 } hsm_ctx_t;
144 
145 
157 void
158 hsm_ctx_set_error(hsm_ctx_t *ctx, int error, const char *action,
159  const char *message, ...);
160 
176 int
178  char *(pin_callback)(unsigned int, const char *, unsigned int));
179 
180 
191 hsm_repository_new(char* name, char* module, char* tokenlabel, char* pin,
192  uint8_t use_pubkey, uint8_t require_backup);
193 
198 void
200 
210 char *
211 hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode);
212 
213 
222 char *
223 hsm_check_pin(unsigned int id, const char *repository, unsigned int mode);
224 
225 
232 int
233 hsm_logout_pin(void);
234 
235 
242 void
243 hsm_close(void);
244 
245 
251 hsm_ctx_t *
252 hsm_create_context(void);
253 
254 
263 int
265 
266 
273 void
275 
276 
289 libhsm_key_t **
290 hsm_list_keys(hsm_ctx_t *context, size_t *count);
291 
292 
306 libhsm_key_t **
308  size_t *count,
309  const char *repository);
310 
311 
312 
322 libhsm_key_t *
324  const char *id);
325 
339 libhsm_key_t *
341  const char *repository,
342  unsigned long keysize);
343 
356 libhsm_key_t *
358  const char *repository,
359  unsigned long keysize);
360 
372 libhsm_key_t *
374  const char *repository);
375 
388 libhsm_key_t *
390  const char *repository,
391  const char *curve);
392 
403 int
404 hsm_remove_key(hsm_ctx_t *context, libhsm_key_t *key);
405 
406 
413 void
414 libhsm_key_list_free(libhsm_key_t **key_list, size_t count);
415 
416 
425 char *
426 hsm_get_key_id(hsm_ctx_t *context,
427  const libhsm_key_t *key);
428 
429 
440 hsm_get_key_info(hsm_ctx_t *context,
441  const libhsm_key_t *key);
442 
443 
448 void
450 
459 int
461  unsigned char *buffer,
462  unsigned long length);
463 
464 
470 uint32_t
472 
473 
479 uint64_t
481 
482 
483 
484 /*
485  * Additional functions for debugging, and non-general use-cases.
486  */
487 
499 int
500 hsm_attach(const char *repository,
501  const char *token_name,
502  const char *path,
503  const char *pin,
504  const hsm_config_t *config);
505 
511 int
513  const char *repository);
514 
523 char *
524 hsm_get_error(hsm_ctx_t *gctx);
525 
526 /* a few debug functions for applications */
527 void hsm_print_session(hsm_session_t *session);
532 
533 /* implementation of a key cache per context, needs changing see
534  * OPENDNSSEC-799.
535  */
536 extern void keycache_create(hsm_ctx_t* ctx);
537 extern void keycache_destroy(hsm_ctx_t* ctx);
538 extern const libhsm_key_t* keycache_lookup(hsm_ctx_t* ctx, const char* locator);
539 
540 #endif /* HSM_H */
uint64_t hsm_random64(hsm_ctx_t *ctx)
Definition: libhsm.c:3129
unsigned long public_key
Definition: libhsm.h:104
char * hsm_get_error(hsm_ctx_t *gctx)
Definition: libhsm.c:3188
hsm_ctx_t * hsm_create_context(void)
Definition: libhsm.c:2256
const char * error_action
Definition: libhsm.h:137
libhsm_key_t * hsm_generate_gost_key(hsm_ctx_t *context, const char *repository)
Definition: libhsm.c:2624
void * handle
Definition: libhsm.h:89
const char * modulename
Definition: libhsm.h:102
ldns_rbtree_t * keycache
Definition: libhsm.h:142
hsm_module_t * module
Definition: libhsm.h:96
hsm_repository_t * next
Definition: libhsm.h:118
char * path
Definition: libhsm.h:88
char * name
Definition: libhsm.h:86
void libhsm_key_list_free(libhsm_key_t **key_list, size_t count)
Definition: libhsm.c:2825
uint8_t require_backup
Definition: libhsm.h:123
libhsm_key_info_t * hsm_get_key_info(hsm_ctx_t *context, const libhsm_key_t *key)
Definition: libhsm.c:2866
int hsm_logout_pin(void)
Definition: pin.c:413
void * sym
Definition: libhsm.h:90
char * hsm_get_key_id(hsm_ctx_t *context, const libhsm_key_t *key)
Definition: libhsm.c:2836
void hsm_close(void)
Definition: libhsm.c:2247
unsigned long algorithm
Definition: libhsm.h:110
hsm_repository_t * hsm_repository_new(char *name, char *module, char *tokenlabel, char *pin, uint8_t use_pubkey, uint8_t require_backup)
Definition: libhsm.c:368
void hsm_print_key(hsm_ctx_t *ctx, libhsm_key_t *key)
Definition: libhsm.c:3240
void hsm_print_tokeninfo(hsm_ctx_t *ctx)
Definition: libhsm.c:3281
const libhsm_key_t * keycache_lookup(hsm_ctx_t *ctx, const char *locator)
Definition: libhsm.c:3353
unsigned long keysize
Definition: libhsm.h:112
libhsm_key_t * hsm_generate_rsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition: libhsm.c:2428
void hsm_ctx_set_error(hsm_ctx_t *ctx, int error, const char *action, const char *message,...)
Definition: libhsm.c:203
int hsm_random_buffer(hsm_ctx_t *ctx, unsigned char *buffer, unsigned long length)
Definition: libhsm.c:3087
void keycache_create(hsm_ctx_t *ctx)
Definition: libhsm.c:3340
void keycache_destroy(hsm_ctx_t *ctx)
Definition: libhsm.c:3346
void hsm_destroy_context(hsm_ctx_t *context)
Definition: libhsm.c:2321
#define HSM_ERROR_MSGSIZE
Definition: libhsm.h:48
unsigned int use_pubkey
Definition: libhsm.h:80
void hsm_repository_free(hsm_repository_t *r)
Definition: libhsm.c:400
size_t session_count
Definition: libhsm.h:130
unsigned long session
Definition: libhsm.h:97
unsigned int id
Definition: libhsm.h:85
int hsm_attach(const char *repository, const char *token_name, const char *path, const char *pin, const hsm_config_t *config)
Definition: libhsm.c:3148
hsm_config_t * config
Definition: libhsm.h:91
int hsm_check_context()
Definition: libhsm.c:2266
#define HSM_MAX_SESSIONS
Definition: libhsm.h:44
uint32_t hsm_random32(hsm_ctx_t *ctx)
Definition: libhsm.c:3114
libhsm_key_t ** hsm_list_keys_repository(hsm_ctx_t *context, size_t *count, const char *repository)
Definition: libhsm.c:2382
hsm_ctx_t * ctx
Definition: hsmutil.c:46
libhsm_key_t ** hsm_list_keys(hsm_ctx_t *context, size_t *count)
Definition: libhsm.c:2356
libhsm_key_t * hsm_generate_ecdsa_key(hsm_ctx_t *context, const char *repository, const char *curve)
Definition: libhsm.c:2702
void hsm_print_ctx(hsm_ctx_t *ctx)
Definition: libhsm.c:3229
uint8_t use_pubkey
Definition: libhsm.h:124
int error
Definition: libhsm.h:133
void hsm_print_error(hsm_ctx_t *ctx)
Definition: libhsm.c:3266
int hsm_open2(hsm_repository_t *rlist, char *(pin_callback)(unsigned int, const char *, unsigned int))
Definition: libhsm.c:2184
int hsm_token_attached(hsm_ctx_t *ctx, const char *repository)
Definition: libhsm.c:3171
int hsm_remove_key(hsm_ctx_t *context, libhsm_key_t *key)
Definition: libhsm.c:2796
libhsm_key_t * hsm_generate_dsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition: libhsm.c:2514
void hsm_print_session(hsm_session_t *session)
Definition: libhsm.c:3219
unsigned long private_key
Definition: libhsm.h:103
char * hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode)
Definition: pin.c:228
char * token_label
Definition: libhsm.h:87
libhsm_key_t * hsm_find_key_by_id(hsm_ctx_t *context, const char *id)
Definition: libhsm.c:2399
char * algorithm_name
Definition: libhsm.h:111
void libhsm_key_info_free(libhsm_key_info_t *key_info)
Definition: libhsm.c:2914
char * hsm_check_pin(unsigned int id, const char *repository, unsigned int mode)
Definition: pin.c:325