lib/includes/gnutls/pkcs11.h

   1 #ifndef __GNUTLS_PKCS11_H
   2 #define __GNUTLS_PKCS11_H
   3
   4
   5 #include <stdarg.h>
   6 #include <gnutls/gnutls.h>
   7 #include <gnutls/x509.h>
   8
   9 #define GNUTLS_PKCS11_MAX_PIN_LEN 32
  10
  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
  16  * will be increased.
  17  */
  18 typedef int (*gnutls_pkcs11_token_callback_t) (void *const global_data,
  19                                                const char *const label,
  20                                                const unsigned retry);
  21
  22 /**
  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.
  30  *
  31  * Enumeration of different PIN flags.
  32  */
  33 typedef enum
  34   {
  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;
  42
  43 /**
  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.
  52  *
  53  * Callback function type for PKCS#11 PIN entry.  It is set by
  54  * gnutls_pkcs11_set_pin_function().
  55  *
  56  * The callback should provides the PIN code to unlock the token with
  57  * label @token_label, specified by the URL @token_url.
  58  *
  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).
  64  *
  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.
  71  *
  72  * Returns: %GNUTLS_E_SUCCESS (0) on success or a negative error code on error.
  73  *
  74  * Since: 2.12.0
  75  **/
  76 typedef int (*gnutls_pkcs11_pin_callback_t) (void *userdata, int attempt,
  77                                              const char *token_url,
  78                                              const char *token_label,
  79                                              unsigned int flags
  80                                              /*gnutls_pkcs11_pin_flag_t */ ,
  81                                              char *pin, size_t pin_max);
  82
  83 struct gnutls_pkcs11_obj_st;
  84 typedef struct gnutls_pkcs11_obj_st *gnutls_pkcs11_obj_t;
  85
  86
  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 */
  89
  90 /* pkcs11.conf format:
  91  * load = /lib/xxx-pkcs11.so
  92  * load = /lib/yyy-pkcs11.so
  93  */
  94
  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,
  99                                        void *userdata);
 100
 101 void gnutls_pkcs11_set_pin_function (gnutls_pkcs11_pin_callback_t fn,
 102                                      void *userdata);
 103 int gnutls_pkcs11_add_provider (const char *name, const char *params);
 104 int gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t * obj);
 105
 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 */
 110
 111   /**
 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.
 116    *
 117    * Enumeration of different URL extraction flags.
 118    */
 119 typedef enum
 120 {
 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;
 125
 126 int gnutls_pkcs11_obj_import_url (gnutls_pkcs11_obj_t, const char *url,
 127                                   unsigned int flags
 128                                   /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
 129 int gnutls_pkcs11_obj_export_url (gnutls_pkcs11_obj_t obj,
 130                                   gnutls_pkcs11_url_type_t detailed,
 131                                   char **url);
 132 void gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t obj);
 133
 134 int gnutls_pkcs11_obj_export (gnutls_pkcs11_obj_t obj,
 135                               void *output_data, size_t * output_data_size);
 136
 137
 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_* */ );
 146
 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_* */ ,
 150                                    unsigned int flags
 151                                    /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
 152
 153   /**
 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.
 165    *
 166    * Enumeration of several object information types.
 167    */
 168 typedef enum
 169 {
 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;
 182
 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);
 186
 187   /**
 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.
 195    *
 196    * Enumeration of several attributes for object enumeration.
 197    */
 198 typedef enum
 199 {
 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;
 207
 208   /**
 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
 214    *
 215    * Enumeration of types for retrieving token information.
 216    */
 217 typedef enum
 218 {
 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;
 224
 225   /**
 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.
 233    *
 234    * Enumeration of object types.
 235    */
 236 typedef enum
 237 {
 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;
 245
 246 int
 247 gnutls_pkcs11_token_init (const char *token_url,
 248                           const char *so_pin, const char *label);
 249
 250 int
 251 gnutls_pkcs11_token_get_mechanism (const char *url, int idx,
 252                                    unsigned long *mechanism);
 253
 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 */
 255   );
 256
 257 int gnutls_pkcs11_token_get_url (unsigned int seq,
 258                                  gnutls_pkcs11_url_type_t detailed,
 259                                  char **url);
 260 int gnutls_pkcs11_token_get_info (const char *url, gnutls_pkcs11_token_info_t ttype,
 261                                   void *output, size_t * output_size);
 262
 263 #define GNUTLS_PKCS11_TOKEN_HW 1
 264 int gnutls_pkcs11_token_get_flags (const char *url, unsigned int *flags);
 265
 266 int gnutls_pkcs11_obj_list_import_url (gnutls_pkcs11_obj_t * p_list,
 267                                        unsigned int *const n_list,
 268                                        const char *url,
 269                                        gnutls_pkcs11_obj_attr_t attrs,
 270                                        unsigned int flags
 271                                        /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
 272
 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,
 276                                        unsigned int flags
 277                                        /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
 278
 279 gnutls_pkcs11_obj_type_t gnutls_pkcs11_obj_get_type (gnutls_pkcs11_obj_t
 280                                                      certificate);
 281 const char *gnutls_pkcs11_type_get_name (gnutls_pkcs11_obj_type_t);
 282
 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 */);
 285
 286
 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,
 291                                             unsigned int *bits);
 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);
 295
 296 int gnutls_pkcs11_privkey_import_url (gnutls_pkcs11_privkey_t pkey,
 297                                       const char *url, unsigned int flags);
 298
 299 int gnutls_pkcs11_privkey_export_url (gnutls_pkcs11_privkey_t key,
 300                                       gnutls_pkcs11_url_type_t detailed,
 301                                       char **url);
 302
 303 /** @} */
 304
 305 #endif