pkcs11-helper
pkcs11h-core.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2005-2018 Alon Bar-Lev <alon.barlev@gmail.com>
3 *
4 * This software is available to you under a choice of one of two
5 * licenses. You may choose to be licensed under the terms of the GNU
6 * General Public License (GPL) Version 2, or the BSD license.
7 *
8 * GNU General Public License (GPL) Version 2
9 * ===========================================
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License version 2
12 * as published by the Free Software Foundation.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with this program (see the file COPYING.GPL included with this
21 * distribution); if not, write to the Free Software Foundation, Inc.,
22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
23 *
24 * BSD License
25 * ============
26 * Redistribution and use in source and binary forms, with or without
27 * modification, are permitted provided that the following conditions are met:
28 *
29 * o Redistributions of source code must retain the above copyright notice,
30 * this list of conditions and the following disclaimer.
31 * o Redistributions in binary form must reproduce the above copyright
32 * notice, this list of conditions and the following disclaimer in the
33 * documentation and/or other materials provided with the distribution.
34 * o Neither the name of the Alon Bar-Lev nor the names of its
35 * contributors may be used to endorse or promote products derived from
36 * this software without specific prior written permission.
37 *
38 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
39 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
41 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
42 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
43 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
44 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
45 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
46 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
47 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
48 * POSSIBILITY OF SUCH DAMAGE.
49 */
50
58
65
66#ifndef __PKCS11H_BASE_H
67#define __PKCS11H_BASE_H
68
69#include <stdarg.h>
70#include <time.h>
71
75
76#if defined(__cplusplus)
77extern "C" {
78#endif
79
87#define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_OPENSSL (1<< 0)
89#define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_GNUTLS (1<< 1)
91#define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_CRYPTOAPI (1<< 2)
96#define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_WIN32 (1<< 2)
98#define PKCS11H_FEATURE_MASK_DEBUG (1<< 3)
100#define PKCS11H_FEATURE_MASK_THREADING (1<< 4)
102#define PKCS11H_FEATURE_MASK_TOKEN (1<< 5)
104#define PKCS11H_FEATURE_MASK_DATA (1<< 6)
106#define PKCS11H_FEATURE_MASK_CERTIFICATE (1<< 7)
108#define PKCS11H_FEATURE_MASK_SLOTEVENT (1<< 8)
110#define PKCS11H_FEATURE_MASK_OPENSSL (1<< 9)
112#define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_POLARSSL (1<< 10)
114#define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_MBEDTLS (1<< 10)
116
124#define PKCS11H_LOG_DEBUG2 5
126#define PKCS11H_LOG_DEBUG1 4
128#define PKCS11H_LOG_INFO 3
130#define PKCS11H_LOG_WARN 2
132#define PKCS11H_LOG_ERROR 1
134#define PKCS11H_LOG_QUIET 0
136
138#define PKCS11H_PIN_CACHE_INFINITE -1
139
146#define PKCS11H_PRIVATEMODE_MASK_AUTO (0)
148#define PKCS11H_PRIVATEMODE_MASK_SIGN (1<<0)
150#define PKCS11H_PRIVATEMODE_MASK_RECOVER (1<<1)
152#define PKCS11H_PRIVATEMODE_MASK_DECRYPT (1<<2)
154#define PKCS11H_PRIVATEMODE_MASK_UNWRAP (1<<3)
156
162/* Auto select by provider information. */
163#define PKCS11H_SLOTEVENT_METHOD_AUTO 0
165#define PKCS11H_SLOTEVENT_METHOD_TRIGGER 1
167#define PKCS11H_SLOTEVENT_METHOD_POLL 2
169#define PKCS11H_SLOTEVENT_METHOD_FETCH 3
171
178#define PKCS11H_PROMPT_MASK_ALLOW_PIN_PROMPT (1<<0)
180#define PKCS11H_PROMPT_MASK_ALLOW_TOKEN_PROMPT (1<<1)
182#define PKCS11H_PROMPT_MASK_ALLOW_KEY_PROMPT (1<<2)
184#define PKCS11H_PROMPT_MASK_ALLOW_ALL ( \
185 PKCS11H_PROMPT_MASK_ALLOW_PIN_PROMPT | \
186 PKCS11H_PROMPT_MASK_ALLOW_TOKEN_PROMPT | \
187 PKCS11H_PROMPT_MASK_ALLOW_KEY_PROMPT | \
188 0 \
189 )
190
191
198#define PKCS11H_ENUM_METHOD_CACHE 0
200#define PKCS11H_ENUM_METHOD_CACHE_EXIST 1
202#define PKCS11H_ENUM_METHOD_RELOAD 2
204
205
211
212/*
213 * @brief The current log level of the helper.
214 * Value type is @ref PKCS11H_LOG.
215 * Default is PKCS11H_LOG_INFO.
216 */
217#define PKCS11H_PROPERTY_LOG_LEVEL 0
218
231#define PKCS11H_PROPERTY_FORK_MODE 1
232
237#define PKCS11H_PROPERTY_LOG_HOOK 2
238
243#define PKCS11H_PROPERTY_LOG_HOOK_DATA 3
244
253#define PKCS11H_PROPERTY_SLOT_EVENT_HOOK 4
254
259#define PKCS11H_PROPERTY_SLOT_EVENT_HOOK_DATA 5
260
267#define PKCS11H_PROPERTY_TOKEN_PROMPT_HOOK 6
268
273#define PKCS11H_PROPERTY_TOKEN_PROMPT_HOOK_DATA 7
274
281#define PKCS11H_PROPERTY_PIN_PROMPT_HOOK 8
282
287#define PKCS11H_PROPERTY_PIN_PROMPT_HOOK_DATA 9
288
294#define PKCS11H_PROPERTY_ALLOW_PROTECTED_AUTHENTICATION 10
295
301#define PKCS11H_PROPERTY_PIN_CACHE_PERIOD 11
302
308#define PKCS11H_PROPERTY_MAX_LOGIN_RETRIES 12
309
316#define PKCS11H_PROPERTY_KEY_PROMPT_HOOK 13
317
322#define PKCS11H_PROPERTY_KEY_PROMPT_HOOK_DATA 14
323
325
331
336#define PKCS11H_PROVIDER_PROPERTY_LOCATION 0
342#define PKCS11H_PROVIDER_PROPERTY_ALLOW_PROTECTED_AUTH 1
348#define PKCS11H_PROVIDER_PROPERTY_MASK_PRIVATE_MODE 2
354#define PKCS11H_PROVIDER_PROPERTY_SLOT_EVENT_METHOD 3
360#define PKCS11H_PROVIDER_PROPERTY_SLOT_POLL_INTERVAL 4
361/*
362 * @brief Provider's certificate access should be done after login.
363 * Value type is @ref PKCS11H_BOOL.
364 * Default value is False.
365*/
366#define PKCS11H_PROVIDER_PROPERTY_CERT_IS_PRIVATE 5
367
373#define PKCS11H_PROVIDER_PROPERTY_INIT_ARGS 6
374
379#define PKCS11H_PROVIDER_PROPERTY_PROVIDER_DESTRUCT_HOOK 7
380
385#define PKCS11H_PROVIDER_PROPERTY_PROVIDER_DESTRUCT_HOOK_DATA 8
386
394#define PKCS11H_PROVIDER_PROPERTY_LOADER_FLAGS 9
395
397#define _PKCS11H_PROVIDER_PROPERTY_LAST 10
398
400
401struct pkcs11h_token_id_s;
402
407
415typedef void (*pkcs11h_hook_log_t)(
416 IN void * const global_data,
417 IN const unsigned flags,
418 IN const char * const format,
419 IN va_list args
420);
421
427 IN void * const global_data
428);
429
438typedef PKCS11H_BOOL (*pkcs11h_hook_token_prompt_t)(
439 IN void * const global_data,
440 IN void * const user_data,
441 IN const pkcs11h_token_id_t token,
442 IN const unsigned retry
443);
444
455typedef PKCS11H_BOOL (*pkcs11h_hook_pin_prompt_t)(
456 IN void * const global_data,
457 IN void * const user_data,
458 IN const pkcs11h_token_id_t token,
459 IN const unsigned retry,
460 OUT char * const pin,
461 IN const size_t pin_max
462);
463
475typedef PKCS11H_BOOL (*pkcs11h_hook_key_prompt_t)(
476 IN void * const global_data,
477 IN void * const user_data,
478 IN const pkcs11h_token_id_t token,
479 IN const char * const label,
480 IN const unsigned retry,
481 OUT char * const pin,
482 IN const size_t pin_max
483);
484
485typedef void (*pkcs11h_provider_destruct_hook_t)(
486 IN void * const global_data,
487 IN const char * const reference
488);
489
495 char display[1024];
497 char manufacturerID[sizeof (((CK_TOKEN_INFO *)NULL)->manufacturerID)+1];
499 char model[sizeof (((CK_TOKEN_INFO *)NULL)->model)+1];
501 char serialNumber[sizeof (((CK_TOKEN_INFO *)NULL)->serialNumber)+1];
503 char label[sizeof (((CK_TOKEN_INFO *)NULL)->label)+1];
504};
505
511const char *
513 IN const CK_RV rv
514);
515
520unsigned int
522
527unsigned int
529
536CK_RV
538
544CK_RV
546
555CK_RV
557 IN const unsigned property,
558 OUT void * const value,
559 IN OUT size_t * const value_size
560);
561
570CK_RV
572 IN const unsigned property,
573 IN const void * const value,
574 IN const size_t value_size
575);
576
581void
583 IN const unsigned flags
584);
585
590unsigned
592
605CK_RV
607 IN const PKCS11H_BOOL safe
608);
609
616CK_RV
618 IN const pkcs11h_hook_log_t hook,
619 IN void * const global_data
620);
621
633CK_RV
635 IN const pkcs11h_hook_slotevent_t hook,
636 IN void * const global_data
637);
638
647CK_RV
649 IN const pkcs11h_hook_token_prompt_t hook,
650 IN void * const global_data
651);
652
661CK_RV
663 IN const pkcs11h_hook_pin_prompt_t hook,
664 IN void * const global_data
665);
666
673CK_RV
675 IN const PKCS11H_BOOL allow_protected_auth
676);
677
684CK_RV
686 IN const int pin_cache_period
687);
688
695CK_RV
697 IN const unsigned max_retries
698);
699
713CK_RV
715 IN const char * const reference,
716 IN const char * const provider_location,
717 IN const PKCS11H_BOOL allow_protected_auth,
718 IN const unsigned mask_private_mode,
719 IN const unsigned slot_event_method,
720 IN const unsigned slot_poll_interval,
721 IN const PKCS11H_BOOL cert_is_private
722);
723
729CK_RV
731 IN const char * const reference
732);
733
740CK_RV
742 IN const char * const reference,
743 IN const char * const property_str,
744 IN const char * const value_str
745);
746
756CK_RV
758 IN const char * const reference,
759 IN const unsigned property,
760 IN const void * value,
761 IN const size_t value_size
762);
763
771CK_RV
773 IN const char * const reference
774);
775
782CK_RV
784 IN const char * const reference
785);
786
802CK_RV
804
816CK_RV
818
823CK_RV
825
826#ifdef __cplusplus
827}
828#endif
829
831
832#endif /* __PKCS11H_BASE_H */
PKCS11H_BOOL(* pkcs11h_hook_key_prompt_t)(IN void *const global_data, IN void *const user_data, IN const pkcs11h_token_id_t token, IN const char *const label, IN const unsigned retry, OUT char *const pin, IN const size_t pin_max)
Key prompt hook.
Definition pkcs11h-core.h:475
CK_RV pkcs11h_setProtectedAuthentication(IN const PKCS11H_BOOL allow_protected_auth)
Set global protected authentication mode.
CK_RV pkcs11h_setForkMode(IN const PKCS11H_BOOL safe)
How does the foked process bahaves after POSIX fork()
CK_RV pkcs11h_setTokenPromptHook(IN const pkcs11h_hook_token_prompt_t hook, IN void *const global_data)
Set a token prompt callback.
struct pkcs11h_token_id_s * pkcs11h_token_id_t
Token identifier.
Definition pkcs11h-core.h:406
CK_RV pkcs11h_getProperty(IN const unsigned property, OUT void *const value, IN OUT size_t *const value_size)
Get library property.
CK_RV pkcs11h_logout(void)
Logout from all sessions.
PKCS11H_BOOL(* pkcs11h_hook_pin_prompt_t)(IN void *const global_data, IN void *const user_data, IN const pkcs11h_token_id_t token, IN const unsigned retry, OUT char *const pin, IN const size_t pin_max)
PIN prompt hook.
Definition pkcs11h-core.h:455
const char * pkcs11h_getMessage(IN const CK_RV rv)
Get message by return value.
CK_RV pkcs11h_setProviderProperty(IN const char *const reference, IN const unsigned property, IN const void *value, IN const size_t value_size)
Set PKCS#11 provider property.
CK_RV pkcs11h_setSlotEventHook(IN const pkcs11h_hook_slotevent_t hook, IN void *const global_data)
Set a slot event callback.
CK_RV pkcs11h_setProviderPropertyByName(IN const char *const reference, IN const char *const property_str, IN const char *const value_str)
Set PKCS#11 provider property by name.
unsigned int pkcs11h_getFeatures(void)
Get features of library.
PKCS11H_BOOL(* pkcs11h_hook_token_prompt_t)(IN void *const global_data, IN void *const user_data, IN const pkcs11h_token_id_t token, IN const unsigned retry)
Token prompt hook.
Definition pkcs11h-core.h:438
CK_RV pkcs11h_forkFixup(void)
Handle special case of POSIX fork()
void(* pkcs11h_hook_log_t)(IN void *const global_data, IN const unsigned flags, IN const char *const format, IN va_list args)
Log hook.
Definition pkcs11h-core.h:415
CK_RV pkcs11h_terminate(void)
Terminate helper interface.
CK_RV pkcs11h_setPINCachePeriod(IN const int pin_cache_period)
Set global PIN cache timeout.
unsigned pkcs11h_getLogLevel(void)
Get current log level.
void pkcs11h_setLogLevel(IN const unsigned flags)
Set current log level of the helper.
CK_RV pkcs11h_setPINPromptHook(IN const pkcs11h_hook_pin_prompt_t hook, IN void *const global_data)
Set a pin prompt callback.
CK_RV pkcs11h_setMaxLoginRetries(IN const unsigned max_retries)
Set global login retries attempts.
CK_RV pkcs11h_removeProvider(IN const char *const reference)
Delete a PKCS#11 provider.
CK_RV pkcs11h_initialize(void)
Initialize helper interface.
CK_RV pkcs11h_registerProvider(IN const char *const reference)
Register a PKCS#11 provider.
CK_RV pkcs11h_initializeProvider(IN const char *const reference)
Initialize a PKCS#11 provider.
void(* pkcs11h_hook_slotevent_t)(IN void *const global_data)
Slotevent hook.
Definition pkcs11h-core.h:426
unsigned int pkcs11h_getVersion(void)
Get version of library.
CK_RV pkcs11h_setProperty(IN const unsigned property, IN const void *const value, IN const size_t value_size)
Set library property.
CK_RV pkcs11h_setLogHook(IN const pkcs11h_hook_log_t hook, IN void *const global_data)
Set a log callback.
CK_RV pkcs11h_plugAndPlay(void)
Handle slot rescan.
CK_RV pkcs11h_addProvider(IN const char *const reference, IN const char *const provider_location, IN const PKCS11H_BOOL allow_protected_auth, IN const unsigned mask_private_mode, IN const unsigned slot_event_method, IN const unsigned slot_poll_interval, IN const PKCS11H_BOOL cert_is_private)
Register, configure and initialize a PKCS#11 provider.
pkcs11-helper core definitions.
pkcs11-helper engines definitions.
pkcs11-helper core.
Token identifier.
Definition pkcs11h-core.h:493
char label[sizeof(((CK_TOKEN_INFO *) NULL) ->label)+1]
Definition pkcs11h-core.h:503
char manufacturerID[sizeof(((CK_TOKEN_INFO *) NULL) ->manufacturerID)+1]
Definition pkcs11h-core.h:497
char model[sizeof(((CK_TOKEN_INFO *) NULL) ->model)+1]
Definition pkcs11h-core.h:499
char serialNumber[sizeof(((CK_TOKEN_INFO *) NULL) ->serialNumber)+1]
Definition pkcs11h-core.h:501
char display[1024]
Definition pkcs11h-core.h:495

pkcs11-helper, Copyright (C) Alon Bar-Lev <alon.barlev@gmail.com>OpenSC-Project.org Logo