1 #ifndef __GNUTLS_PKCS11_H
2 #define __GNUTLS_PKCS11_H
6 #include <gnutls/gnutls.h>
7 #include <gnutls/x509.h>
9 #define GNUTLS_PKCS11_MAX_PIN_LEN 32
11 /* Token callback function. The callback will be used to
12 * ask the user to re-enter the token with given null terminated
13 * label. Callback should return zero if token has been inserted
14 * by user and a negative error code otherwise. It might be called
15 * multiple times if the token is not detected and the retry counter
18 typedef int (*gnutls_pkcs11_token_callback_t
) (void *const global_data
,
19 const char *const label
,
20 const unsigned retry
);
23 * gnutls_pkcs11_pin_flag_t:
24 * @GNUTLS_PKCS11_PIN_USER: The PIN for the user.
25 * @GNUTLS_PKCS11_PIN_SO: The PIN for the security officer.
26 * @GNUTLS_PKCS11_PIN_CONTEXT_SPECIFIC: The PIN is for a specific action and key like signing.
27 * @GNUTLS_PKCS11_PIN_FINAL_TRY: This is the final try before blocking.
28 * @GNUTLS_PKCS11_PIN_COUNT_LOW: Few tries remain before token blocks.
29 * @GNUTLS_PKCS11_PIN_WRONG: Last given PIN was not correct.
31 * Enumeration of different PIN flags.
35 GNUTLS_PKCS11_PIN_USER
= (1 << 0),
36 GNUTLS_PKCS11_PIN_SO
= (1 << 1),
37 GNUTLS_PKCS11_PIN_FINAL_TRY
= (1 << 2),
38 GNUTLS_PKCS11_PIN_COUNT_LOW
= (1 << 3),
39 GNUTLS_PKCS11_PIN_CONTEXT_SPECIFIC
= (1 << 4),
40 GNUTLS_PKCS11_PIN_WRONG
= (1 << 5),
41 } gnutls_pkcs11_pin_flag_t
;
44 * gnutls_pkcs11_pin_callback_t:
45 * @userdata: user-controlled data from gnutls_pkcs11_set_pin_function().
46 * @attempt: pin-attempt counter, initially 0.
47 * @token_url: PKCS11 URL.
48 * @token_label: label of PKCS11 token.
49 * @flags: a #gnutls_pkcs11_pin_flag_t flag.
50 * @pin: buffer to hold PIN, of size @pin_max.
51 * @pin_max: size of @pin buffer.
53 * Callback function type for PKCS#11 PIN entry. It is set by
54 * gnutls_pkcs11_set_pin_function().
56 * The callback should provides the PIN code to unlock the token with
57 * label @token_label, specified by the URL @token_url.
59 * The PIN code, as a NUL-terminated ASCII string, should be copied
60 * into the @pin buffer (of maximum size @pin_max), and return 0 to
61 * indicate success. Alternatively, the callback may return a
62 * negative gnutls error code to indicate failure and cancel PIN entry
63 * (in which case, the contents of the @pin parameter are ignored).
65 * When a PIN is required, the callback will be invoked repeatedly
66 * (and indefinitely) until either the returned PIN code is correct,
67 * the callback returns failure, or the token refuses login (e.g. when
68 * the token is locked due to too many incorrect PINs!). For the
69 * first such invocation, the @attempt counter will have value zero;
70 * it will increase by one for each subsequent attempt.
72 * Returns: %GNUTLS_E_SUCCESS (0) on success or a negative error code on error.
76 typedef int (*gnutls_pkcs11_pin_callback_t
) (void *userdata
, int attempt
,
77 const char *token_url
,
78 const char *token_label
,
80 /*gnutls_pkcs11_pin_flag_t */ ,
81 char *pin
, size_t pin_max
);
83 struct gnutls_pkcs11_obj_st
;
84 typedef struct gnutls_pkcs11_obj_st
*gnutls_pkcs11_obj_t
;
87 #define GNUTLS_PKCS11_FLAG_MANUAL 0 /* Manual loading of libraries */
88 #define GNUTLS_PKCS11_FLAG_AUTO 1 /* Automatically load libraries by reading /etc/gnutls/pkcs11.conf */
90 /* pkcs11.conf format:
91 * load = /lib/xxx-pkcs11.so
92 * load = /lib/yyy-pkcs11.so
95 int gnutls_pkcs11_init (unsigned int flags
, const char *deprecated_config_file
);
96 int gnutls_pkcs11_reinit (void);
97 void gnutls_pkcs11_deinit (void);
98 void gnutls_pkcs11_set_token_function (gnutls_pkcs11_token_callback_t fn
,
101 void gnutls_pkcs11_set_pin_function (gnutls_pkcs11_pin_callback_t fn
,
103 int gnutls_pkcs11_add_provider (const char *name
, const char *params
);
104 int gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t
* obj
);
106 #define GNUTLS_PKCS11_OBJ_FLAG_LOGIN (1<<0) /* force login in the token for the operation */
107 #define GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED (1<<1) /* object marked as trusted */
108 #define GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE (1<<2) /* object marked as sensitive (unexportable) */
109 #define GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO (1<<3) /* force login as a security officer in the token for the operation */
112 * gnutls_pkcs11_url_type_t:
113 * @GNUTLS_PKCS11_URL_GENERIC: A generic-purpose URL.
114 * @GNUTLS_PKCS11_URL_LIB: A URL that specifies the library used as well.
115 * @GNUTLS_PKCS11_URL_LIB_VERSION: A URL that specifies the library and its version.
117 * Enumeration of different URL extraction flags.
121 GNUTLS_PKCS11_URL_GENERIC
, /* URL specifies the object on token level */
122 GNUTLS_PKCS11_URL_LIB
, /* URL specifies the object on module level */
123 GNUTLS_PKCS11_URL_LIB_VERSION
/* URL specifies the object on module and version level */
124 } gnutls_pkcs11_url_type_t
;
126 int gnutls_pkcs11_obj_import_url (gnutls_pkcs11_obj_t
, const char *url
,
128 /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
129 int gnutls_pkcs11_obj_export_url (gnutls_pkcs11_obj_t obj
,
130 gnutls_pkcs11_url_type_t detailed
,
132 void gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t obj
);
134 int gnutls_pkcs11_obj_export (gnutls_pkcs11_obj_t obj
,
135 void *output_data
, size_t * output_data_size
);
138 int gnutls_pkcs11_copy_x509_crt (const char *token_url
, gnutls_x509_crt_t crt
,
139 const char *label
, unsigned int flags
140 /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
141 int gnutls_pkcs11_copy_x509_privkey (const char *token_url
, gnutls_x509_privkey_t key
,
142 const char *label
, unsigned int key_usage
/*GNUTLS_KEY_* */, unsigned int flags
143 /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
144 int gnutls_pkcs11_delete_url (const char *object_url
, unsigned int flags
145 /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
147 int gnutls_pkcs11_copy_secret_key (const char *token_url
,
148 gnutls_datum_t
* key
, const char *label
,
149 unsigned int key_usage
/* GNUTLS_KEY_* */ ,
151 /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
154 * gnutls_pkcs11_obj_info_t:
155 * @GNUTLS_PKCS11_OBJ_ID_HEX: The object ID in hex.
156 * @GNUTLS_PKCS11_OBJ_LABEL: The object label.
157 * @GNUTLS_PKCS11_OBJ_TOKEN_LABEL: The token's label.
158 * @GNUTLS_PKCS11_OBJ_TOKEN_SERIAL: The token's serial number.
159 * @GNUTLS_PKCS11_OBJ_TOKEN_MANUFACTURER: The token's manufacturer.
160 * @GNUTLS_PKCS11_OBJ_TOKEN_MODEL: The token's model.
161 * @GNUTLS_PKCS11_OBJ_ID: The object ID.
162 * @GNUTLS_PKCS11_OBJ_LIBRARY_VERSION: The library's used to access the object version.
163 * @GNUTLS_PKCS11_OBJ_LIBRARY_DESCRIPTION: The library's used to access the object description (name).
164 * @GNUTLS_PKCS11_OBJ_LIBRARY_MANUFACTURER: The library's used to access the object manufacturer name.
166 * Enumeration of several object information types.
170 GNUTLS_PKCS11_OBJ_ID_HEX
= 1,
171 GNUTLS_PKCS11_OBJ_LABEL
,
172 GNUTLS_PKCS11_OBJ_TOKEN_LABEL
,
173 GNUTLS_PKCS11_OBJ_TOKEN_SERIAL
,
174 GNUTLS_PKCS11_OBJ_TOKEN_MANUFACTURER
,
175 GNUTLS_PKCS11_OBJ_TOKEN_MODEL
,
176 GNUTLS_PKCS11_OBJ_ID
,
177 /* the pkcs11 provider library info */
178 GNUTLS_PKCS11_OBJ_LIBRARY_VERSION
,
179 GNUTLS_PKCS11_OBJ_LIBRARY_DESCRIPTION
,
180 GNUTLS_PKCS11_OBJ_LIBRARY_MANUFACTURER
181 } gnutls_pkcs11_obj_info_t
;
183 int gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t crt
,
184 gnutls_pkcs11_obj_info_t itype
, void *output
,
185 size_t * output_size
);
188 * gnutls_pkcs11_obj_attr_t:
189 * @GNUTLS_PKCS11_OBJ_ATTR_CRT_ALL: Specify all certificates.
190 * @GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED: Specify all certificates marked as trusted.
191 * @GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY: Specify all certificates with a corresponding private key.
192 * @GNUTLS_PKCS11_OBJ_ATTR_PUBKEY: Specify all public keys.
193 * @GNUTLS_PKCS11_OBJ_ATTR_PRIVKEY: Specify all private keys.
194 * @GNUTLS_PKCS11_OBJ_ATTR_ALL: Specify all objects.
196 * Enumeration of several attributes for object enumeration.
200 GNUTLS_PKCS11_OBJ_ATTR_CRT_ALL
= 1, /* all certificates */
201 GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED
, /* certificates marked as trusted */
202 GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY
, /* certificates with corresponding private key */
203 GNUTLS_PKCS11_OBJ_ATTR_PUBKEY
, /* public keys */
204 GNUTLS_PKCS11_OBJ_ATTR_PRIVKEY
, /* private keys */
205 GNUTLS_PKCS11_OBJ_ATTR_ALL
/* everything! */
206 } gnutls_pkcs11_obj_attr_t
;
209 * gnutls_pkcs11_token_info_t:
210 * @GNUTLS_PKCS11_TOKEN_LABEL: The token's label
211 * @GNUTLS_PKCS11_TOKEN_SERIAL: The token's serial number
212 * @GNUTLS_PKCS11_TOKEN_MANUFACTURER: The token's manufacturer
213 * @GNUTLS_PKCS11_TOKEN_MODEL: The token's model
215 * Enumeration of types for retrieving token information.
219 GNUTLS_PKCS11_TOKEN_LABEL
,
220 GNUTLS_PKCS11_TOKEN_SERIAL
,
221 GNUTLS_PKCS11_TOKEN_MANUFACTURER
,
222 GNUTLS_PKCS11_TOKEN_MODEL
223 } gnutls_pkcs11_token_info_t
;
226 * gnutls_pkcs11_obj_type_t:
227 * @GNUTLS_PKCS11_OBJ_UNKNOWN: Unknown PKCS11 object.
228 * @GNUTLS_PKCS11_OBJ_X509_CRT: X.509 certificate.
229 * @GNUTLS_PKCS11_OBJ_PUBKEY: Public key.
230 * @GNUTLS_PKCS11_OBJ_PRIVKEY: Private key.
231 * @GNUTLS_PKCS11_OBJ_SECRET_KEY: Secret key.
232 * @GNUTLS_PKCS11_OBJ_DATA: Data object.
234 * Enumeration of object types.
238 GNUTLS_PKCS11_OBJ_UNKNOWN
,
239 GNUTLS_PKCS11_OBJ_X509_CRT
,
240 GNUTLS_PKCS11_OBJ_PUBKEY
,
241 GNUTLS_PKCS11_OBJ_PRIVKEY
,
242 GNUTLS_PKCS11_OBJ_SECRET_KEY
,
243 GNUTLS_PKCS11_OBJ_DATA
244 } gnutls_pkcs11_obj_type_t
;
247 gnutls_pkcs11_token_init (const char *token_url
,
248 const char *so_pin
, const char *label
);
251 gnutls_pkcs11_token_get_mechanism (const char *url
, int idx
,
252 unsigned long *mechanism
);
254 int gnutls_pkcs11_token_set_pin (const char *token_url
, const char *oldpin
, const char *newpin
, unsigned int flags
/*gnutls_pkcs11_pin_flag_t */
257 int gnutls_pkcs11_token_get_url (unsigned int seq
,
258 gnutls_pkcs11_url_type_t detailed
,
260 int gnutls_pkcs11_token_get_info (const char *url
, gnutls_pkcs11_token_info_t ttype
,
261 void *output
, size_t * output_size
);
263 #define GNUTLS_PKCS11_TOKEN_HW 1
264 int gnutls_pkcs11_token_get_flags (const char *url
, unsigned int *flags
);
266 int gnutls_pkcs11_obj_list_import_url (gnutls_pkcs11_obj_t
* p_list
,
267 unsigned int *const n_list
,
269 gnutls_pkcs11_obj_attr_t attrs
,
271 /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
273 int gnutls_x509_crt_import_pkcs11 (gnutls_x509_crt_t crt
,
274 gnutls_pkcs11_obj_t pkcs11_crt
);
275 int gnutls_x509_crt_import_pkcs11_url (gnutls_x509_crt_t crt
, const char *url
,
277 /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
279 gnutls_pkcs11_obj_type_t
gnutls_pkcs11_obj_get_type (gnutls_pkcs11_obj_t
281 const char *gnutls_pkcs11_type_get_name (gnutls_pkcs11_obj_type_t
);
283 int gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t
* certs
, unsigned int cert_max
,
284 gnutls_pkcs11_obj_t
* const objs
, unsigned int flags
/* must be zero */);
287 /* private key functions...*/
288 int gnutls_pkcs11_privkey_init (gnutls_pkcs11_privkey_t
* key
);
289 void gnutls_pkcs11_privkey_deinit (gnutls_pkcs11_privkey_t key
);
290 int gnutls_pkcs11_privkey_get_pk_algorithm (gnutls_pkcs11_privkey_t key
,
292 int gnutls_pkcs11_privkey_get_info (gnutls_pkcs11_privkey_t pkey
,
293 gnutls_pkcs11_obj_info_t itype
,
294 void *output
, size_t * output_size
);
296 int gnutls_pkcs11_privkey_import_url (gnutls_pkcs11_privkey_t pkey
,
297 const char *url
, unsigned int flags
);
299 int gnutls_pkcs11_privkey_export_url (gnutls_pkcs11_privkey_t key
,
300 gnutls_pkcs11_url_type_t detailed
,