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

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