libp11 header file More...

#include <openssl/bio.h>
#include <openssl/err.h>
#include <openssl/x509.h>

Data Structures
struct	PKCS11_key_st
	PKCS11 key object (public or private) More...

struct	PKCS11_cert_st
	PKCS11 certificate object. More...

struct	PKCS11_token_st
	PKCS11 token: smart card or USB key. More...

struct	PKCS11_slot_st
	PKCS11 slot: card reader. More...

struct	PKCS11_ctx_st
	PKCS11 context. More...

Macros
#define	ERR_LIB_PKCS11 ERR_LIB_USER

#define	PKCS11err(f, r) ERR_PUT_error(ERR_LIB_PKCS11,(f),(r),__FILE__,__LINE__)

#define	PKCS11_F_PKCS11_CTX_LOAD 1

#define	PKCS11_F_PKCS11_ENUM_SLOTS 2

#define	PKCS11_F_PKCS11_CHECK_TOKEN 3

#define	PKCS11_F_PKCS11_OPEN_SESSION 4

#define	PKCS11_F_PKCS11_LOGIN 5

#define	PKCS11_F_PKCS11_ENUM_KEYS 6

#define	PKCS11_F_PKCS11_GET_KEY 7

#define	PKCS11_F_PKCS11_RSA_DECRYPT 8

#define	PKCS11_F_PKCS11_RSA_ENCRYPT 9

#define	PKCS11_F_PKCS11_RSA_SIGN 10

#define	PKCS11_F_PKCS11_RSA_VERIFY 11

#define	PKCS11_F_PKCS11_ENUM_CERTS 12

#define	PKCS11_F_PKCS11_INIT_TOKEN 13

#define	PKCS11_F_PKCS11_INIT_PIN 14

#define	PKCS11_F_PKCS11_LOGOUT 15

#define	PKCS11_F_PKCS11_STORE_PRIVATE_KEY 16

#define	PKCS11_F_PKCS11_GENERATE_KEY 17

#define	PKCS11_F_PKCS11_STORE_PUBLIC_KEY 18

#define	PKCS11_F_PKCS11_STORE_CERTIFICATE 19

#define	PKCS11_F_PKCS11_SEED_RANDOM 20

#define	PKCS11_F_PKCS11_GENERATE_RANDOM 21

#define	PKCS11_F_PKCS11_CHANGE_PIN 22

#define	PKCS11_F_PKCS11_GETATTR 40

#define	PKCS11_ERR_BASE 1024

#define	PKCS11_LOAD_MODULE_ERROR (PKCS11_ERR_BASE+1)

#define	PKCS11_MODULE_LOADED_ERROR (PKCS11_ERR_BASE+2)

#define	PKCS11_SYMBOL_NOT_FOUND_ERROR (PKCS11_ERR_BASE+3)

#define	PKCS11_NOT_SUPPORTED (PKCS11_ERR_BASE+4)

#define	PKCS11_NO_SESSION (PKCS11_ERR_BASE+5)

#define	PKCS11_KEYGEN_FAILED (PKCS11_ERR_BASE+6)

Typedefs
typedef struct PKCS11_key_st	PKCS11_KEY
	PKCS11 key object (public or private)

typedef struct PKCS11_cert_st	PKCS11_CERT
	PKCS11 certificate object.

typedef struct PKCS11_token_st	PKCS11_TOKEN
	PKCS11 token: smart card or USB key.

typedef struct PKCS11_slot_st	PKCS11_SLOT
	PKCS11 slot: card reader.

typedef struct PKCS11_ctx_st	PKCS11_CTX
	PKCS11 context.

Functions
PKCS11_CTX *	PKCS11_CTX_new (void)
	Create a new libp11 context.

void	PKCS11_CTX_init_args (PKCS11_CTX ctx, const char init_args)
	Specify any private PKCS#11 module initializtion args, if necessary.

int	PKCS11_CTX_load (PKCS11_CTX ctx, const char ident)
	Load a PKCS#11 module.

void	PKCS11_CTX_unload (PKCS11_CTX *ctx)
	Unload a PKCS#11 module.

void	PKCS11_CTX_free (PKCS11_CTX *ctx)
	Free a libp11 context.

int	PKCS11_open_session (PKCS11_SLOT *slot, int rw)
	Open a session in RO or RW mode.

int	PKCS11_enumerate_slots (PKCS11_CTX ctx, PKCS11_SLOT slotsp, unsigned int nslotsp)
	Get a list of all slots.

unsigned long	PKCS11_get_slotid_from_slot (PKCS11_SLOT *slotp)
	Get the slot_id from a slot as it is stored in private.

void	PKCS11_release_all_slots (PKCS11_CTX ctx, PKCS11_SLOT slots, unsigned int nslots)
	Free the list of slots allocated by PKCS11_enumerate_slots()

PKCS11_SLOT *	PKCS11_find_token (PKCS11_CTX ctx, PKCS11_SLOT slots, unsigned int nslots)
	Find the first slot with a token.

int	PKCS11_login (PKCS11_SLOT slot, int so, const char pin)
	Authenticate to the card.

