OpenDNSSEC-libhsm 2.1.13
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#include <pthread.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 * Note that this constant also determines the size of the shared PIN memory.
42 * Increasing this size requires any existing memory to be removed and should
43 * be part of a migration script.
44 */
45#define HSM_MAX_SESSIONS 100
46
47#define HSM_MAX_ALGONAME 16
48
49#define HSM_ERROR_MSGSIZE 512
50
51/* TODO: depends on type and key, or just leave it at current
52 * maximum? */
53#define HSM_MAX_SIGNATURE_LENGTH 512
54
55/* Note that this constant also determines the size of the shared PIN memory.
56 * Increasing this size requires any existing memory to be removed and should
57 * be part of a migration script.
58 */
59#define HSM_MAX_PIN_LENGTH 255
60
65#define HSM_OK 0
66#define HSM_ERROR 0x10000001
67#define HSM_PIN_INCORRECT 0x10000002
68#define HSM_CONFIG_FILE_ERROR 0x10000003
69#define HSM_REPOSITORY_NOT_FOUND 0x10000004
70#define HSM_NO_REPOSITORIES 0x10000005
71#define HSM_MODULE_NOT_FOUND 0x10000006
72
74#define HSM_PIN_FIRST 0 /* Used when getting the PIN for the first time. */
75#define HSM_PIN_RETRY 1 /* Used when we failed to login the first time. */
76#define HSM_PIN_SAVE 2 /* The latest PIN can be saved for future use. Called
77 after a successful login. */
78
80typedef struct {
81 unsigned int use_pubkey;
82 unsigned int allow_extract;
84
86typedef struct {
87 unsigned int id;
88 char *name;
89 char *token_label;
90 char *path;
91 void *handle;
92 void *sym;
93 hsm_config_t *config;
95
97typedef struct {
98 hsm_module_t *module;
99 unsigned long session;
101
103typedef struct {
104 char *modulename;
105 unsigned long private_key;
106 unsigned long public_key;
108
110typedef struct {
111 char *id;
112 unsigned long algorithm;
113 char *algorithm_name;
114 unsigned long keysize;
116
121 char *name;
122 char *module;
124 char *pin;
126 uint8_t use_pubkey;
127 unsigned int allow_extract;
128};
129
131typedef struct {
133 size_t session_count;
136 int error;
137
140 const char *error_action;
141
143 char error_message[HSM_ERROR_MSGSIZE];
145 ldns_rbtree_t* keycache;
146 pthread_mutex_t *keycache_lock;
147} hsm_ctx_t;
148
149
161extern void
162hsm_ctx_set_error(hsm_ctx_t *ctx, int error, const char *action,
163 const char *message, ...)
164#ifdef HAVE___ATTRIBUTE__
165 __attribute__ ((format (printf, 4, 5)))
166#endif
167 ;
168
184extern int
186 char *(pin_callback)(unsigned int, const char *, unsigned int));
187
188
199hsm_repository_new(char* name, char* module, char* tokenlabel, char* pin,
200 uint8_t use_pubkey, uint8_t allowextract, uint8_t require_backup);
201
206void
208
218extern char *
219hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode);
220
221
230extern char *
231hsm_check_pin(unsigned int id, const char *repository, unsigned int mode);
232
233
240extern int
241hsm_logout_pin(void);
242
243
250extern void
251hsm_close(void);
252
253
259extern hsm_ctx_t *
261
262
271extern int
273
274
281extern void
283
284extern void
286
299extern libhsm_key_t **
300hsm_list_keys(hsm_ctx_t *context, size_t *count);
301
302
316extern libhsm_key_t **
318 size_t *count,
319 const char *repository);
320
321
322
332extern libhsm_key_t *
334 const char *id);
335
349extern libhsm_key_t *
351 const char *repository,
352 unsigned long keysize);
353
366extern libhsm_key_t *
368 const char *repository,
369 unsigned long keysize);
370
382extern libhsm_key_t *
384 const char *repository);
385
398extern libhsm_key_t *
400 const char *repository,
401 const char *curve);
402
417 const char *repository,
418 const char *curve);
419
430extern int
432
433
440extern void
441libhsm_key_list_free(libhsm_key_t **key_list, size_t count);
442
443
452extern char *
454 const libhsm_key_t *key);
455
456
466extern libhsm_key_info_t *
468 const libhsm_key_t *key);
469
470
475extern void
477
486extern int
488 unsigned char *buffer,
489 unsigned long length);
490
491
497extern uint32_t
499
500
506extern uint64_t
508
509
510
511/*
512 * Additional functions for debugging, and non-general use-cases.
513 */
514
526extern int
527hsm_attach(const char *repository,
528 const char *token_name,
529 const char *path,
530 const char *pin,
531 const hsm_config_t *config);
532
538extern int
540 const char *repository);
541
550extern char *
552
553/* a few debug functions for applications */
554extern void hsm_print_session(hsm_session_t *session);
555extern void hsm_print_ctx(hsm_ctx_t *ctx);
556extern void hsm_print_key(hsm_ctx_t *ctx, libhsm_key_t *key);
557extern void hsm_print_error(hsm_ctx_t *ctx);
558extern void hsm_print_tokeninfo(hsm_ctx_t *ctx);
559
560/* implementation of a key cache per context, needs changing see
561 * OPENDNSSEC-799.
562 */
563extern void keycache_create(hsm_ctx_t* ctx);
564extern void keycache_destroy(hsm_ctx_t* ctx);
565extern const libhsm_key_t* keycache_lookup(hsm_ctx_t* ctx, const char* locator);
566
567#endif /* HSM_H */
ldns_algorithm algorithm
Definition hsmspeed.c:43
hsm_ctx_t * ctx
Definition hsmutil.c:46
hsm_repository_t * hsm_repository_new(char *name, char *module, char *tokenlabel, char *pin, uint8_t use_pubkey, uint8_t allowextract, uint8_t require_backup)
Definition libhsm.c:374
char * hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode)
Definition pin.c:228
libhsm_key_t ** hsm_list_keys_repository(hsm_ctx_t *context, size_t *count, const char *repository)
Definition libhsm.c:2504
void libhsm_key_list_free(libhsm_key_t **key_list, size_t count)
Definition libhsm.c:3053
libhsm_key_t * hsm_generate_ecdsa_key(hsm_ctx_t *context, const char *repository, const char *curve)
Definition libhsm.c:2832
int hsm_attach(const char *repository, const char *token_name, const char *path, const char *pin, const hsm_config_t *config)
Definition libhsm.c:3374
void hsm_ctx_set_error(hsm_ctx_t *ctx, int error, const char *action, const char *message,...)
Definition libhsm.c:209
hsm_ctx_t * hsm_create_context(void)
Definition libhsm.c:2374
const libhsm_key_t * keycache_lookup(hsm_ctx_t *ctx, const char *locator)
Definition libhsm.c:3586
uint64_t hsm_random64(hsm_ctx_t *ctx)
Definition libhsm.c:3355
char * hsm_get_error(hsm_ctx_t *gctx)
Definition libhsm.c:3414
uint32_t hsm_random32(hsm_ctx_t *ctx)
Definition libhsm.c:3340
libhsm_key_t * hsm_generate_rsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition libhsm.c:2550
int hsm_token_attached(hsm_ctx_t *ctx, const char *repository)
Definition libhsm.c:3397
int hsm_remove_key(hsm_ctx_t *context, libhsm_key_t *key)
Definition libhsm.c:3024
char * hsm_check_pin(unsigned int id, const char *repository, unsigned int mode)
Definition pin.c:325
#define HSM_ERROR_MSGSIZE
Definition libhsm.h:49
libhsm_key_t * hsm_find_key_by_id(hsm_ctx_t *context, const char *id)
Definition libhsm.c:2521
void hsm_print_key(hsm_ctx_t *ctx, libhsm_key_t *key)
Definition libhsm.c:3467
libhsm_key_t * hsm_generate_dsa_key(hsm_ctx_t *context, const char *repository, unsigned long keysize)
Definition libhsm.c:2638
void hsm_print_error(hsm_ctx_t *ctx)
Definition libhsm.c:3493
libhsm_key_t * hsm_generate_eddsa_key(hsm_ctx_t *context, const char *repository, const char *curve)
Definition libhsm.c:2928
void hsm_close(void)
Definition libhsm.c:2364
void hsm_print_ctx(hsm_ctx_t *ctx)
Definition libhsm.c:3456
void hsm_repository_free(hsm_repository_t *r)
Definition libhsm.c:407
int hsm_check_context()
Definition libhsm.c:2384
libhsm_key_t * hsm_generate_gost_key(hsm_ctx_t *context, const char *repository)
Definition libhsm.c:2752
void libhsm_key_info_free(libhsm_key_info_t *key_info)
Definition libhsm.c:3140
libhsm_key_t ** hsm_list_keys(hsm_ctx_t *context, size_t *count)
Definition libhsm.c:2478
int hsm_random_buffer(hsm_ctx_t *ctx, unsigned char *buffer, unsigned long length)
Definition libhsm.c:3313
int hsm_open2(hsm_repository_t *rlist, char *(pin_callback)(unsigned int, const char *, unsigned int))
Definition libhsm.c:2297
void hsm_print_session(hsm_session_t *session)
Definition libhsm.c:3446
void keycache_create(hsm_ctx_t *ctx)
Definition libhsm.c:3568
int hsm_logout_pin(void)
Definition pin.c:413
void hsm_print_tokeninfo(hsm_ctx_t *ctx)
Definition libhsm.c:3508
void hsm_destroy_context(hsm_ctx_t *context)
Definition libhsm.c:2439
char * hsm_get_key_id(hsm_ctx_t *context, const libhsm_key_t *key)
Definition libhsm.c:3063
#define HSM_MAX_SESSIONS
Definition libhsm.h:35
libhsm_key_info_t * hsm_get_key_info(hsm_ctx_t *context, const libhsm_key_t *key)
Definition libhsm.c:3089
void keycache_destroy(hsm_ctx_t *ctx)
Definition libhsm.c:3576
void libhsm_key_free(libhsm_key_t *key)
Definition libhsm.c:2471
#define session_count
Definition pkcs11.h:123
char *char * tokenlabel
Definition libhsm.h:122
hsm_repository_t * next
Definition libhsm.h:119
unsigned int allow_extract
Definition libhsm.h:126
uint8_t require_backup
Definition libhsm.h:124