OpenDNSSEC-libhsm  1.4.9
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 
33 /* Note that currently the MySQL kasp schema limits the number of HSMs to
34  * 127; so to increase it beyond that requires some database changes similar
35  * to when keypairs(id) was increased, see svn r4465.
36  *
37  * Note that this constant also determines the size of the shared PIN memory.
38  * Increasing this size requires any existing memory to be removed and should
39  * be part of a migration script.
40  */
41 #define HSM_MAX_SESSIONS 100
42 
43 #define HSM_MAX_ALGONAME 16
44 
45 #define HSM_ERROR_MSGSIZE 512
46 
47 /* TODO: depends on type and key, or just leave it at current
48  * maximum? */
49 #define HSM_MAX_SIGNATURE_LENGTH 512
50 
51 /* Note that this constant also determines the size of the shared PIN memory.
52  * Increasing this size requires any existing memory to be removed and should
53  * be part of a migration script.
54  */
55 #define HSM_MAX_PIN_LENGTH 255
56 
61 #define HSM_OK 0
62 #define HSM_ERROR 0x10000001
63 #define HSM_PIN_INCORRECT 0x10000002
64 #define HSM_CONFIG_FILE_ERROR 0x10000003
65 #define HSM_REPOSITORY_NOT_FOUND 0x10000004
66 #define HSM_NO_REPOSITORIES 0x10000005
67 #define HSM_MODULE_NOT_FOUND 0x10000006
68 
70 #define HSM_PIN_FIRST 0 /* Used when getting the PIN for the first time. */
71 #define HSM_PIN_RETRY 1 /* Used when we failed to login the first time. */
72 #define HSM_PIN_SAVE 2 /* The latest PIN can be saved for future use. Called
73  after a successful login. */
74 
76 typedef struct {
77  unsigned int use_pubkey;
78  unsigned int allow_extract;
79 } hsm_config_t;
80 
82 typedef struct {
83  unsigned int id;
84  char *name;
85  char *token_label;
86  char *path;
87  void *handle;
88  void *sym;
90 } hsm_module_t;
91 
93 typedef struct {
95  unsigned long session;
97 
99 typedef struct {
101  unsigned long private_key;
102  unsigned long public_key;
103 } hsm_key_t;
104 
106 typedef struct {
107  char *id;
108  unsigned long algorithm;
110  unsigned long keysize;
112 
114 typedef struct {
116  size_t session_count;
119  int error;
120 
123  const char *error_action;
124 
126  char error_message[HSM_ERROR_MSGSIZE];
127 } hsm_ctx_t;
128 
129 
145 int
146 hsm_open(const char *config,
147  char *(pin_callback)(unsigned int, const char *, unsigned int));
148 
149 
159 char *
160 hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode);
161 
162 
171 char *
172 hsm_check_pin(unsigned int id, const char *repository, unsigned int mode);
173 
174 
181 int
183 
184 
191 int
192 hsm_close();
193 
194 
200 hsm_ctx_t *
201 hsm_create_context(void);
202 
203 
212 int
213 hsm_check_context(hsm_ctx_t *context);
214 
215 
222 void
224 
225 
238 hsm_key_t **
239 hsm_list_keys(hsm_ctx_t *context, size_t *count);
240 
241 
255 hsm_key_t **
257  size_t *count,
258  const char *repository);
259 
260 
265 size_t
266 hsm_count_keys(hsm_ctx_t *context);
267 
268 
274 size_t
276  const char *repository);
277 
278 
279 
289 hsm_key_t *
291  const char *id);
292 
306 hsm_key_t *
308  const char *repository,
309  unsigned long keysize);
310 
323 hsm_key_t *
325  const char *repository,
326  unsigned long keysize);
327 
339 hsm_key_t *
341  const char *repository);
342 
353 int
354 hsm_remove_key(hsm_ctx_t *context, hsm_key_t *key);
355 
356 
361 void
362 hsm_key_free(hsm_key_t *key);
363 
364 
371 void
372 hsm_key_list_free(hsm_key_t **key_list, size_t count);
373 
374 
383 char *
384 hsm_get_key_id(hsm_ctx_t *context,
385  const hsm_key_t *key);
386 
387 
398 hsm_get_key_info(hsm_ctx_t *context,
399  const hsm_key_t *key);
400 
401 
406 void
408 
417 int
419  unsigned char *buffer,
420  unsigned long length);
421 
422 
428 uint32_t
429 hsm_random32(hsm_ctx_t *ctx);
430 
431 
437 uint64_t
438 hsm_random64(hsm_ctx_t *ctx);
439 
440 
441 
442 /*
443  * Additional functions for debugging, and non-general use-cases.
444  */
445 
457 int
458 hsm_attach(const char *repository,
459  const char *token_name,
460  const char *path,
461  const char *pin,
462  const hsm_config_t *config);
463 
469 int
470 hsm_detach(const char *repository);
471 
477 int
479  const char *repository);
480 
489 char *
490 hsm_get_error(hsm_ctx_t *gctx);
491 
492 /* a few debug functions for applications */
493 void hsm_print_session(hsm_session_t *session);
494 void hsm_print_ctx(hsm_ctx_t *gctx);
495 void hsm_print_key(hsm_key_t *key);
496 void hsm_print_error(hsm_ctx_t *ctx);
497 void hsm_print_tokeninfo(hsm_ctx_t *gctx);
498 
499 #endif /* HSM_H */
size_t hsm_count_keys_repository(hsm_ctx_t *context, const char *repository)
Definition: libhsm.c:2311
uint64_t hsm_random64(hsm_ctx_t *ctx)
Definition: libhsm.c:3091
char * hsm_get_error(hsm_ctx_t *gctx)
Definition: libhsm.c:3199
hsm_ctx_t * hsm_create_context(void)
Definition: libhsm.c:2153
const char * error_action
Definition: libhsm.h:123
void * handle
Definition: libhsm.h:87
hsm_module_t * module
Definition: libhsm.h:94
char * hsm_get_key_id(hsm_ctx_t *context, const hsm_key_t *key)
Definition: libhsm.c:2688
char * path
Definition: libhsm.h:86
char * name
Definition: libhsm.h:84
unsigned long private_key
Definition: libhsm.h:101
int hsm_close()
Definition: libhsm.c:2146
hsm_key_t ** hsm_list_keys(hsm_ctx_t *context, size_t *count)
Definition: libhsm.c:2244
size_t hsm_count_keys(hsm_ctx_t *context)
Definition: libhsm.c:2298
unsigned long algorithm
Definition: libhsm.h:108
hsm_key_info_t * hsm_get_key_info(hsm_ctx_t *context, const hsm_key_t *key)
Definition: libhsm.c:2719
void * sym
Definition: libhsm.h:88
unsigned int allow_extract
Definition: libhsm.h:78
int hsm_detach(const char *repository)
Definition: libhsm.c:3134
void hsm_key_info_free(hsm_key_info_t *key_info)
Definition: libhsm.c:2766
hsm_key_t * hsm_find_key_by_id(hsm_ctx_t *context, const char *id)
Definition: libhsm.c:2327
int hsm_random_buffer(hsm_ctx_t *ctx, unsigned char *buffer, unsigned long length)
Definition: libhsm.c:3048
int hsm_open(const char *config, char *(pin_callback)(unsigned int, const char *, unsigned int))
Definition: libhsm.c:1990
void hsm_key_list_free(hsm_key_t **key_list, size_t count)
Definition: libhsm.c:2678
hsm_key_t * hsm_generate_rsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition: libhsm.c:2343
unsigned long public_key
Definition: libhsm.h:102
void hsm_destroy_context(hsm_ctx_t *context)
Definition: libhsm.c:2209
#define HSM_ERROR_MSGSIZE
Definition: libhsm.h:45
unsigned int use_pubkey
Definition: libhsm.h:77
size_t session_count
Definition: libhsm.h:116
unsigned long session
Definition: libhsm.h:95
unsigned int id
Definition: libhsm.h:83
int hsm_check_context(hsm_ctx_t *context)
Definition: libhsm.c:2159
int hsm_remove_key(hsm_ctx_t *context, hsm_key_t *key)
Definition: libhsm.c:2640
int hsm_attach(const char *repository, const char *token_name, const char *path, const char *pin, const hsm_config_t *config)
Definition: libhsm.c:3110
int hsm_logout_pin()
Definition: pin.c:413
hsm_config_t * config
Definition: libhsm.h:89
char * algorithm_name
Definition: libhsm.h:109
hsm_key_t ** hsm_list_keys_repository(hsm_ctx_t *context, size_t *count, const char *repository)
Definition: libhsm.c:2280
#define HSM_MAX_SESSIONS
Definition: libhsm.h:41
uint32_t hsm_random32(hsm_ctx_t *ctx)
Definition: libhsm.c:3076
const hsm_module_t * module
Definition: libhsm.h:100
void hsm_print_tokeninfo(hsm_ctx_t *gctx)
Definition: libhsm.c:3299
int error
Definition: libhsm.h:119
void hsm_print_error(hsm_ctx_t *ctx)
Definition: libhsm.c:3284
void hsm_print_key(hsm_key_t *key)
Definition: libhsm.c:3257
int hsm_token_attached(hsm_ctx_t *ctx, const char *repository)
Definition: libhsm.c:3158
hsm_key_t * hsm_generate_dsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition: libhsm.c:2436
hsm_key_t * hsm_generate_gost_key(hsm_ctx_t *context, const char *repository)
Definition: libhsm.c:2554
unsigned long keysize
Definition: libhsm.h:110
char * id
Definition: libhsm.h:107
void hsm_key_free(hsm_key_t *key)
Definition: libhsm.c:2670
void hsm_print_session(hsm_session_t *session)
Definition: libhsm.c:3230
char * hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode)
Definition: pin.c:228
char * token_label
Definition: libhsm.h:85
void hsm_print_ctx(hsm_ctx_t *gctx)
Definition: libhsm.c:3240
char * hsm_check_pin(unsigned int id, const char *repository, unsigned int mode)
Definition: pin.c:325