int	PKCS11_logout (PKCS11_SLOT *slot)
	De-authenticate from the card.

int	PKCS11_enumerate_keys (PKCS11_TOKEN , PKCS11_KEY , unsigned int )

int	PKCS11_get_key_type (PKCS11_KEY *)

int	PKCS11_get_key_size (const PKCS11_KEY *)

int	PKCS11_get_key_modulus (PKCS11_KEY , BIGNUM *)

int	PKCS11_get_key_exponent (PKCS11_KEY , BIGNUM *)

EVP_PKEY *	PKCS11_get_private_key (PKCS11_KEY *key)
	Returns a EVP_PKEY object for the private key.

EVP_PKEY *	PKCS11_get_public_key (PKCS11_KEY *key)
	Returns a EVP_PKEY object with the public key.

PKCS11_CERT *	PKCS11_find_certificate (PKCS11_KEY *)

PKCS11_KEY *	PKCS11_find_key (PKCS11_CERT *)

int	PKCS11_enumerate_certs (PKCS11_TOKEN , PKCS11_CERT , unsigned int )

int	PKCS11_init_token (PKCS11_TOKEN token, const char pin, const char *label)
	Initialize a token.

int	PKCS11_init_pin (PKCS11_TOKEN token, const char pin)
	Initialize the user PIN on a token.

int	PKCS11_change_pin (PKCS11_SLOT slot, const char old_pin, const char *new_pin)
	Change the user PIN on a token.

int	PKCS11_generate_key (PKCS11_TOKEN token, int algorithm, unsigned int bits, char label, unsigned char *id, size_t id_len)
	Generate and store a private key on the token.

int	PKCS11_store_private_key (PKCS11_TOKEN token, EVP_PKEY pk, char label, unsigned char id, size_t id_len)
	Store private key on a token.

int	PKCS11_store_public_key (PKCS11_TOKEN token, EVP_PKEY pk, char label, unsigned char id, size_t id_len)
	Store public key on a token.

int	PKCS11_store_certificate (PKCS11_TOKEN token, X509 x509, char label, unsigned char id, size_t id_len, PKCS11_CERT **ret_cert)
	Store certificate on a token.

int	PKCS11_sign (int type, const unsigned char m, unsigned int m_len, unsigned char sigret, unsigned int siglen, const PKCS11_KEY key)

int	PKCS11_private_encrypt (int flen, const unsigned char from, unsigned char to, const PKCS11_KEY *rsa, int padding)

int	PKCS11_private_decrypt (int flen, const unsigned char from, unsigned char to, PKCS11_KEY *key, int padding)
	Decrypts data using the private key.

int	PKCS11_verify (int type, const unsigned char m, unsigned int m_len, unsigned char signature, unsigned int siglen, PKCS11_KEY *key)

int	PKCS11_seed_random (PKCS11_SLOT , const unsigned char s, unsigned int s_len)

int	PKCS11_generate_random (PKCS11_SLOT , unsigned char r, unsigned int r_len)

RSA_METHOD *	PKCS11_get_rsa_method (void)

void	ERR_load_PKCS11_strings (void)
	Load PKCS11 error strings.

Detailed Description

libp11 header file

Definition in file libp11.h.

Function Documentation

void ERR_load_PKCS11_strings ( void )

Load PKCS11 error strings.

Call this function to be able to use ERR_reason_error_string(ERR_get_error()) to get an textual version of the latest error code

int PKCS11_change_pin	(	PKCS11_SLOT *	slot,
		const char *	old_pin,
		const char *	new_pin
	)

Change the user PIN on a token.

Parameters

slot	slot returned by PKCS11_find_token()
old_pin	old PIN value
new_pin	new PIN value

Return values

0	success
-1	error

void PKCS11_CTX_free ( PKCS11_CTX * ctx )

Free a libp11 context.

Parameters

ctx	context allocated by PKCS11_CTX_new()

void PKCS11_CTX_init_args	(	PKCS11_CTX *	ctx,
		const char *	init_args
	)

Specify any private PKCS#11 module initializtion args, if necessary.

Returns: none

int PKCS11_CTX_load	(	PKCS11_CTX *	ctx,
		const char *	ident
	)

Load a PKCS#11 module.

Parameters

ctx	context allocated by PKCS11_CTX_new()
ident	PKCS#11 library filename

Return values

0	success
-1	error

PKCS11_CTX* PKCS11_CTX_new ( void )

Create a new libp11 context.

This should be the first function called in the use of libp11

Returns: an allocated context

void PKCS11_CTX_unload ( PKCS11_CTX * ctx )

Unload a PKCS#11 module.

Parameters

ctx	context allocated by PKCS11_CTX_new()

int PKCS11_enumerate_slots	(	PKCS11_CTX *	ctx,
		PKCS11_SLOT **	slotsp,
		unsigned int *	nslotsp
	)

Get a list of all slots.

Parameters

ctx	context allocated by PKCS11_CTX_new()
slotsp	pointer on a list of slots
nslotsp	size of the allocated list

Return values

0	success
-1	error

PKCS11_SLOT* PKCS11_find_token	(	PKCS11_CTX *	ctx,
		PKCS11_SLOT *	slots,
		unsigned int	nslots
	)

