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 
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
36 extern "C" {
37 #endif
38 
39 int ERR_load_CKR_strings(void);
40 void ERR_unload_CKR_strings(void);
41 void ERR_CKR_error(int function, int reason, char *file, int line);
42 # define CKRerr(f,r) ERR_CKR_error((f),(r),__FILE__,__LINE__)
43 int 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 
52 typedef 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;
59 } PKCS11_KEY;
60 
62 typedef struct PKCS11_cert_st {
63  char *label;
64  unsigned char *id;
65  size_t id_len;
66  X509 *x509;
67  void *_private;
68 } PKCS11_CERT;
69 
71 typedef 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;
91 } PKCS11_TOKEN;
92 
94 typedef struct PKCS11_slot_st {
95  char *manufacturer;
96  char *description;
97  unsigned char removable;
99  void *_private;
100 } PKCS11_SLOT;
101 
103 typedef struct PKCS11_ctx_st {
104  char *manufacturer;
105  char *description;
106  void *_private;
107 } PKCS11_CTX;
108 
109 typedef struct PKCS11_ec_kgen_st {
110  const char *curve;
112 
113 typedef struct PKCS11_rsa_kgen_st {
114  unsigned int bits;
116 
117 typedef struct PKCS11_params {
118  unsigned char extractable;
119  unsigned char sensitive;
120 } PKCS11_params;
121 
122 typedef 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;
137 
139 typedef void (*PKCS11_VLOG_A_CB)(int, const char *, va_list);
140 
147 extern PKCS11_CTX *PKCS11_CTX_new(void);
148 
154 extern void PKCS11_CTX_init_args(PKCS11_CTX *ctx, const char *init_args);
155 
164 extern int PKCS11_CTX_load(PKCS11_CTX *ctx, const char *ident);
165 
171 extern void PKCS11_CTX_unload(PKCS11_CTX *ctx);
172 
178 extern void PKCS11_CTX_free(PKCS11_CTX *ctx);
179 
187 extern int PKCS11_open_session(PKCS11_SLOT *slot, int rw);
188 
198 extern int PKCS11_enumerate_slots(PKCS11_CTX *ctx,
199  PKCS11_SLOT **slotsp, unsigned int *nslotsp);
200 
215 extern int PKCS11_update_slots(PKCS11_CTX *ctx,
216  PKCS11_SLOT **slotsp, unsigned int *nslotsp);
217 
224 extern unsigned long PKCS11_get_slotid_from_slot(PKCS11_SLOT *slotp);
225 
233 extern void PKCS11_release_all_slots(PKCS11_CTX *ctx,
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 
271 extern int PKCS11_is_logged_in(PKCS11_SLOT *slot, int so, int *res);
272 
282 extern int PKCS11_login(PKCS11_SLOT *slot, int so, const char *pin);
283 
291 extern int PKCS11_logout(PKCS11_SLOT *slot);
292 
293 /* Get a list of private keys associated with this token */
294 extern 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 */
298 extern int PKCS11_enumerate_keys_ext(PKCS11_TOKEN *,
299  const PKCS11_KEY *, PKCS11_KEY **, unsigned int *);
300 
301 /* Remove the key from this token */
302 extern int PKCS11_remove_key(PKCS11_KEY *);
303 
304 /* Get a list of public keys associated with this token */
305 extern 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 */
309 extern 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) */
313 extern int PKCS11_get_key_type(PKCS11_KEY *);
314 
322 extern EVP_PKEY *PKCS11_get_private_key(PKCS11_KEY *key);
323 
331 extern EVP_PKEY *PKCS11_get_public_key(PKCS11_KEY *key);
332 
333 /* Find the corresponding certificate (if any) */
334 extern PKCS11_CERT *PKCS11_find_certificate(PKCS11_KEY *);
335 
336 /* Find the corresponding key (if any) */
337 extern PKCS11_KEY *PKCS11_find_key(PKCS11_CERT *);
338 
339 /* Get a list of all certificates associated with this token */
340 extern 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 */
343 extern int PKCS11_enumerate_certs_ext(PKCS11_TOKEN *,
344  const PKCS11_CERT *, PKCS11_CERT **, unsigned int *);
345 
346 /* Remove the certificate from this token */
347 extern int PKCS11_remove_certificate(PKCS11_CERT *);
348 
349 /* Set UI method to allow retrieving CKU_CONTEXT_SPECIFIC PINs interactively */
350 extern int PKCS11_set_ui_method(PKCS11_CTX *ctx,
351  UI_METHOD *ui_method, void *ui_user_data);
352 
362 extern int PKCS11_init_token(PKCS11_TOKEN *token, const char *pin,
363  const char *label);
364 
373 extern int PKCS11_init_pin(PKCS11_TOKEN *token, const char *pin);
374 
384 extern int PKCS11_change_pin(PKCS11_SLOT *slot, const char *old_pin,
385  const char *new_pin);
386 
398 extern int PKCS11_store_private_key(PKCS11_TOKEN *token, EVP_PKEY *pk, char *label, unsigned char *id, size_t id_len);
399 
411 extern int PKCS11_store_public_key(PKCS11_TOKEN *token, EVP_PKEY *pk, char *label, unsigned char *id, size_t id_len);
412 
425 extern 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 */
430 extern int PKCS11_seed_random(PKCS11_SLOT *slot, const unsigned char *s, unsigned int s_len);
431 extern int PKCS11_generate_random(PKCS11_SLOT *slot, unsigned char *r, unsigned int r_len);
432 
433 /*
434  * PKCS#11 implementation for OpenSSL methods
435  */
436 RSA_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)
439 EC_KEY_METHOD *PKCS11_get_ec_key_method(void);
440 void *PKCS11_get_ecdsa_method(void);
441 void *PKCS11_get_ecdh_method(void);
442 #else
443 void *PKCS11_get_ec_key_method(void);
444 ECDSA_METHOD *PKCS11_get_ecdsa_method(void);
445 ECDH_METHOD *PKCS11_get_ecdh_method(void);
446 #endif
447 int PKCS11_pkey_meths(ENGINE *e, EVP_PKEY_METHOD **pmeth,
448  const int **nids, int nid);
449 
456 extern 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 
472 extern int PKCS11_keygen(PKCS11_TOKEN *token, PKCS11_KGEN_ATTRS *kgen_attrs);
473 
486 extern int PKCS11_generate_key(PKCS11_TOKEN *token,
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) */
491 extern int PKCS11_get_key_size(PKCS11_KEY *);
492 
493 /* Get the RSA key modules as BIGNUM */
494 extern int PKCS11_get_key_modulus(PKCS11_KEY *, BIGNUM **);
495 
496 /* Get the RSA key public exponent as BIGNUM */
497 extern int PKCS11_get_key_exponent(PKCS11_KEY *, BIGNUM **);
498 
499 /* Sign with the EC private key */
500 extern 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 */
505 extern 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 */
510 extern 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 */
515 extern int PKCS11_private_encrypt(
516  int flen, const unsigned char *from,
517  unsigned char *to, PKCS11_KEY *rsa, int padding);
518 
529 extern int PKCS11_private_decrypt(
530  int flen, const unsigned char *from,
531  unsigned char *to, PKCS11_KEY *key, int padding);
532 
533 /* Set the logging callback */
534 extern 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: */
void PKCS11_release_all_slots(PKCS11_CTX *ctx, PKCS11_SLOT *slots, unsigned int nslots)
Free the list of slots allocated by PKCS11_enumerate_slots()
void PKCS11_CTX_unload(PKCS11_CTX *ctx)
Unload a PKCS#11 module.
EVP_PKEY * PKCS11_get_private_key(PKCS11_KEY *key)
Returns a EVP_PKEY object for the private key.
int PKCS11_init_pin(PKCS11_TOKEN *token, const char *pin)
Initialize the user PIN on a token.
int PKCS11_CTX_load(PKCS11_CTX *ctx, const char *ident)
Load a PKCS#11 module.
unsigned char isPrivate
private key present?
Definition: libp11.h:56
void(* PKCS11_VLOG_A_CB)(int, const char *, va_list)
PKCS11 ASCII logging callback.
Definition: libp11.h:139
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_login(PKCS11_SLOT *slot, int so, const char *pin)
Authenticate to the card.
PKCS11_TOKEN * token
NULL if no token present.
Definition: libp11.h:98
EVP_PKEY * PKCS11_get_public_key(PKCS11_KEY *key)
Returns a EVP_PKEY object with the public key.
struct PKCS11_cert_st PKCS11_CERT
PKCS11 certificate object.
unsigned long PKCS11_get_slotid_from_slot(PKCS11_SLOT *slotp)
Get the slot_id from a slot as it is stored in private.
PKCS11 token: smart card or USB key.
Definition: libp11.h:71
int PKCS11_keygen(PKCS11_TOKEN *token, PKCS11_KGEN_ATTRS *kgen_attrs)
Generate key pair on the token.
unsigned char needLogin
login to read private key?
Definition: libp11.h:57
PKCS11 key object (public or private)
Definition: libp11.h:52
void ERR_load_PKCS11_strings(void)
Load PKCS11 error strings.
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_enumerate_slots(PKCS11_CTX *ctx, PKCS11_SLOT **slotsp, unsigned int *nslotsp)
Get a list of all slots.
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_open_session(PKCS11_SLOT *slot, int rw)
Open a session in RO or RW mode.
struct PKCS11_ctx_st PKCS11_CTX
PKCS11 context.
PKCS11_CTX * PKCS11_CTX_new(void)
Create a new libp11 context.
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.
PKCS11 slot: card reader.
Definition: libp11.h:94
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.
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.
struct PKCS11_slot_st PKCS11_SLOT
PKCS11 slot: card reader.
PKCS11_SLOT * PKCS11_find_token(PKCS11_CTX *ctx, PKCS11_SLOT *slots, unsigned int nslots)
Find the first slot with a token.
PKCS11 context.
Definition: libp11.h:103
int PKCS11_logout(PKCS11_SLOT *slot)
De-authenticate from the card.
int PKCS11_update_slots(PKCS11_CTX *ctx, PKCS11_SLOT **slotsp, unsigned int *nslotsp)
Get or update a list of all slots.
struct PKCS11_key_st PKCS11_KEY
PKCS11 key object (public or private)
int PKCS11_init_token(PKCS11_TOKEN *token, const char *pin, const char *label)
Initialize a token.
void PKCS11_CTX_free(PKCS11_CTX *ctx)
Free a libp11 context.
PKCS11 certificate object.
Definition: libp11.h:62
int PKCS11_is_logged_in(PKCS11_SLOT *slot, int so, int *res)
Check if user is already authenticated to a card.
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_token_st PKCS11_TOKEN
PKCS11 token: smart card or USB key.
void PKCS11_CTX_init_args(PKCS11_CTX *ctx, const char *init_args)
Specify any private PKCS#11 module initialization args, if necessary.

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