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

libp11 header file More...

#include <openssl/bio.h>
#include <openssl/err.h>
#include <openssl/x509.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 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_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 initializtion 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...
 
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...
 
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_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. 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_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 user PIN on a token. More...
 
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. 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_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. More...
 
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. 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 user 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 initializtion 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_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
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
tokentoken returned by PKCS11_find_token()
algorithmEVP_PKEY_RSA
bitssize of the modulus in bits
labellabel for this key
idbytes to use as id value
id_lenlength of 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 EVP_PKEY object. The returned EVP_PKEY object should be treated as const and must not be freed.
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 EVP_PKEY object. The returned EVP_PKEY object should be treated as const and must not be freed.
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_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
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 id value
id_lenlength of 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 id value
id_lenlength of 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 id value
id_lenlength of id value.
Return values
0success
-1error

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