libp11  0.4.12
Data Structures | Macros | Typedefs | Functions
libp11.h File Reference

libp11 header file More...

#include "p11_err.h"
#include <openssl/bio.h>
#include <openssl/err.h>
#include <openssl/bn.h>
#include <openssl/rsa.h>
#include <openssl/x509.h>
#include <openssl/evp.h>

Go to the source code of this file.

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 CKRerr(f, r)   ERR_CKR_error((f),(r),__FILE__,__LINE__)
 
#define P11_DEPRECATED(msg)
 
#define P11_DEPRECATED_FUNC   P11_DEPRECATED("This function will be removed in libp11 0.5.0")
 
#define CKR_F_PKCS11_CHANGE_PIN   100
 
#define CKR_F_PKCS11_CHECK_TOKEN   101
 
#define CKR_F_PKCS11_CTX_LOAD   102
 
#define CKR_F_PKCS11_ECDH_DERIVE   103
 
#define CKR_F_PKCS11_ECDSA_SIGN   104
 
#define CKR_F_PKCS11_ENUMERATE_SLOTS   105
 
#define CKR_F_PKCS11_FIND_CERTS   106
 
#define CKR_F_PKCS11_FIND_KEYS   107
 
#define CKR_F_PKCS11_GENERATE_RANDOM   108
 
#define CKR_F_PKCS11_GETATTR_ALLOC   109
 
#define CKR_F_PKCS11_GETATTR_BN   110
 
#define CKR_F_PKCS11_GETATTR_INT   111
 
#define CKR_F_PKCS11_INIT_PIN   112
 
#define CKR_F_PKCS11_INIT_SLOT   113
 
#define CKR_F_PKCS11_INIT_TOKEN   114
 
#define CKR_F_PKCS11_IS_LOGGED_IN   115
 
#define CKR_F_PKCS11_LOGIN   116
 
#define CKR_F_PKCS11_LOGOUT   117
 
#define CKR_F_PKCS11_NEXT_CERT   118
 
#define CKR_F_PKCS11_NEXT_KEY   119
 
#define CKR_F_PKCS11_OPEN_SESSION   120
 
#define CKR_F_PKCS11_PRIVATE_DECRYPT   121
 
#define CKR_F_PKCS11_PRIVATE_ENCRYPT   122
 
#define CKR_F_PKCS11_RELOAD_KEY   123
 
#define CKR_F_PKCS11_SEED_RANDOM   125
 
#define CKR_F_PKCS11_STORE_CERTIFICATE   126
 
#define CKR_F_PKCS11_STORE_KEY   127
 
#define CKR_F_PKCS11_REMOVE_KEY   128
 
#define CKR_F_PKCS11_REMOVE_CERTIFICATE   129
 
#define CKR_F_PKCS11_GENERATE_KEY   130
 
#define CKR_F_PKCS11_RELOAD_CERTIFICATE   131
 
#define CKR_F_PKCS11_GET_SESSION   132
 
#define PKCS11_F_PKCS11_CHANGE_PIN   CKR_F_PKCS11_CHANGE_PIN
 
#define PKCS11_F_PKCS11_CHECK_TOKEN   CKR_F_PKCS11_CHECK_TOKEN
 
#define PKCS11_F_PKCS11_CTX_LOAD   CKR_F_PKCS11_CTX_LOAD
 
#define PKCS11_F_PKCS11_ECDH_DERIVE   CKR_F_PKCS11_ECDH_DERIVE
 
#define PKCS11_F_PKCS11_ECDSA_SIGN   CKR_F_PKCS11_ECDSA_SIGN
 
#define PKCS11_F_PKCS11_ENUMERATE_SLOTS   CKR_F_PKCS11_ENUMERATE_SLOTS
 
#define PKCS11_F_PKCS11_FIND_CERTS   CKR_F_PKCS11_FIND_CERTS
 
#define PKCS11_F_PKCS11_FIND_KEYS   CKR_F_PKCS11_FIND_KEYS
 
