Debian Codegraph @

deps/libneon/src/ne_pkcs11.h

raw
1 /*
2 PKCS#11 support for neon
3 Copyright (C) 2008, Joe Orton <[email protected]>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public
16 License along with this library; if not, write to the Free
17 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
18 MA 02111-1307, USA
19
20 */
21
22 #ifndef NE_PKCS11_H
23 #define NE_PKCS11_H 1
24
25 #include "ne_defs.h"
26 #include "ne_session.h"
27
28 NE_BEGIN_DECLS
29
30 typedef struct ne_ssl_pkcs11_provider_s ne_ssl_pkcs11_provider;
31
32 #define NE_PK11_OK (0)
33 #define NE_PK11_NOTIMPL (-1)
34 #define NE_PK11_FAILED (-2)
35
36 /* Initialize a PKCS#11 provider of given name. Returns NE_OK on
37 * success, NE_PK11_FAILED if the provider could not be
38 * loaded/initialized, and NE_PK11_NOTIMPL if PKCS#11 is not
39 * supported. On success, *provider is set to non-NULL. */
40 int ne_ssl_pkcs11_provider_init(ne_ssl_pkcs11_provider **provider,
41 const char *name);
42
43 /* Initialize a NSS softoken pseudo-PKCS#11 provider of given name
44 * (e.g. "softokn3") to supply a client certificate if requested,
45 * using database in given directory name; the other parameters may be
46 * NULL. Returns NE_OK on success, NE_PK11_FAILED if the provider
47 * could not be loaded/initialized, and NE_PK11_NOTIMPL if PKCS#11 is
48 * not supported. On success, *provider is set to non-NULL. */
49 int ne_ssl_pkcs11_nss_provider_init(ne_ssl_pkcs11_provider **provider,
50 const char *name, const char *directory,
51 const char *cert_prefix,
52 const char *key_prefix,
53 const char *secmod_db);
54
55 /* Destroy a PKCS#11 provider object. */
56 void ne_ssl_pkcs11_provider_destroy(ne_ssl_pkcs11_provider *provider);
57
58
59 /* Flags passed to PIN entry callback: */
60 #define NE_SSL_P11PIN_COUNT_LOW (0x01) /* an incorrect PIN has been
61 * entered. */
62 #define NE_SSL_P11PIN_FINAL_TRY (0x02) /* token will become locked if
63 * entered PIN is incorrect */
64
65 /* Size of buffer passed to PIN entry callback: */
66 #define NE_SSL_P11PINLEN (256)
67
68 /* Callback for PKCS#11 PIN entry. The callback provides the PIN code
69 * to unlock the token with label 'token_label' in the slot described
70 * by 'slot_descr'.
71 *
72 * The PIN code, as a NUL-terminated ASCII string, should be copied
73 * into the 'pin' buffer (of fixed length NE_SSL_P11PINLEN), and
74 * return 0 to indicate success. Alternatively, the callback may
75 * return -1 to indicate failure and cancel PIN entry (in which case,
76 * the contents of the 'pin' parameter are ignored).
77 *
78 * When a PIN is required, the callback will be invoked repeatedly
79 * (and indefinitely) until either the returned PIN code is correct,
80 * the callback returns failure, or the token refuses login (e.g. when
81 * the token is locked due to too many incorrect PINs!). For the
82 * first such invocation, the 'attempt' counter will have value zero;
83 * it will increase by one for each subsequent attempt.
84 *
85 * The NE_SSL_P11PIN_COUNT_LOW and/or NE_SSL_P11PIN_FINAL_TRY hints
86 * may be set in the 'flags' argument, if these hints are made
87 * available by the token; not all tokens expose these hints. */
88 typedef int (*ne_ssl_pkcs11_pin_fn)(void *userdata, int attempt,
89 const char *slot_descr,
90 const char *token_label,
91 unsigned int flags,
92 char *pin);
93
94 /* Set the PIN entry callback for the given provider. This is
95 * necessary for some (but not all) types of token. For tokens which
96 * implement an out-of-band ("protected") authentication path, the PIN
97 * entry callback will not be invoked. */
98 void ne_ssl_pkcs11_provider_pin(ne_ssl_pkcs11_provider *provider,
99 ne_ssl_pkcs11_pin_fn fn,
100 void *userdata);
101
102 /* Set up a given PKCS#11 provider to supply an appropriate client
103 * certificate if requested by the server. A provider may be
104 * configured for use in multiple sessions. */
105 void ne_ssl_set_pkcs11_provider(ne_session *sess,
106 ne_ssl_pkcs11_provider *provider);
107
108 NE_END_DECLS
109
110 #endif /* NE_PKCS11_H */