| 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 */ |