#define PKCS11_F_PKCS11_GENERATE_RANDOM   CKR_F_PKCS11_GENERATE_RANDOM
 
#define PKCS11_F_PKCS11_GETATTR_ALLOC   CKR_F_PKCS11_GETATTR_ALLOC
 
#define PKCS11_F_PKCS11_GETATTR_BN   CKR_F_PKCS11_GETATTR_BN
 
#define PKCS11_F_PKCS11_GETATTR_INT   CKR_F_PKCS11_GETATTR_INT
 
#define PKCS11_F_PKCS11_INIT_PIN   CKR_F_PKCS11_INIT_PIN
 
#define PKCS11_F_PKCS11_INIT_SLOT   CKR_F_PKCS11_INIT_SLOT
 
#define PKCS11_F_PKCS11_INIT_TOKEN   CKR_F_PKCS11_INIT_TOKEN
 
#define PKCS11_F_PKCS11_IS_LOGGED_IN   CKR_F_PKCS11_IS_LOGGED_IN
 
#define PKCS11_F_PKCS11_LOGIN   CKR_F_PKCS11_LOGIN
 
#define PKCS11_F_PKCS11_LOGOUT   CKR_F_PKCS11_LOGOUT
 
#define PKCS11_F_PKCS11_NEXT_CERT   CKR_F_PKCS11_NEXT_CERT
 
#define PKCS11_F_PKCS11_NEXT_KEY   CKR_F_PKCS11_NEXT_KEY
 
#define PKCS11_F_PKCS11_OPEN_SESSION   CKR_F_PKCS11_OPEN_SESSION
 
#define PKCS11_F_PKCS11_PRIVATE_DECRYPT   CKR_F_PKCS11_PRIVATE_DECRYPT
 
#define PKCS11_F_PKCS11_PRIVATE_ENCRYPT   CKR_F_PKCS11_PRIVATE_ENCRYPT
 
#define PKCS11_F_PKCS11_RELOAD_KEY   CKR_F_PKCS11_RELOAD_KEY
 
#define PKCS11_F_PKCS11_SEED_RANDOM   CKR_F_PKCS11_SEED_RANDOM
 
#define PKCS11_F_PKCS11_STORE_CERTIFICATE   CKR_F_PKCS11_STORE_CERTIFICATE
 
#define PKCS11_F_PKCS11_STORE_KEY   CKR_F_PKCS11_STORE_KEY
 
#define PKCS11_F_PKCS11_REMOVE_KEY   CKR_F_PKCS11_REMOVE_KEY
 
#define PKCS11_F_PKCS11_REMOVE_CERTIFICATE   CKR_F_PKCS11_REMOVE_CERTIFICATE
 
#define PKCS11_F_PKCS11_GENERATE_KEY   CKR_F_PKCS11_GENERATE_KEY
 
#define PKCS11_LOAD_MODULE_ERROR   P11_R_LOAD_MODULE_ERROR
 
#define PKCS11_MODULE_LOADED_ERROR   -1
 
#define PKCS11_SYMBOL_NOT_FOUND_ERROR   -1
 
#define PKCS11_NOT_SUPPORTED   P11_R_NOT_SUPPORTED
 
#define PKCS11_NO_SESSION   P11_R_NO_SESSION
 
#define PKCS11_KEYGEN_FAILED   P11_R_KEYGEN_FAILED
 
#define PKCS11_UI_FAILED   P11_R_UI_FAILED
 
#define ERR_LIB_PKCS11   (ERR_get_CKR_code())
 

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

int ERR_load_CKR_strings (void)
 
void ERR_unload_CKR_strings (void)
 
void ERR_CKR_error (int function, int reason, char *file, int line)
 
int ERR_get_CKR_code (void)
 
PKCS11_CTXPKCS11_CTX_new (void)
 Create a new libp11 context. More...
 
void PKCS11_CTX_init_args (PKCS11_CTX *ctx, const char *init_args)
 Specify any private PKCS#11 module initialization args, if necessary. More...
 
