libp11  0.4.8
libp11.h
Go to the documentation of this file.
1 /* libp11, a simple layer on to 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 
44 /*
45  * The purpose of this library is to provide a simple PKCS11
46  * interface to OpenSSL application that wish to use a previously
47  * initialized card (as opposed to initializing it, etc).
48  *
49  * I am therefore making some simplifying assumptions:
50  *
51  * - no support for any operations that alter the card,
52  * i.e. readonly-login
53  */
54 
56 typedef struct PKCS11_key_st {
57  char *label;
58  unsigned char *id;
59  size_t id_len;
60  unsigned char isPrivate;
61  unsigned char needLogin;
62  EVP_PKEY *evp_key;
63  void *_private;
64 } PKCS11_KEY;
65 
67 typedef struct PKCS11_cert_st {
68  char *label;
69  unsigned char *id;
70  size_t id_len;
71  X509 *x509;
72  void *_private;
73 } PKCS11_CERT;
74 
76 typedef struct PKCS11_token_st {
77  char *label;
78  char *manufacturer;
79  char *model;
80  char *serialnr;
81  unsigned char initialized;
82  unsigned char loginRequired;
83  unsigned char secureLogin;
84  unsigned char userPinSet;
85  unsigned char readOnly;
86  unsigned char hasRng;
87  unsigned char userPinCountLow;
88  unsigned char userPinFinalTry;
89  unsigned char userPinLocked;
90  unsigned char userPinToBeChanged;
91  unsigned char soPinCountLow;
92  unsigned char soPinFinalTry;
93  unsigned char soPinLocked;
94  unsigned char soPinToBeChanged;
95  void *_private;
96 } PKCS11_TOKEN;
97 
99 typedef struct PKCS11_slot_st {
100  char *manufacturer;
101  char *description;
102  unsigned char removable;
104  void *_private;
105 } PKCS11_SLOT;
106 
108 typedef struct PKCS11_ctx_st {
109  char *manufacturer;
110  char *description;
111  void *_private;
112 } PKCS11_CTX;
113 
120 extern PKCS11_CTX *PKCS11_CTX_new(void);
121 
127 extern void PKCS11_CTX_init_args(PKCS11_CTX * ctx, const char * init_args);
128 
137 extern int PKCS11_CTX_load(PKCS11_CTX * ctx, const char * ident);
138 
146 extern int PKCS11_CTX_reload(PKCS11_CTX * ctx);
147 
153 extern void PKCS11_CTX_unload(PKCS11_CTX * ctx);
154 
160 extern void PKCS11_CTX_free(PKCS11_CTX * ctx);
161 
169 extern int PKCS11_open_session(PKCS11_SLOT * slot, int rw);
170 
180 extern int PKCS11_enumerate_slots(PKCS11_CTX * ctx,
181  PKCS11_SLOT **slotsp, unsigned int *nslotsp);
182 
189 extern unsigned long PKCS11_get_slotid_from_slot(PKCS11_SLOT *slotp);
190 
198 extern void PKCS11_release_all_slots(PKCS11_CTX * ctx,
199  PKCS11_SLOT *slots, unsigned int nslots);
200 
211  PKCS11_SLOT *slots, unsigned int nslots);
212 
224  PKCS11_SLOT *slots, unsigned int nslots,
225  PKCS11_SLOT *slot);
226 
236 extern int PKCS11_is_logged_in(PKCS11_SLOT * slot, int so, int * res);
237 
247 extern int PKCS11_login(PKCS11_SLOT * slot, int so, const char *pin);
248 
256 extern int PKCS11_logout(PKCS11_SLOT * slot);
257 
258 /* Get a list of private keys associated with this token */
259 extern int PKCS11_enumerate_keys(PKCS11_TOKEN *,
260  PKCS11_KEY **, unsigned int *);
261 
262 /* Remove the key from this token */
263 extern int PKCS11_remove_key(PKCS11_KEY *);
264 
265 /* Get a list of public keys associated with this token */
266 extern int PKCS11_enumerate_public_keys(PKCS11_TOKEN *,
267  PKCS11_KEY **, unsigned int *);
268 
269 /* Get the key type (as EVP_PKEY_XXX) */
270 extern int PKCS11_get_key_type(PKCS11_KEY *);
271 
279 extern EVP_PKEY *PKCS11_get_private_key(PKCS11_KEY *key);
280 
288 extern EVP_PKEY *PKCS11_get_public_key(PKCS11_KEY *key);
289 
290 /* Find the corresponding certificate (if any) */
291 extern PKCS11_CERT *PKCS11_find_certificate(PKCS11_KEY *);
292 
293 /* Find the corresponding key (if any) */
294 extern PKCS11_KEY *PKCS11_find_key(PKCS11_CERT *);
295 
296 /* Get a list of all certificates associated with this token */
297 extern int PKCS11_enumerate_certs(PKCS11_TOKEN *, PKCS11_CERT **, unsigned int *);
298 
299 /* Remove the certificate from this token */
300 extern int PKCS11_remove_certificate(PKCS11_CERT *);
301 
302 /* Set UI method to allow retrieving CKU_CONTEXT_SPECIFIC PINs interactively */
303 extern int PKCS11_set_ui_method(PKCS11_CTX *ctx,
304  UI_METHOD *ui_method, void *ui_user_data);
305 
315 extern int PKCS11_init_token(PKCS11_TOKEN * token, const char *pin,
316  const char *label);
317 
326 extern int PKCS11_init_pin(PKCS11_TOKEN * token, const char *pin);
327 
337 extern int PKCS11_change_pin(PKCS11_SLOT * slot, const char *old_pin,
338  const char *new_pin);
339 
351 extern int PKCS11_store_private_key(PKCS11_TOKEN * token, EVP_PKEY * pk, char *label, unsigned char *id, size_t id_len);
352 
364 extern int PKCS11_store_public_key(PKCS11_TOKEN * token, EVP_PKEY * pk, char *label, unsigned char *id, size_t id_len);
365 
378 extern int PKCS11_store_certificate(PKCS11_TOKEN * token, X509 * x509,
379  char *label, unsigned char *id, size_t id_len,
380  PKCS11_CERT **ret_cert);
381 
382 /* Access the random number generator */
383 extern int PKCS11_seed_random(PKCS11_SLOT *slot, const unsigned char *s, unsigned int s_len);
384 extern int PKCS11_generate_random(PKCS11_SLOT *slot, unsigned char *r, unsigned int r_len);
385 
386 /*
387  * PKCS#11 implementation for OpenSSL methods
388  */
389 RSA_METHOD *PKCS11_get_rsa_method(void);
390 /* Also define unsupported methods to retain backward compatibility */
391 #if OPENSSL_VERSION_NUMBER >= 0x10100002L && !defined(LIBRESSL_VERSION_NUMBER)
392 EC_KEY_METHOD *PKCS11_get_ec_key_method(void);
393 void *PKCS11_get_ecdsa_method(void);
394 void *PKCS11_get_ecdh_method(void);
395 #else
396 void *PKCS11_get_ec_key_method(void);
397 ECDSA_METHOD *PKCS11_get_ecdsa_method(void);
398 ECDH_METHOD *PKCS11_get_ecdh_method(void);
399 #endif
400 int PKCS11_pkey_meths(ENGINE *e, EVP_PKEY_METHOD **pmeth,
401  const int **nids, int nid);
402 
409 extern void ERR_load_PKCS11_strings(void);
410 
411 #if defined(_LIBP11_INT_H)
412  /* Deprecated functions will no longer be exported in libp11 0.5.0 */
413  /* They are, however, used internally in OpenSSL method definitions */
414 #define P11_DEPRECATED(msg)
415 #elif defined(_MSC_VER)
416 #define P11_DEPRECATED(msg) __declspec(deprecated(msg))
417 #elif defined(__GNUC__)
418 #if (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__) >= 40500
419  /* GCC >= 4.5.0 supports printing a message */
420 #define P11_DEPRECATED(msg) __attribute__ ((deprecated(msg)))
421 #else
422 #define P11_DEPRECATED(msg) __attribute__ ((deprecated))
423 #endif
424 #elif defined(__clang__)
425 #define P11_DEPRECATED(msg) __attribute__ ((deprecated(msg)))
426 #else
427 #define P11_DEPRECATED(msg)
428 #endif
429 
430 #define P11_DEPRECATED_FUNC \
431  P11_DEPRECATED("This function will be removed in libp11 0.5.0")
432 
433 /*
434  * These functions will be removed from libp11, because they partially
435  * duplicate the functionality OpenSSL provides for EVP_PKEY objects
436  */
437 
450 P11_DEPRECATED_FUNC extern int PKCS11_generate_key(PKCS11_TOKEN * token,
451  int algorithm, unsigned int bits,
452  char *label, unsigned char* id, size_t id_len);
453 
454 /* Get the RSA key modulus size (in bytes) */
455 P11_DEPRECATED_FUNC extern int PKCS11_get_key_size(PKCS11_KEY *);
456 
457 /* Get the RSA key modules as BIGNUM */
458 P11_DEPRECATED_FUNC extern int PKCS11_get_key_modulus(PKCS11_KEY *, BIGNUM **);
459 
460 /* Get the RSA key public exponent as BIGNUM */
461 P11_DEPRECATED_FUNC extern int PKCS11_get_key_exponent(PKCS11_KEY *, BIGNUM **);
462 
463 /* Sign with the EC private key */
464 P11_DEPRECATED_FUNC extern int PKCS11_ecdsa_sign(
465  const unsigned char *m, unsigned int m_len,
466  unsigned char *sigret, unsigned int *siglen, PKCS11_KEY * key);
467 
468 /* Sign with the RSA private key */
469 P11_DEPRECATED_FUNC extern int PKCS11_sign(int type,
470  const unsigned char *m, unsigned int m_len,
471  unsigned char *sigret, unsigned int *siglen, PKCS11_KEY * key);
472 
473 /* This function has never been implemented */
474 P11_DEPRECATED_FUNC extern int PKCS11_verify(int type,
475  const unsigned char *m, unsigned int m_len,
476  unsigned char *signature, unsigned int siglen, PKCS11_KEY * key);
477 
478 /* Encrypts data using the private key */
479 P11_DEPRECATED_FUNC extern int PKCS11_private_encrypt(
480  int flen, const unsigned char *from,
481  unsigned char *to, PKCS11_KEY * rsa, int padding);
482 
493 P11_DEPRECATED_FUNC extern int PKCS11_private_decrypt(
494  int flen, const unsigned char *from,
495  unsigned char *to, PKCS11_KEY * key, int padding);
496 
497 /* Function codes */
498 # define CKR_F_PKCS11_CHANGE_PIN 100
499 # define CKR_F_PKCS11_CHECK_TOKEN 101
500 # define CKR_F_PKCS11_CTX_LOAD 102
501 # define CKR_F_PKCS11_ECDH_DERIVE 103
502 # define CKR_F_PKCS11_ECDSA_SIGN 104
503 # define CKR_F_PKCS11_ENUMERATE_SLOTS 105
504 # define CKR_F_PKCS11_FIND_CERTS 106
505 # define CKR_F_PKCS11_FIND_KEYS 107
506 # define CKR_F_PKCS11_GENERATE_RANDOM 108
507 # define CKR_F_PKCS11_GETATTR_ALLOC 109
508 # define CKR_F_PKCS11_GETATTR_BN 110
509 # define CKR_F_PKCS11_GETATTR_INT 111
510 # define CKR_F_PKCS11_INIT_PIN 112
511 # define CKR_F_PKCS11_INIT_SLOT 113
512 # define CKR_F_PKCS11_INIT_TOKEN 114
513 # define CKR_F_PKCS11_IS_LOGGED_IN 115
514 # define CKR_F_PKCS11_LOGIN 116
515 # define CKR_F_PKCS11_LOGOUT 117
516 # define CKR_F_PKCS11_NEXT_CERT 118
517 # define CKR_F_PKCS11_NEXT_KEY 119
518 # define CKR_F_PKCS11_OPEN_SESSION 120
519 # define CKR_F_PKCS11_PRIVATE_DECRYPT 121
520 # define CKR_F_PKCS11_PRIVATE_ENCRYPT 122
521 # define CKR_F_PKCS11_RELOAD_KEY 123
522 # define CKR_F_PKCS11_REOPEN_SESSION 124
523 # define CKR_F_PKCS11_SEED_RANDOM 125
524 # define CKR_F_PKCS11_STORE_CERTIFICATE 126
525 # define CKR_F_PKCS11_STORE_KEY 127
526 # define CKR_F_PKCS11_REMOVE_KEY 128
527 # define CKR_F_PKCS11_REMOVE_CERTIFICATE 129
528 # define CKR_F_PKCS11_GENERATE_KEY 130
529 
530 /* Backward compatibility of error function codes */
531 #define PKCS11_F_PKCS11_CHANGE_PIN CKR_F_PKCS11_CHANGE_PIN
532 #define PKCS11_F_PKCS11_CHECK_TOKEN CKR_F_PKCS11_CHECK_TOKEN
533 #define PKCS11_F_PKCS11_CTX_LOAD CKR_F_PKCS11_CTX_LOAD
534 #define PKCS11_F_PKCS11_ECDH_DERIVE CKR_F_PKCS11_ECDH_DERIVE
535 #define PKCS11_F_PKCS11_ECDSA_SIGN CKR_F_PKCS11_ECDSA_SIGN
536 #define PKCS11_F_PKCS11_ENUMERATE_SLOTS CKR_F_PKCS11_ENUMERATE_SLOTS
537 #define PKCS11_F_PKCS11_FIND_CERTS CKR_F_PKCS11_FIND_CERTS
538 #define PKCS11_F_PKCS11_FIND_KEYS CKR_F_PKCS11_FIND_KEYS
539 #define PKCS11_F_PKCS11_GENERATE_RANDOM CKR_F_PKCS11_GENERATE_RANDOM
540 #define PKCS11_F_PKCS11_GETATTR_ALLOC CKR_F_PKCS11_GETATTR_ALLOC
541 #define PKCS11_F_PKCS11_GETATTR_BN CKR_F_PKCS11_GETATTR_BN
542 #define PKCS11_F_PKCS11_GETATTR_INT CKR_F_PKCS11_GETATTR_INT
543 #define PKCS11_F_PKCS11_INIT_PIN CKR_F_PKCS11_INIT_PIN
544 #define PKCS11_F_PKCS11_INIT_SLOT CKR_F_PKCS11_INIT_SLOT
545 #define PKCS11_F_PKCS11_INIT_TOKEN CKR_F_PKCS11_INIT_TOKEN
546 #define PKCS11_F_PKCS11_IS_LOGGED_IN CKR_F_PKCS11_IS_LOGGED_IN
547 #define PKCS11_F_PKCS11_LOGIN CKR_F_PKCS11_LOGIN
548 #define PKCS11_F_PKCS11_LOGOUT CKR_F_PKCS11_LOGOUT
549 #define PKCS11_F_PKCS11_NEXT_CERT CKR_F_PKCS11_NEXT_CERT
550 #define PKCS11_F_PKCS11_NEXT_KEY CKR_F_PKCS11_NEXT_KEY
551 #define PKCS11_F_PKCS11_OPEN_SESSION CKR_F_PKCS11_OPEN_SESSION
552 #define PKCS11_F_PKCS11_PRIVATE_DECRYPT CKR_F_PKCS11_PRIVATE_DECRYPT
553 #define PKCS11_F_PKCS11_PRIVATE_ENCRYPT CKR_F_PKCS11_PRIVATE_ENCRYPT
554 #define PKCS11_F_PKCS11_RELOAD_KEY CKR_F_PKCS11_RELOAD_KEY
555 #define PKCS11_F_PKCS11_REOPEN_SESSION CKR_F_PKCS11_REOPEN_SESSION
556 #define PKCS11_F_PKCS11_SEED_RANDOM CKR_F_PKCS11_SEED_RANDOM
557 #define PKCS11_F_PKCS11_STORE_CERTIFICATE CKR_F_PKCS11_STORE_CERTIFICATE
558 #define PKCS11_F_PKCS11_STORE_KEY CKR_F_PKCS11_STORE_KEY
559 #define PKCS11_F_PKCS11_REMOVE_KEY CKR_F_PKCS11_REMOVE_KEY
560 #define PKCS11_F_PKCS11_REMOVE_CERTIFICATE CKR_F_PKCS11_REMOVE_CERTIFICATE
561 #define PKCS11_F_PKCS11_GENERATE_KEY CKR_F_PKCS11_GENERATE_KEY
562 
563 /* Backward compatibility of error reason codes */
564 #define PKCS11_LOAD_MODULE_ERROR P11_R_LOAD_MODULE_ERROR
565 #define PKCS11_MODULE_LOADED_ERROR -1
566 #define PKCS11_SYMBOL_NOT_FOUND_ERROR -1
567 #define PKCS11_NOT_SUPPORTED P11_R_NOT_SUPPORTED
568 #define PKCS11_NO_SESSION P11_R_NO_SESSION
569 #define PKCS11_KEYGEN_FAILED P11_R_KEYGEN_FAILED
570 #define PKCS11_UI_FAILED P11_R_UI_FAILED
571 
572 /* Backward compatibility emulation of the ERR_LIB_PKCS11 constant.
573  * We currently use two separate variables for library error codes:
574  * one for imported PKCS#11 module errors, and one for our own libp11 errors.
575  * We return the value for PKCS#11, as it is more likely to be needed. */
576 #define ERR_LIB_PKCS11 (ERR_get_CKR_code())
577 
578 #ifdef __cplusplus
579 }
580 #endif
581 #endif
582 
583 /* 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:60
int PKCS11_login(PKCS11_SLOT *slot, int so, const char *pin)
Authenticate to the card.
EVP_PKEY * evp_key
initially NULL, need to call PKCS11_load_key
Definition: libp11.h:62
PKCS11_TOKEN * token
NULL if no token present.
Definition: libp11.h:103
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:76
unsigned char needLogin
login to read private key?
Definition: libp11.h:61
PKCS11 key object (public or private)
Definition: libp11.h:56
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.
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.
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.
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.
PKCS11 slot: card reader.
Definition: libp11.h:99
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:108
int PKCS11_logout(PKCS11_SLOT *slot)
De-authenticate from the card.
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:67
int PKCS11_CTX_reload(PKCS11_CTX *ctx)
Reinitialize a PKCS#11 module (after a fork)
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