OpenDNSSEC-libhsm  1.3.14
libhsm.h
Go to the documentation of this file.
1 /* $Id: libhsm.h 5651 2011-09-21 15:12:10Z sion $ */
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 #define HSM_MAX_SESSIONS 100
36 /*
37  * Note that currently the MySQL kasp schema limits the number of HSMs to
38  * 127; so to increase it beyond that requires some database changes similar
39  * to when keypairs(id) was increased, see svn r4465.
40  */
41 #define HSM_MAX_ALGONAME 16
42 
43 #define HSM_ERROR_MSGSIZE 512
44 
49 #define HSM_OK 0
50 #define HSM_ERROR 0x10000001
51 #define HSM_PIN_INCORRECT 0x10000002
52 #define HSM_CONFIG_FILE_ERROR 0x10000003
53 #define HSM_REPOSITORY_NOT_FOUND 0x10000004
54 #define HSM_NO_REPOSITORIES 0x10000005
55 #define HSM_MODULE_NOT_FOUND 0x10000006
56 
57 
59 typedef struct {
60  unsigned int use_pubkey;
61 } hsm_config_t;
62 
64 typedef struct {
65  unsigned int id;
66  char *name;
67  char *token_label;
68  char *path;
69  void *handle;
70  void *sym;
72 } hsm_module_t;
73 
75 typedef struct {
77  unsigned long session;
79 
81 typedef struct {
83  unsigned long private_key;
84  unsigned long public_key;
85 } hsm_key_t;
86 
88 typedef struct {
89  char *id;
90  unsigned long algorithm;
92  unsigned long keysize;
94 
96 typedef struct {
98  size_t session_count;
101  int error;
102 
105  const char *error_action;
106 
108  char error_message[HSM_ERROR_MSGSIZE];
109 } hsm_ctx_t;
110 
111 
129 int
130 hsm_open(const char *config,
131  char *(pin_callback)(const char *repository, void *),
132  void *data);
133 
134 
142 char *
143 hsm_prompt_pin(const char *repository, void *data);
144 
145 
152 int
153 hsm_close();
154 
155 
161 hsm_ctx_t *
162 hsm_create_context(void);
163 
172 int
173 hsm_check_context(hsm_ctx_t *context);
174 
175 
182 void
184 
185 
198 hsm_key_t **
199 hsm_list_keys(hsm_ctx_t *context, size_t *count);
200 
201 
215 hsm_key_t **
217  size_t *count,
218  const char *repository);
219 
220 
225 size_t
226 hsm_count_keys(hsm_ctx_t *context);
227 
228 
234 size_t
236  const char *repository);
237 
238 
239 
249 hsm_key_t *
251  const char *id);
252 
266 hsm_key_t *
268  const char *repository,
269  unsigned long keysize);
270 
271 
282 int
283 hsm_remove_key(hsm_ctx_t *context, hsm_key_t *key);
284 
285 
290 void
291 hsm_key_free(hsm_key_t *key);
292 
293 
300 void
301 hsm_key_list_free(hsm_key_t **key_list, size_t count);
302 
303 
312 char *
313 hsm_get_key_id(hsm_ctx_t *context,
314  const hsm_key_t *key);
315 
316 
327 hsm_get_key_info(hsm_ctx_t *context,
328  const hsm_key_t *key);
329 
330 
335 void
337 
346 int
348  unsigned char *buffer,
349  unsigned long length);
350 
351 
357 uint32_t
358 hsm_random32(hsm_ctx_t *ctx);
359 
360 
366 uint64_t
367 hsm_random64(hsm_ctx_t *ctx);
368 
369 
370 
371 /*
372  * Additional functions for debugging, and non-general use-cases.
373  */
374 
386 int
387 hsm_attach(const char *repository,
388  const char *token_name,
389  const char *path,
390  const char *pin,
391  const hsm_config_t *config);
392 
398 int
399 hsm_detach(const char *repository);
400 
406 int
408  const char *repository);
409 
418 char *
419 hsm_get_error(hsm_ctx_t *gctx);
420 
421 /* a few debug functions for applications */
422 void hsm_print_session(hsm_session_t *session);
423 void hsm_print_ctx(hsm_ctx_t *gctx);
424 void hsm_print_key(hsm_key_t *key);
425 void hsm_print_error(hsm_ctx_t *ctx);
426 void hsm_print_tokeninfo(hsm_ctx_t *gctx);
427 
428 #endif /* HSM_H */