Public Key abstraction layer. More...

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.

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)

Types for RSA-alt abstraction.

Definition at line 203 of file pk.h.

Enumeration Type Documentation

enum pk_debug_type

Types for interfacing with the debug module.

Definition at line 116 of file pk.h.

enum pk_type_t

Public key types.

Definition at line 92 of file pk.h.

Function Documentation

int pk_can_do	(	pk_context *	ctx,
		pk_type_t	type
	)

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

Parameters:

ctx	Context to test
type	Target type

Returns:: 0 if context can't do the operations, 1 otherwise.

Definition at line 147 of file pk.c.

int pk_check_pair	(	const pk_context *	pub,
		const pk_context *	prv
	)

Check if a public-private pair of keys matches.

Parameters:

pub	Context holding a public key.
prv	Context holding a private (and public) key.

Returns:: 0 on success or POLARSSL_ERR_PK_BAD_INPUT_DATA

Definition at line 302 of file pk.c.

int pk_debug	(	const pk_context *	ctx,
		pk_debug_item *	items
	)

Export debug information.

Parameters:

ctx	Context to use
items	Place to write debug items

Returns:: 0 on success or POLARSSL_ERR_PK_BAD_INPUT_DATA

Definition at line 339 of file pk.c.

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.

Definition at line 266 of file pk.c.

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.

Definition at line 284 of file pk.c.

void pk_free ( pk_context * ctx )

Free a pk_context.

Definition at line 63 of file pk.c.

static size_t pk_get_len ( const pk_context * ctx ) [static]

Get the length in bytes of the underlying key.

Parameters:

ctx	Context to use

Returns:: Key length in bytes, or 0 on error

Definition at line 281 of file pk.h.

const char* pk_get_name ( const pk_context * ctx )

Access the type name.

Parameters:

ctx	Context to use

Returns:: Type name on success, or "invalid PK"

Definition at line 354 of file pk.c.

size_t pk_get_size ( const pk_context * ctx )

Get the size in bits of the underlying key.

Parameters:

ctx	Context to use

Returns:: Key size in bits, or 0 on error

Definition at line 328 of file pk.c.

pk_type_t pk_get_type ( const pk_context * ctx )

Get the key type.

Parameters:

ctx	Context to use

Returns:: Type on success, or POLARSSL_PK_NONE

Definition at line 365 of file pk.c.

const pk_info_t* pk_info_from_type ( pk_type_t pk_type )

Return information associated with the given PK type.

Parameters:

pk_type PK type to search for.

Returns:: The PK info associated with the type or NULL if not found.

Definition at line 76 of file pk.c.

void pk_init ( pk_context * ctx )

Initialize a pk_context (as NONE)

Definition at line 51 of file pk.c.

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.

Definition at line 102 of file pk.c.

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.

Definition at line 118 of file pk.c.

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

Definition at line 1053 of file pkparse.c.

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

Definition at line 115 of file pkparse.c.

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

Definition at line 1224 of file pkparse.c.

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

Definition at line 140 of file pkparse.c.

int pk_parse_subpubkey	(	unsigned char **	p,
		const unsigned char *	end,
		pk_context *	pk
	)

Parse a SubjectPublicKeyInfo DER structure.

Parameters:

p	the position in the ASN.1 data
end	end of the buffer
pk	the key to fill

Returns:: 0 if successful, or a specific PK error code

Definition at line 573 of file pkparse.c.

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

Definition at line 247 of file pk.c.

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

Definition at line 176 of file pk.c.

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.

Definition at line 194 of file pk.c.

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

Definition at line 200 of file pkwrite.c.

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.

Parameters:

ctx	private to write away
buf	buffer to write to
size	size of the buffer

Returns:: 0 successful, or a specific error code

Definition at line 401 of file pkwrite.c.

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

Definition at line 131 of file pkwrite.c.

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

Definition at line 152 of file pkwrite.c.

int pk_write_pubkey_pem	(	pk_context *	ctx,
		unsigned char *	buf,
		size_t	size
	)

Write a public key to a PEM string.

Parameters:

ctx	public key to write away
buf	buffer to write to
size	size of the buffer

Returns:: 0 successful, or a specific error code

Definition at line 379 of file pkwrite.c.

Type:	Library
Created:	11 Jun 2015
Imports:	10
Forks:	0
Commits:	1
Dependents:	2
Dependencies:	0
Followers:	1

pk.h File Reference

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

pk.h File Reference

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning