mbed TLS library
Dependents: HTTPClient-SSL WS_SERVER
pk.h File Reference
Public Key abstraction layer. More...
Go to the source code of this file.
Data Structures | |
struct | pk_rsassa_pss_options |
Options for RSASSA-PSS signature verification. More... | |
struct | pk_debug_item |
Item to send to the debug module. More... | |
struct | pk_info_t |
Public key information and operations. More... | |
struct | pk_context |
Public key container. More... | |
Typedefs | |
typedef int(* | pk_rsa_alt_decrypt_func )(void *ctx, int mode, size_t *olen, const unsigned char *input, unsigned char *output, size_t output_max_len) |
Types for RSA-alt abstraction. | |
Enumerations | |
enum | pk_type_t |
Public key types. More... | |
enum | pk_debug_type |
Types for interfacing with the debug module. More... | |
Functions | |
const pk_info_t * | pk_info_from_type (pk_type_t pk_type) |
Return information associated with the given PK type. | |
void | pk_init (pk_context *ctx) |
Initialize a pk_context (as NONE) | |
void | pk_free (pk_context *ctx) |
Free a pk_context. | |
int | pk_init_ctx (pk_context *ctx, const pk_info_t *info) |
Initialize a PK context with the information given and allocates the type-specific PK subcontext. | |
int | pk_init_ctx_rsa_alt (pk_context *ctx, void *key, pk_rsa_alt_decrypt_func decrypt_func, pk_rsa_alt_sign_func sign_func, pk_rsa_alt_key_len_func key_len_func) |
Initialize an RSA-alt context. | |
size_t | pk_get_size (const pk_context *ctx) |
Get the size in bits of the underlying key. | |
static size_t | pk_get_len (const pk_context *ctx) |
Get the length in bytes of the underlying key. | |
int | pk_can_do (pk_context *ctx, pk_type_t type) |
Tell if a context can do the operation given by type. | |
int | pk_verify (pk_context *ctx, md_type_t md_alg, const unsigned char *hash, size_t hash_len, const unsigned char *sig, size_t sig_len) |
Verify signature (including padding if relevant). | |
int | pk_verify_ext (pk_type_t type, const void *options, pk_context *ctx, md_type_t md_alg, const unsigned char *hash, size_t hash_len, const unsigned char *sig, size_t sig_len) |
Verify signature, with options. | |
int | pk_sign (pk_context *ctx, md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t *sig_len, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng) |
Make signature, including padding if relevant. | |
int | pk_decrypt (pk_context *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen, size_t osize, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng) |
Decrypt message (including padding if relevant). | |
int | pk_encrypt (pk_context *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen, size_t osize, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng) |
Encrypt message (including padding if relevant). | |
int | pk_check_pair (const pk_context *pub, const pk_context *prv) |
Check if a public-private pair of keys matches. | |
int | pk_debug (const pk_context *ctx, pk_debug_item *items) |
Export debug information. | |
const char * | pk_get_name (const pk_context *ctx) |
Access the type name. | |
pk_type_t | pk_get_type (const pk_context *ctx) |
Get the key type. | |
int | pk_parse_key (pk_context *ctx, const unsigned char *key, size_t keylen, const unsigned char *pwd, size_t pwdlen) |
Parse a private key. | |
int | pk_parse_public_key (pk_context *ctx, const unsigned char *key, size_t keylen) |
Parse a public key. | |
int | pk_parse_keyfile (pk_context *ctx, const char *path, const char *password) |
Load and parse a private key. | |
int | pk_parse_public_keyfile (pk_context *ctx, const char *path) |
Load and parse a public key. | |
int | pk_write_key_der (pk_context *ctx, unsigned char *buf, size_t size) |
Write a private key to a PKCS#1 or SEC1 DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer. | |
int | pk_write_pubkey_der (pk_context *ctx, unsigned char *buf, size_t size) |
Write a public key to a SubjectPublicKeyInfo DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer. | |
int | pk_write_pubkey_pem (pk_context *ctx, unsigned char *buf, size_t size) |
Write a public key to a PEM string. | |
int | pk_write_key_pem (pk_context *ctx, unsigned char *buf, size_t size) |
Write a private key to a PKCS#1 or SEC1 PEM string. | |
int | pk_parse_subpubkey (unsigned char **p, const unsigned char *end, pk_context *pk) |
Parse a SubjectPublicKeyInfo DER structure. | |
int | pk_write_pubkey (unsigned char **p, unsigned char *start, const pk_context *key) |
Write a subjectPublicKey to ASN.1 data Note: function works backwards in data buffer. |
Detailed Description
Public Key abstraction layer.
Public Key abstraction layer: wrapper functions.
Copyright (C) 2006-2013, ARM Limited, All Rights Reserved
This file is part of mbed TLS (https://tls.mbed.org)
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.
Definition in file pk.h.
Typedef Documentation
typedef int(* pk_rsa_alt_decrypt_func)(void *ctx, int mode, size_t *olen, const unsigned char *input, unsigned char *output, size_t output_max_len) |
Enumeration Type Documentation
enum pk_debug_type |
Function Documentation
int pk_can_do | ( | pk_context * | ctx, |
pk_type_t | type | ||
) |
int pk_check_pair | ( | const pk_context * | pub, |
const pk_context * | prv | ||
) |
int pk_debug | ( | const pk_context * | ctx, |
pk_debug_item * | items | ||
) |
int pk_decrypt | ( | pk_context * | ctx, |
const unsigned char * | input, | ||
size_t | ilen, | ||
unsigned char * | output, | ||
size_t * | olen, | ||
size_t | osize, | ||
int(*)(void *, unsigned char *, size_t) | f_rng, | ||
void * | p_rng | ||
) |
Decrypt message (including padding if relevant).
- Parameters:
-
ctx PK context to use input Input to decrypt ilen Input size output Decrypted output olen Decrypted message length osize Size of the output buffer f_rng RNG function p_rng RNG parameter
- Note:
- For RSA keys, the default padding type is PKCS#1 v1.5.
- Returns:
- 0 on success, or a specific error code.
int pk_encrypt | ( | pk_context * | ctx, |
const unsigned char * | input, | ||
size_t | ilen, | ||
unsigned char * | output, | ||
size_t * | olen, | ||
size_t | osize, | ||
int(*)(void *, unsigned char *, size_t) | f_rng, | ||
void * | p_rng | ||
) |
Encrypt message (including padding if relevant).
- Parameters:
-
ctx PK context to use input Message to encrypt ilen Message size output Encrypted output olen Encrypted output length osize Size of the output buffer f_rng RNG function p_rng RNG parameter
- Note:
- For RSA keys, the default padding type is PKCS#1 v1.5.
- Returns:
- 0 on success, or a specific error code.
void pk_free | ( | pk_context * | ctx ) |
Free a pk_context.
static size_t pk_get_len | ( | const pk_context * | ctx ) | [static] |
const char* pk_get_name | ( | const pk_context * | ctx ) |
size_t pk_get_size | ( | const pk_context * | ctx ) |
pk_type_t pk_get_type | ( | const pk_context * | ctx ) |
void pk_init | ( | pk_context * | ctx ) |
Initialize a pk_context (as NONE)
int pk_init_ctx | ( | pk_context * | ctx, |
const pk_info_t * | info | ||
) |
Initialize a PK context with the information given and allocates the type-specific PK subcontext.
- Parameters:
-
ctx Context to initialize. Must be empty (type NONE). info Information to use
- Returns:
- 0 on success, POLARSSL_ERR_PK_BAD_INPUT_DATA on invalid input, POLARSSL_ERR_PK_MALLOC_FAILED on allocation failure.
- Note:
- For contexts holding an RSA-alt key, use
pk_init_ctx_rsa_alt()
instead.
int pk_init_ctx_rsa_alt | ( | pk_context * | ctx, |
void * | key, | ||
pk_rsa_alt_decrypt_func | decrypt_func, | ||
pk_rsa_alt_sign_func | sign_func, | ||
pk_rsa_alt_key_len_func | key_len_func | ||
) |
Initialize an RSA-alt context.
- Parameters:
-
ctx Context to initialize. Must be empty (type NONE). key RSA key pointer decrypt_func Decryption function sign_func Signing function key_len_func Function returning key length in bytes
- Returns:
- 0 on success, or POLARSSL_ERR_PK_BAD_INPUT_DATA if the context wasn't already initialized as RSA_ALT.
- Note:
- This function replaces
pk_init_ctx()
for RSA-alt.
int pk_parse_key | ( | pk_context * | ctx, |
const unsigned char * | key, | ||
size_t | keylen, | ||
const unsigned char * | pwd, | ||
size_t | pwdlen | ||
) |
Parse a private key.
- Parameters:
-
ctx key to be initialized key input buffer keylen size of the buffer pwd password for decryption (optional) pwdlen size of the password
- Note:
- On entry, ctx must be empty, either freshly initialised with pk_init() or reset with pk_free(). If you need a specific key type, check the result with pk_can_do().
- The key is also checked for correctness.
- Returns:
- 0 if successful, or a specific PK or PEM error code
int pk_parse_keyfile | ( | pk_context * | ctx, |
const char * | path, | ||
const char * | password | ||
) |
Load and parse a private key.
- Parameters:
-
ctx key to be initialized path filename to read the private key from password password to decrypt the file (can be NULL)
- Note:
- On entry, ctx must be empty, either freshly initialised with pk_init() or reset with pk_free(). If you need a specific key type, check the result with pk_can_do().
- The key is also checked for correctness.
- Returns:
- 0 if successful, or a specific PK or PEM error code
int pk_parse_public_key | ( | pk_context * | ctx, |
const unsigned char * | key, | ||
size_t | keylen | ||
) |
Parse a public key.
- Parameters:
-
ctx key to be initialized key input buffer keylen size of the buffer
- Note:
- On entry, ctx must be empty, either freshly initialised with pk_init() or reset with pk_free(). If you need a specific key type, check the result with pk_can_do().
- The key is also checked for correctness.
- Returns:
- 0 if successful, or a specific PK or PEM error code
int pk_parse_public_keyfile | ( | pk_context * | ctx, |
const char * | path | ||
) |
Load and parse a public key.
- Parameters:
-
ctx key to be initialized path filename to read the private key from
- Note:
- On entry, ctx must be empty, either freshly initialised with pk_init() or reset with pk_free(). If you need a specific key type, check the result with pk_can_do().
- The key is also checked for correctness.
- Returns:
- 0 if successful, or a specific PK or PEM error code
int pk_parse_subpubkey | ( | unsigned char ** | p, |
const unsigned char * | end, | ||
pk_context * | pk | ||
) |
int pk_sign | ( | pk_context * | ctx, |
md_type_t | md_alg, | ||
const unsigned char * | hash, | ||
size_t | hash_len, | ||
unsigned char * | sig, | ||
size_t * | sig_len, | ||
int(*)(void *, unsigned char *, size_t) | f_rng, | ||
void * | p_rng | ||
) |
Make signature, including padding if relevant.
- Parameters:
-
ctx PK context to use md_alg Hash algorithm used (see notes) hash Hash of the message to sign hash_len Hash length or 0 (see notes) sig Place to write the signature sig_len Number of bytes written f_rng RNG function p_rng RNG parameter
- Returns:
- 0 on success, or a specific error code.
- Note:
- For RSA keys, the default padding type is PKCS#1 v1.5. There is no interface in the PK module to make RSASSA-PSS signatures yet.
- If hash_len is 0, then the length associated with md_alg is used instead, or an error returned if it is invalid.
- md_alg may be POLARSSL_MD_NONE, only if hash_len != 0
int pk_verify | ( | pk_context * | ctx, |
md_type_t | md_alg, | ||
const unsigned char * | hash, | ||
size_t | hash_len, | ||
const unsigned char * | sig, | ||
size_t | sig_len | ||
) |
Verify signature (including padding if relevant).
- Parameters:
-
ctx PK context to use md_alg Hash algorithm used (see notes) hash Hash of the message to sign hash_len Hash length or 0 (see notes) sig Signature to verify sig_len Signature length
- Returns:
- 0 on success (signature is valid), POLARSSL_ERR_PK_SIG_LEN_MISMATCH if the signature is valid but its actual length is less than sig_len, or a specific error code.
- Note:
- For RSA keys, the default padding type is PKCS#1 v1.5. Use
pk_verify_ext
( POLARSSL_PK_RSASSA_PSS, ... ) to verify RSASSA_PSS signatures. - If hash_len is 0, then the length associated with md_alg is used instead, or an error returned if it is invalid.
- md_alg may be POLARSSL_MD_NONE, only if hash_len != 0
int pk_verify_ext | ( | pk_type_t | type, |
const void * | options, | ||
pk_context * | ctx, | ||
md_type_t | md_alg, | ||
const unsigned char * | hash, | ||
size_t | hash_len, | ||
const unsigned char * | sig, | ||
size_t | sig_len | ||
) |
Verify signature, with options.
(Includes verification of the padding depending on type.)
- Parameters:
-
type Signature type (inc. possible padding type) to verify options Pointer to type-specific options, or NULL ctx PK context to use md_alg Hash algorithm used (see notes) hash Hash of the message to sign hash_len Hash length or 0 (see notes) sig Signature to verify sig_len Signature length
- Returns:
- 0 on success (signature is valid), POLARSSL_ERR_PK_TYPE_MISMATCH if the PK context can't be used for this type of signatures, POLARSSL_ERR_PK_SIG_LEN_MISMATCH if the signature is valid but its actual length is less than sig_len, or a specific error code.
- Note:
- If hash_len is 0, then the length associated with md_alg is used instead, or an error returned if it is invalid.
- md_alg may be POLARSSL_MD_NONE, only if hash_len != 0
- If type is POLARSSL_PK_RSASSA_PSS, then options must point to a pk_rsassa_pss_options structure, otherwise it must be NULL.
int pk_write_key_der | ( | pk_context * | ctx, |
unsigned char * | buf, | ||
size_t | size | ||
) |
Write a private key to a PKCS#1 or SEC1 DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer.
- Parameters:
-
ctx private to write away buf buffer to write to size size of the buffer
- Returns:
- length of data written if successful, or a specific error code
int pk_write_key_pem | ( | pk_context * | ctx, |
unsigned char * | buf, | ||
size_t | size | ||
) |
int pk_write_pubkey | ( | unsigned char ** | p, |
unsigned char * | start, | ||
const pk_context * | key | ||
) |
Write a subjectPublicKey to ASN.1 data Note: function works backwards in data buffer.
- Parameters:
-
p reference to current position pointer start start of the buffer (for bounds-checking) key public key to write away
- Returns:
- the length written or a negative error code
int pk_write_pubkey_der | ( | pk_context * | ctx, |
unsigned char * | buf, | ||
size_t | size | ||
) |
Write a public key to a SubjectPublicKeyInfo DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer.
- Parameters:
-
ctx public key to write away buf buffer to write to size size of the buffer
- Returns:
- length of data written if successful, or a specific error code
int pk_write_pubkey_pem | ( | pk_context * | ctx, |
unsigned char * | buf, | ||
size_t | size | ||
) |
Generated on Tue Jul 12 2022 13:50:40 by
![doxygen](doxygen.png)