int PKCS11_CTX_load (PKCS11_CTX *ctx, const char *ident)
 Load a PKCS#11 module. More...
 
void PKCS11_CTX_unload (PKCS11_CTX *ctx)
 Unload a PKCS#11 module. More...
 
void PKCS11_CTX_free (PKCS11_CTX *ctx)
 Free a libp11 context. More...
 
int PKCS11_open_session (PKCS11_SLOT *slot, int rw)
 Open a session in RO or RW mode. More...
 
int PKCS11_enumerate_slots (PKCS11_CTX *ctx, PKCS11_SLOT **slotsp, unsigned int *nslotsp)
 Get a list of all slots. More...
 
int PKCS11_update_slots (PKCS11_CTX *ctx, PKCS11_SLOT **slotsp, unsigned int *nslotsp)
 Get or update a list of all slots. More...
 
unsigned long PKCS11_get_slotid_from_slot (PKCS11_SLOT *slotp)
 Get the slot_id from a slot as it is stored in private. More...
 
void PKCS11_release_all_slots (PKCS11_CTX *ctx, PKCS11_SLOT *slots, unsigned int nslots)
 Free the list of slots allocated by PKCS11_enumerate_slots() More...
 
PKCS11_SLOTPKCS11_find_token (PKCS11_CTX *ctx, PKCS11_SLOT *slots, unsigned int nslots)
 Find the first slot with a token. More...
 
PKCS11_SLOTPKCS11_find_next_token (PKCS11_CTX *ctx, PKCS11_SLOT *slots, unsigned int nslots, PKCS11_SLOT *slot)
 Find the next slot with a token. More...
 
int PKCS11_is_logged_in (PKCS11_SLOT *slot, int so, int *res)
 Check if user is already authenticated to a card. More...
 
int PKCS11_login (PKCS11_SLOT *slot, int so, const char *pin)
 Authenticate to the card. More...
 
int PKCS11_logout (PKCS11_SLOT *slot)
 De-authenticate from the card. More...
 
int PKCS11_enumerate_keys (PKCS11_TOKEN *, PKCS11_KEY **, unsigned int *)
 
int PKCS11_remove_key (PKCS11_KEY *)
 
int PKCS11_enumerate_public_keys (PKCS11_TOKEN *, PKCS11_KEY **, unsigned int *)
 
int PKCS11_get_key_type (PKCS11_KEY *)
 
EVP_PKEY * PKCS11_get_private_key (PKCS11_KEY *key)
 Returns a EVP_PKEY object for the private key. More...
 
EVP_PKEY * PKCS11_get_public_key (PKCS11_KEY *key)
 Returns a EVP_PKEY object with the public key. More...
 
PKCS11_CERTPKCS11_find_certificate (PKCS11_KEY *)
 
PKCS11_KEYPKCS11_find_key (PKCS11_CERT *)
 
int PKCS11_enumerate_certs (PKCS11_TOKEN *, PKCS11_CERT **, unsigned int *)
 
int PKCS11_remove_certificate (PKCS11_CERT *)
 
int PKCS11_set_ui_method (PKCS11_CTX *ctx, UI_METHOD *ui_method, void *ui_user_data)
 
int PKCS11_init_token (PKCS11_TOKEN *token, const char *pin, const char *label)
 Initialize a token. More...
 
int PKCS11_init_pin (PKCS11_TOKEN *token, const char *pin)
 Initialize the user PIN on a token. More...
 
int PKCS11_change_pin (PKCS11_SLOT *slot, const char *old_pin, const char *new_pin)
 Change the currently used (either USER or SO) PIN on a token. More...
 
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. More...
 
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. More...
 
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. More...
 
int PKCS11_seed_random (PKCS11_SLOT *slot, const unsigned char *s, unsigned int s_len)
 
int PKCS11_generate_random (PKCS11_SLOT *slot, unsigned char *r, unsigned int r_len)
 
RSA_METHOD * PKCS11_get_rsa_method (void)
 
void * PKCS11_get_ec_key_method (void)
 
ECDSA_METHOD * PKCS11_get_ecdsa_method (void)
 
