OpenDNSSEC-libhsm  1.3.4
/build/buildd/opendnssec-1.3.4/libhsm/src/libhsm.h
Go to the documentation of this file.
00001 /* $Id: libhsm.h 5651 2011-09-21 15:12:10Z sion $ */
00002 
00003 /*
00004  * Copyright (c) 2009 .SE (The Internet Infrastructure Foundation).
00005  * Copyright (c) 2009 NLNet Labs.
00006  * All rights reserved.
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions
00010  * are met:
00011  * 1. Redistributions of source code must retain the above copyright
00012  *    notice, this list of conditions and the following disclaimer.
00013  * 2. Redistributions in binary form must reproduce the above copyright
00014  *    notice, this list of conditions and the following disclaimer in the
00015  *    documentation and/or other materials provided with the distribution.
00016  *
00017  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
00018  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00019  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00020  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
00021  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00022  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
00023  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00024  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
00025  * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
00026  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
00027  * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00028  */
00029 
00030 #ifndef HSM_H
00031 #define HSM_H 1
00032 
00033 #include <stdint.h>
00034 
00035 #define HSM_MAX_SESSIONS 100
00036 /* 
00037  * Note that currently the MySQL kasp schema limits the number of HSMs to 
00038  * 127; so to increase it beyond that requires some database changes similar
00039  * to when keypairs(id) was increased, see svn r4465.
00040  */
00041 #define HSM_MAX_ALGONAME 16
00042 
00043 #define HSM_ERROR_MSGSIZE 512
00044 
00049 #define HSM_OK                    0
00050 #define HSM_ERROR                 0x10000001
00051 #define HSM_PIN_INCORRECT         0x10000002
00052 #define HSM_CONFIG_FILE_ERROR     0x10000003
00053 #define HSM_REPOSITORY_NOT_FOUND  0x10000004
00054 #define HSM_NO_REPOSITORIES       0x10000005
00055 #define HSM_MODULE_NOT_FOUND      0x10000006
00056 
00057 
00059 typedef struct {
00060     unsigned int use_pubkey;     
00061 } hsm_config_t;
00062 
00064 typedef struct {
00065     unsigned int id;             
00066     char         *name;          
00067     char         *token_label;   
00068     char         *path;          
00069     void         *handle;        
00070     void         *sym;           
00071     hsm_config_t *config;        
00072 } hsm_module_t;
00073 
00075 typedef struct {
00076     hsm_module_t  *module;
00077     unsigned long session;
00078 } hsm_session_t;
00079 
00081 typedef struct {
00082     const hsm_module_t *module;      
00083     unsigned long      private_key;  
00084     unsigned long      public_key;   
00085 } hsm_key_t;
00086 
00088 typedef struct {
00089   char          *id;             
00090   unsigned long algorithm;       
00091   char          *algorithm_name; 
00092   unsigned long keysize;         
00093 } hsm_key_info_t;
00094 
00096 typedef struct {
00097     hsm_session_t *session[HSM_MAX_SESSIONS];  
00098     size_t        session_count;               
00101     int error;
00102 
00105     const char *error_action;
00106 
00108     char error_message[HSM_ERROR_MSGSIZE];
00109 } hsm_ctx_t;
00110 
00111 
00129 int
00130 hsm_open(const char *config,
00131          char *(pin_callback)(const char *repository, void *),
00132          void *data);
00133 
00134 
00142 char *
00143 hsm_prompt_pin(const char *repository, void *data);
00144 
00145 
00152 int
00153 hsm_close();
00154 
00155 
00161 hsm_ctx_t *
00162 hsm_create_context(void);
00163 
00172 int
00173 hsm_check_context(hsm_ctx_t *context);
00174 
00175 
00182 void
00183 hsm_destroy_context(hsm_ctx_t *context);
00184 
00185 
00198 hsm_key_t **
00199 hsm_list_keys(hsm_ctx_t *context, size_t *count);
00200 
00201 
00215 hsm_key_t **
00216 hsm_list_keys_repository(hsm_ctx_t *context,
00217                          size_t *count,
00218                          const char *repository);
00219 
00220 
00225 size_t
00226 hsm_count_keys(hsm_ctx_t *context);
00227 
00228 
00234 size_t
00235 hsm_count_keys_repository(hsm_ctx_t *context,
00236                           const char *repository);
00237 
00238 
00239 
00249 hsm_key_t *
00250 hsm_find_key_by_id(hsm_ctx_t *context,
00251                    const char *id);
00252 
00266 hsm_key_t *
00267 hsm_generate_rsa_key(hsm_ctx_t *context,
00268                      const char *repository,
00269                      unsigned long keysize);
00270 
00271 
00282 int
00283 hsm_remove_key(hsm_ctx_t *context, hsm_key_t *key);
00284 
00285 
00290 void
00291 hsm_key_free(hsm_key_t *key);
00292 
00293 
00300 void
00301 hsm_key_list_free(hsm_key_t **key_list, size_t count);
00302 
00303 
00312 char *
00313 hsm_get_key_id(hsm_ctx_t *context,
00314                const hsm_key_t *key);
00315 
00316 
00326 hsm_key_info_t *
00327 hsm_get_key_info(hsm_ctx_t *context,
00328                  const hsm_key_t *key);
00329 
00330 
00335 void
00336 hsm_key_info_free(hsm_key_info_t *key_info);
00337 
00346 int
00347 hsm_random_buffer(hsm_ctx_t *ctx,
00348                   unsigned char *buffer,
00349                   unsigned long length);
00350 
00351 
00357 uint32_t
00358 hsm_random32(hsm_ctx_t *ctx);
00359 
00360 
00366 uint64_t
00367 hsm_random64(hsm_ctx_t *ctx);
00368 
00369 
00370 
00371 /*
00372  * Additional functions for debugging, and non-general use-cases.
00373  */
00374 
00386 int
00387 hsm_attach(const char *repository,
00388            const char *token_name,
00389            const char *path,
00390            const char *pin,
00391            const hsm_config_t *config);
00392 
00398 int
00399 hsm_detach(const char *repository);
00400 
00406 int
00407 hsm_token_attached(hsm_ctx_t *ctx,
00408                    const char *repository);
00409 
00418 char *
00419 hsm_get_error(hsm_ctx_t *gctx);
00420 
00421 /* a few debug functions for applications */
00422 void hsm_print_session(hsm_session_t *session);
00423 void hsm_print_ctx(hsm_ctx_t *gctx);
00424 void hsm_print_key(hsm_key_t *key);
00425 void hsm_print_error(hsm_ctx_t *ctx);
00426 void hsm_print_tokeninfo(hsm_ctx_t *gctx);
00427 
00428 #endif /* HSM_H */