OpenDNSSEC-libhsm  1.4.3
libhsm.h
Go to the documentation of this file.
1 /* $Id: libhsm.h 6704 2012-09-20 10:43:19Z rb $ */
2 
3 /*
4  * Copyright (c) 2009 .SE (The Internet Infrastructure Foundation).
5  * Copyright (c) 2009 NLNet Labs.
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  * 1. Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  * 2. Redistributions in binary form must reproduce the above copyright
14  * notice, this list of conditions and the following disclaimer in the
15  * documentation and/or other materials provided with the distribution.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
21  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
23  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
25  * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
26  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
27  * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28  */
29 
30 #ifndef HSM_H
31 #define HSM_H 1
32 
33 #include <stdint.h>
34 
35 /* Note that currently the MySQL kasp schema limits the number of HSMs to
36  * 127; so to increase it beyond that requires some database changes similar
37  * to when keypairs(id) was increased, see svn r4465.
38  *
39  * Note that this constant also determines the size of the shared PIN memory.
40  * Increasing this size requires any existing memory to be removed and should
41  * be part of a migration script.
42  */
43 #define HSM_MAX_SESSIONS 100
44 
45 #define HSM_MAX_ALGONAME 16
46 
47 #define HSM_ERROR_MSGSIZE 512
48 
49 /* TODO: depends on type and key, or just leave it at current
50  * maximum? */
51 #define HSM_MAX_SIGNATURE_LENGTH 512
52 
53 /* Note that this constant also determines the size of the shared PIN memory.
54  * Increasing this size requires any existing memory to be removed and should
55  * be part of a migration script.
56  */
57 #define HSM_MAX_PIN_LENGTH 255
58 
63 #define HSM_OK 0
64 #define HSM_ERROR 0x10000001
65 #define HSM_PIN_INCORRECT 0x10000002
66 #define HSM_CONFIG_FILE_ERROR 0x10000003
67 #define HSM_REPOSITORY_NOT_FOUND 0x10000004
68 #define HSM_NO_REPOSITORIES 0x10000005
69 #define HSM_MODULE_NOT_FOUND 0x10000006
70 
72 #define HSM_PIN_FIRST 0 /* Used when getting the PIN for the first time. */
73 #define HSM_PIN_RETRY 1 /* Used when we failed to login the first time. */
74 #define HSM_PIN_SAVE 2 /* The latest PIN can be saved for future use. Called
75  after a successful login. */
76 
78 typedef struct {
79  unsigned int use_pubkey;
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 {
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 } hsm_ctx_t;
129 
130 
146 int
147 hsm_open(const char *config,
148  char *(pin_callback)(unsigned int, const char *, unsigned int));
149 
150 
160 char *
161 hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode);
162 
163 
172 char *
173 hsm_check_pin(unsigned int id, const char *repository, unsigned int mode);
174 
175 
182 int
184 
185 
192 int
193 hsm_close();
194 
195 
201 hsm_ctx_t *
202 hsm_create_context(void);
203 
204 
213 int
214 hsm_check_context(hsm_ctx_t *context);
215 
216 
223 void
225 
226 
239 hsm_key_t **
240 hsm_list_keys(hsm_ctx_t *context, size_t *count);
241 
242 
256 hsm_key_t **
258  size_t *count,
259  const char *repository);
260 
261 
266 size_t
267 hsm_count_keys(hsm_ctx_t *context);
268 
269 
275 size_t
277  const char *repository);
278 
279 
280 
290 hsm_key_t *
292  const char *id);
293 
307 hsm_key_t *
309  const char *repository,
310  unsigned long keysize);
311 
324 hsm_key_t *
326  const char *repository,
327  unsigned long keysize);
328 
340 hsm_key_t *
342  const char *repository);
343 
354 int
355 hsm_remove_key(hsm_ctx_t *context, hsm_key_t *key);
356 
357 
362 void
363 hsm_key_free(hsm_key_t *key);
364 
365 
372 void
373 hsm_key_list_free(hsm_key_t **key_list, size_t count);
374 
375 
384 char *
385 hsm_get_key_id(hsm_ctx_t *context,
386  const hsm_key_t *key);
387 
388 
399 hsm_get_key_info(hsm_ctx_t *context,
400  const hsm_key_t *key);
401 
402 
407 void
409 
418 int
420  unsigned char *buffer,
421  unsigned long length);
422 
423 
429 uint32_t
430 hsm_random32(hsm_ctx_t *ctx);
431 
432 
438 uint64_t
439 hsm_random64(hsm_ctx_t *ctx);
440 
441 
442 
443 /*
444  * Additional functions for debugging, and non-general use-cases.
445  */
446 
458 int
459 hsm_attach(const char *repository,
460  const char *token_name,
461  const char *path,
462  const char *pin,
463  const hsm_config_t *config);
464 
470 int
471 hsm_detach(const char *repository);
472 
478 int
480  const char *repository);
481 
490 char *
491 hsm_get_error(hsm_ctx_t *gctx);
492 
493 /* a few debug functions for applications */
494 void hsm_print_session(hsm_session_t *session);
495 void hsm_print_ctx(hsm_ctx_t *gctx);
496 void hsm_print_key(hsm_key_t *key);
497 void hsm_print_error(hsm_ctx_t *ctx);
498 void hsm_print_tokeninfo(hsm_ctx_t *gctx);
499 
500 #endif /* HSM_H */
size_t hsm_count_keys_repository(hsm_ctx_t *context, const char *repository)
Definition: libhsm.c:2280
uint64_t hsm_random64(hsm_ctx_t *ctx)
Definition: libhsm.c:3037
char * hsm_get_error(hsm_ctx_t *gctx)
Definition: libhsm.c:3145
hsm_ctx_t * hsm_create_context(void)
Definition: libhsm.c:2128
const char * error_action
Definition: libhsm.h:124
void * handle
Definition: libhsm.h:88
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:2640
char * path
Definition: libhsm.h:87
char * name
Definition: libhsm.h:85
unsigned long private_key
Definition: libhsm.h:102
int hsm_close()
Definition: libhsm.c:2121
hsm_key_t ** hsm_list_keys(hsm_ctx_t *context, size_t *count)
Definition: libhsm.c:2219
size_t hsm_count_keys(hsm_ctx_t *context)
Definition: libhsm.c:2267
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:2668
void * sym
Definition: libhsm.h:89
int hsm_detach(const char *repository)
Definition: libhsm.c:3080
void hsm_key_info_free(hsm_key_info_t *key_info)
Definition: libhsm.c:2715
hsm_key_t * hsm_find_key_by_id(hsm_ctx_t *context, const char *id)
Definition: libhsm.c:2296
int hsm_random_buffer(hsm_ctx_t *ctx, unsigned char *buffer, unsigned long length)
Definition: libhsm.c:2994
int hsm_open(const char *config, char *(pin_callback)(unsigned int, const char *, unsigned int))
Definition: libhsm.c:1967
void hsm_key_list_free(hsm_key_t **key_list, size_t count)
Definition: libhsm.c:2630
hsm_key_t * hsm_generate_rsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition: libhsm.c:2312
unsigned long public_key
Definition: libhsm.h:103
void hsm_destroy_context(hsm_ctx_t *context)
Definition: libhsm.c:2184
#define HSM_ERROR_MSGSIZE
Definition: libhsm.h:47
unsigned int use_pubkey
Definition: libhsm.h:79
size_t session_count
Definition: libhsm.h:117
unsigned long session
Definition: libhsm.h:96
unsigned int id
Definition: libhsm.h:84
int hsm_check_context(hsm_ctx_t *context)
Definition: libhsm.c:2134
int hsm_remove_key(hsm_ctx_t *context, hsm_key_t *key)
Definition: libhsm.c:2592
int hsm_attach(const char *repository, const char *token_name, const char *path, const char *pin, const hsm_config_t *config)
Definition: libhsm.c:3056
int hsm_logout_pin()
Definition: pin.c:415
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:2249
#define HSM_MAX_SESSIONS
Definition: libhsm.h:43
uint32_t hsm_random32(hsm_ctx_t *ctx)
Definition: libhsm.c:3022
const hsm_module_t * module
Definition: libhsm.h:101
void hsm_print_tokeninfo(hsm_ctx_t *gctx)
Definition: libhsm.c:3245
int error
Definition: libhsm.h:120
void hsm_print_error(hsm_ctx_t *ctx)
Definition: libhsm.c:3230
void hsm_print_key(hsm_key_t *key)
Definition: libhsm.c:3203
int hsm_token_attached(hsm_ctx_t *ctx, const char *repository)
Definition: libhsm.c:3104
hsm_key_t * hsm_generate_dsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition: libhsm.c:2398
hsm_key_t * hsm_generate_gost_key(hsm_ctx_t *context, const char *repository)
Definition: libhsm.c:2512
unsigned long keysize
Definition: libhsm.h:111
char * id
Definition: libhsm.h:108
void hsm_key_free(hsm_key_t *key)
Definition: libhsm.c:2622
void hsm_print_session(hsm_session_t *session)
Definition: libhsm.c:3176
char * hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode)
Definition: pin.c:230
char * token_label
Definition: libhsm.h:86
void hsm_print_ctx(hsm_ctx_t *gctx)
Definition: libhsm.c:3186
char * hsm_check_pin(unsigned int id, const char *repository, unsigned int mode)
Definition: pin.c:327