libp11 0.4.14
libp11.h
Go to the documentation of this file.
1/* libp11, a simple layer on top of PKCS#11 API
2 * Copyright (C) 2005 Olaf Kirch <okir@lst.de>
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 */
18
23
24#ifndef _LIB11_H
25#define _LIB11_H
26
27#include "p11_err.h"
28#include <openssl/bio.h>
29#include <openssl/err.h>
30#include <openssl/bn.h>
31#include <openssl/rsa.h>
32#include <openssl/x509.h>
33#include <openssl/evp.h>
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39int ERR_load_CKR_strings(void);
40void ERR_unload_CKR_strings(void);
41void ERR_CKR_error(int function, int reason, char *file, int line);
42# define CKRerr(f,r) ERR_CKR_error((f),(r),__FILE__,__LINE__)
43int ERR_get_CKR_code(void);
44
45/*
46 * The purpose of this library is to provide a simple PKCS#11
47 * interface to OpenSSL application. It was never a goal
48 * of this project to expose the entire PKCS#11 functionality.
49 */
50
52typedef struct PKCS11_key_st {
53 char *label;
54 unsigned char *id;
55 size_t id_len;
56 unsigned char isPrivate;
57 unsigned char needLogin;
58 void *_private;
60
62typedef struct PKCS11_cert_st {
63 char *label;
64 unsigned char *id;
65 size_t id_len;
66 X509 *x509;
67 void *_private;
69
71typedef struct PKCS11_token_st {
72 char *label;
73 char *manufacturer;
74 char *model;
75 char *serialnr;
76 unsigned char initialized;
77 unsigned char loginRequired;
78 unsigned char secureLogin;
79 unsigned char userPinSet;
80 unsigned char readOnly;
81 unsigned char hasRng;
82 unsigned char userPinCountLow;
83 unsigned char userPinFinalTry;
84 unsigned char userPinLocked;
85 unsigned char userPinToBeChanged;
86 unsigned char soPinCountLow;
87 unsigned char soPinFinalTry;
88 unsigned char soPinLocked;
89 unsigned char soPinToBeChanged;
90 struct PKCS11_slot_st *slot;
92
94typedef struct PKCS11_slot_st {
95 char *manufacturer;
96 char *description;
97 unsigned char removable;
99 void *_private;
101
103typedef struct PKCS11_ctx_st {
104 char *manufacturer;
105 char *description;
106 void *_private;
108
109typedef struct PKCS11_ec_kgen_st {
110 const char *curve;
111} PKCS11_EC_KGEN;
112
113typedef struct PKCS11_rsa_kgen_st {
114 unsigned int bits;
115} PKCS11_RSA_KGEN;
116
117typedef struct PKCS11_params {
118 unsigned char extractable;
119 unsigned char sensitive;
121
122typedef struct PKCS11_kgen_attrs_st {
123 /* Key generation type from OpenSSL. Given the union below this should
124 * be either EVP_PKEY_EC or EVP_PKEY_RSA
125 */
126 int type;
127 union {
128 PKCS11_EC_KGEN *ec;
129 PKCS11_RSA_KGEN *rsa;
130 } kgen;
131 const char *token_label;
132 const char *key_label;
133 const unsigned char *key_id;
134 size_t id_len;
135 const PKCS11_params *key_params;
136} PKCS11_KGEN_ATTRS;
137
139typedef void (*PKCS11_VLOG_A_CB)(int, const char *, va_list);
140
148
154extern void PKCS11_CTX_init_args(PKCS11_CTX *ctx, const char *init_args);
155
164extern int PKCS11_CTX_load(PKCS11_CTX *ctx, const char *ident);
165
172
178extern void PKCS11_CTX_free(PKCS11_CTX *ctx);
179
187extern int PKCS11_open_session(PKCS11_SLOT *slot, int rw);
188
199 PKCS11_SLOT **slotsp, unsigned int *nslotsp);
200
216 PKCS11_SLOT **slotsp, unsigned int *nslotsp);
217
224extern unsigned long PKCS11_get_slotid_from_slot(PKCS11_SLOT *slotp);
225
234 PKCS11_SLOT *slots, unsigned int nslots);
235
246 PKCS11_SLOT *slots, unsigned int nslots);
247
259 PKCS11_SLOT *slots, unsigned int nslots,
260 PKCS11_SLOT *slot);
261
271extern int PKCS11_is_logged_in(PKCS11_SLOT *slot, int so, int *res);
272
282extern int PKCS11_login(PKCS11_SLOT *slot, int so, const char *pin);
283
291extern int PKCS11_logout(PKCS11_SLOT *slot);
292
293/* Get a list of private keys associated with this token */
294extern int PKCS11_enumerate_keys(PKCS11_TOKEN *,
295 PKCS11_KEY **, unsigned int *);
296
297/* Get a list of private keys associated with this token and matching the key template */
298extern int PKCS11_enumerate_keys_ext(PKCS11_TOKEN *,
299 const PKCS11_KEY *, PKCS11_KEY **, unsigned int *);
300
301/* Remove the key from this token */
302extern int PKCS11_remove_key(PKCS11_KEY *);
303
304/* Get a list of public keys associated with this token */
305extern int PKCS11_enumerate_public_keys(PKCS11_TOKEN *,
306 PKCS11_KEY **, unsigned int *);
307
308/* Get a list of public keys associated with this token and matching the key template */
309extern int PKCS11_enumerate_public_keys_ext(PKCS11_TOKEN *,
310 const PKCS11_KEY *, PKCS11_KEY **, unsigned int *);
311
312/* Get the key type (as EVP_PKEY_XXX) */
313extern int PKCS11_get_key_type(PKCS11_KEY *);
314
322extern EVP_PKEY *PKCS11_get_private_key(PKCS11_KEY *key);
323
331extern EVP_PKEY *PKCS11_get_public_key(PKCS11_KEY *key);
332
333/* Find the corresponding certificate (if any) */
334extern PKCS11_CERT *PKCS11_find_certificate(PKCS11_KEY *);
335
336/* Find the corresponding key (if any) */
337extern PKCS11_KEY *PKCS11_find_key(PKCS11_CERT *);
338
339/* Get a list of all certificates associated with this token */
340extern int PKCS11_enumerate_certs(PKCS11_TOKEN *, PKCS11_CERT **, unsigned int *);
341
342/* Get a list of all certificates associated with this token and matching cert template */
343extern int PKCS11_enumerate_certs_ext(PKCS11_TOKEN *,
344 const PKCS11_CERT *, PKCS11_CERT **, unsigned int *);
345
346/* Remove the certificate from this token */
347extern int PKCS11_remove_certificate(PKCS11_CERT *);
348
349/* Set UI method to allow retrieving CKU_CONTEXT_SPECIFIC PINs interactively */
350extern int PKCS11_set_ui_method(PKCS11_CTX *ctx,
351 UI_METHOD *ui_method, void *ui_user_data);
352
362extern int PKCS11_init_token(PKCS11_TOKEN *token, const char *pin,
363 const char *label);
364
373extern int PKCS11_init_pin(PKCS11_TOKEN *token, const char *pin);
374
384extern int PKCS11_change_pin(PKCS11_SLOT *slot, const char *old_pin,
385 const char *new_pin);
386
398extern int PKCS11_store_private_key(PKCS11_TOKEN *token, EVP_PKEY *pk, char *label, unsigned char *id, size_t id_len);
399
411extern int PKCS11_store_public_key(PKCS11_TOKEN *token, EVP_PKEY *pk, char *label, unsigned char *id, size_t id_len);
412
425extern int PKCS11_store_certificate(PKCS11_TOKEN *token, X509 *x509,
426 char *label, unsigned char *id, size_t id_len,
427 PKCS11_CERT **ret_cert);
428
429/* Access the random number generator */
430extern int PKCS11_seed_random(PKCS11_SLOT *slot, const unsigned char *s, unsigned int s_len);
431extern int PKCS11_generate_random(PKCS11_SLOT *slot, unsigned char *r, unsigned int r_len);
432
433/*
434 * PKCS#11 implementation for OpenSSL methods
435 */
436RSA_METHOD *PKCS11_get_rsa_method(void);
437/* Also define unsupported methods to retain backward compatibility */
438#if OPENSSL_VERSION_NUMBER >= 0x10100002L && !defined(LIBRESSL_VERSION_NUMBER)
439EC_KEY_METHOD *PKCS11_get_ec_key_method(void);
440void *PKCS11_get_ecdsa_method(void);
441void *PKCS11_get_ecdh_method(void);
442#else
443void *PKCS11_get_ec_key_method(void);
444ECDSA_METHOD *PKCS11_get_ecdsa_method(void);
445ECDH_METHOD *PKCS11_get_ecdh_method(void);
446#endif
447int PKCS11_pkey_meths(ENGINE *e, EVP_PKEY_METHOD **pmeth,
448 const int **nids, int nid);
449
456extern void ERR_load_PKCS11_strings(void);
457
458/*
459 * The following functions are discouraged, because they partially
460 * duplicate the functionality OpenSSL provides for EVP_PKEY objects
461 */
462
472extern int PKCS11_keygen(PKCS11_TOKEN *token, PKCS11_KGEN_ATTRS *kgen_attrs);
473
487 int algorithm, unsigned int bits_or_nid,
488 char *label, unsigned char *id, size_t id_len);
489
490/* Get the RSA key modulus size (in bytes) */
491extern int PKCS11_get_key_size(PKCS11_KEY *);
492
493/* Get the RSA key modules as BIGNUM */
494extern int PKCS11_get_key_modulus(PKCS11_KEY *, BIGNUM **);
495
496/* Get the RSA key public exponent as BIGNUM */
497extern int PKCS11_get_key_exponent(PKCS11_KEY *, BIGNUM **);
498
499/* Sign with the EC private key */
500extern int PKCS11_ecdsa_sign(
501 const unsigned char *m, unsigned int m_len,
502 unsigned char *sigret, unsigned int *siglen, PKCS11_KEY *key);
503
504/* Sign with the RSA private key */
505extern int PKCS11_sign(int type,
506 const unsigned char *m, unsigned int m_len,
507 unsigned char *sigret, unsigned int *siglen, PKCS11_KEY *key);
508
509/* This function has never been implemented */
510extern int PKCS11_verify(int type,
511 const unsigned char *m, unsigned int m_len,
512 unsigned char *signature, unsigned int siglen, PKCS11_KEY *key);
513
514/* Encrypts data using the private key */
515extern int PKCS11_private_encrypt(
516 int flen, const unsigned char *from,
517 unsigned char *to, PKCS11_KEY *rsa, int padding);
518
530 int flen, const unsigned char *from,
531 unsigned char *to, PKCS11_KEY *key, int padding);
532
533/* Set the logging callback */
534extern void PKCS11_set_vlog_a_method(PKCS11_CTX *pctx, PKCS11_VLOG_A_CB cb);
535
536/* Function codes */
537# define CKR_F_PKCS11_CHANGE_PIN 100
538# define CKR_F_PKCS11_CHECK_TOKEN 101
539# define CKR_F_PKCS11_CTX_LOAD 102
540# define CKR_F_PKCS11_ECDH_DERIVE 103
541# define CKR_F_PKCS11_ECDSA_SIGN 104
542# define CKR_F_PKCS11_ENUMERATE_SLOTS 105
543# define CKR_F_PKCS11_FIND_CERTS 106
544# define CKR_F_PKCS11_FIND_KEYS 107
545# define CKR_F_PKCS11_GENERATE_RANDOM 108
546# define CKR_F_PKCS11_GETATTR_ALLOC 109
547# define CKR_F_PKCS11_GETATTR_BN 110
548# define CKR_F_PKCS11_GETATTR_INT 111
549# define CKR_F_PKCS11_INIT_PIN 112
550# define CKR_F_PKCS11_INIT_SLOT 113
551# define CKR_F_PKCS11_INIT_TOKEN 114
552# define CKR_F_PKCS11_IS_LOGGED_IN 115
553# define CKR_F_PKCS11_LOGIN 116
554# define CKR_F_PKCS11_LOGOUT 117
555# define CKR_F_PKCS11_NEXT_CERT 118
556# define CKR_F_PKCS11_NEXT_KEY 119
557# define CKR_F_PKCS11_OPEN_SESSION 120
558# define CKR_F_PKCS11_PRIVATE_DECRYPT 121
559# define CKR_F_PKCS11_PRIVATE_ENCRYPT 122
560# define CKR_F_PKCS11_RELOAD_KEY 123
561# define CKR_F_PKCS11_SEED_RANDOM 125
562# define CKR_F_PKCS11_STORE_CERTIFICATE 126
563# define CKR_F_PKCS11_STORE_KEY 127
564# define CKR_F_PKCS11_REMOVE_KEY 128
565# define CKR_F_PKCS11_REMOVE_CERTIFICATE 129
566# define CKR_F_PKCS11_GENERATE_KEY 130
567# define CKR_F_PKCS11_RELOAD_CERTIFICATE 131
568# define CKR_F_PKCS11_GET_SESSION 132
569
570/* Backward compatibility of error function codes */
571#define PKCS11_F_PKCS11_CHANGE_PIN CKR_F_PKCS11_CHANGE_PIN
572#define PKCS11_F_PKCS11_CHECK_TOKEN CKR_F_PKCS11_CHECK_TOKEN
573#define PKCS11_F_PKCS11_CTX_LOAD CKR_F_PKCS11_CTX_LOAD
574#define PKCS11_F_PKCS11_ECDH_DERIVE CKR_F_PKCS11_ECDH_DERIVE
575#define PKCS11_F_PKCS11_ECDSA_SIGN CKR_F_PKCS11_ECDSA_SIGN
576#define PKCS11_F_PKCS11_ENUMERATE_SLOTS CKR_F_PKCS11_ENUMERATE_SLOTS
577#define PKCS11_F_PKCS11_FIND_CERTS CKR_F_PKCS11_FIND_CERTS
578#define PKCS11_F_PKCS11_FIND_KEYS CKR_F_PKCS11_FIND_KEYS
579#define PKCS11_F_PKCS11_GENERATE_RANDOM CKR_F_PKCS11_GENERATE_RANDOM
580#define PKCS11_F_PKCS11_GETATTR_ALLOC CKR_F_PKCS11_GETATTR_ALLOC
581#define PKCS11_F_PKCS11_GETATTR_BN CKR_F_PKCS11_GETATTR_BN
582#define PKCS11_F_PKCS11_GETATTR_INT CKR_F_PKCS11_GETATTR_INT
583#define PKCS11_F_PKCS11_INIT_PIN CKR_F_PKCS11_INIT_PIN
584#define PKCS11_F_PKCS11_INIT_SLOT CKR_F_PKCS11_INIT_SLOT
585#define PKCS11_F_PKCS11_INIT_TOKEN CKR_F_PKCS11_INIT_TOKEN
586#define PKCS11_F_PKCS11_IS_LOGGED_IN CKR_F_PKCS11_IS_LOGGED_IN
587#define PKCS11_F_PKCS11_LOGIN CKR_F_PKCS11_LOGIN
588#define PKCS11_F_PKCS11_LOGOUT CKR_F_PKCS11_LOGOUT
589#define PKCS11_F_PKCS11_NEXT_CERT CKR_F_PKCS11_NEXT_CERT
590#define PKCS11_F_PKCS11_NEXT_KEY CKR_F_PKCS11_NEXT_KEY
591#define PKCS11_F_PKCS11_OPEN_SESSION CKR_F_PKCS11_OPEN_SESSION
592#define PKCS11_F_PKCS11_PRIVATE_DECRYPT CKR_F_PKCS11_PRIVATE_DECRYPT
593#define PKCS11_F_PKCS11_PRIVATE_ENCRYPT CKR_F_PKCS11_PRIVATE_ENCRYPT
594#define PKCS11_F_PKCS11_RELOAD_KEY CKR_F_PKCS11_RELOAD_KEY
595#define PKCS11_F_PKCS11_SEED_RANDOM CKR_F_PKCS11_SEED_RANDOM
596#define PKCS11_F_PKCS11_STORE_CERTIFICATE CKR_F_PKCS11_STORE_CERTIFICATE
597#define PKCS11_F_PKCS11_STORE_KEY CKR_F_PKCS11_STORE_KEY
598#define PKCS11_F_PKCS11_REMOVE_KEY CKR_F_PKCS11_REMOVE_KEY
599#define PKCS11_F_PKCS11_REMOVE_CERTIFICATE CKR_F_PKCS11_REMOVE_CERTIFICATE
600#define PKCS11_F_PKCS11_GENERATE_KEY CKR_F_PKCS11_GENERATE_KEY
601
602/* Backward compatibility of error reason codes */
603#define PKCS11_LOAD_MODULE_ERROR P11_R_LOAD_MODULE_ERROR
604#define PKCS11_MODULE_LOADED_ERROR -1
605#define PKCS11_SYMBOL_NOT_FOUND_ERROR -1
606#define PKCS11_NOT_SUPPORTED P11_R_NOT_SUPPORTED
607#define PKCS11_NO_SESSION P11_R_NO_SESSION
608#define PKCS11_KEYGEN_FAILED P11_R_KEYGEN_FAILED
609#define PKCS11_UI_FAILED P11_R_UI_FAILED
610
611/* Backward compatibility emulation of the ERR_LIB_PKCS11 constant.
612 * We currently use two separate variables for library error codes:
613 * one for imported PKCS#11 module errors, and one for our own libp11 errors.
614 * We return the value for PKCS#11, as it is more likely to be needed. */
615#define ERR_LIB_PKCS11 (ERR_get_CKR_code())
616
617#ifdef __cplusplus
618}
619#endif
620#endif
621
622/* vim: set noexpandtab: */
struct PKCS11_ctx_st PKCS11_CTX
PKCS11 context.
unsigned long PKCS11_get_slotid_from_slot(PKCS11_SLOT *slotp)
Get the slot_id from a slot as it is stored in private.
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.
void PKCS11_CTX_free(PKCS11_CTX *ctx)
Free a libp11 context.
struct PKCS11_slot_st PKCS11_SLOT
PKCS11 slot: card reader.
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.
struct PKCS11_key_st PKCS11_KEY
PKCS11 key object (public or private)
void(* PKCS11_VLOG_A_CB)(int, const char *, va_list)
PKCS11 ASCII logging callback.
Definition libp11.h:139
int PKCS11_init_pin(PKCS11_TOKEN *token, const char *pin)
Initialize the user PIN 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.
EVP_PKEY * PKCS11_get_public_key(PKCS11_KEY *key)
Returns a EVP_PKEY object with the public key.
int PKCS11_keygen(PKCS11_TOKEN *token, PKCS11_KGEN_ATTRS *kgen_attrs)
Generate key pair on the token.
int PKCS11_login(PKCS11_SLOT *slot, int so, const char *pin)
Authenticate to the card.
void PKCS11_CTX_unload(PKCS11_CTX *ctx)
Unload a PKCS#11 module.
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.
int PKCS11_init_token(PKCS11_TOKEN *token, const char *pin, const char *label)
Initialize a token.
int PKCS11_enumerate_slots(PKCS11_CTX *ctx, PKCS11_SLOT **slotsp, unsigned int *nslotsp)
Get a list of all slots.
PKCS11_CTX * PKCS11_CTX_new(void)
Create a new libp11 context.
EVP_PKEY * PKCS11_get_private_key(PKCS11_KEY *key)
Returns a EVP_PKEY object for the private key.
int PKCS11_is_logged_in(PKCS11_SLOT *slot, int so, int *res)
Check if user is already authenticated to a card.
int PKCS11_update_slots(PKCS11_CTX *ctx, PKCS11_SLOT **slotsp, unsigned int *nslotsp)
Get or update a list of all slots.
void PKCS11_CTX_init_args(PKCS11_CTX *ctx, const char *init_args)
Specify any private PKCS#11 module initialization args, if necessary.
struct PKCS11_token_st PKCS11_TOKEN
PKCS11 token: smart card or USB key.
struct PKCS11_cert_st PKCS11_CERT
PKCS11 certificate object.
int PKCS11_CTX_load(PKCS11_CTX *ctx, const char *ident)
Load a PKCS#11 module.
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_open_session(PKCS11_SLOT *slot, int rw)
Open a session in RO or RW mode.
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_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_generate_key(PKCS11_TOKEN *token, int algorithm, unsigned int bits_or_nid, char *label, unsigned char *id, size_t id_len)
Generate a private key on the token.
void ERR_load_PKCS11_strings(void)
Load PKCS11 error strings.
int PKCS11_logout(PKCS11_SLOT *slot)
De-authenticate from the card.
PKCS11 certificate object.
Definition libp11.h:62
PKCS11 context.
Definition libp11.h:103
PKCS11 key object (public or private)
Definition libp11.h:52
unsigned char isPrivate
private key present?
Definition libp11.h:56
unsigned char needLogin
login to read private key?
Definition libp11.h:57
PKCS11 slot: card reader.
Definition libp11.h:94
PKCS11_TOKEN * token
NULL if no token present.
Definition libp11.h:98
PKCS11 token: smart card or USB key.
Definition libp11.h:71

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