mbed TLS v2.2.0
Data Structures | Macros | Typedefs | Enumerations | Functions
pk.h File Reference

Detailed Description

Public Key abstraction layer.

Public Key abstraction layer: wrapper functions.

Copyright (C) 2006-2015, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of mbed TLS (https://tls.mbed.org)

Definition in file pk.h.

#include <config-sl-crypto-all-acceleration.h>
#include "md.h"
Include dependency graph for pk.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  mbedtls_pk_rsassa_pss_options
 Options for RSASSA-PSS signature verification. More...
 
struct  mbedtls_pk_debug_item
 Item to send to the debug module. More...
 
struct  mbedtls_pk_context
 Public key container. More...
 

Macros

#define MBEDTLS_ERR_PK_ALLOC_FAILED   -0x3F80
 Memory allocation failed. More...
 
#define MBEDTLS_ERR_PK_TYPE_MISMATCH   -0x3F00
 Type mismatch, eg attempt to encrypt with an ECDSA key. More...
 
#define MBEDTLS_ERR_PK_BAD_INPUT_DATA   -0x3E80
 Bad input parameters to function. More...
 
#define MBEDTLS_ERR_PK_FILE_IO_ERROR   -0x3E00
 Read/write of file failed. More...
 
#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION   -0x3D80
 Unsupported key version. More...
 
#define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT   -0x3D00
 Invalid key tag or value. More...
 
#define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG   -0x3C80
 Key algorithm is unsupported (only RSA and EC are supported). More...
 
#define MBEDTLS_ERR_PK_PASSWORD_REQUIRED   -0x3C00
 Private key password can't be empty. More...
 
#define MBEDTLS_ERR_PK_PASSWORD_MISMATCH   -0x3B80
 Given private key password does not allow for correct decryption. More...
 
#define MBEDTLS_ERR_PK_INVALID_PUBKEY   -0x3B00
 The pubkey tag or value is invalid (only RSA and EC are supported). More...
 
#define MBEDTLS_ERR_PK_INVALID_ALG   -0x3A80
 The algorithm tag or value is invalid. More...
 
#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE   -0x3A00
 Elliptic curve is unsupported (only NIST curves are supported). More...
 
#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE   -0x3980
 Unavailable feature, e.g. More...
 
#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH   -0x3900
 The signature is valid but its length is less than expected. More...
 
#define MBEDTLS_PK_DEBUG_MAX_ITEMS   3
 Maximum number of item send for debugging, plus 1. More...
 

Typedefs

typedef struct mbedtls_pk_info_t mbedtls_pk_info_t
 Public key information and operations. More...
 

Enumerations

enum  mbedtls_pk_type_t {
  MBEDTLS_PK_NONE =0, MBEDTLS_PK_RSA, MBEDTLS_PK_ECKEY, MBEDTLS_PK_ECKEY_DH,
  MBEDTLS_PK_ECDSA, MBEDTLS_PK_RSA_ALT, MBEDTLS_PK_RSASSA_PSS
}
 Public key types. More...
 
enum  mbedtls_pk_debug_type { MBEDTLS_PK_DEBUG_NONE = 0, MBEDTLS_PK_DEBUG_MPI, MBEDTLS_PK_DEBUG_ECP }
 Types for interfacing with the debug module. More...
 

Functions

const mbedtls_pk_info_tmbedtls_pk_info_from_type (mbedtls_pk_type_t pk_type)
 Return information associated with the given PK type. More...
 
void mbedtls_pk_init (mbedtls_pk_context *ctx)
 Initialize a mbedtls_pk_context (as NONE) More...
 
void mbedtls_pk_free (mbedtls_pk_context *ctx)
 Free a mbedtls_pk_context. More...
 
int mbedtls_pk_setup (mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info)
 Initialize a PK context with the information given and allocates the type-specific PK subcontext. More...
 
size_t mbedtls_pk_get_bitlen (const mbedtls_pk_context *ctx)
 Get the size in bits of the underlying key. More...
 
static size_t mbedtls_pk_get_len (const mbedtls_pk_context *ctx)
 Get the length in bytes of the underlying key. More...
 
int mbedtls_pk_can_do (const mbedtls_pk_context *ctx, mbedtls_pk_type_t type)
 Tell if a context can do the operation given by type. More...
 
int mbedtls_pk_verify (mbedtls_pk_context *ctx, mbedtls_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). More...
 
int mbedtls_pk_verify_ext (mbedtls_pk_type_t type, const void *options, mbedtls_pk_context *ctx, mbedtls_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. More...
 
int mbedtls_pk_sign (mbedtls_pk_context *ctx, mbedtls_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. More...
 
int mbedtls_pk_decrypt (mbedtls_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). More...
 
int mbedtls_pk_encrypt (mbedtls_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). More...
 
int mbedtls_pk_check_pair (const mbedtls_pk_context *pub, const mbedtls_pk_context *prv)
 Check if a public-private pair of keys matches. More...
 
int mbedtls_pk_debug (const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items)
 Export debug information. More...
 
const char * mbedtls_pk_get_name (const mbedtls_pk_context *ctx)
 Access the type name. More...
 
mbedtls_pk_type_t mbedtls_pk_get_type (const mbedtls_pk_context *ctx)
 Get the key type. More...
 

Macro Definition Documentation

#define MBEDTLS_ERR_PK_ALLOC_FAILED   -0x3F80

Memory allocation failed.

Definition at line 52 of file pk.h.

#define MBEDTLS_ERR_PK_BAD_INPUT_DATA   -0x3E80

Bad input parameters to function.

Definition at line 54 of file pk.h.

#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE   -0x3980

Unavailable feature, e.g.

RSA disabled for RSA key.

Definition at line 64 of file pk.h.

#define MBEDTLS_ERR_PK_FILE_IO_ERROR   -0x3E00

Read/write of file failed.

Definition at line 55 of file pk.h.

#define MBEDTLS_ERR_PK_INVALID_ALG   -0x3A80

The algorithm tag or value is invalid.

Definition at line 62 of file pk.h.

#define MBEDTLS_ERR_PK_INVALID_PUBKEY   -0x3B00

The pubkey tag or value is invalid (only RSA and EC are supported).

Definition at line 61 of file pk.h.

#define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT   -0x3D00

Invalid key tag or value.

Definition at line 57 of file pk.h.

#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION   -0x3D80

Unsupported key version.

Definition at line 56 of file pk.h.

#define MBEDTLS_ERR_PK_PASSWORD_MISMATCH   -0x3B80

Given private key password does not allow for correct decryption.

Definition at line 60 of file pk.h.

#define MBEDTLS_ERR_PK_PASSWORD_REQUIRED   -0x3C00

Private key password can't be empty.

Definition at line 59 of file pk.h.

#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH   -0x3900

The signature is valid but its length is less than expected.

Definition at line 65 of file pk.h.

#define MBEDTLS_ERR_PK_TYPE_MISMATCH   -0x3F00

Type mismatch, eg attempt to encrypt with an ECDSA key.

Definition at line 53 of file pk.h.

#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE   -0x3A00

Elliptic curve is unsupported (only NIST curves are supported).

Definition at line 63 of file pk.h.

#define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG   -0x3C80

Key algorithm is unsupported (only RSA and EC are supported).

Definition at line 58 of file pk.h.

#define MBEDTLS_PK_DEBUG_MAX_ITEMS   3

Maximum number of item send for debugging, plus 1.

Definition at line 116 of file pk.h.

Typedef Documentation

Public key information and operations.

Definition at line 121 of file pk.h.

Enumeration Type Documentation

Types for interfacing with the debug module.

Enumerator
MBEDTLS_PK_DEBUG_NONE 
MBEDTLS_PK_DEBUG_MPI 
MBEDTLS_PK_DEBUG_ECP 

Definition at line 98 of file pk.h.

Public key types.

Enumerator
MBEDTLS_PK_NONE 
MBEDTLS_PK_RSA 
MBEDTLS_PK_ECKEY 
MBEDTLS_PK_ECKEY_DH 
MBEDTLS_PK_ECDSA 
MBEDTLS_PK_RSA_ALT 
MBEDTLS_PK_RSASSA_PSS 

Definition at line 74 of file pk.h.

Function Documentation

int mbedtls_pk_can_do ( const mbedtls_pk_context ctx,
mbedtls_pk_type_t  type 
)

Tell if a context can do the operation given by type.

Parameters
ctxContext to test
typeTarget type
Returns
0 if context can't do the operations, 1 otherwise.
int mbedtls_pk_check_pair ( const mbedtls_pk_context pub,
const mbedtls_pk_context prv 
)

Check if a public-private pair of keys matches.

Parameters
pubContext holding a public key.
prvContext holding a private (and public) key.
Returns
0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
int mbedtls_pk_debug ( const mbedtls_pk_context ctx,
mbedtls_pk_debug_item items 
)

Export debug information.

Parameters
ctxContext to use
itemsPlace to write debug items
Returns
0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
int mbedtls_pk_decrypt ( mbedtls_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
ctxPK context to use - must hold a private key
inputInput to decrypt
ilenInput size
outputDecrypted output
olenDecrypted message length
osizeSize of the output buffer
f_rngRNG function
p_rngRNG parameter
Note
For RSA keys, the default padding type is PKCS#1 v1.5.
Returns
0 on success, or a specific error code.
int mbedtls_pk_encrypt ( mbedtls_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
ctxPK context to use
inputMessage to encrypt
ilenMessage size
outputEncrypted output
olenEncrypted output length
osizeSize of the output buffer
f_rngRNG function
p_rngRNG parameter
Note
For RSA keys, the default padding type is PKCS#1 v1.5.
Returns
0 on success, or a specific error code.
void mbedtls_pk_free ( mbedtls_pk_context ctx)
size_t mbedtls_pk_get_bitlen ( const mbedtls_pk_context ctx)

Get the size in bits of the underlying key.

Parameters
ctxContext to use
Returns
Key size in bits, or 0 on error

Referenced by mbedtls_pk_get_len().

static size_t mbedtls_pk_get_len ( const mbedtls_pk_context ctx)
inlinestatic

Get the length in bytes of the underlying key.

Parameters
ctxContext to use
Returns
Key length in bytes, or 0 on error

Definition at line 243 of file pk.h.

References mbedtls_pk_get_bitlen().

const char* mbedtls_pk_get_name ( const mbedtls_pk_context ctx)

Access the type name.

Parameters
ctxContext to use
Returns
Type name on success, or "invalid PK"
mbedtls_pk_type_t mbedtls_pk_get_type ( const mbedtls_pk_context ctx)

Get the key type.

Parameters
ctxContext to use
Returns
Type on success, or MBEDTLS_PK_NONE
const mbedtls_pk_info_t* mbedtls_pk_info_from_type ( mbedtls_pk_type_t  pk_type)

Return information associated with the given PK type.

Parameters
pk_typePK type to search for.
Returns
The PK info associated with the type or NULL if not found.
void mbedtls_pk_init ( mbedtls_pk_context ctx)

Initialize a mbedtls_pk_context (as NONE)

int mbedtls_pk_setup ( mbedtls_pk_context ctx,
const mbedtls_pk_info_t info 
)

Initialize a PK context with the information given and allocates the type-specific PK subcontext.

Parameters
ctxContext to initialize. Must be empty (type NONE).
infoInformation to use
Returns
0 on success, MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input, MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
Note
For contexts holding an RSA-alt key, use mbedtls_pk_setup_rsa_alt() instead.
int mbedtls_pk_sign ( mbedtls_pk_context ctx,
mbedtls_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
ctxPK context to use - must hold a private key
md_algHash algorithm used (see notes)
hashHash of the message to sign
hash_lenHash length or 0 (see notes)
sigPlace to write the signature
sig_lenNumber of bytes written
f_rngRNG function
p_rngRNG 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.
For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0. For ECDSA, md_alg may never be MBEDTLS_MD_NONE.
int mbedtls_pk_verify ( mbedtls_pk_context ctx,
mbedtls_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
ctxPK context to use
md_algHash algorithm used (see notes)
hashHash of the message to sign
hash_lenHash length or 0 (see notes)
sigSignature to verify
sig_lenSignature length
Returns
0 on success (signature is valid), MBEDTLS_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 mbedtls_pk_verify_ext( MBEDTLS_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 MBEDTLS_MD_NONE, only if hash_len != 0
int mbedtls_pk_verify_ext ( mbedtls_pk_type_t  type,
const void *  options,
mbedtls_pk_context ctx,
mbedtls_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
typeSignature type (inc. possible padding type) to verify
optionsPointer to type-specific options, or NULL
ctxPK context to use
md_algHash algorithm used (see notes)
hashHash of the message to sign
hash_lenHash length or 0 (see notes)
sigSignature to verify
sig_lenSignature length
Returns
0 on success (signature is valid), MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be used for this type of signatures, MBEDTLS_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 MBEDTLS_MD_NONE, only if hash_len != 0
If type is MBEDTLS_PK_RSASSA_PSS, then options must point to a mbedtls_pk_rsassa_pss_options structure, otherwise it must be NULL.