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 
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)
77 extern "C" {
78 #endif
79 
87 #define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_OPENSSL (1<< 0)
88 
89 #define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_GNUTLS (1<< 1)
90 
91 #define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_CRYPTOAPI (1<< 2)
92 
96 #define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_WIN32 (1<< 2)
97 
98 #define PKCS11H_FEATURE_MASK_DEBUG (1<< 3)
99 
100 #define PKCS11H_FEATURE_MASK_THREADING (1<< 4)
101 
102 #define PKCS11H_FEATURE_MASK_TOKEN (1<< 5)
103 
104 #define PKCS11H_FEATURE_MASK_DATA (1<< 6)
105 
106 #define PKCS11H_FEATURE_MASK_CERTIFICATE (1<< 7)
107 
108 #define PKCS11H_FEATURE_MASK_SLOTEVENT (1<< 8)
109 
110 #define PKCS11H_FEATURE_MASK_OPENSSL (1<< 9)
111 
112 #define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_POLARSSL (1<< 10)
113 
114 #define PKCS11H_FEATURE_MASK_ENGINE_CRYPTO_MBEDTLS (1<< 10)
115 
124 #define PKCS11H_LOG_DEBUG2 5
125 
126 #define PKCS11H_LOG_DEBUG1 4
127 
128 #define PKCS11H_LOG_INFO 3
129 
130 #define PKCS11H_LOG_WARN 2
131 
132 #define PKCS11H_LOG_ERROR 1
133 
134 #define PKCS11H_LOG_QUIET 0
135 
138 #define PKCS11H_PIN_CACHE_INFINITE -1
139 
146 #define PKCS11H_PRIVATEMODE_MASK_AUTO (0)
147 
148 #define PKCS11H_PRIVATEMODE_MASK_SIGN (1<<0)
149 
150 #define PKCS11H_PRIVATEMODE_MASK_RECOVER (1<<1)
151 
152 #define PKCS11H_PRIVATEMODE_MASK_DECRYPT (1<<2)
153 
154 #define PKCS11H_PRIVATEMODE_MASK_UNWRAP (1<<3)
155 
162 /* Auto select by provider information. */
163 #define PKCS11H_SLOTEVENT_METHOD_AUTO 0
164 
165 #define PKCS11H_SLOTEVENT_METHOD_TRIGGER 1
166 
167 #define PKCS11H_SLOTEVENT_METHOD_POLL 2
168 
169 #define PKCS11H_SLOTEVENT_METHOD_FETCH 3
170 
178 #define PKCS11H_PROMPT_MASK_ALLOW_PIN_PROMPT (1<<0)
179 
180 #define PKCS11H_PROMPT_MASK_ALLOW_TOKEN_PROMPT (1<<1)
181 
182 #define PKCS11H_PROMPT_MASK_ALLOW_KEY_PROMPT (1<<2)
183 
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 
198 #define PKCS11H_ENUM_METHOD_CACHE 0
199 
200 #define PKCS11H_ENUM_METHOD_CACHE_EXIST 1
201 
202 #define PKCS11H_ENUM_METHOD_RELOAD 2
203 
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 
336 #define PKCS11H_PROVIDER_PROPERTY_LOCATION 0
337 
342 #define PKCS11H_PROVIDER_PROPERTY_ALLOW_PROTECTED_AUTH 1
343 
348 #define PKCS11H_PROVIDER_PROPERTY_MASK_PRIVATE_MODE 2
349 
354 #define PKCS11H_PROVIDER_PROPERTY_SLOT_EVENT_METHOD 3
355 
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 
401 struct pkcs11h_token_id_s;
402 
407 
415 typedef 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 
426 typedef void (*pkcs11h_hook_slotevent_t)(
427  IN void * const global_data
428 );
429 
438 typedef 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 
455 typedef 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 
475 typedef 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 
485 typedef 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 
511 const char *
513  IN const CK_RV rv
514 );
515 
520 unsigned int
521 pkcs11h_getVersion (void);
522 
527 unsigned int
528 pkcs11h_getFeatures (void);
529 
536 CK_RV
537 pkcs11h_initialize (void);
538 
544 CK_RV
545 pkcs11h_terminate (void);
546 
555 CK_RV
557  IN const unsigned property,
558  OUT void * const value,
559  IN OUT size_t * const value_size
560 );
561 
570 CK_RV
572  IN const unsigned property,
573  IN const void * const value,
574  IN const size_t value_size
575 );
576 
581 void
583  IN const unsigned flags
584 );
585 
590 unsigned
591 pkcs11h_getLogLevel (void);
592 
605 CK_RV
607  IN const PKCS11H_BOOL safe
608 );
609 
616 CK_RV
618  IN const pkcs11h_hook_log_t hook,
619  IN void * const global_data
620 );
621 
633 CK_RV
635  IN const pkcs11h_hook_slotevent_t hook,
636  IN void * const global_data
637 );
638 
647 CK_RV
649  IN const pkcs11h_hook_token_prompt_t hook,
650  IN void * const global_data
651 );
652 
661 CK_RV
663  IN const pkcs11h_hook_pin_prompt_t hook,
664  IN void * const global_data
665 );
666 
673 CK_RV
675  IN const PKCS11H_BOOL allow_protected_auth
676 );
677 
684 CK_RV
686  IN const int pin_cache_period
687 );
688 
695 CK_RV
697  IN const unsigned max_retries
698 );
699 
713 CK_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 
729 CK_RV
731  IN const char * const reference
732 );
733 
740 CK_RV
742  IN const char * const reference,
743  IN const char * const property_str,
744  IN const char * const value_str
745 );
746 
756 CK_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 
771 CK_RV
773  IN const char * const reference
774 );
775 
782 CK_RV
784  IN const char * const reference
785 );
786 
802 CK_RV
803 pkcs11h_forkFixup (void);
804 
816 CK_RV
817 pkcs11h_plugAndPlay (void);
818 
823 CK_RV
824 pkcs11h_logout (void);
825 
826 #ifdef __cplusplus
827 }
828 #endif
829 
832 #endif /* __PKCS11H_BASE_H */
CK_RV pkcs11h_registerProvider(IN const char *const reference)
Register a PKCS#11 provider.
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
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.
char serialNumber[sizeof(((CK_TOKEN_INFO *) NULL) ->serialNumber)+1]
Definition: pkcs11h-core.h:501
const char * pkcs11h_getMessage(IN const CK_RV rv)
Get message by return value.
unsigned pkcs11h_getLogLevel(void)
Get current log level.
char model[sizeof(((CK_TOKEN_INFO *) NULL) ->model)+1]
Definition: pkcs11h-core.h:499
char manufacturerID[sizeof(((CK_TOKEN_INFO *) NULL) ->manufacturerID)+1]
Definition: pkcs11h-core.h:497
CK_RV pkcs11h_plugAndPlay(void)
Handle slot rescan.
char display[1024]
Definition: pkcs11h-core.h:495
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.
CK_RV pkcs11h_setMaxLoginRetries(IN const unsigned max_retries)
Set global login retries attempts.
Token identifier.
Definition: pkcs11h-core.h:493
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_forkFixup(void)
Handle special case of POSIX fork()
void(* pkcs11h_hook_slotevent_t)(IN void *const global_data)
Slotevent hook.
Definition: pkcs11h-core.h:426
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
unsigned int pkcs11h_getFeatures(void)
Get features of library.
CK_RV pkcs11h_setTokenPromptHook(IN const pkcs11h_hook_token_prompt_t hook, IN void *const global_data)
Set a token prompt callback.
CK_RV pkcs11h_setPINCachePeriod(IN const int pin_cache_period)
Set global PIN cache timeout.
CK_RV pkcs11h_setPINPromptHook(IN const pkcs11h_hook_pin_prompt_t hook, IN void *const global_data)
Set a pin prompt callback.
pkcs11-helper core.
CK_RV pkcs11h_initialize(void)
Initialize helper interface.
CK_RV pkcs11h_terminate(void)
Terminate helper interface.
CK_RV pkcs11h_setProtectedAuthentication(IN const PKCS11H_BOOL allow_protected_auth)
Set global protected authentication mode.
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_setSlotEventHook(IN const pkcs11h_hook_slotevent_t hook, IN void *const global_data)
Set a slot event callback.
CK_RV pkcs11h_removeProvider(IN const char *const reference)
Delete a PKCS#11 provider.
CK_RV pkcs11h_setForkMode(IN const PKCS11H_BOOL safe)
How does the foked process bahaves after POSIX fork()
CK_RV pkcs11h_setLogHook(IN const pkcs11h_hook_log_t hook, IN void *const global_data)
Set a log callback.
unsigned int pkcs11h_getVersion(void)
Get version 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_initializeProvider(IN const char *const reference)
Initialize a PKCS#11 provider.
void pkcs11h_setLogLevel(IN const unsigned flags)
Set current log level of the helper.
pkcs11-helper engines definitions.
struct pkcs11h_token_id_s * pkcs11h_token_id_t
Token identifier.
Definition: pkcs11h-core.h:406
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_getProperty(IN const unsigned property, OUT void *const value, IN OUT size_t *const value_size)
Get library property.
pkcs11-helper core definitions.
char label[sizeof(((CK_TOKEN_INFO *) NULL) ->label)+1]
Definition: pkcs11h-core.h:503

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