Hannes Tschofenig
/
aes-gcm-test-program
Example program to test AES-GCM functionality. Used for a workshop
Embed:
(wiki syntax)
Show/hide line numbers
pk.h
Go to the documentation of this file.
00001 /** 00002 * \file pk.h 00003 * 00004 * \brief Public Key abstraction layer 00005 * 00006 * Copyright (C) 2006-2013, Brainspark B.V. 00007 * 00008 * This file is part of PolarSSL (http://www.polarssl.org) 00009 * Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org> 00010 * 00011 * All rights reserved. 00012 * 00013 * This program is free software; you can redistribute it and/or modify 00014 * it under the terms of the GNU General Public License as published by 00015 * the Free Software Foundation; either version 2 of the License, or 00016 * (at your option) any later version. 00017 * 00018 * This program is distributed in the hope that it will be useful, 00019 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00020 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00021 * GNU General Public License for more details. 00022 * 00023 * You should have received a copy of the GNU General Public License along 00024 * with this program; if not, write to the Free Software Foundation, Inc., 00025 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 00026 */ 00027 00028 #ifndef POLARSSL_PK_H 00029 #define POLARSSL_PK_H 00030 00031 #if !defined(POLARSSL_CONFIG_FILE) 00032 #include "config.h" 00033 #else 00034 #include POLARSSL_CONFIG_FILE 00035 #endif 00036 00037 #include "md.h" 00038 00039 #if defined(POLARSSL_RSA_C) 00040 #include "rsa.h" 00041 #endif 00042 00043 #if defined(POLARSSL_ECP_C) 00044 #include "ecp.h" 00045 #endif 00046 00047 #if defined(POLARSSL_ECDSA_C) 00048 #include "ecdsa.h" 00049 #endif 00050 00051 #define POLARSSL_ERR_PK_MALLOC_FAILED -0x2F80 /**< Memory alloation failed. */ 00052 #define POLARSSL_ERR_PK_TYPE_MISMATCH -0x2F00 /**< Type mismatch, eg attempt to encrypt with an ECDSA key */ 00053 #define POLARSSL_ERR_PK_BAD_INPUT_DATA -0x2E80 /**< Bad input parameters to function. */ 00054 #define POLARSSL_ERR_PK_FILE_IO_ERROR -0x2E00 /**< Read/write of file failed. */ 00055 #define POLARSSL_ERR_PK_KEY_INVALID_VERSION -0x2D80 /**< Unsupported key version */ 00056 #define POLARSSL_ERR_PK_KEY_INVALID_FORMAT -0x2D00 /**< Invalid key tag or value. */ 00057 #define POLARSSL_ERR_PK_UNKNOWN_PK_ALG -0x2C80 /**< Key algorithm is unsupported (only RSA and EC are supported). */ 00058 #define POLARSSL_ERR_PK_PASSWORD_REQUIRED -0x2C00 /**< Private key password can't be empty. */ 00059 #define POLARSSL_ERR_PK_PASSWORD_MISMATCH -0x2B80 /**< Given private key password does not allow for correct decryption. */ 00060 #define POLARSSL_ERR_PK_INVALID_PUBKEY -0x2B00 /**< The pubkey tag or value is invalid (only RSA and EC are supported). */ 00061 #define POLARSSL_ERR_PK_INVALID_ALG -0x2A80 /**< The algorithm tag or value is invalid. */ 00062 #define POLARSSL_ERR_PK_UNKNOWN_NAMED_CURVE -0x2A00 /**< Elliptic curve is unsupported (only NIST curves are supported). */ 00063 #define POLARSSL_ERR_PK_FEATURE_UNAVAILABLE -0x2980 /**< Unavailable feature, e.g. RSA disabled for RSA key. */ 00064 #define POLARSSL_ERR_PK_SIG_LEN_MISMATCH -0x2000 /**< The signature is valid but its length is less than expected. */ 00065 00066 00067 #if defined(POLARSSL_RSA_C) 00068 /** 00069 * Quick access to an RSA context inside a PK context. 00070 * 00071 * \warning You must make sure the PK context actually holds an RSA context 00072 * before using this macro! 00073 */ 00074 #define pk_rsa( pk ) ( (rsa_context *) (pk).pk_ctx ) 00075 #endif /* POLARSSL_RSA_C */ 00076 00077 #if defined(POLARSSL_ECP_C) 00078 /** 00079 * Quick access to an EC context inside a PK context. 00080 * 00081 * \warning You must make sure the PK context actually holds an EC context 00082 * before using this macro! 00083 */ 00084 #define pk_ec( pk ) ( (ecp_keypair *) (pk).pk_ctx ) 00085 #endif /* POLARSSL_ECP_C */ 00086 00087 00088 #ifdef __cplusplus 00089 extern "C" { 00090 #endif 00091 00092 /** 00093 * \brief Public key types 00094 */ 00095 typedef enum { 00096 POLARSSL_PK_NONE=0, 00097 POLARSSL_PK_RSA, 00098 POLARSSL_PK_ECKEY, 00099 POLARSSL_PK_ECKEY_DH, 00100 POLARSSL_PK_ECDSA, 00101 POLARSSL_PK_RSA_ALT, 00102 } pk_type_t; 00103 00104 /** 00105 * \brief Types for interfacing with the debug module 00106 */ 00107 typedef enum 00108 { 00109 POLARSSL_PK_DEBUG_NONE = 0, 00110 POLARSSL_PK_DEBUG_MPI, 00111 POLARSSL_PK_DEBUG_ECP, 00112 } pk_debug_type; 00113 00114 /** 00115 * \brief Item to send to the debug module 00116 */ 00117 typedef struct 00118 { 00119 pk_debug_type type; 00120 const char *name; 00121 void *value; 00122 } pk_debug_item; 00123 00124 /** Maximum number of item send for debugging, plus 1 */ 00125 #define POLARSSL_PK_DEBUG_MAX_ITEMS 3 00126 00127 /** 00128 * \brief Public key information and operations 00129 */ 00130 typedef struct 00131 { 00132 /** Public key type */ 00133 pk_type_t type; 00134 00135 /** Type name */ 00136 const char *name; 00137 00138 /** Get key size in bits */ 00139 size_t (*get_size)( const void * ); 00140 00141 /** Tell if the context implements this type (e.g. ECKEY can do ECDSA) */ 00142 int (*can_do)( pk_type_t type ); 00143 00144 /** Verify signature */ 00145 int (*verify_func)( void *ctx, md_type_t md_alg, 00146 const unsigned char *hash, size_t hash_len, 00147 const unsigned char *sig, size_t sig_len ); 00148 00149 /** Make signature */ 00150 int (*sign_func)( void *ctx, md_type_t md_alg, 00151 const unsigned char *hash, size_t hash_len, 00152 unsigned char *sig, size_t *sig_len, 00153 int (*f_rng)(void *, unsigned char *, size_t), 00154 void *p_rng ); 00155 00156 /** Decrypt message */ 00157 int (*decrypt_func)( void *ctx, const unsigned char *input, size_t ilen, 00158 unsigned char *output, size_t *olen, size_t osize, 00159 int (*f_rng)(void *, unsigned char *, size_t), 00160 void *p_rng ); 00161 00162 /** Encrypt message */ 00163 int (*encrypt_func)( void *ctx, const unsigned char *input, size_t ilen, 00164 unsigned char *output, size_t *olen, size_t osize, 00165 int (*f_rng)(void *, unsigned char *, size_t), 00166 void *p_rng ); 00167 00168 /** Allocate a new context */ 00169 void * (*ctx_alloc_func)( void ); 00170 00171 /** Free the given context */ 00172 void (*ctx_free_func)( void *ctx ); 00173 00174 /** Interface with the debug module */ 00175 void (*debug_func)( const void *ctx, pk_debug_item *items ); 00176 00177 } pk_info_t; 00178 00179 /** 00180 * \brief Public key container 00181 */ 00182 typedef struct 00183 { 00184 const pk_info_t * pk_info; /**< Public key informations */ 00185 void * pk_ctx; /**< Underlying public key context */ 00186 } pk_context; 00187 00188 /** 00189 * \brief Types for RSA-alt abstraction 00190 */ 00191 typedef int (*pk_rsa_alt_decrypt_func)( void *ctx, int mode, size_t *olen, 00192 const unsigned char *input, unsigned char *output, 00193 size_t output_max_len ); 00194 typedef int (*pk_rsa_alt_sign_func)( void *ctx, 00195 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng, 00196 int mode, md_type_t md_alg, unsigned int hashlen, 00197 const unsigned char *hash, unsigned char *sig ); 00198 typedef size_t (*pk_rsa_alt_key_len_func)( void *ctx ); 00199 00200 /** 00201 * \brief Return information associated with the given PK type 00202 * 00203 * \param pk_type PK type to search for. 00204 * 00205 * \return The PK info associated with the type or NULL if not found. 00206 */ 00207 const pk_info_t *pk_info_from_type( pk_type_t pk_type ); 00208 00209 /** 00210 * \brief Initialize a pk_context (as NONE) 00211 */ 00212 void pk_init( pk_context *ctx ); 00213 00214 /** 00215 * \brief Free a pk_context 00216 */ 00217 void pk_free( pk_context *ctx ); 00218 00219 /** 00220 * \brief Initialize a PK context with the information given 00221 * and allocates the type-specific PK subcontext. 00222 * 00223 * \param ctx Context to initialize. Must be empty (type NONE). 00224 * \param info Information to use 00225 * 00226 * \return 0 on success, 00227 * POLARSSL_ERR_PK_BAD_INPUT_DATA on invalid input, 00228 * POLARSSL_ERR_PK_MALLOC_FAILED on allocation failure. 00229 * 00230 * \note For contexts holding an RSA-alt key, use 00231 * \c pk_init_ctx_rsa_alt() instead. 00232 */ 00233 int pk_init_ctx( pk_context *ctx, const pk_info_t *info ); 00234 00235 /** 00236 * \brief Initialize an RSA-alt context 00237 * 00238 * \param ctx Context to initialize. Must be empty (type NONE). 00239 * \param key RSA key pointer 00240 * \param decrypt_func Decryption function 00241 * \param sign_func Signing function 00242 * \param key_len_func Function returning key length in bytes 00243 * 00244 * \return 0 on success, or POLARSSL_ERR_PK_BAD_INPUT_DATA if the 00245 * context wasn't already initialized as RSA_ALT. 00246 * 00247 * \note This function replaces \c pk_init_ctx() for RSA-alt. 00248 */ 00249 int pk_init_ctx_rsa_alt( pk_context *ctx, void * key, 00250 pk_rsa_alt_decrypt_func decrypt_func, 00251 pk_rsa_alt_sign_func sign_func, 00252 pk_rsa_alt_key_len_func key_len_func ); 00253 00254 /** 00255 * \brief Get the size in bits of the underlying key 00256 * 00257 * \param ctx Context to use 00258 * 00259 * \return Key size in bits, or 0 on error 00260 */ 00261 size_t pk_get_size( const pk_context *ctx ); 00262 00263 /** 00264 * \brief Get the length in bytes of the underlying key 00265 * \param ctx Context to use 00266 * 00267 * \return Key length in bytes, or 0 on error 00268 */ 00269 static inline size_t pk_get_len( const pk_context *ctx ) 00270 { 00271 return( ( pk_get_size( ctx ) + 7 ) / 8 ); 00272 } 00273 00274 /** 00275 * \brief Tell if a context can do the operation given by type 00276 * 00277 * \param ctx Context to test 00278 * \param type Target type 00279 * 00280 * \return 0 if context can't do the operations, 00281 * 1 otherwise. 00282 */ 00283 int pk_can_do( pk_context *ctx, pk_type_t type ); 00284 00285 /** 00286 * \brief Verify signature 00287 * 00288 * \param ctx PK context to use 00289 * \param md_alg Hash algorithm used (see notes) 00290 * \param hash Hash of the message to sign 00291 * \param hash_len Hash length or 0 (see notes) 00292 * \param sig Signature to verify 00293 * \param sig_len Signature length 00294 * 00295 * \return 0 on success (signature is valid), 00296 * POLARSSL_ERR_PK_SIG_LEN_MISMATCH if the signature is 00297 * valid but its actual length is less than sig_len, 00298 * or a specific error code. 00299 * 00300 * \note If hash_len is 0, then the length associated with md_alg 00301 * is used instead, or an error returned if it is invalid. 00302 * 00303 * \note md_alg may be POLARSSL_MD_NONE, only if hash_len != 0 00304 */ 00305 int pk_verify( pk_context *ctx, md_type_t md_alg, 00306 const unsigned char *hash, size_t hash_len, 00307 const unsigned char *sig, size_t sig_len ); 00308 00309 /** 00310 * \brief Make signature 00311 * 00312 * \param ctx PK context to use 00313 * \param md_alg Hash algorithm used (see notes) 00314 * \param hash Hash of the message to sign 00315 * \param hash_len Hash length or 0 (see notes) 00316 * \param sig Place to write the signature 00317 * \param sig_len Number of bytes written 00318 * \param f_rng RNG function 00319 * \param p_rng RNG parameter 00320 * 00321 * \return 0 on success, or a specific error code. 00322 * 00323 * \note If hash_len is 0, then the length associated with md_alg 00324 * is used instead, or an error returned if it is invalid. 00325 * 00326 * \note md_alg may be POLARSSL_MD_NONE, only if hash_len != 0 00327 */ 00328 int pk_sign( pk_context *ctx, md_type_t md_alg, 00329 const unsigned char *hash, size_t hash_len, 00330 unsigned char *sig, size_t *sig_len, 00331 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); 00332 00333 /** 00334 * \brief Decrypt message 00335 * 00336 * \param ctx PK context to use 00337 * \param input Input to decrypt 00338 * \param ilen Input size 00339 * \param output Decrypted output 00340 * \param olen Decrypted message length 00341 * \param osize Size of the output buffer 00342 * \param f_rng RNG function 00343 * \param p_rng RNG parameter 00344 * 00345 * \return 0 on success, or a specific error code. 00346 */ 00347 int pk_decrypt( pk_context *ctx, 00348 const unsigned char *input, size_t ilen, 00349 unsigned char *output, size_t *olen, size_t osize, 00350 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); 00351 00352 /** 00353 * \brief Encrypt message 00354 * 00355 * \param ctx PK context to use 00356 * \param input Message to encrypt 00357 * \param ilen Message size 00358 * \param output Encrypted output 00359 * \param olen Encrypted output length 00360 * \param osize Size of the output buffer 00361 * \param f_rng RNG function 00362 * \param p_rng RNG parameter 00363 * 00364 * \return 0 on success, or a specific error code. 00365 */ 00366 int pk_encrypt( pk_context *ctx, 00367 const unsigned char *input, size_t ilen, 00368 unsigned char *output, size_t *olen, size_t osize, 00369 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); 00370 00371 /** 00372 * \brief Export debug information 00373 * 00374 * \param ctx Context to use 00375 * \param items Place to write debug items 00376 * 00377 * \return 0 on success or POLARSSL_ERR_PK_BAD_INPUT_DATA 00378 */ 00379 int pk_debug( const pk_context *ctx, pk_debug_item *items ); 00380 00381 /** 00382 * \brief Access the type name 00383 * 00384 * \param ctx Context to use 00385 * 00386 * \return Type name on success, or "invalid PK" 00387 */ 00388 const char * pk_get_name( const pk_context *ctx ); 00389 00390 /** 00391 * \brief Get the key type 00392 * 00393 * \param ctx Context to use 00394 * 00395 * \return Type on success, or POLARSSL_PK_NONE 00396 */ 00397 pk_type_t pk_get_type( const pk_context *ctx ); 00398 00399 #if defined(POLARSSL_PK_PARSE_C) 00400 /** \ingroup pk_module */ 00401 /** 00402 * \brief Parse a private key 00403 * 00404 * \param ctx key to be initialized 00405 * \param key input buffer 00406 * \param keylen size of the buffer 00407 * \param pwd password for decryption (optional) 00408 * \param pwdlen size of the password 00409 * 00410 * \note On entry, ctx must be empty, either freshly initialised 00411 * with pk_init() or reset with pk_free(). If you need a 00412 * specific key type, check the result with pk_can_do(). 00413 * 00414 * \note The key is also checked for correctness. 00415 * 00416 * \return 0 if successful, or a specific PK or PEM error code 00417 */ 00418 int pk_parse_key( pk_context *ctx, 00419 const unsigned char *key, size_t keylen, 00420 const unsigned char *pwd, size_t pwdlen ); 00421 00422 /** \ingroup pk_module */ 00423 /** 00424 * \brief Parse a public key 00425 * 00426 * \param ctx key to be initialized 00427 * \param key input buffer 00428 * \param keylen size of the buffer 00429 * 00430 * \note On entry, ctx must be empty, either freshly initialised 00431 * with pk_init() or reset with pk_free(). If you need a 00432 * specific key type, check the result with pk_can_do(). 00433 * 00434 * \note The key is also checked for correctness. 00435 * 00436 * \return 0 if successful, or a specific PK or PEM error code 00437 */ 00438 int pk_parse_public_key( pk_context *ctx, 00439 const unsigned char *key, size_t keylen ); 00440 00441 #if defined(POLARSSL_FS_IO) 00442 /** \ingroup pk_module */ 00443 /** 00444 * \brief Load and parse a private key 00445 * 00446 * \param ctx key to be initialized 00447 * \param path filename to read the private key from 00448 * \param password password to decrypt the file (can be NULL) 00449 * 00450 * \note On entry, ctx must be empty, either freshly initialised 00451 * with pk_init() or reset with pk_free(). If you need a 00452 * specific key type, check the result with pk_can_do(). 00453 * 00454 * \note The key is also checked for correctness. 00455 * 00456 * \return 0 if successful, or a specific PK or PEM error code 00457 */ 00458 int pk_parse_keyfile( pk_context *ctx, 00459 const char *path, const char *password ); 00460 00461 /** \ingroup pk_module */ 00462 /** 00463 * \brief Load and parse a public key 00464 * 00465 * \param ctx key to be initialized 00466 * \param path filename to read the private key from 00467 * 00468 * \note On entry, ctx must be empty, either freshly initialised 00469 * with pk_init() or reset with pk_free(). If you need a 00470 * specific key type, check the result with pk_can_do(). 00471 * 00472 * \note The key is also checked for correctness. 00473 * 00474 * \return 0 if successful, or a specific PK or PEM error code 00475 */ 00476 int pk_parse_public_keyfile( pk_context *ctx, const char *path ); 00477 #endif /* POLARSSL_FS_IO */ 00478 #endif /* POLARSSL_PK_PARSE_C */ 00479 00480 #if defined(POLARSSL_PK_WRITE_C) 00481 /** 00482 * \brief Write a private key to a PKCS#1 or SEC1 DER structure 00483 * Note: data is written at the end of the buffer! Use the 00484 * return value to determine where you should start 00485 * using the buffer 00486 * 00487 * \param ctx private to write away 00488 * \param buf buffer to write to 00489 * \param size size of the buffer 00490 * 00491 * \return length of data written if successful, or a specific 00492 * error code 00493 */ 00494 int pk_write_key_der( pk_context *ctx, unsigned char *buf, size_t size ); 00495 00496 /** 00497 * \brief Write a public key to a SubjectPublicKeyInfo DER structure 00498 * Note: data is written at the end of the buffer! Use the 00499 * return value to determine where you should start 00500 * using the buffer 00501 * 00502 * \param ctx public key to write away 00503 * \param buf buffer to write to 00504 * \param size size of the buffer 00505 * 00506 * \return length of data written if successful, or a specific 00507 * error code 00508 */ 00509 int pk_write_pubkey_der( pk_context *ctx, unsigned char *buf, size_t size ); 00510 00511 #if defined(POLARSSL_PEM_WRITE_C) 00512 /** 00513 * \brief Write a public key to a PEM string 00514 * 00515 * \param ctx public key to write away 00516 * \param buf buffer to write to 00517 * \param size size of the buffer 00518 * 00519 * \return 0 successful, or a specific error code 00520 */ 00521 int pk_write_pubkey_pem( pk_context *ctx, unsigned char *buf, size_t size ); 00522 00523 /** 00524 * \brief Write a private key to a PKCS#1 or SEC1 PEM string 00525 * 00526 * \param ctx private to write away 00527 * \param buf buffer to write to 00528 * \param size size of the buffer 00529 * 00530 * \return 0 successful, or a specific error code 00531 */ 00532 int pk_write_key_pem( pk_context *ctx, unsigned char *buf, size_t size ); 00533 #endif /* POLARSSL_PEM_WRITE_C */ 00534 #endif /* POLARSSL_PK_WRITE_C */ 00535 00536 /* 00537 * WARNING: Low-level functions. You probably do not want to use these unless 00538 * you are certain you do ;) 00539 */ 00540 00541 #if defined(POLARSSL_PK_PARSE_C) 00542 /** 00543 * \brief Parse a SubjectPublicKeyInfo DER structure 00544 * 00545 * \param p the position in the ASN.1 data 00546 * \param end end of the buffer 00547 * \param pk the key to fill 00548 * 00549 * \return 0 if successful, or a specific PK error code 00550 */ 00551 int pk_parse_subpubkey( unsigned char **p, const unsigned char *end, 00552 pk_context *pk ); 00553 #endif /* POLARSSL_PK_PARSE_C */ 00554 00555 #if defined(POLARSSL_PK_WRITE_C) 00556 /** 00557 * \brief Write a subjectPublicKey to ASN.1 data 00558 * Note: function works backwards in data buffer 00559 * 00560 * \param p reference to current position pointer 00561 * \param start start of the buffer (for bounds-checking) 00562 * \param key public key to write away 00563 * 00564 * \return the length written or a negative error code 00565 */ 00566 int pk_write_pubkey( unsigned char **p, unsigned char *start, 00567 const pk_context *key ); 00568 #endif /* POLARSSL_PK_WRITE_C */ 00569 00570 #ifdef __cplusplus 00571 } 00572 #endif 00573 00574 #endif /* POLARSSL_PK_H */ 00575 00576
Generated on Tue Jul 12 2022 19:40:19 by 1.7.2