OpenDNSSEC-libhsm  1.4.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 
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 } hsm_config_t;
79 
81 typedef struct {
82  unsigned int id;
83  char *name;
84  char *token_label;
85  char *path;
86  void *handle;
87  void *sym;
88  hsm_config_t *config;
89 } hsm_module_t;
90 
92 typedef struct {
93  hsm_module_t *module;
94  unsigned long session;
96 
98 typedef struct {
99  const hsm_module_t *module;
100  unsigned long private_key;
101  unsigned long public_key;
102 } hsm_key_t;
103 
105 typedef struct {
106  char *id;
107  unsigned long algorithm;
108  char *algorithm_name;
109  unsigned long keysize;
111 
113 typedef struct {
115  size_t session_count;
118  int error;
122  const char *error_action;
125  char error_message[HSM_ERROR_MSGSIZE];
126 } hsm_ctx_t;
127 
128 
144 int
145 hsm_open(const char *config,
146  char *(pin_callback)(unsigned int, const char *, unsigned int));
147 
148 
158 char *
159 hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode);
160 
161 
170 char *
171 hsm_check_pin(unsigned int id, const char *repository, unsigned int mode);
172 
173 
180 int
182 
183 
190 int
191 hsm_close();
192 
193 
199 hsm_ctx_t *
200 hsm_create_context(void);
201 
202 
211 int
212 hsm_check_context(hsm_ctx_t *context);
213 
214 
221 void
223 
224 
237 hsm_key_t **
238 hsm_list_keys(hsm_ctx_t *context, size_t *count);
239 
240 
254 hsm_key_t **
256  size_t *count,
257  const char *repository);
258 
259 
264 size_t
265 hsm_count_keys(hsm_ctx_t *context);
266 
267 
273 size_t
275  const char *repository);
276 
277 
278 
288 hsm_key_t *
290  const char *id);
291 
305 hsm_key_t *
307  const char *repository,
308  unsigned long keysize);
309 
322 hsm_key_t *
324  const char *repository,
325  unsigned long keysize);
326 
338 hsm_key_t *
340  const char *repository);
341 
352 int
353 hsm_remove_key(hsm_ctx_t *context, hsm_key_t *key);
354 
355 
360 void
361 hsm_key_free(hsm_key_t *key);
362 
363 
370 void
371 hsm_key_list_free(hsm_key_t **key_list, size_t count);
372 
373 
382 char *
383 hsm_get_key_id(hsm_ctx_t *context,
384  const hsm_key_t *key);
385 
386 
397 hsm_get_key_info(hsm_ctx_t *context,
398  const hsm_key_t *key);
399 
400 
405 void
407 
416 int
418  unsigned char *buffer,
419  unsigned long length);
420 
421 
427 uint32_t
428 hsm_random32(hsm_ctx_t *ctx);
429 
430 
436 uint64_t
437 hsm_random64(hsm_ctx_t *ctx);
438 
439 
440 
441 /*
442  * Additional functions for debugging, and non-general use-cases.
443  */
444 
456 int
457 hsm_attach(const char *repository,
458  const char *token_name,
459  const char *path,
460  const char *pin,
461  const hsm_config_t *config);
462 
468 int
469 hsm_detach(const char *repository);
470 
476 int
478  const char *repository);
479 
488 char *
489 hsm_get_error(hsm_ctx_t *gctx);
490 
491 /* a few debug functions for applications */
492 void hsm_print_session(hsm_session_t *session);
493 void hsm_print_ctx(hsm_ctx_t *gctx);
494 void hsm_print_key(hsm_key_t *key);
495 void hsm_print_error(hsm_ctx_t *ctx);
496 void hsm_print_tokeninfo(hsm_ctx_t *gctx);
497 
498 #endif /* HSM_H */