pk.h 6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
/**
 * \file pk.h
 *
 * \brief Public Key abstraction layer
 *
 *  Copyright (C) 2006-2013, Brainspark B.V.
 *
 *  This file is part of PolarSSL (http://www.polarssl.org)
 *  Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
 *
 *  All rights reserved.
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, write to the Free Software Foundation, Inc.,
 *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */
27

28 29 30
#ifndef POLARSSL_PK_H
#define POLARSSL_PK_H

31 32 33 34 35 36
#include "config.h"

#if defined(POLARSSL_RSA_C)
#include "rsa.h"
#endif

37 38 39 40
#if defined(POLARSSL_ECP_C)
#include "ecp.h"
#endif

41 42 43 44
#if defined(POLARSSL_ECDSA_C)
#include "ecdsa.h"
#endif

45
#define POLARSSL_ERR_PK_MALLOC_FAILED       -0x2F80  /**< Memory alloation failed. */
Manuel Pégourié-Gonnard's avatar
Manuel Pégourié-Gonnard committed
46 47
#define POLARSSL_ERR_PK_TYPE_MISMATCH       -0x2F00  /**< Type mismatch, eg attempt to use a RSA key as EC, or to modify key type. */
#define POLARSSL_ERR_PK_BAD_INPUT_DATA      -0x2E80  /**< Bad input parameters to function. */
48

49 50 51 52 53 54 55
#if defined(POLARSSL_RSA_C)
/**
 * Quick access to an RSA context inside a PK context.
 *
 * \warning You must make sure the PK context actually holds an RSA context
 * before using this macro!
 */
56
#define pk_rsa( pk )        ( (rsa_context *) (pk).pk_ctx )
57
#endif /* POLARSSL_RSA_C */
58 59 60 61 62 63 64 65

#if defined(POLARSSL_ECP_C)
/**
 * Quick access to an EC context inside a PK context.
 *
 * \warning You must make sure the PK context actually holds an EC context
 * before using this macro!
 */
66
#define pk_ec( pk )         ( (ecp_keypair *) (pk).pk_ctx )
67
#endif /* POLARSSL_ECP_C */
68 69


70 71 72 73 74 75 76 77 78 79
#ifdef __cplusplus
extern "C" {
#endif

/**
 * \brief          Public key types
 */
typedef enum {
    POLARSSL_PK_NONE=0,
    POLARSSL_PK_RSA,
80 81
    POLARSSL_PK_ECKEY,
    POLARSSL_PK_ECKEY_DH,
82
    POLARSSL_PK_ECDSA,
83 84
} pk_type_t;

85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
/**
 * \brief           Types for interfacing with the debug module
 */
typedef enum
{
    POLARSSL_PK_DEBUG_NONE = 0,
    POLARSSL_PK_DEBUG_MPI,
    POLARSSL_PK_DEBUG_ECP,
} pk_debug_type;

/**
 * \brief           Item to send to the debug module
 */
typedef struct
{
    pk_debug_type type;
    char *name;
    void *value;
} pk_debug_item;

/** Maximum number of item send for debugging, plus 1 */
#define POLARSSL_PK_DEBUG_MAX_ITEMS 3

108
/**
109
 * \brief           Public key information and operations
110 111 112 113 114 115
 */
typedef struct
{
    /** Public key type */
    pk_type_t type;

116 117 118 119
    /** Type name */
    const char *name;

    /** Get key size in bits */
120
    size_t (*get_size)( const void * );
121

122 123 124
    /** Tell if the context implements this type (eg ECKEY can do ECDSA) */
    int (*can_do)( pk_type_t type );

125 126 127 128
    /** Verify signature */
    int (*verify_func)( void *ctx,
                        const unsigned char *hash, const md_info_t *md_info,
                        const unsigned char *sig, size_t sig_len );
129 130 131 132 133 134 135

    /** Allocate a new context */
    void * (*ctx_alloc_func)( void );

    /** Free the given context */
    void (*ctx_free_func)( void *ctx );

136 137 138
    /** Interface with the debug module */
    void (*debug_func)( const void *ctx, pk_debug_item *items );

139 140
} pk_info_t;

141 142 143 144 145
/**
 * \brief           Public key container
 */
typedef struct
{
146 147
    const pk_info_t *   pk_info;    /**< Public key informations        */
    void *              pk_ctx;     /**< Underlying public key context  */
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
} pk_context;

/**
 * \brief           Initialize a pk_context (as NONE)
 */
void pk_init( pk_context *ctx );

/**
 * \brief           Free a pk_context
 */
void pk_free( pk_context *ctx );

/**
 * \brief           Set a pk_context to a given type
 *
 * \param ctx       Context to initialize
 * \param type      Type of key
 *
166 167 168 169 170 171
 * \note            Once the type of a key has been set, it cannot be reset.
 *                  If you want to do so, you need to use pk_free() first.
 *
 * \return          O on success,
 *                  POLARSSL_ERR_PK_MALLOC_FAILED on memory allocation fail,
 *                  POLARSSL_ERR_PK_TYPE_MISMATCH on attempts to reset type.
172 173 174
 */
int pk_set_type( pk_context *ctx, pk_type_t type );

175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
/**
 * \brief           Get the size in bits of the underlying key
 *
 * \param ctx       Context to use
 *
 * \return          Key size in bits, or 0 on error
 */
size_t pk_get_size( const pk_context *ctx );

/**
 * \brief           Tell if a context can do the operation given by type
 *
 * \param ctx       Context to test
 * \param type      Target type
 *
 * \return          0 if context can't do the operations,
 *                  1 otherwise.
 */
int pk_can_do( pk_context *ctx, pk_type_t type );

/**
 * \brief           Verify signature
 *
 * \param ctx       PK context to use
 * \param hash      Hash of the message to sign
 * \param md_info   Information about the hash function used
 * \param sig       Signature to verify
 * \param sig_len   Signature length
 *
 * \return          0 on success (signature is valid),
 *                  or a specific error code.
 */
int pk_verify( pk_context *ctx,
               const unsigned char *hash, const md_info_t *md_info,
               const unsigned char *sig, size_t sig_len );

211 212 213 214 215 216 217 218 219 220
/**
 * \brief           Export debug information
 *
 * \param ctx       Context to use
 * \param items     Place to write debug items
 *
 * \return          0 on sucess or POLARSSL_ERR_PK_BAD_INPUT_DATA
 */
int pk_debug( const pk_context *ctx, pk_debug_item *items );

221 222 223 224 225 226 227 228 229
/**
 * \brief           Access the type name
 *
 * \param ctx       Context to use
 *
 * \return          Type name on success, or "invalid PK"
 */
const char * pk_get_name( const pk_context *ctx );

230 231 232 233
#ifdef __cplusplus
}
#endif

234
#endif /* POLARSSL_PK_H */