src/libpolarssl/pk.h

   1 /**
   2  * \file pk.h
   3  *
   4  * \brief Public Key abstraction layer
   5  *
   6  *  Copyright (C) 2006-2013, Brainspark B.V.
   7  *
   8  *  This file is part of PolarSSL (http://www.polarssl.org)
   9  *  Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
  10  *
  11  *  All rights reserved.
  12  *
  13  *  This program is free software; you can redistribute it and/or modify
  14  *  it under the terms of the GNU General Public License as published by
  15  *  the Free Software Foundation; either version 2 of the License, or
  16  *  (at your option) any later version.
  17  *
  18  *  This program is distributed in the hope that it will be useful,
  19  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  *  GNU General Public License for more details.
  22  *
  23  *  You should have received a copy of the GNU General Public License along
  24  *  with this program; if not, write to the Free Software Foundation, Inc.,
  25  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  26  */
  27
  28 #ifndef POLARSSL_PK_H
  29 #define POLARSSL_PK_H
  30
  31 #if !defined(POLARSSL_CONFIG_FILE)
  32 #include "config.h"
  33 #else
  34 #include POLARSSL_CONFIG_FILE
  35 #endif
  36
  37 #include "md.h"
  38
  39 #if defined(POLARSSL_RSA_C)
  40 #include "rsa.h"
  41 #endif
  42
  43 #if defined(POLARSSL_ECP_C)
  44 #include "ecp.h"
  45 #endif
  46
  47 #if defined(POLARSSL_ECDSA_C)
  48 #include "ecdsa.h"
  49 #endif
  50
  51 #define POLARSSL_ERR_PK_MALLOC_FAILED       -0x2F80  /**< Memory alloation failed. */
  52 #define POLARSSL_ERR_PK_TYPE_MISMATCH       -0x2F00  /**< Type mismatch, eg attempt to encrypt with an ECDSA key */
  53 #define POLARSSL_ERR_PK_BAD_INPUT_DATA      -0x2E80  /**< Bad input parameters to function. */
  54 #define POLARSSL_ERR_PK_FILE_IO_ERROR       -0x2E00  /**< Read/write of file failed. */
  55 #define POLARSSL_ERR_PK_KEY_INVALID_VERSION -0x2D80  /**< Unsupported key version */
  56 #define POLARSSL_ERR_PK_KEY_INVALID_FORMAT  -0x2D00  /**< Invalid key tag or value. */
  57 #define POLARSSL_ERR_PK_UNKNOWN_PK_ALG      -0x2C80  /**< Key algorithm is unsupported (only RSA and EC are supported). */
  58 #define POLARSSL_ERR_PK_PASSWORD_REQUIRED   -0x2C00  /**< Private key password can't be empty. */
  59 #define POLARSSL_ERR_PK_PASSWORD_MISMATCH   -0x2B80  /**< Given private key password does not allow for correct decryption. */
  60 #define POLARSSL_ERR_PK_INVALID_PUBKEY      -0x2B00  /**< The pubkey tag or value is invalid (only RSA and EC are supported). */
  61 #define POLARSSL_ERR_PK_INVALID_ALG         -0x2A80  /**< The algorithm tag or value is invalid. */
  62 #define POLARSSL_ERR_PK_UNKNOWN_NAMED_CURVE -0x2A00  /**< Elliptic curve is unsupported (only NIST curves are supported). */
  63 #define POLARSSL_ERR_PK_FEATURE_UNAVAILABLE -0x2980  /**< Unavailable feature, e.g. RSA disabled for RSA key. */
  64 #define POLARSSL_ERR_PK_SIG_LEN_MISMATCH    -0x2000  /**< The signature is valid but its length is less than expected. */
  65
  66
  67 #if defined(POLARSSL_RSA_C)
  68 /**
  69  * Quick access to an RSA context inside a PK context.
  70  *
  71  * \warning You must make sure the PK context actually holds an RSA context
  72  * before using this macro!
  73  */
  74 #define pk_rsa( pk )        ( (rsa_context *) (pk).pk_ctx )
  75 #endif /* POLARSSL_RSA_C */
  76
  77 #if defined(POLARSSL_ECP_C)
  78 /**
  79  * Quick access to an EC context inside a PK context.
  80  *
  81  * \warning You must make sure the PK context actually holds an EC context
  82  * before using this macro!
  83  */
  84 #define pk_ec( pk )         ( (ecp_keypair *) (pk).pk_ctx )
  85 #endif /* POLARSSL_ECP_C */
  86
  87
  88 #ifdef __cplusplus
  89 extern "C" {
  90 #endif
  91
  92 /**
  93  * \brief          Public key types
  94  */
  95 typedef enum {
  96     POLARSSL_PK_NONE=0,
  97     POLARSSL_PK_RSA,
  98     POLARSSL_PK_ECKEY,
  99     POLARSSL_PK_ECKEY_DH,
 100     POLARSSL_PK_ECDSA,
 101     POLARSSL_PK_RSA_ALT,
 102 } pk_type_t;
 103
 104 /**
 105  * \brief           Types for interfacing with the debug module
 106  */
 107 typedef enum
 108 {
 109     POLARSSL_PK_DEBUG_NONE = 0,
 110     POLARSSL_PK_DEBUG_MPI,
 111     POLARSSL_PK_DEBUG_ECP,
 112 } pk_debug_type;
 113
 114 /**
 115  * \brief           Item to send to the debug module
 116  */
 117 typedef struct
 118 {
 119     pk_debug_type type;
 120     const char *name;
 121     void *value;
 122 } pk_debug_item;
 123
 124 /** Maximum number of item send for debugging, plus 1 */
 125 #define POLARSSL_PK_DEBUG_MAX_ITEMS 3
 126
 127 /**
 128  * \brief           Public key information and operations
 129  */
 130 typedef struct
 131 {
 132     /** Public key type */
 133     pk_type_t type;
 134
 135     /** Type name */
 136     const char *name;
 137
 138     /** Get key size in bits */
 139     size_t (*get_size)( const void * );
 140
 141     /** Tell if the context implements this type (e.g. ECKEY can do ECDSA) */
 142     int (*can_do)( pk_type_t type );
 143
 144     /** Verify signature */
 145     int (*verify_func)( void *ctx, md_type_t md_alg,
 146                         const unsigned char *hash, size_t hash_len,
 147                         const unsigned char *sig, size_t sig_len );
 148
 149     /** Make signature */
 150     int (*sign_func)( void *ctx, md_type_t md_alg,
 151                       const unsigned char *hash, size_t hash_len,
 152                       unsigned char *sig, size_t *sig_len,
 153                       int (*f_rng)(void *, unsigned char *, size_t),
 154                       void *p_rng );
 155
 156     /** Decrypt message */
 157     int (*decrypt_func)( void *ctx, const unsigned char *input, size_t ilen,
 158                          unsigned char *output, size_t *olen, size_t osize,
 159                          int (*f_rng)(void *, unsigned char *, size_t),
 160                          void *p_rng );
 161
 162     /** Encrypt message */
 163     int (*encrypt_func)( void *ctx, const unsigned char *input, size_t ilen,
 164                          unsigned char *output, size_t *olen, size_t osize,
 165                          int (*f_rng)(void *, unsigned char *, size_t),
 166                          void *p_rng );
 167
 168     /** Allocate a new context */
 169     void * (*ctx_alloc_func)( void );
 170
 171     /** Free the given context */
 172     void (*ctx_free_func)( void *ctx );
 173
 174     /** Interface with the debug module */
 175     void (*debug_func)( const void *ctx, pk_debug_item *items );
 176
 177 } pk_info_t;
 178
 179 /**
 180  * \brief           Public key container
 181  */
 182 typedef struct
 183 {
 184     const pk_info_t *   pk_info;    /**< Public key informations        */
 185     void *              pk_ctx;     /**< Underlying public key context  */
 186 } pk_context;
 187
 188 /**
 189  * \brief           Types for RSA-alt abstraction
 190  */
 191 typedef int (*pk_rsa_alt_decrypt_func)( void *ctx, int mode, size_t *olen,
 192                     const unsigned char *input, unsigned char *output,
 193                     size_t output_max_len );
 194 typedef int (*pk_rsa_alt_sign_func)( void *ctx,
 195                     int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
 196                     int mode, md_type_t md_alg, unsigned int hashlen,
 197                     const unsigned char *hash, unsigned char *sig );
 198 typedef size_t (*pk_rsa_alt_key_len_func)( void *ctx );
 199
 200 /**
 201  * \brief           Return information associated with the given PK type
 202  *
 203  * \param pk_type   PK type to search for.
 204  *
 205  * \return          The PK info associated with the type or NULL if not found.
 206  */
 207 const pk_info_t *pk_info_from_type( pk_type_t pk_type );
 208
 209 /**
 210  * \brief           Initialize a pk_context (as NONE)
 211  */
 212 void pk_init( pk_context *ctx );
 213
 214 /**
 215  * \brief           Free a pk_context
 216  */
 217 void pk_free( pk_context *ctx );
 218
 219 /**
 220  * \brief           Initialize a PK context with the information given
 221  *                  and allocates the type-specific PK subcontext.
 222  *
 223  * \param ctx       Context to initialize. Must be empty (type NONE).
 224  * \param info      Information to use
 225  *
 226  * \return          0 on success,
 227  *                  POLARSSL_ERR_PK_BAD_INPUT_DATA on invalid input,
 228  *                  POLARSSL_ERR_PK_MALLOC_FAILED on allocation failure.
 229  *
 230  * \note            For contexts holding an RSA-alt key, use
 231  *                  \c pk_init_ctx_rsa_alt() instead.
 232  */
 233 int pk_init_ctx( pk_context *ctx, const pk_info_t *info );
 234
 235 /**
 236  * \brief           Initialize an RSA-alt context
 237  *
 238  * \param ctx       Context to initialize. Must be empty (type NONE).
 239  * \param key       RSA key pointer
 240  * \param decrypt_func  Decryption function
 241  * \param sign_func     Signing function
 242  * \param key_len_func  Function returning key length in bytes
 243  *
 244  * \return          0 on success, or POLARSSL_ERR_PK_BAD_INPUT_DATA if the
 245  *                  context wasn't already initialized as RSA_ALT.
 246  *
 247  * \note            This function replaces \c pk_init_ctx() for RSA-alt.
 248  */
 249 int pk_init_ctx_rsa_alt( pk_context *ctx, void * key,
 250                          pk_rsa_alt_decrypt_func decrypt_func,
 251                          pk_rsa_alt_sign_func sign_func,
 252                          pk_rsa_alt_key_len_func key_len_func );
 253
 254 /**
 255  * \brief           Get the size in bits of the underlying key
 256  *
 257  * \param ctx       Context to use
 258  *
 259  * \return          Key size in bits, or 0 on error
 260  */
 261 size_t pk_get_size( const pk_context *ctx );
 262
 263 /**
 264  * \brief           Get the length in bytes of the underlying key
 265  * \param ctx       Context to use
 266  *
 267  * \return          Key length in bytes, or 0 on error
 268  */
 269 static inline size_t pk_get_len( const pk_context *ctx )
 270 {
 271     return( ( pk_get_size( ctx ) + 7 ) / 8 );
 272 }
 273
 274 /**
 275  * \brief           Tell if a context can do the operation given by type
 276  *
 277  * \param ctx       Context to test
 278  * \param type      Target type
 279  *
 280  * \return          0 if context can't do the operations,
 281  *                  1 otherwise.
 282  */
 283 int pk_can_do( pk_context *ctx, pk_type_t type );
 284
 285 /**
 286  * \brief           Verify signature
 287  *
 288  * \param ctx       PK context to use
 289  * \param md_alg    Hash algorithm used (see notes)
 290  * \param hash      Hash of the message to sign
 291  * \param hash_len  Hash length or 0 (see notes)
 292  * \param sig       Signature to verify
 293  * \param sig_len   Signature length
 294  *
 295  * \return          0 on success (signature is valid),
 296  *                  POLARSSL_ERR_PK_SIG_LEN_MISMATCH if the signature is
 297  *                  valid but its actual length is less than sig_len,
 298  *                  or a specific error code.
 299  *
 300  * \note            If hash_len is 0, then the length associated with md_alg
 301  *                  is used instead, or an error returned if it is invalid.
 302  *
 303  * \note            md_alg may be POLARSSL_MD_NONE, only if hash_len != 0
 304  */
 305 int pk_verify( pk_context *ctx, md_type_t md_alg,
 306                const unsigned char *hash, size_t hash_len,
 307                const unsigned char *sig, size_t sig_len );
 308
 309 /**
 310  * \brief           Make signature
 311  *
 312  * \param ctx       PK context to use
 313  * \param md_alg    Hash algorithm used (see notes)
 314  * \param hash      Hash of the message to sign
 315  * \param hash_len  Hash length or 0 (see notes)
 316  * \param sig       Place to write the signature
 317  * \param sig_len   Number of bytes written
 318  * \param f_rng     RNG function
 319  * \param p_rng     RNG parameter
 320  *
 321  * \return          0 on success, or a specific error code.
 322  *
 323  * \note            If hash_len is 0, then the length associated with md_alg
 324  *                  is used instead, or an error returned if it is invalid.
 325  *
 326  * \note            md_alg may be POLARSSL_MD_NONE, only if hash_len != 0
 327  */
 328 int pk_sign( pk_context *ctx, md_type_t md_alg,
 329              const unsigned char *hash, size_t hash_len,
 330              unsigned char *sig, size_t *sig_len,
 331              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
 332
 333 /**
 334  * \brief           Decrypt message
 335  *
 336  * \param ctx       PK context to use
 337  * \param input     Input to decrypt
 338  * \param ilen      Input size
 339  * \param output    Decrypted output
 340  * \param olen      Decrypted message length
 341  * \param osize     Size of the output buffer
 342  * \param f_rng     RNG function
 343  * \param p_rng     RNG parameter
 344  *
 345  * \return          0 on success, or a specific error code.
 346  */
 347 int pk_decrypt( pk_context *ctx,
 348                 const unsigned char *input, size_t ilen,
 349                 unsigned char *output, size_t *olen, size_t osize,
 350                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
 351
 352 /**
 353  * \brief           Encrypt message
 354  *
 355  * \param ctx       PK context to use
 356  * \param input     Message to encrypt
 357  * \param ilen      Message size
 358  * \param output    Encrypted output
 359  * \param olen      Encrypted output length
 360  * \param osize     Size of the output buffer
 361  * \param f_rng     RNG function
 362  * \param p_rng     RNG parameter
 363  *
 364  * \return          0 on success, or a specific error code.
 365  */
 366 int pk_encrypt( pk_context *ctx,
 367                 const unsigned char *input, size_t ilen,
 368                 unsigned char *output, size_t *olen, size_t osize,
 369                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
 370
 371 /**
 372  * \brief           Export debug information
 373  *
 374  * \param ctx       Context to use
 375  * \param items     Place to write debug items
 376  *
 377  * \return          0 on success or POLARSSL_ERR_PK_BAD_INPUT_DATA
 378  */
 379 int pk_debug( const pk_context *ctx, pk_debug_item *items );
 380
 381 /**
 382  * \brief           Access the type name
 383  *
 384  * \param ctx       Context to use
 385  *
 386  * \return          Type name on success, or "invalid PK"
 387  */
 388 const char * pk_get_name( const pk_context *ctx );
 389
 390 /**
 391  * \brief           Get the key type
 392  *
 393  * \param ctx       Context to use
 394  *
 395  * \return          Type on success, or POLARSSL_PK_NONE
 396  */
 397 pk_type_t pk_get_type( const pk_context *ctx );
 398
 399 #if defined(POLARSSL_PK_PARSE_C)
 400 /** \ingroup pk_module */
 401 /**
 402  * \brief           Parse a private key
 403  *
 404  * \param ctx       key to be initialized
 405  * \param key       input buffer
 406  * \param keylen    size of the buffer
 407  * \param pwd       password for decryption (optional)
 408  * \param pwdlen    size of the password
 409  *
 410  * \note            On entry, ctx must be empty, either freshly initialised
 411  *                  with pk_init() or reset with pk_free(). If you need a
 412  *                  specific key type, check the result with pk_can_do().
 413  *
 414  * \note            The key is also checked for correctness.
 415  *
 416  * \return          0 if successful, or a specific PK or PEM error code
 417  */
 418 int pk_parse_key( pk_context *ctx,
 419                   const unsigned char *key, size_t keylen,
 420                   const unsigned char *pwd, size_t pwdlen );
 421
 422 /** \ingroup pk_module */
 423 /**
 424  * \brief           Parse a public key
 425  *
 426  * \param ctx       key to be initialized
 427  * \param key       input buffer
 428  * \param keylen    size of the buffer
 429  *
 430  * \note            On entry, ctx must be empty, either freshly initialised
 431  *                  with pk_init() or reset with pk_free(). If you need a
 432  *                  specific key type, check the result with pk_can_do().
 433  *
 434  * \note            The key is also checked for correctness.
 435  *
 436  * \return          0 if successful, or a specific PK or PEM error code
 437  */
 438 int pk_parse_public_key( pk_context *ctx,
 439                          const unsigned char *key, size_t keylen );
 440
 441 #if defined(POLARSSL_FS_IO)
 442 /** \ingroup pk_module */
 443 /**
 444  * \brief           Load and parse a private key
 445  *
 446  * \param ctx       key to be initialized
 447  * \param path      filename to read the private key from
 448  * \param password  password to decrypt the file (can be NULL)
 449  *
 450  * \note            On entry, ctx must be empty, either freshly initialised
 451  *                  with pk_init() or reset with pk_free(). If you need a
 452  *                  specific key type, check the result with pk_can_do().
 453  *
 454  * \note            The key is also checked for correctness.
 455  *
 456  * \return          0 if successful, or a specific PK or PEM error code
 457  */
 458 int pk_parse_keyfile( pk_context *ctx,
 459                       const char *path, const char *password );
 460
 461 /** \ingroup pk_module */
 462 /**
 463  * \brief           Load and parse a public key
 464  *
 465  * \param ctx       key to be initialized
 466  * \param path      filename to read the private key from
 467  *
 468  * \note            On entry, ctx must be empty, either freshly initialised
 469  *                  with pk_init() or reset with pk_free(). If you need a
 470  *                  specific key type, check the result with pk_can_do().
 471  *
 472  * \note            The key is also checked for correctness.
 473  *
 474  * \return          0 if successful, or a specific PK or PEM error code
 475  */
 476 int pk_parse_public_keyfile( pk_context *ctx, const char *path );
 477 #endif /* POLARSSL_FS_IO */
 478 #endif /* POLARSSL_PK_PARSE_C */
 479
 480 #if defined(POLARSSL_PK_WRITE_C)
 481 /**
 482  * \brief           Write a private key to a PKCS#1 or SEC1 DER structure
 483  *                  Note: data is written at the end of the buffer! Use the
 484  *                        return value to determine where you should start
 485  *                        using the buffer
 486  *
 487  * \param ctx       private to write away
 488  * \param buf       buffer to write to
 489  * \param size      size of the buffer
 490  *
 491  * \return          length of data written if successful, or a specific
 492  *                  error code
 493  */
 494 int pk_write_key_der( pk_context *ctx, unsigned char *buf, size_t size );
 495
 496 /**
 497  * \brief           Write a public key to a SubjectPublicKeyInfo DER structure
 498  *                  Note: data is written at the end of the buffer! Use the
 499  *                        return value to determine where you should start
 500  *                        using the buffer
 501  *
 502  * \param ctx       public key to write away
 503  * \param buf       buffer to write to
 504  * \param size      size of the buffer
 505  *
 506  * \return          length of data written if successful, or a specific
 507  *                  error code
 508  */
 509 int pk_write_pubkey_der( pk_context *ctx, unsigned char *buf, size_t size );
 510
 511 #if defined(POLARSSL_PEM_WRITE_C)
 512 /**
 513  * \brief           Write a public key to a PEM string
 514  *
 515  * \param ctx       public key to write away
 516  * \param buf       buffer to write to
 517  * \param size      size of the buffer
 518  *
 519  * \return          0 successful, or a specific error code
 520  */
 521 int pk_write_pubkey_pem( pk_context *ctx, unsigned char *buf, size_t size );
 522
 523 /**
 524  * \brief           Write a private key to a PKCS#1 or SEC1 PEM string
 525  *
 526  * \param ctx       private to write away
 527  * \param buf       buffer to write to
 528  * \param size      size of the buffer
 529  *
 530  * \return          0 successful, or a specific error code
 531  */
 532 int pk_write_key_pem( pk_context *ctx, unsigned char *buf, size_t size );
 533 #endif /* POLARSSL_PEM_WRITE_C */
 534 #endif /* POLARSSL_PK_WRITE_C */
 535
 536 /*
 537  * WARNING: Low-level functions. You probably do not want to use these unless
 538  *          you are certain you do ;)
 539  */
 540
 541 #if defined(POLARSSL_PK_PARSE_C)
 542 /**
 543  * \brief           Parse a SubjectPublicKeyInfo DER structure
 544  *
 545  * \param p         the position in the ASN.1 data
 546  * \param end       end of the buffer
 547  * \param pk        the key to fill
 548  *
 549  * \return          0 if successful, or a specific PK error code
 550  */
 551 int pk_parse_subpubkey( unsigned char **p, const unsigned char *end,
 552                         pk_context *pk );
 553 #endif /* POLARSSL_PK_PARSE_C */
 554
 555 #if defined(POLARSSL_PK_WRITE_C)
 556 /**
 557  * \brief           Write a subjectPublicKey to ASN.1 data
 558  *                  Note: function works backwards in data buffer
 559  *
 560  * \param p         reference to current position pointer
 561  * \param start     start of the buffer (for bounds-checking)
 562  * \param key       public key to write away
 563  *
 564  * \return          the length written or a negative error code
 565  */
 566 int pk_write_pubkey( unsigned char **p, unsigned char *start,
 567                      const pk_context *key );
 568 #endif /* POLARSSL_PK_WRITE_C */
 569
 570 #ifdef __cplusplus
 571 }
 572 #endif
 573
 574 #endif /* POLARSSL_PK_H */