libp11  0.4.2
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 <openssl/bio.h>
28 #include <openssl/err.h>
29 #include <openssl/bn.h>
30 #include <openssl/rsa.h>
31 #include <openssl/x509.h>
32 
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36 
37 /* Get some structures for local code to handle PKCS#11 data readily */
38 #define ERR_LIB_PKCS11 ERR_LIB_USER
39 
40 #define PKCS11err(f,r) \
41  ERR_PUT_error(ERR_LIB_PKCS11,(f),(r),__FILE__,__LINE__)
42 
43 /*
44  * The purpose of this library is to provide a simple PKCS11
45  * interface to OpenSSL application that wish to use a previously
46  * initialized card (as opposed to initializing it, etc).
47  *
48  * I am therefore making some simplifying assumptions:
49  *
50  * - no support for any operations that alter the card,
51  * i.e. readonly-login
52  */
53 
55 typedef struct PKCS11_key_st {
56  char *label;
57  unsigned char *id;
58  size_t id_len;
59  unsigned char isPrivate;
60  unsigned char needLogin;
61  EVP_PKEY *evp_key;
62  void *_private;
63 } PKCS11_KEY;
64 
66 typedef struct PKCS11_cert_st {
67  char *label;
68  unsigned char *id;
69  size_t id_len;
70  X509 *x509;
71  void *_private;
72 } PKCS11_CERT;
73 
75 typedef struct PKCS11_token_st {
76  char *label;
77  char *manufacturer;
78  char *model;
79  char *serialnr;
80  unsigned char initialized;
81  unsigned char loginRequired;
82  unsigned char secureLogin;
83  unsigned char userPinSet;
84  unsigned char readOnly;
85  unsigned char hasRng;
86  unsigned char userPinCountLow;
87  unsigned char userPinFinalTry;
88  unsigned char userPinLocked;
89  unsigned char userPinToBeChanged;
90  unsigned char soPinCountLow;
91  unsigned char soPinFinalTry;
92  unsigned char soPinLocked;
93  unsigned char soPinToBeChanged;
94  void *_private;
95 } PKCS11_TOKEN;
96 
98 typedef struct PKCS11_slot_st {
99  char *manufacturer;
100  char *description;
101  unsigned char removable;
103  void *_private;
104 } PKCS11_SLOT;
105 
107 typedef struct PKCS11_ctx_st {
108  char *manufacturer;
109  char *description;
110  void *_private;
111 } PKCS11_CTX;
112 
119 extern PKCS11_CTX *PKCS11_CTX_new(void);
120 
126 extern void PKCS11_CTX_init_args(PKCS11_CTX * ctx, const char * init_args);
127 
136 extern int PKCS11_CTX_load(PKCS11_CTX * ctx, const char * ident);
137 
145 extern int PKCS11_CTX_reload(PKCS11_CTX * ctx);
146 
152 extern void PKCS11_CTX_unload(PKCS11_CTX * ctx);
153 
159 extern void PKCS11_CTX_free(PKCS11_CTX * ctx);
160 
168 extern int PKCS11_open_session(PKCS11_SLOT * slot, int rw);
169 
179 extern int PKCS11_enumerate_slots(PKCS11_CTX * ctx,
180  PKCS11_SLOT **slotsp, unsigned int *nslotsp);
181 
188 extern unsigned long PKCS11_get_slotid_from_slot(PKCS11_SLOT *slotp);
189 
197 extern void PKCS11_release_all_slots(PKCS11_CTX * ctx,
198  PKCS11_SLOT *slots, unsigned int nslots);
199 
210  PKCS11_SLOT *slots, unsigned int nslots);
211 
221 extern int PKCS11_is_logged_in(PKCS11_SLOT * slot, int so, int * res);
222 
232 extern int PKCS11_login(PKCS11_SLOT * slot, int so, const char *pin);
233 
241 extern int PKCS11_logout(PKCS11_SLOT * slot);
242 
243 /* Get a list of private keys associated with this token */
244 extern int PKCS11_enumerate_keys(PKCS11_TOKEN *,
245  PKCS11_KEY **, unsigned int *);
246 
247 /* Get a list of public keys associated with this token */
248 extern int PKCS11_enumerate_public_keys(PKCS11_TOKEN *,
249  PKCS11_KEY **, unsigned int *);
250 
251 /* Get the key type (as EVP_PKEY_XXX) */
252 extern int PKCS11_get_key_type(PKCS11_KEY *);
253 
261 extern EVP_PKEY *PKCS11_get_private_key(PKCS11_KEY *key);
262 
270 extern EVP_PKEY *PKCS11_get_public_key(PKCS11_KEY *key);
271 
272 /* Find the corresponding certificate (if any) */
273 extern PKCS11_CERT *PKCS11_find_certificate(PKCS11_KEY *);
274 
275 /* Find the corresponding key (if any) */
276 extern PKCS11_KEY *PKCS11_find_key(PKCS11_CERT *);
277 
278 /* Find the corresponding key (if any) pub <-> priv base on ID */
279 extern PKCS11_KEY *PKCS11_find_key_from_key(PKCS11_KEY *);
280 
281 /* Get a list of all certificates associated with this token */
282 extern int PKCS11_enumerate_certs(PKCS11_TOKEN *, PKCS11_CERT **, unsigned int *);
283 
293 extern int PKCS11_init_token(PKCS11_TOKEN * token, const char *pin,
294  const char *label);
295 
304 extern int PKCS11_init_pin(PKCS11_TOKEN * token, const char *pin);
305 
315 extern int PKCS11_change_pin(PKCS11_SLOT * slot, const char *old_pin,
316  const char *new_pin);
317 
329 extern int PKCS11_store_private_key(PKCS11_TOKEN * token, EVP_PKEY * pk, char *label, unsigned char *id, size_t id_len);
330 
342 extern int PKCS11_store_public_key(PKCS11_TOKEN * token, EVP_PKEY * pk, char *label, unsigned char *id, size_t id_len);
343 
356 extern int PKCS11_store_certificate(PKCS11_TOKEN * token, X509 * x509,
357  char *label, unsigned char *id, size_t id_len,
358  PKCS11_CERT **ret_cert);
359 
360 /* Access the random number generator */
361 extern int PKCS11_seed_random(PKCS11_SLOT *slot, const unsigned char *s, unsigned int s_len);
362 extern int PKCS11_generate_random(PKCS11_SLOT *slot, unsigned char *r, unsigned int r_len);
363 
364 /*
365  * PKCS#11 implementation for OpenSSL methods
366  */
367 RSA_METHOD *PKCS11_get_rsa_method(void);
368 /* Also define unsupported methods to retain backward compatibility */
369 #if OPENSSL_VERSION_NUMBER >= 0x10100002L
370 EC_KEY_METHOD *PKCS11_get_ec_key_method(void);
371 void *PKCS11_get_ecdsa_method(void);
372 void *PKCS11_get_ecdh_method(void);
373 #else
374 void *PKCS11_get_ec_key_method(void);
375 ECDSA_METHOD *PKCS11_get_ecdsa_method(void);
376 ECDH_METHOD *PKCS11_get_ecdh_method(void);
377 #endif
378 
385 extern void ERR_load_PKCS11_strings(void);
386 
387 #if defined(_LIBP11_INT_H)
388  /* Deprecated functions will no longer be exported in libp11 0.5.0 */
389  /* They are, however, used internally in OpenSSL method definitions */
390 #define P11_DEPRECATED(msg)
391 #elif defined(_MSC_VER)
392 #define P11_DEPRECATED(msg) __declspec(deprecated(msg))
393 #elif defined(__GNUC__)
394 #if (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__) >= 40500
395  /* GCC >= 4.5.0 supports printing a message */
396 #define P11_DEPRECATED(msg) __attribute__ ((deprecated(msg)))
397 #else
398 #define P11_DEPRECATED(msg) __attribute__ ((deprecated))
399 #endif
400 #elif defined(__clang__)
401 #define P11_DEPRECATED(msg) __attribute__ ((deprecated(msg)))
402 #else
403 #define P11_DEPRECATED(msg)
404 #endif
405 
406 #define P11_DEPRECATED_FUNC \
407  P11_DEPRECATED("This function will be removed in libp11 0.5.0")
408 
409 /*
410  * These functions will be removed from libp11, because they partially
411  * duplicate the functionality OpenSSL provides for EVP_PKEY objects
412  */
413 
426 P11_DEPRECATED_FUNC extern int PKCS11_generate_key(PKCS11_TOKEN * token,
427  int algorithm, unsigned int bits,
428  char *label, unsigned char* id, size_t id_len);
429 
430 /* Get the RSA key modulus size (in bytes) */
431 P11_DEPRECATED_FUNC extern int PKCS11_get_key_size(PKCS11_KEY *);
432 
433 /* Get the RSA key modules as BIGNUM */
434 P11_DEPRECATED_FUNC extern int PKCS11_get_key_modulus(PKCS11_KEY *, BIGNUM **);
435 
436 /* Get the RSA key public exponent as BIGNUM */
437 P11_DEPRECATED_FUNC extern int PKCS11_get_key_exponent(PKCS11_KEY *, BIGNUM **);
438 
439 /* Sign with the EC private key */
440 P11_DEPRECATED_FUNC extern int PKCS11_ecdsa_sign(
441  const unsigned char *m, unsigned int m_len,
442  unsigned char *sigret, unsigned int *siglen, PKCS11_KEY * key);
443 
444 /* Sign with the RSA private key */
445 P11_DEPRECATED_FUNC extern int PKCS11_sign(int type,
446  const unsigned char *m, unsigned int m_len,
447  unsigned char *sigret, unsigned int *siglen, PKCS11_KEY * key);
448 
449 /* This function has never been implemented */
450 P11_DEPRECATED_FUNC extern int PKCS11_verify(int type,
451  const unsigned char *m, unsigned int m_len,
452  unsigned char *signature, unsigned int siglen, PKCS11_KEY * key);
453 
454 /* Encrypts data using the private key */
455 P11_DEPRECATED_FUNC extern int PKCS11_private_encrypt(
456  int flen, const unsigned char *from,
457  unsigned char *to, PKCS11_KEY * rsa, int padding);
458 
469 P11_DEPRECATED_FUNC extern int PKCS11_private_decrypt(
470  int flen, const unsigned char *from,
471  unsigned char *to, PKCS11_KEY * key, int padding);
472 
473 /*
474  * Function and reason codes
475  */
476 #define PKCS11_F_PKCS11_CTX_LOAD 1
477 #define PKCS11_F_PKCS11_ENUM_SLOTS 2
478 #define PKCS11_F_PKCS11_CHECK_TOKEN 3
479 #define PKCS11_F_PKCS11_OPEN_SESSION 4
480 #define PKCS11_F_PKCS11_LOGIN 5
481 #define PKCS11_F_PKCS11_ENUM_KEYS 6
482 #define PKCS11_F_PKCS11_GET_KEY 7
483 #define PKCS11_F_PKCS11_RSA_DECRYPT 8
484 #define PKCS11_F_PKCS11_RSA_ENCRYPT 9
485 #define PKCS11_F_PKCS11_RSA_SIGN 10
486 #define PKCS11_F_PKCS11_RSA_VERIFY 11
487 #define PKCS11_F_PKCS11_ENUM_CERTS 12
488 #define PKCS11_F_PKCS11_INIT_TOKEN 13
489 #define PKCS11_F_PKCS11_INIT_PIN 14
490 #define PKCS11_F_PKCS11_LOGOUT 15
491 #define PKCS11_F_PKCS11_STORE_PRIVATE_KEY 16
492 #define PKCS11_F_PKCS11_GENERATE_KEY 17
493 #define PKCS11_F_PKCS11_STORE_PUBLIC_KEY 18
494 #define PKCS11_F_PKCS11_STORE_CERTIFICATE 19
495 #define PKCS11_F_PKCS11_SEED_RANDOM 20
496 #define PKCS11_F_PKCS11_GENERATE_RANDOM 21
497 #define PKCS11_F_PKCS11_CHANGE_PIN 22
498 #define PKCS11_F_PKCS11_GETATTR 40
499 #define PKCS11_F_PKCS11_EC_KEY_SIGN 41
500 #define PKCS11_F_PKCS11_EC_KEY_VERIFY 42
501 #define PKCS11_F_PKCS11_GETSESSIONINFO 43
502 #define PKCS11_F_PKCS11_EC_KEY_COMPUTE_KEY 44
503 
504 #define PKCS11_ERR_BASE 1024
505 #define PKCS11_LOAD_MODULE_ERROR (PKCS11_ERR_BASE+1)
506 #define PKCS11_MODULE_LOADED_ERROR (PKCS11_ERR_BASE+2)
507 #define PKCS11_SYMBOL_NOT_FOUND_ERROR (PKCS11_ERR_BASE+3)
508 #define PKCS11_NOT_SUPPORTED (PKCS11_ERR_BASE+4)
509 #define PKCS11_NO_SESSION (PKCS11_ERR_BASE+5)
510 #define PKCS11_KEYGEN_FAILED (PKCS11_ERR_BASE+6)
511 #define PKCS11_ALIEN_KEY (PKCS11_ERR_BASE+7)
512 
513 #ifdef __cplusplus
514 }
515 #endif
516 #endif
517 
518 /* 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:59
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:61
PKCS11_TOKEN * token
NULL if no token present.
Definition: libp11.h:102
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:75
unsigned char needLogin
login to read private key?
Definition: libp11.h:60
PKCS11 key object (public or private)
Definition: libp11.h:55
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.
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 and store 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:98
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:107
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:66
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 user 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