ECDH_METHOD * PKCS11_get_ecdh_method (void)
 
int PKCS11_pkey_meths (ENGINE *e, EVP_PKEY_METHOD **pmeth, const int **nids, int nid)
 
void ERR_load_PKCS11_strings (void)
 Load PKCS11 error strings. More...
 
P11_DEPRECATED_FUNC int PKCS11_generate_key (PKCS11_TOKEN *token, int algorithm, unsigned int bits, char *label, unsigned char *id, size_t id_len)
 Generate a private key on the token. More...
 
P11_DEPRECATED_FUNC int PKCS11_get_key_size (PKCS11_KEY *)
 
P11_DEPRECATED_FUNC int PKCS11_get_key_modulus (PKCS11_KEY *, BIGNUM **)
 
P11_DEPRECATED_FUNC int PKCS11_get_key_exponent (PKCS11_KEY *, BIGNUM **)
 
P11_DEPRECATED_FUNC int PKCS11_ecdsa_sign (const unsigned char *m, unsigned int m_len, unsigned char *sigret, unsigned int *siglen, PKCS11_KEY *key)
 
P11_DEPRECATED_FUNC int PKCS11_sign (int type, const unsigned char *m, unsigned int m_len, unsigned char *sigret, unsigned int *siglen, PKCS11_KEY *key)
 
P11_DEPRECATED_FUNC int PKCS11_verify (int type, const unsigned char *m, unsigned int m_len, unsigned char *signature, unsigned int siglen, PKCS11_KEY *key)
 
P11_DEPRECATED_FUNC int PKCS11_private_encrypt (int flen, const unsigned char *from, unsigned char *to, PKCS11_KEY *rsa, int padding)
 
P11_DEPRECATED_FUNC int PKCS11_private_decrypt (int flen, const unsigned char *from, unsigned char *to, PKCS11_KEY *key, int padding)
 Decrypts data using the private key. More...
 

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 currently used (either USER or SO) PIN on a token.

Parameters
slotslot returned by PKCS11_find_token()
old_pinold PIN value
new_pinnew PIN value
Return values
0success
-1error
void PKCS11_CTX_free ( PKCS11_CTX ctx)

Free a libp11 context.

Parameters
ctxcontext allocated by PKCS11_CTX_new()
void PKCS11_CTX_init_args ( PKCS11_CTX ctx,
const char *  init_args 
)

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

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

Load a PKCS#11 module.

Parameters
ctxcontext allocated by PKCS11_CTX_new()
identPKCS#11 library filename
Return values
0success
-1error
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
ctxcontext 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
ctxcontext allocated by PKCS11_CTX_new()
slotsppointer on a list of slots
nslotspsize of the allocated list
Return values
0success
-1error
PKCS11_SLOT* PKCS11_find_next_token ( PKCS11_CTX ctx,
PKCS11_SLOT slots,
unsigned int  nslots,
PKCS11_SLOT slot 
)

Find the next slot with a token.

Parameters
ctxcontext allocated by PKCS11_CTX_new()
slotslist of slots allocated by PKCS11_enumerate_slots()
nslotssize of the list
slotcurrent slot
Return values
!=NULLpointer on a slot structure
NULLerror
PKCS11_SLOT* PKCS11_find_token ( PKCS11_CTX ctx,
PKCS11_SLOT slots,
unsigned int  nslots 
)

Find the first slot with a token.

Parameters
ctxcontext allocated by PKCS11_CTX_new()
slotslist of slots allocated by PKCS11_enumerate_slots()
nslotssize of the list
Return values
!=NULLpointer on a slot structure
NULLerror
P11_DEPRECATED_FUNC int PKCS11_generate_key ( PKCS11_TOKEN token,
int  algorithm,
unsigned int  bits,
char *  label,
unsigned char *  id,
size_t  id_len 
)

Generate a private key on the token.

