libhsm.h

Go to the documentation of this file.

/* $Id: libhsm.h 5651 2011-09-21 15:12:10Z sion $ */

/*
 * 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>

#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.
 */
#define HSM_MAX_ALGONAME 16

#define HSM_ERROR_MSGSIZE 512

#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


typedef struct {
    unsigned int use_pubkey;     
} 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 {
    const hsm_module_t *module;      
    unsigned long      private_key;  
    unsigned long      public_key;   
} hsm_key_t;

typedef struct {
  char          *id;             
  unsigned long algorithm;       
  char          *algorithm_name; 
  unsigned long keysize;         
} hsm_key_info_t;

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];
} hsm_ctx_t;


int
hsm_open(const char *config,
         char *(pin_callback)(const char *repository, void *),
         void *data);


char *
hsm_prompt_pin(const char *repository, void *data);


int
hsm_close();


hsm_ctx_t *
hsm_create_context(void);

int
hsm_check_context(hsm_ctx_t *context);


void
hsm_destroy_context(hsm_ctx_t *context);


hsm_key_t **
hsm_list_keys(hsm_ctx_t *context, size_t *count);


hsm_key_t **
hsm_list_keys_repository(hsm_ctx_t *context,
                         size_t *count,
                         const char *repository);


size_t
hsm_count_keys(hsm_ctx_t *context);


size_t
hsm_count_keys_repository(hsm_ctx_t *context,
                          const char *repository);



hsm_key_t *
hsm_find_key_by_id(hsm_ctx_t *context,
                   const char *id);

hsm_key_t *
hsm_generate_rsa_key(hsm_ctx_t *context,
                     const char *repository,
                     unsigned long keysize);


int
hsm_remove_key(hsm_ctx_t *context, hsm_key_t *key);


void
hsm_key_free(hsm_key_t *key);


void
hsm_key_list_free(hsm_key_t **key_list, size_t count);


char *
hsm_get_key_id(hsm_ctx_t *context,
               const hsm_key_t *key);


hsm_key_info_t *
hsm_get_key_info(hsm_ctx_t *context,
                 const hsm_key_t *key);


void
hsm_key_info_free(hsm_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_detach(const char *repository);

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 *gctx);
void hsm_print_key(hsm_key_t *key);
void hsm_print_error(hsm_ctx_t *ctx);
void hsm_print_tokeninfo(hsm_ctx_t *gctx);

#endif /* HSM_H */