libhsm.h

Go to the documentation of this file.

/*
 * Copyright (c) 2009 .SE (The Internet Infrastructure Foundation).
 * Copyright (c) 2009 NLNet Labs.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
 * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
#ifndef HSM_H
#define HSM_H 1
 
#include <stdint.h>
#include <ldns/rbtree.h>
#include <pthread.h>
 
#define HSM_MAX_SESSIONS 100
/* 
 * Note that currently the MySQL kasp schema limits the number of HSMs to 
 * 127; so to increase it beyond that requires some database changes similar
 * to when keypairs(id) was increased, see svn r4465.
 *
 * Note that this constant also determines the size of the shared PIN memory.
 * Increasing this size requires any existing memory to be removed and should
 * be part of a migration script.
 */
#define HSM_MAX_SESSIONS 100
 
#define HSM_MAX_ALGONAME 16
 
#define HSM_ERROR_MSGSIZE 512
 
/* TODO: depends on type and key, or just leave it at current
 * maximum? */
#define HSM_MAX_SIGNATURE_LENGTH 512
 
/* Note that this constant also determines the size of the shared PIN memory.
 * Increasing this size requires any existing memory to be removed and should
 * be part of a migration script.
 */
#define HSM_MAX_PIN_LENGTH 255
 
#define HSM_OK                    0
#define HSM_ERROR                 0x10000001
#define HSM_PIN_INCORRECT         0x10000002
#define HSM_CONFIG_FILE_ERROR     0x10000003
#define HSM_REPOSITORY_NOT_FOUND  0x10000004
#define HSM_NO_REPOSITORIES       0x10000005
#define HSM_MODULE_NOT_FOUND      0x10000006
 
#define HSM_PIN_FIRST   0       /* Used when getting the PIN for the first time. */
#define HSM_PIN_RETRY   1       /* Used when we failed to login the first time. */
#define HSM_PIN_SAVE    2       /* The latest PIN can be saved for future use. Called
                                   after a successful login. */
 
typedef struct {
    unsigned int use_pubkey;     
    unsigned int allow_extract;  
} hsm_config_t;
 
typedef struct {
    unsigned int id;             
    char         *name;          
    char         *token_label;   
    char         *path;          
    void         *handle;        
    void         *sym;           
    hsm_config_t *config;        
} hsm_module_t;
 
typedef struct {
    hsm_module_t  *module;
    unsigned long session;
} hsm_session_t;
 
typedef struct {
    char *modulename;   
    unsigned long      private_key;  
    unsigned long      public_key;   
} libhsm_key_t;
 
typedef struct {
  char          *id;             
  unsigned long algorithm;       
  char          *algorithm_name; 
  unsigned long keysize;         
} libhsm_key_info_t;
 
typedef struct hsm_repository_struct hsm_repository_t;
struct hsm_repository_struct {
    hsm_repository_t* next; 
    char    *name;          
    char    *module;        
    char    *tokenlabel;    
    char    *pin;           
    uint8_t require_backup; 
    uint8_t use_pubkey;     
    unsigned int allow_extract;  
};
 
typedef struct {
    hsm_session_t *session[HSM_MAX_SESSIONS];  
    size_t        session_count;               
    int error;
 
    const char *error_action;
 
    char error_message[HSM_ERROR_MSGSIZE];
    
    ldns_rbtree_t* keycache;
    pthread_mutex_t *keycache_lock;
} hsm_ctx_t;
 
 
void
hsm_ctx_set_error(hsm_ctx_t *ctx, int error, const char *action,
                 const char *message, ...);
 
int
hsm_open2(hsm_repository_t* rlist,
         char *(pin_callback)(unsigned int, const char *, unsigned int));
 
 
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);
 
void
hsm_repository_free(hsm_repository_t* r);
 
char *
hsm_prompt_pin(unsigned int id, const char *repository, unsigned int mode);
 
 
char *
hsm_check_pin(unsigned int id, const char *repository, unsigned int mode);
 
 
int
hsm_logout_pin(void);
 
 
void
hsm_close(void);
 
 
hsm_ctx_t *
hsm_create_context(void);
 
 
int
hsm_check_context();
 
 
void
hsm_destroy_context(hsm_ctx_t *context);
 
void
libhsm_key_free(libhsm_key_t *key);
 
libhsm_key_t **
hsm_list_keys(hsm_ctx_t *context, size_t *count);
 
 
libhsm_key_t **
hsm_list_keys_repository(hsm_ctx_t *context,
                         size_t *count,
                         const char *repository);
 
 
 
libhsm_key_t *
hsm_find_key_by_id(hsm_ctx_t *context,
                   const char *id);
 
libhsm_key_t *
hsm_generate_rsa_key(hsm_ctx_t *context,
                     const char *repository,
                     unsigned long keysize);
 
libhsm_key_t *
hsm_generate_dsa_key(hsm_ctx_t *context,
                     const char *repository,
                     unsigned long keysize);
 
libhsm_key_t *
hsm_generate_gost_key(hsm_ctx_t *context,
                     const char *repository);
 
libhsm_key_t *
hsm_generate_ecdsa_key(hsm_ctx_t *context,
                       const char *repository,
                       const char *curve);
 
int
hsm_remove_key(hsm_ctx_t *context, libhsm_key_t *key);
 
 
void
libhsm_key_list_free(libhsm_key_t **key_list, size_t count);
 
 
char *
hsm_get_key_id(hsm_ctx_t *context,
               const libhsm_key_t *key);
 
 
libhsm_key_info_t *
hsm_get_key_info(hsm_ctx_t *context,
                 const libhsm_key_t *key);
 
 
void
libhsm_key_info_free(libhsm_key_info_t *key_info);
 
int
hsm_random_buffer(hsm_ctx_t *ctx,
                  unsigned char *buffer,
                  unsigned long length);
 
 
uint32_t
hsm_random32(hsm_ctx_t *ctx);
 
 
uint64_t
hsm_random64(hsm_ctx_t *ctx);
 
 
 
/*
 * Additional functions for debugging, and non-general use-cases.
 */
 
int
hsm_attach(const char *repository,
           const char *token_name,
           const char *path,
           const char *pin,
           const hsm_config_t *config);
 
int
hsm_token_attached(hsm_ctx_t *ctx,
                   const char *repository);
 
char *
hsm_get_error(hsm_ctx_t *gctx);
 
/* a few debug functions for applications */
void hsm_print_session(hsm_session_t *session);
void hsm_print_ctx(hsm_ctx_t *ctx);
void hsm_print_key(hsm_ctx_t *ctx, libhsm_key_t *key);
void hsm_print_error(hsm_ctx_t *ctx);
void hsm_print_tokeninfo(hsm_ctx_t *ctx);
 
/* implementation of a key cache per context, needs changing see
 * OPENDNSSEC-799.
 */
extern void keycache_create(hsm_ctx_t* ctx);
extern void keycache_destroy(hsm_ctx_t* ctx);
extern const libhsm_key_t* keycache_lookup(hsm_ctx_t* ctx, const char* locator);
 
#endif /* HSM_H */