Parameters
tokentoken returned by PKCS11_find_token()
algorithmIGNORED (still here for backward compatibility)
bitssize of the modulus in bits
labellabel for this key
idbytes to use as the id value
id_lenlength of the id value
Return values
0success
-1error
EVP_PKEY* PKCS11_get_private_key ( PKCS11_KEY key)

Returns a EVP_PKEY object for the private key.

Parameters
keyPKCS11_KEY object
Return values
!=NULLreference to the EVP_PKEY object
NULLerror
EVP_PKEY* PKCS11_get_public_key ( PKCS11_KEY key)

Returns a EVP_PKEY object with the public key.

Parameters
keyPKCS11_KEY object
Return values
!=NULLreference to the EVP_PKEY object
NULLerror
unsigned long PKCS11_get_slotid_from_slot ( PKCS11_SLOT slotp)

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

Parameters
slotppointer on a slot
Return values
theslotid
int PKCS11_init_pin ( PKCS11_TOKEN token,
const char *  pin 
)

Initialize the user PIN on a token.

Parameters
tokentoken descriptor (in general slot->token)
pinnew user PIN value
Return values
0success
-1error
int PKCS11_init_token ( PKCS11_TOKEN token,
const char *  pin,
const char *  label 
)

Initialize a token.

Parameters
tokentoken descriptor (in general slot->token)
pinSecurity Officer PIN value
labelnew name of the token
Return values
0success
-1error
int PKCS11_is_logged_in ( PKCS11_SLOT slot,
int  so,
int *  res 
)

Check if user is already authenticated to a card.

Parameters
slotslot returned by PKCS11_find_token()
sokind of login to check: CKU_SO if != 0, otherwise CKU_USER
respointer to return value: 1 if logged in, 0 if not logged in
Return values
0success
-1error
int PKCS11_login ( PKCS11_SLOT slot,
int  so,
const char *  pin 
)

Authenticate to the card.

Parameters
slotslot returned by PKCS11_find_token()
sologin as CKU_SO if != 0, otherwise login as CKU_USER
pinPIN value
Return values
0success
-1error
int PKCS11_logout ( PKCS11_SLOT slot)

De-authenticate from the card.

Parameters
slotslot returned by PKCS11_find_token()
Return values
0success
-1error
int PKCS11_open_session ( PKCS11_SLOT slot,
int  rw 
)

Open a session in RO or RW mode.

Parameters
slotslot descriptor returned by PKCS11_find_token() or PKCS11_enumerate_slots()
rwopen in read/write mode is mode != 0, otherwise in read only mode
Return values
0success
-1error
P11_DEPRECATED_FUNC 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
flenlength of the encrypted data
fromencrypted data
tooutput buffer (MUST be a least flen bytes long)
keyprivate key object
paddingpadding 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
ctxcontext allocated by PKCS11_CTX_new()
slotslist of slots allocated by PKCS11_enumerate_slots()
nslotssize 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
tokentoken returned by PKCS11_find_token()
x509x509 certificate object
labellabel for this certificate
idbytes to use as the id value
id_lenlength of the id value
ret_certput new PKCS11_CERT object here
Return values
0success
-1error
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
tokentoken returned by PKCS11_find_token()
pkprivate key
labellabel for this key
idbytes to use as the id value
id_lenlength of the id value
Return values
0success
-1error
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
tokentoken returned by PKCS11_find_token()
pkprivate key
labellabel for this key
idbytes to use as the id value
id_lenlength of the id value
Return values
0success
-1error
int PKCS11_update_slots ( PKCS11_CTX ctx,
PKCS11_SLOT **  slotsp,
unsigned int *  nslotsp 
)

Get or update a list of all slots.

The difference to PKCS11_enumerate_slots() is that this will expect as input previous slot list (or zero initialized count and null pointer) for the list. This function always reuses the slots found from the previous list to avoid unexpected slot and key object destructon.

Parameters
ctxcontext allocated by PKCS11_CTX_new()
slotsppointer on a list of slots
nslotsppointer to size of the allocated list
Return values
0success
-1error

libp11, Copyright (C) 2005 Olaf Kirch <okir@lst.de>OpenSC-Project.org Logo