OpenDNSSEC-libhsm  1.4.10
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 /* Note that currently the MySQL kasp schema limits the number of HSMs to
35  * 127; so to increase it beyond that requires some database changes similar
36  * to when keypairs(id) was increased, see svn r4465.
37  *
38  * Note that this constant also determines the size of the shared PIN memory.
39  * Increasing this size requires any existing memory to be removed and should
40  * be part of a migration script.
41  */
42 #define HSM_MAX_SESSIONS 100
43 
44 #define HSM_MAX_ALGONAME 16
45 
46 #define HSM_ERROR_MSGSIZE 512
47 
48 /* TODO: depends on type and key, or just leave it at current
49  * maximum? */
50 #define HSM_MAX_SIGNATURE_LENGTH 512
51 
52 /* Note that this constant also determines the size of the shared PIN memory.
53  * Increasing this size requires any existing memory to be removed and should
54  * be part of a migration script.
55  */
56 #define HSM_MAX_PIN_LENGTH 255
57 
62 #define HSM_OK 0
63 #define HSM_ERROR 0x10000001
64 #define HSM_PIN_INCORRECT 0x10000002
65 #define HSM_CONFIG_FILE_ERROR 0x10000003
66 #define HSM_REPOSITORY_NOT_FOUND 0x10000004
67 #define HSM_NO_REPOSITORIES 0x10000005
68 #define HSM_MODULE_NOT_FOUND 0x10000006
69 
71 #define HSM_PIN_FIRST 0 /* Used when getting the PIN for the first time. */
72 #define HSM_PIN_RETRY 1 /* Used when we failed to login the first time. */
73 #define HSM_PIN_SAVE 2 /* The latest PIN can be saved for future use. Called
74  after a successful login. */
75 
77 typedef struct {
78  unsigned int use_pubkey;
79  unsigned int allow_extract;
80 } hsm_config_t;
81 
83 typedef struct {
84  unsigned int id;
85  char *name;
86  char *token_label;
87  char *path;
88  void *handle;
89  void *sym;
91 } hsm_module_t;
92 
94 typedef struct {
96  unsigned long session;
98 
100 typedef struct {
101  const char * modulename;
102  unsigned long private_key;
103  unsigned long public_key;
104 } hsm_key_t;
105 
107 typedef struct {
108  char *id;
109  unsigned long algorithm;
111  unsigned long keysize;
113 
115 typedef struct {
117  size_t session_count;
120  int error;
121 
124  const char *error_action;
125 
127  char error_message[HSM_ERROR_MSGSIZE];
128 
129  ldns_rbtree_t* keycache;
130 } hsm_ctx_t;
131 
132 
148 int
149 hsm_open(const char *config,
150  char *(pin_callback)(unsigned int, const char *, unsigned int));
151 
152 
162 char *
163 hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode);
164 
165 
174 char *
175 hsm_check_pin(unsigned int id, const char *repository, unsigned int mode);
176 
177 
184 int
186 
187 
194 void
195 hsm_close();
196 
197 
203 hsm_ctx_t *
204 hsm_create_context(void);
205 
206 
215 int
217 
218 
225 void
227 
228 
241 hsm_key_t **
242 hsm_list_keys(hsm_ctx_t *context, size_t *count);
243 
244 
258 hsm_key_t **
260  size_t *count,
261  const char *repository);
262 
263 
268 size_t
269 hsm_count_keys(hsm_ctx_t *context);
270 
271 
277 size_t
279  const char *repository);
280 
281 
282 
292 hsm_key_t *
294  const char *id);
295 
309 hsm_key_t *
311  const char *repository,
312  unsigned long keysize);
313 
326 hsm_key_t *
328  const char *repository,
329  unsigned long keysize);
330 
342 hsm_key_t *
344  const char *repository);
345 
356 int
357 hsm_remove_key(hsm_ctx_t *context, hsm_key_t *key);
358 
359 
364 void
365 hsm_key_free(hsm_key_t *key);
366 
367 
374 void
375 hsm_key_list_free(hsm_key_t **key_list, size_t count);
376 
377 
386 char *
387 hsm_get_key_id(hsm_ctx_t *context,
388  const hsm_key_t *key);
389 
390 
401 hsm_get_key_info(hsm_ctx_t *context,
402  const hsm_key_t *key);
403 
404 
409 void
411 
420 int
422  unsigned char *buffer,
423  unsigned long length);
424 
425 
431 uint32_t
433 
434 
440 uint64_t
442 
443 
444 
445 /*
446  * Additional functions for debugging, and non-general use-cases.
447  */
448 
460 int
461 hsm_attach(const char *repository,
462  const char *token_name,
463  const char *path,
464  const char *pin,
465  const hsm_config_t *config);
466 
472 int
473 hsm_detach(const char *repository);
474 
480 int
482  const char *repository);
483 
492 char *
493 hsm_get_error(hsm_ctx_t *gctx);
494 
495 /* a few debug functions for applications */
496 void hsm_print_session(hsm_session_t *session);
498 void hsm_print_key(hsm_ctx_t *ctx, hsm_key_t *key);
501 
502 /* implementation of a key cache per context, needs changing see
503  * OPENDNSSEC-799.
504  */
505 extern void keycache_create(hsm_ctx_t* ctx);
506 extern void keycache_destroy(hsm_ctx_t* ctx);
507 extern const hsm_key_t* keycache_lookup(hsm_ctx_t* ctx, const char* locator);
508 
509 #endif /* HSM_H */
size_t hsm_count_keys_repository(hsm_ctx_t *context, const char *repository)
Definition: libhsm.c:2324
uint64_t hsm_random64(hsm_ctx_t *ctx)
Definition: libhsm.c:3121
char * hsm_get_error(hsm_ctx_t *gctx)
Definition: libhsm.c:3227
hsm_ctx_t * hsm_create_context(void)
Definition: libhsm.c:2162
const char * error_action
Definition: libhsm.h:124
void * handle
Definition: libhsm.h:88
ldns_rbtree_t * keycache
Definition: libhsm.h:129
hsm_module_t * module
Definition: libhsm.h:95
char * hsm_get_key_id(hsm_ctx_t *context, const hsm_key_t *key)
Definition: libhsm.c:2723
char * path
Definition: libhsm.h:87
char * name
Definition: libhsm.h:85
unsigned long private_key
Definition: libhsm.h:102
hsm_key_t ** hsm_list_keys(hsm_ctx_t *context, size_t *count)
Definition: libhsm.c:2262
size_t hsm_count_keys(hsm_ctx_t *context)
Definition: libhsm.c:2311
unsigned long algorithm
Definition: libhsm.h:109
hsm_key_info_t * hsm_get_key_info(hsm_ctx_t *context, const hsm_key_t *key)
Definition: libhsm.c:2753
void * sym
Definition: libhsm.h:89
unsigned int allow_extract
Definition: libhsm.h:79
int hsm_detach(const char *repository)
Definition: libhsm.c:3163
void hsm_key_info_free(hsm_key_info_t *key_info)
Definition: libhsm.c:2799
void hsm_print_tokeninfo(hsm_ctx_t *ctx)
Definition: libhsm.c:3315
hsm_key_t * hsm_find_key_by_id(hsm_ctx_t *context, const char *id)
Definition: libhsm.c:2340
int hsm_random_buffer(hsm_ctx_t *ctx, unsigned char *buffer, unsigned long length)
Definition: libhsm.c:3079
const char * modulename
Definition: libhsm.h:101
int hsm_open(const char *config, char *(pin_callback)(unsigned int, const char *, unsigned int))
Definition: libhsm.c:1994
void hsm_close()
Definition: libhsm.c:2153
void keycache_create(hsm_ctx_t *ctx)
Definition: libhsm.c:3373
void hsm_key_list_free(hsm_key_t **key_list, size_t count)
Definition: libhsm.c:2712
hsm_key_t * hsm_generate_rsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition: libhsm.c:2356
unsigned long public_key
Definition: libhsm.h:103
void keycache_destroy(hsm_ctx_t *ctx)
Definition: libhsm.c:3379
void hsm_destroy_context(hsm_ctx_t *context)
Definition: libhsm.c:2227
#define HSM_ERROR_MSGSIZE
Definition: libhsm.h:46
unsigned int use_pubkey
Definition: libhsm.h:78
size_t session_count
Definition: libhsm.h:117
unsigned long session
Definition: libhsm.h:96
unsigned int id
Definition: libhsm.h:84
int hsm_remove_key(hsm_ctx_t *context, hsm_key_t *key)
Definition: libhsm.c:2675
int hsm_attach(const char *repository, const char *token_name, const char *path, const char *pin, const hsm_config_t *config)
Definition: libhsm.c:3140
const hsm_key_t * keycache_lookup(hsm_ctx_t *ctx, const char *locator)
Definition: libhsm.c:3386
int hsm_logout_pin()
Definition: pin.c:413
hsm_config_t * config
Definition: libhsm.h:90
char * algorithm_name
Definition: libhsm.h:110
hsm_key_t ** hsm_list_keys_repository(hsm_ctx_t *context, size_t *count, const char *repository)
Definition: libhsm.c:2294
int hsm_check_context()
Definition: libhsm.c:2172
#define HSM_MAX_SESSIONS
Definition: libhsm.h:42
uint32_t hsm_random32(hsm_ctx_t *ctx)
Definition: libhsm.c:3106
hsm_ctx_t * ctx
Definition: hsmutil.c:43
void hsm_print_ctx(hsm_ctx_t *ctx)
Definition: libhsm.c:3268
void hsm_print_key(hsm_ctx_t *ctx, hsm_key_t *key)
Definition: libhsm.c:3279
int error
Definition: libhsm.h:120
void hsm_print_error(hsm_ctx_t *ctx)
Definition: libhsm.c:3300
int hsm_token_attached(hsm_ctx_t *ctx, const char *repository)
Definition: libhsm.c:3187
hsm_key_t * hsm_generate_dsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition: libhsm.c:2448
hsm_key_t * hsm_generate_gost_key(hsm_ctx_t *context, const char *repository)
Definition: libhsm.c:2578
unsigned long keysize
Definition: libhsm.h:111
char * id
Definition: libhsm.h:108
void hsm_key_free(hsm_key_t *key)
Definition: libhsm.c:2704
void hsm_print_session(hsm_session_t *session)
Definition: libhsm.c:3258
char * hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode)
Definition: pin.c:228
char * token_label
Definition: libhsm.h:86
char * hsm_check_pin(unsigned int id, const char *repository, unsigned int mode)
Definition: pin.c:325