Find the first slot with a token.

Parameters

ctx	context allocated by PKCS11_CTX_new()
slots	list of slots allocated by PKCS11_enumerate_slots()
nslots	size of the list

Return values

!=NULL	pointer on a slot structure
NULL	error

int PKCS11_generate_key	(	PKCS11_TOKEN *	token,
		int	algorithm,
		unsigned int	bits,
		char *	label,
		unsigned char *	id,
		size_t	id_len
	)

Generate and store a private key on the token.

Parameters

token	token returned by PKCS11_find_token()
algorithm	EVP_PKEY_RSA
bits	size of the modulus in bits
label	label for this key
id	bytes to use as id value
id_len	length of id value.

Return values

0	success
-1	error

EVP_PKEY* PKCS11_get_private_key ( PKCS11_KEY * key )

Returns a EVP_PKEY object for the private key.

Parameters

key	PKCS11_KEY object

Return values

!=NULL	reference to EVP_PKEY object. The returned EVP_PKEY object should be treated as const and must not be freed.
NULL	error

EVP_PKEY* PKCS11_get_public_key ( PKCS11_KEY * key )

Returns a EVP_PKEY object with the public key.

Parameters

key	PKCS11_KEY object

Return values

!=NULL	reference to EVP_PKEY object. The returned EVP_PKEY object should be treated as const and must not be freed.
NULL	error

unsigned long PKCS11_get_slotid_from_slot ( PKCS11_SLOT * slotp )

Get the slot_id from a slot as it is stored in private.

Parameters

slotp pointer on a slot

Return values

the slotid

int PKCS11_init_pin	(	PKCS11_TOKEN *	token,
		const char *	pin
	)

Initialize the user PIN on a token.

Parameters

token	token descriptor (in general slot->token)
pin	new user PIN value

Return values

0	success
-1	error

int PKCS11_init_token	(	PKCS11_TOKEN *	token,
		const char *	pin,
		const char *	label
	)

Initialize a token.

Parameters

token	token descriptor (in general slot->token)
pin	Security Officer PIN value
label	new name of the token

Return values

0	success
-1	error

int PKCS11_login	(	PKCS11_SLOT *	slot,
		int	so,
		const char *	pin
	)

Authenticate to the card.

Parameters

slot	slot returned by PKCS11_find_token()
so	login as CKU_SO if != 0, otherwise login as CKU_USER
pin	PIN value

Return values

0	success
-1	error

int PKCS11_logout ( PKCS11_SLOT * slot )

De-authenticate from the card.

Parameters

slot	slot returned by PKCS11_find_token()

Return values

0	success
-1	error

int PKCS11_open_session	(	PKCS11_SLOT *	slot,
		int	rw
	)

Open a session in RO or RW mode.

Parameters

slot	slot descriptor returned by PKCS11_find_token() or PKCS11_enumerate_slots()
rw	open in read/write mode is mode != 0, otherwise in read only mode

Return values

0	success
-1	error

int PKCS11_private_decrypt	(	int	flen,
		const unsigned char *	from,
		unsigned char *	to,
		PKCS11_KEY *	key,
		int	padding
	)

Decrypts data using the private key.

Parameters

flen	length of the encrypted data
from	encrypted data
to	output buffer (MUST be a least flen bytes long)
key	private key object
padding	padding algorithm to be used

Returns: the length of the decrypted data or 0 if an error occurred

void PKCS11_release_all_slots	(	PKCS11_CTX *	ctx,
		PKCS11_SLOT *	slots,
		unsigned int	nslots
	)

Free the list of slots allocated by PKCS11_enumerate_slots()

Parameters

ctx	context allocated by PKCS11_CTX_new()
slots	list of slots allocated by PKCS11_enumerate_slots()
nslots	size of the list

int PKCS11_store_certificate	(	PKCS11_TOKEN *	token,
		X509 *	x509,
		char *	label,
		unsigned char *	id,
		size_t	id_len,
		PKCS11_CERT **	ret_cert
	)

Store certificate on a token.

Parameters

token	token returned by PKCS11_find_token()
x509	x509 certificate object
label	label for this certificate
id	bytes to use as id value
id_len	length of id value.
ret_cert	put new PKCS11_CERT object here

Return values

0	success
-1	error

int PKCS11_store_private_key	(	PKCS11_TOKEN *	token,
		EVP_PKEY *	pk,
		char *	label,
		unsigned char *	id,
		size_t	id_len
	)

Store private key on a token.

Parameters

token	token returned by PKCS11_find_token()
pk	private key
label	label for this key
id	bytes to use as id value
id_len	length of id value.

Return values

0	success
-1	error

int PKCS11_store_public_key	(	PKCS11_TOKEN *	token,
		EVP_PKEY *	pk,
		char *	label,
		unsigned char *	id,
		size_t	id_len
	)

Store public key on a token.

Parameters

token	token returned by PKCS11_find_token()
pk	private key
label	label for this key
id	bytes to use as id value
id_len	length of id value.

Return values

0	success
-1	error

Data Structures

Macros

Typedefs

Functions

Detailed Description

Function Documentation