doc/pkcs11-api.texi

   1
   2 @subheading gnutls_pkcs11_add_provider
   3 @anchor{gnutls_pkcs11_add_provider}
   4 @deftypefun {int} {gnutls_pkcs11_add_provider} (const char * @var{name}, const char * @var{params})
   5 @var{name}: The filename of the module
   6
   7 @var{params}: should be NULL
   8
   9 This function will load and add a PKCS 11 module to the module
  10 list used in gnutls. After this function is called the module will
  11 be used for PKCS 11 operations.
  12
  13 When loading a module to be used for certificate verification,
  14 use the string 'trusted' as  @code{params} .
  15
  16 Note that this function is not thread safe.
  17
  18 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
  19 negative error value.
  20
  21 @strong{Since:} 2.12.0
  22 @end deftypefun
  23
  24 @subheading gnutls_pkcs11_copy_secret_key
  25 @anchor{gnutls_pkcs11_copy_secret_key}
  26 @deftypefun {int} {gnutls_pkcs11_copy_secret_key} (const char * @var{token_url}, gnutls_datum_t * @var{key}, const char * @var{label}, unsigned int @var{key_usage}, unsigned int @var{flags})
  27 @var{token_url}: A PKCS @code{11}  URL specifying a token
  28
  29 @var{key}: The raw key
  30
  31 @var{label}: A name to be used for the stored data
  32
  33 @var{key_usage}: One of GNUTLS_KEY_*
  34
  35 @var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_*
  36
  37 This function will copy a raw secret (symmetric) key into a PKCS @code{11}
  38 token specified by a URL. The key can be marked as sensitive or not.
  39
  40 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
  41 negative error value.
  42
  43 @strong{Since:} 2.12.0
  44 @end deftypefun
  45
  46 @subheading gnutls_pkcs11_copy_x509_crt
  47 @anchor{gnutls_pkcs11_copy_x509_crt}
  48 @deftypefun {int} {gnutls_pkcs11_copy_x509_crt} (const char * @var{token_url}, gnutls_x509_crt_t @var{crt}, const char * @var{label}, unsigned int @var{flags})
  49 @var{token_url}: A PKCS @code{11}  URL specifying a token
  50
  51 @var{crt}: The certificate to copy
  52
  53 @var{label}: The name to be used for the stored data
  54
  55 @var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_*
  56
  57 This function will copy a certificate into a PKCS @code{11}  token specified by
  58 a URL. The certificate can be marked as trusted or not.
  59
  60 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
  61 negative error value.
  62
  63 @strong{Since:} 2.12.0
  64 @end deftypefun
  65
  66 @subheading gnutls_pkcs11_copy_x509_crt2
  67 @anchor{gnutls_pkcs11_copy_x509_crt2}
  68 @deftypefun {int} {gnutls_pkcs11_copy_x509_crt2} (const char * @var{token_url}, gnutls_x509_crt_t @var{crt}, const char * @var{label}, const gnutls_datum_t * @var{cid}, unsigned int @var{flags})
  69 @var{token_url}: A PKCS @code{11}  URL specifying a token
  70
  71 @var{crt}: The certificate to copy
  72
  73 @var{label}: The name to be used for the stored data
  74
  75 @var{cid}: The CKA_ID to set for the object -if NULL, the ID will be derived from the public key
  76
  77 @var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_*
  78
  79 This function will copy a certificate into a PKCS @code{11}  token specified by
  80 a URL. The certificate can be marked as trusted or not.
  81
  82 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
  83 negative error value.
  84
  85 @strong{Since:} 3.3.26
  86 @end deftypefun
  87
  88 @subheading gnutls_pkcs11_copy_x509_privkey
  89 @anchor{gnutls_pkcs11_copy_x509_privkey}
  90 @deftypefun {int} {gnutls_pkcs11_copy_x509_privkey} (const char * @var{token_url}, gnutls_x509_privkey_t @var{key}, const char * @var{label}, unsigned int @var{key_usage}, unsigned int @var{flags})
  91 @var{token_url}: A PKCS @code{11}  URL specifying a token
  92
  93 @var{key}: A private key
  94
  95 @var{label}: A name to be used for the stored data
  96
  97 @var{key_usage}: One of GNUTLS_KEY_*
  98
  99 @var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
 100
 101 This function will copy a private key into a PKCS @code{11}  token specified by
 102 a URL. It is highly recommended flags to contain @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE}
 103 unless there is a strong reason not to.
 104
 105 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 106 negative error value.
 107
 108 @strong{Since:} 2.12.0
 109 @end deftypefun
 110
 111 @subheading gnutls_pkcs11_copy_x509_privkey2
 112 @anchor{gnutls_pkcs11_copy_x509_privkey2}
 113 @deftypefun {int} {gnutls_pkcs11_copy_x509_privkey2} (const char * @var{token_url}, gnutls_x509_privkey_t @var{key}, const char * @var{label}, const gnutls_datum_t * @var{cid}, unsigned int @var{key_usage}, unsigned int @var{flags})
 114 @var{token_url}: A PKCS @code{11}  URL specifying a token
 115
 116 @var{key}: A private key
 117
 118 @var{label}: A name to be used for the stored data
 119
 120 @var{cid}: The CKA_ID to set for the object -if NULL, the ID will be derived from the public key
 121
 122 @var{key_usage}: One of GNUTLS_KEY_*
 123
 124 @var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
 125
 126 This function will copy a private key into a PKCS @code{11}  token specified by
 127 a URL. It is highly recommended flags to contain @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE}
 128 unless there is a strong reason not to.
 129
 130 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 131 negative error value.
 132
 133 @strong{Since:} 3.3.26
 134 @end deftypefun
 135
 136 @subheading gnutls_pkcs11_crt_is_known
 137 @anchor{gnutls_pkcs11_crt_is_known}
 138 @deftypefun {int} {gnutls_pkcs11_crt_is_known} (const char * @var{url}, gnutls_x509_crt_t @var{cert}, unsigned int @var{flags})
 139 @var{url}: A PKCS 11 url identifying a token
 140
 141 @var{cert}: is the certificate to find issuer for
 142
 143 @var{flags}: Use zero or flags from @code{GNUTLS_PKCS11_OBJ_FLAG} .
 144
 145 This function will check whether the provided certificate is stored
 146 in the specified token. This is useful in combination with
 147 @code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_TRUSTED}  or
 148 @code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED} ,
 149 to check whether a CA is present or a certificate is blacklisted in
 150 a trust PKCS @code{11}  module.
 151
 152 This function can be used with a  @code{url} of "pkcs11:", and in that case all modules
 153 will be searched. To restrict the modules to the marked as trusted in p11-kit
 154 use the @code{GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE}  flag.
 155
 156 Note that the flag @code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED}  is
 157 specific to p11-kit trust modules.
 158
 159 @strong{Returns:} If the certificate exists non-zero is returned, otherwise zero.
 160
 161 @strong{Since:} 3.3.0
 162 @end deftypefun
 163
 164 @subheading gnutls_pkcs11_deinit
 165 @anchor{gnutls_pkcs11_deinit}
 166 @deftypefun {void} {gnutls_pkcs11_deinit} ( @var{void})
 167
 168 This function will deinitialize the PKCS 11 subsystem in gnutls.
 169 This function is only needed if you need to deinitialize the
 170 subsystem without calling @code{gnutls_global_deinit()} .
 171
 172 @strong{Since:} 2.12.0
 173 @end deftypefun
 174
 175 @subheading gnutls_pkcs11_delete_url
 176 @anchor{gnutls_pkcs11_delete_url}
 177 @deftypefun {int} {gnutls_pkcs11_delete_url} (const char * @var{object_url}, unsigned int @var{flags})
 178 @var{object_url}: The URL of the object to delete.
 179
 180 @var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
 181
 182 This function will delete objects matching the given URL.
 183 Note that not all tokens support the delete operation.
 184
 185 @strong{Returns:} On success, the number of objects deleted is returned, otherwise a
 186 negative error value.
 187
 188 @strong{Since:} 2.12.0
 189 @end deftypefun
 190
 191 @subheading gnutls_pkcs11_get_pin_function
 192 @anchor{gnutls_pkcs11_get_pin_function}
 193 @deftypefun {gnutls_pin_callback_t} {gnutls_pkcs11_get_pin_function} (void ** @var{userdata})
 194 @var{userdata}: data to be supplied to callback
 195
 196 This function will return the callback function set using
 197 @code{gnutls_pkcs11_set_pin_function()} .
 198
 199 @strong{Returns:} The function set or NULL otherwise.
 200
 201 @strong{Since:} 3.1.0
 202 @end deftypefun
 203
 204 @subheading gnutls_pkcs11_get_raw_issuer
 205 @anchor{gnutls_pkcs11_get_raw_issuer}
 206 @deftypefun {int} {gnutls_pkcs11_get_raw_issuer} (const char * @var{url}, gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{issuer}, gnutls_x509_crt_fmt_t @var{fmt}, unsigned int @var{flags})
 207 @var{url}: A PKCS 11 url identifying a token
 208
 209 @var{cert}: is the certificate to find issuer for
 210
 211 @var{issuer}: Will hold the issuer if any in an allocated buffer.
 212
 213 @var{fmt}: The format of the exported issuer.
 214
 215 @var{flags}: Use zero or flags from @code{GNUTLS_PKCS11_OBJ_FLAG} .
 216
 217 This function will return the issuer of a given certificate, if it
 218 is stored in the token. By default only marked as trusted issuers
 219 are retuned. If any issuer should be returned specify
 220 @code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY}  in  @code{flags} .
 221
 222 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 223 negative error value.
 224
 225 @strong{Since:} 3.2.7
 226 @end deftypefun
 227
 228 @subheading gnutls_pkcs11_init
 229 @anchor{gnutls_pkcs11_init}
 230 @deftypefun {int} {gnutls_pkcs11_init} (unsigned int @var{flags}, const char * @var{deprecated_config_file})
 231 @var{flags}: An ORed sequence of @code{GNUTLS_PKCS11_FLAG_} *
 232
 233 @var{deprecated_config_file}: either NULL or the location of a deprecated
 234 configuration file
 235
 236 This function will initialize the PKCS 11 subsystem in gnutls. It will
 237 read configuration files if @code{GNUTLS_PKCS11_FLAG_AUTO}  is used or allow
 238 you to independently load PKCS 11 modules using @code{gnutls_pkcs11_add_provider()}
 239 if @code{GNUTLS_PKCS11_FLAG_MANUAL}  is specified.
 240
 241 Normally you don't need to call this function since it is being called
 242 when the first PKCS 11 operation is requested using the @code{GNUTLS_PKCS11_FLAG_AUTO}
 243 flag. If another flags are required then it must be called independently
 244 prior to any PKCS 11 operation.
 245
 246 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 247 negative error value.
 248
 249 @strong{Since:} 2.12.0
 250 @end deftypefun
 251
 252 @subheading gnutls_pkcs11_obj_deinit
 253 @anchor{gnutls_pkcs11_obj_deinit}
 254 @deftypefun {void} {gnutls_pkcs11_obj_deinit} (gnutls_pkcs11_obj_t @var{obj})
 255 @var{obj}: The structure to be initialized
 256
 257 This function will deinitialize a certificate structure.
 258
 259 @strong{Since:} 2.12.0
 260 @end deftypefun
 261
 262 @subheading gnutls_pkcs11_obj_export
 263 @anchor{gnutls_pkcs11_obj_export}
 264 @deftypefun {int} {gnutls_pkcs11_obj_export} (gnutls_pkcs11_obj_t @var{obj}, void * @var{output_data}, size_t * @var{output_data_size})
 265 @var{obj}: Holds the object
 266
 267 @var{output_data}: will contain the object data
 268
 269 @var{output_data_size}: holds the size of output_data (and will be
 270 replaced by the actual size of parameters)
 271
 272 This function will export the PKCS11 object data.  It is normal for
 273 data to be inaccesible and in that case @code{GNUTLS_E_INVALID_REQUEST}
 274 will be returned.
 275
 276 If the buffer provided is not long enough to hold the output, then
 277 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
 278 be returned.
 279
 280 @strong{Returns:} In case of failure a negative error code will be
 281 returned, and @code{GNUTLS_E_SUCCESS}  (0) on success.
 282
 283 @strong{Since:} 2.12.0
 284 @end deftypefun
 285
 286 @subheading gnutls_pkcs11_obj_export2
 287 @anchor{gnutls_pkcs11_obj_export2}
 288 @deftypefun {int} {gnutls_pkcs11_obj_export2} (gnutls_pkcs11_obj_t @var{obj}, gnutls_datum_t * @var{out})
 289 @var{obj}: Holds the object
 290
 291 @var{out}: will contain the object data
 292
 293 This function will export the PKCS11 object data.  It is normal for
 294 data to be inaccesible and in that case @code{GNUTLS_E_INVALID_REQUEST}
 295 will be returned.
 296
 297 The output buffer is allocated using @code{gnutls_malloc()} .
 298
 299 @strong{Returns:} In case of failure a negative error code will be
 300 returned, and @code{GNUTLS_E_SUCCESS}  (0) on success.
 301
 302 @strong{Since:} 3.1.3
 303 @end deftypefun
 304
 305 @subheading gnutls_pkcs11_obj_export3
 306 @anchor{gnutls_pkcs11_obj_export3}
 307 @deftypefun {int} {gnutls_pkcs11_obj_export3} (gnutls_pkcs11_obj_t @var{obj}, gnutls_x509_crt_fmt_t @var{fmt}, gnutls_datum_t * @var{out})
 308 @var{obj}: Holds the object
 309
 310 @var{fmt}: The format of the exported data
 311
 312 @var{out}: will contain the object data
 313
 314 This function will export the PKCS11 object data.  It is normal for
 315 data to be inaccesible and in that case @code{GNUTLS_E_INVALID_REQUEST}
 316 will be returned.
 317
 318 The output buffer is allocated using @code{gnutls_malloc()} .
 319
 320 @strong{Returns:} In case of failure a negative error code will be
 321 returned, and @code{GNUTLS_E_SUCCESS}  (0) on success.
 322
 323 @strong{Since:} 3.2.7
 324 @end deftypefun
 325
 326 @subheading gnutls_pkcs11_obj_export_url
 327 @anchor{gnutls_pkcs11_obj_export_url}
 328 @deftypefun {int} {gnutls_pkcs11_obj_export_url} (gnutls_pkcs11_obj_t @var{obj}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url})
 329 @var{obj}: Holds the PKCS 11 certificate
 330
 331 @var{detailed}: non zero if a detailed URL is required
 332
 333 @var{url}: will contain an allocated url
 334
 335 This function will export a URL identifying the given certificate.
 336
 337 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 338 negative error value.
 339
 340 @strong{Since:} 2.12.0
 341 @end deftypefun
 342
 343 @subheading gnutls_pkcs11_obj_flags_get_str
 344 @anchor{gnutls_pkcs11_obj_flags_get_str}
 345 @deftypefun {char *} {gnutls_pkcs11_obj_flags_get_str} (unsigned int @var{flags})
 346 @var{flags}: holds the flags
 347
 348 This function given an or-sequence of @code{GNUTLS_PKCS11_OBJ_FLAG_MARK} ,
 349 will return an allocated string with its description. The string
 350 needs to be deallocated using @code{gnutls_free()} .
 351
 352 @strong{Returns:} If flags is zero @code{NULL}  is returned, otherwise an allocated string.
 353
 354 @strong{Since:} 3.3.7
 355 @end deftypefun
 356
 357 @subheading gnutls_pkcs11_obj_get_exts
 358 @anchor{gnutls_pkcs11_obj_get_exts}
 359 @deftypefun {int} {gnutls_pkcs11_obj_get_exts} (gnutls_pkcs11_obj_t @var{obj}, gnutls_x509_ext_st ** @var{exts}, unsigned int * @var{exts_size}, unsigned int @var{flags})
 360 @var{obj}: should contain a @code{gnutls_pkcs11_obj_t}  type
 361
 362 @var{exts}: a pointer to a @code{gnutls_x509_ext_st}  pointer
 363
 364 @var{exts_size}: will be updated with the number of  @code{exts}
 365
 366 @var{flags}: Or sequence of @code{GNUTLS_PKCS11_OBJ_} * flags
 367
 368 This function will return information about attached extensions
 369 that associate to the provided object (which should be a certificate).
 370 The extensions are the attached p11-kit trust module extensions.
 371
 372 Each element of  @code{exts} must be deinitialized using @code{gnutls_x509_ext_deinit()}
 373 while  @code{exts} should be deallocated using @code{gnutls_free()} .
 374
 375 @strong{Returns:} @code{GNUTLS_E_SUCCESS}  (0) on success or a negative error code on error.
 376
 377 @strong{Since:} 3.3.8
 378 @end deftypefun
 379
 380 @subheading gnutls_pkcs11_obj_get_flags
 381 @anchor{gnutls_pkcs11_obj_get_flags}
 382 @deftypefun {int} {gnutls_pkcs11_obj_get_flags} (gnutls_pkcs11_obj_t @var{obj}, unsigned int * @var{oflags})
 383 @var{obj}: The structure that holds the object
 384
 385 @var{oflags}: Will hold the output flags
 386
 387 This function will return the flags of the object being
 388 stored in the structure. The  @code{oflags} are the @code{GNUTLS_PKCS11_OBJ_FLAG_MARK}
 389 flags.
 390
 391 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 392 negative error value.
 393
 394 @strong{Since:} 3.3.7
 395 @end deftypefun
 396
 397 @subheading gnutls_pkcs11_obj_get_info
 398 @anchor{gnutls_pkcs11_obj_get_info}
 399 @deftypefun {int} {gnutls_pkcs11_obj_get_info} (gnutls_pkcs11_obj_t @var{obj}, gnutls_pkcs11_obj_info_t @var{itype}, void * @var{output}, size_t * @var{output_size})
 400 @var{obj}: should contain a @code{gnutls_pkcs11_obj_t}  structure
 401
 402 @var{itype}: Denotes the type of information requested
 403
 404 @var{output}: where output will be stored
 405
 406 @var{output_size}: contains the maximum size of the output and will be overwritten with actual
 407
 408 This function will return information about the PKCS11 certificate
 409 such as the label, id as well as token information where the key is
 410 stored. When output is text it returns null terminated string
 411 although  @code{output_size} contains the size of the actual data only.
 412
 413 @strong{Returns:} @code{GNUTLS_E_SUCCESS}  (0) on success or a negative error code on error.
 414
 415 @strong{Since:} 2.12.0
 416 @end deftypefun
 417
 418 @subheading gnutls_pkcs11_obj_get_type
 419 @anchor{gnutls_pkcs11_obj_get_type}
 420 @deftypefun {gnutls_pkcs11_obj_type_t} {gnutls_pkcs11_obj_get_type} (gnutls_pkcs11_obj_t @var{obj})
 421 @var{obj}: Holds the PKCS 11 object
 422
 423 This function will return the type of the object being
 424 stored in the structure.
 425
 426 @strong{Returns:} The type of the object
 427
 428 @strong{Since:} 2.12.0
 429 @end deftypefun
 430
 431 @subheading gnutls_pkcs11_obj_import_url
 432 @anchor{gnutls_pkcs11_obj_import_url}
 433 @deftypefun {int} {gnutls_pkcs11_obj_import_url} (gnutls_pkcs11_obj_t @var{obj}, const char * @var{url}, unsigned int @var{flags})
 434 @var{obj}: The structure to store the object
 435
 436 @var{url}: a PKCS 11 url identifying the key
 437
 438 @var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags
 439
 440 This function will "import" a PKCS 11 URL identifying an object (e.g. certificate)
 441 to the @code{gnutls_pkcs11_obj_t}  structure. This does not involve any
 442 parsing (such as X.509 or OpenPGP) since the @code{gnutls_pkcs11_obj_t}  is
 443 format agnostic. Only data are transferred.
 444
 445 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 446 negative error value.
 447
 448 @strong{Since:} 2.12.0
 449 @end deftypefun
 450
 451 @subheading gnutls_pkcs11_obj_init
 452 @anchor{gnutls_pkcs11_obj_init}
 453 @deftypefun {int} {gnutls_pkcs11_obj_init} (gnutls_pkcs11_obj_t * @var{obj})
 454 @var{obj}: The structure to be initialized
 455
 456 This function will initialize a pkcs11 certificate structure.
 457
 458 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 459 negative error value.
 460
 461 @strong{Since:} 2.12.0
 462 @end deftypefun
 463
 464 @subheading gnutls_pkcs11_obj_list_import_url
 465 @anchor{gnutls_pkcs11_obj_list_import_url}
 466 @deftypefun {int} {gnutls_pkcs11_obj_list_import_url} (gnutls_pkcs11_obj_t * @var{p_list}, unsigned int * @var{n_list}, const char * @var{url}, gnutls_pkcs11_obj_attr_t @var{attrs}, unsigned int @var{flags})
 467 @var{p_list}: An uninitialized object list (may be NULL)
 468
 469 @var{n_list}: initially should hold the maximum size of the list. Will contain the actual size.
 470
 471 @var{url}: A PKCS 11 url identifying a set of objects
 472
 473 @var{attrs}: Attributes of type @code{gnutls_pkcs11_obj_attr_t}  that can be used to limit output
 474
 475 @var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags
 476
 477 This function will initialize and set values to an object list
 478 by using all objects identified by a PKCS 11 URL.
 479
 480 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 481 negative error value.
 482
 483 @strong{Since:} 2.12.0
 484 @end deftypefun
 485
 486 @subheading gnutls_pkcs11_obj_list_import_url2
 487 @anchor{gnutls_pkcs11_obj_list_import_url2}
 488 @deftypefun {int} {gnutls_pkcs11_obj_list_import_url2} (gnutls_pkcs11_obj_t ** @var{p_list}, unsigned int * @var{n_list}, const char * @var{url}, gnutls_pkcs11_obj_attr_t @var{attrs}, unsigned int @var{flags})
 489 @var{p_list}: An uninitialized object list (may be NULL)
 490
 491 @var{n_list}: It will contain the size of the list.
 492
 493 @var{url}: A PKCS 11 url identifying a set of objects
 494
 495 @var{attrs}: Attributes of type @code{gnutls_pkcs11_obj_attr_t}  that can be used to limit output
 496
 497 @var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags
 498
 499 This function will initialize and set values to an object list
 500 by using all objects identified by the PKCS 11 URL. The output
 501 is stored in  @code{p_list} , which will be initialized.
 502
 503 All returned objects must be deinitialized using @code{gnutls_pkcs11_obj_deinit()} ,
 504 and  @code{p_list} must be free'd using @code{gnutls_free()} .
 505
 506 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 507 negative error value.
 508
 509 @strong{Since:} 3.1.0
 510 @end deftypefun
 511
 512 @subheading gnutls_pkcs11_obj_set_info
 513 @anchor{gnutls_pkcs11_obj_set_info}
 514 @deftypefun {int} {gnutls_pkcs11_obj_set_info} (gnutls_pkcs11_obj_t @var{obj}, gnutls_pkcs11_obj_info_t @var{itype}, const void * @var{data}, size_t @var{data_size}, unsigned @var{flags})
 515 @var{obj}: should contain a @code{gnutls_pkcs11_obj_t}  structure
 516
 517 @var{itype}: Denotes the type of information to be set
 518
 519 @var{data}: the data to set
 520
 521 @var{data_size}: the size of data
 522
 523 @var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags
 524
 525 This function will set attributes on the provided object.
 526 Available options for  @code{itype} are @code{GNUTLS_PKCS11_OBJ_LABEL} ,
 527 @code{GNUTLS_PKCS11_OBJ_ID_HEX} , and @code{GNUTLS_PKCS11_OBJ_ID} .
 528
 529 @strong{Returns:} @code{GNUTLS_E_SUCCESS}  (0) on success or a negative error code on error.
 530
 531 @strong{Since:} 3.3.26
 532 @end deftypefun
 533
 534 @subheading gnutls_pkcs11_obj_set_pin_function
 535 @anchor{gnutls_pkcs11_obj_set_pin_function}
 536 @deftypefun {void} {gnutls_pkcs11_obj_set_pin_function} (gnutls_pkcs11_obj_t @var{obj}, gnutls_pin_callback_t @var{fn}, void * @var{userdata})
 537 @var{obj}: The object structure
 538
 539 @var{fn}: the callback
 540
 541 @var{userdata}: data associated with the callback
 542
 543 This function will set a callback function to be used when
 544 required to access the object. This function overrides the global
 545 set using @code{gnutls_pkcs11_set_pin_function()} .
 546
 547 @strong{Since:} 3.1.0
 548 @end deftypefun
 549
 550 @subheading gnutls_pkcs11_privkey_deinit
 551 @anchor{gnutls_pkcs11_privkey_deinit}
 552 @deftypefun {void} {gnutls_pkcs11_privkey_deinit} (gnutls_pkcs11_privkey_t @var{key})
 553 @var{key}: The structure to be initialized
 554
 555 This function will deinitialize a private key structure.
 556 @end deftypefun
 557
 558 @subheading gnutls_pkcs11_privkey_export_pubkey
 559 @anchor{gnutls_pkcs11_privkey_export_pubkey}
 560 @deftypefun {int} {gnutls_pkcs11_privkey_export_pubkey} (gnutls_pkcs11_privkey_t @var{pkey}, gnutls_x509_crt_fmt_t @var{fmt}, gnutls_datum_t * @var{data}, unsigned int @var{flags})
 561 @var{pkey}: The private key
 562
 563 @var{fmt}: the format of output params. PEM or DER.
 564
 565 @var{data}: will hold the public key
 566
 567 @var{flags}: should be zero
 568
 569 This function will extract the public key (modulus and public
 570 exponent) from the private key specified by the  @code{url} private key.
 571 This public key will be stored in  @code{pubkey} in the format specified
 572 by  @code{fmt} .  @code{pubkey} should be deinitialized using @code{gnutls_free()} .
 573
 574 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 575 negative error value.
 576
 577 @strong{Since:} 3.3.7
 578 @end deftypefun
 579
 580 @subheading gnutls_pkcs11_privkey_export_url
 581 @anchor{gnutls_pkcs11_privkey_export_url}
 582 @deftypefun {int} {gnutls_pkcs11_privkey_export_url} (gnutls_pkcs11_privkey_t @var{key}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url})
 583 @var{key}: Holds the PKCS 11 key
 584
 585 @var{detailed}: non zero if a detailed URL is required
 586
 587 @var{url}: will contain an allocated url
 588
 589 This function will export a URL identifying the given key.
 590
 591 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 592 negative error value.
 593 @end deftypefun
 594
 595 @subheading gnutls_pkcs11_privkey_generate
 596 @anchor{gnutls_pkcs11_privkey_generate}
 597 @deftypefun {int} {gnutls_pkcs11_privkey_generate} (const char * @var{url}, gnutls_pk_algorithm_t @var{pk}, unsigned int @var{bits}, const char * @var{label}, unsigned int @var{flags})
 598 @var{url}: a token URL
 599
 600 @var{pk}: the public key algorithm
 601
 602 @var{bits}: the security bits
 603
 604 @var{label}: a label
 605
 606 @var{flags}: should be zero
 607
 608 This function will generate a private key in the specified
 609 by the  @code{url} token. The private key will be generate within
 610 the token and will not be exportable.
 611
 612 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 613 negative error value.
 614
 615 @strong{Since:} 3.0
 616 @end deftypefun
 617
 618 @subheading gnutls_pkcs11_privkey_generate2
 619 @anchor{gnutls_pkcs11_privkey_generate2}
 620 @deftypefun {int} {gnutls_pkcs11_privkey_generate2} (const char * @var{url}, gnutls_pk_algorithm_t @var{pk}, unsigned int @var{bits}, const char * @var{label}, gnutls_x509_crt_fmt_t @var{fmt}, gnutls_datum_t * @var{pubkey}, unsigned int @var{flags})
 621 @var{url}: a token URL
 622
 623 @var{pk}: the public key algorithm
 624
 625 @var{bits}: the security bits
 626
 627 @var{label}: a label
 628
 629 @var{fmt}: the format of output params. PEM or DER
 630
 631 @var{pubkey}: will hold the public key (may be @code{NULL} )
 632
 633 @var{flags}: zero or an OR'ed sequence of @code{GNUTLS_PKCS11_OBJ_FLAGs}
 634
 635 This function will generate a private key in the specified
 636 by the  @code{url} token. The private key will be generate within
 637 the token and will not be exportable. This function will
 638 store the DER-encoded public key in the SubjectPublicKeyInfo format
 639 in  @code{pubkey} . The  @code{pubkey} should be deinitialized using @code{gnutls_free()} .
 640
 641 Note that when generating an elliptic curve key, the curve
 642 can be substituted in the place of the bits parameter using the
 643 @code{GNUTLS_CURVE_TO_BITS()}  macro.
 644
 645 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 646 negative error value.
 647
 648 @strong{Since:} 3.1.5
 649 @end deftypefun
 650
 651 @subheading gnutls_pkcs11_privkey_generate3
 652 @anchor{gnutls_pkcs11_privkey_generate3}
 653 @deftypefun {int} {gnutls_pkcs11_privkey_generate3} (const char * @var{url}, gnutls_pk_algorithm_t @var{pk}, unsigned int @var{bits}, const char * @var{label}, const gnutls_datum_t * @var{cid}, gnutls_x509_crt_fmt_t @var{fmt}, gnutls_datum_t * @var{pubkey}, unsigned int @var{flags})
 654 @var{url}: a token URL
 655
 656 @var{pk}: the public key algorithm
 657
 658 @var{bits}: the security bits
 659
 660 @var{label}: a label
 661
 662 @var{cid}: The CKA_ID to use for the new object
 663
 664 @var{fmt}: the format of output params. PEM or DER
 665
 666 @var{pubkey}: will hold the public key (may be @code{NULL} )
 667
 668 @var{flags}: zero or an OR'ed sequence of @code{GNUTLS_PKCS11_OBJ_FLAGs}
 669
 670 This function will generate a private key in the specified
 671 by the  @code{url} token. The private key will be generate within
 672 the token and will not be exportable. This function will
 673 store the DER-encoded public key in the SubjectPublicKeyInfo format
 674 in  @code{pubkey} . The  @code{pubkey} should be deinitialized using @code{gnutls_free()} .
 675
 676 Note that when generating an elliptic curve key, the curve
 677 can be substituted in the place of the bits parameter using the
 678 @code{GNUTLS_CURVE_TO_BITS()}  macro.
 679
 680 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 681 negative error value.
 682
 683 @strong{Since:} 3.3.26
 684 @end deftypefun
 685
 686 @subheading gnutls_pkcs11_privkey_get_info
 687 @anchor{gnutls_pkcs11_privkey_get_info}
 688 @deftypefun {int} {gnutls_pkcs11_privkey_get_info} (gnutls_pkcs11_privkey_t @var{pkey}, gnutls_pkcs11_obj_info_t @var{itype}, void * @var{output}, size_t * @var{output_size})
 689 @var{pkey}: should contain a @code{gnutls_pkcs11_privkey_t}  structure
 690
 691 @var{itype}: Denotes the type of information requested
 692
 693 @var{output}: where output will be stored
 694
 695 @var{output_size}: contains the maximum size of the output and will be overwritten with actual
 696
 697 This function will return information about the PKCS 11 private key such
 698 as the label, id as well as token information where the key is stored. When
 699 output is text it returns null terminated string although @code{output_size}  contains
 700 the size of the actual data only.
 701
 702 @strong{Returns:} @code{GNUTLS_E_SUCCESS}  (0) on success or a negative error code on error.
 703 @end deftypefun
 704
 705 @subheading gnutls_pkcs11_privkey_get_pk_algorithm
 706 @anchor{gnutls_pkcs11_privkey_get_pk_algorithm}
 707 @deftypefun {int} {gnutls_pkcs11_privkey_get_pk_algorithm} (gnutls_pkcs11_privkey_t @var{key}, unsigned int * @var{bits})
 708 @var{key}: should contain a @code{gnutls_pkcs11_privkey_t}  structure
 709
 710 @var{bits}: if bits is non null it will hold the size of the parameters' in bits
 711
 712 This function will return the public key algorithm of a private
 713 key.
 714
 715 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t}  enumeration on
 716 success, or a negative error code on error.
 717 @end deftypefun
 718
 719 @subheading gnutls_pkcs11_privkey_import_url
 720 @anchor{gnutls_pkcs11_privkey_import_url}
 721 @deftypefun {int} {gnutls_pkcs11_privkey_import_url} (gnutls_pkcs11_privkey_t @var{pkey}, const char * @var{url}, unsigned int @var{flags})
 722 @var{pkey}: The structure to store the parsed key
 723
 724 @var{url}: a PKCS 11 url identifying the key
 725
 726 @var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags
 727
 728 This function will "import" a PKCS 11 URL identifying a private
 729 key to the @code{gnutls_pkcs11_privkey_t}  structure. In reality since
 730 in most cases keys cannot be exported, the private key structure
 731 is being associated with the available operations on the token.
 732
 733 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 734 negative error value.
 735 @end deftypefun
 736
 737 @subheading gnutls_pkcs11_privkey_init
 738 @anchor{gnutls_pkcs11_privkey_init}
 739 @deftypefun {int} {gnutls_pkcs11_privkey_init} (gnutls_pkcs11_privkey_t * @var{key})
 740 @var{key}: The structure to be initialized
 741
 742 This function will initialize an private key structure.
 743
 744 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 745 negative error value.
 746 @end deftypefun
 747
 748 @subheading gnutls_pkcs11_privkey_set_pin_function
 749 @anchor{gnutls_pkcs11_privkey_set_pin_function}
 750 @deftypefun {void} {gnutls_pkcs11_privkey_set_pin_function} (gnutls_pkcs11_privkey_t @var{key}, gnutls_pin_callback_t @var{fn}, void * @var{userdata})
 751 @var{key}: The private key
 752
 753 @var{fn}: the callback
 754
 755 @var{userdata}: data associated with the callback
 756
 757 This function will set a callback function to be used when
 758 required to access the object. This function overrides the global
 759 set using @code{gnutls_pkcs11_set_pin_function()} .
 760
 761 @strong{Since:} 3.1.0
 762 @end deftypefun
 763
 764 @subheading gnutls_pkcs11_privkey_status
 765 @anchor{gnutls_pkcs11_privkey_status}
 766 @deftypefun {int} {gnutls_pkcs11_privkey_status} (gnutls_pkcs11_privkey_t @var{key})
 767 @var{key}: Holds the key
 768
 769 Checks the status of the private key token.
 770
 771 @strong{Returns:} this function will return non-zero if the token
 772 holding the private key is still available (inserted), and zero otherwise.
 773
 774 @strong{Since:} 3.1.9
 775 @end deftypefun
 776
 777 @subheading gnutls_pkcs11_reinit
 778 @anchor{gnutls_pkcs11_reinit}
 779 @deftypefun {int} {gnutls_pkcs11_reinit} ( @var{void})
 780
 781 This function will reinitialize the PKCS 11 subsystem in gnutls.
 782 This is required by PKCS 11 when an application uses @code{fork()} . The
 783 reinitialization function must be called on the child.
 784
 785 Note that since GnuTLS 3.3.0, the reinitialization of the PKCS @code{11}
 786 subsystem occurs automatically after fork.
 787
 788 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 789 negative error value.
 790
 791 @strong{Since:} 3.0
 792 @end deftypefun
 793
 794 @subheading gnutls_pkcs11_set_pin_function
 795 @anchor{gnutls_pkcs11_set_pin_function}
 796 @deftypefun {void} {gnutls_pkcs11_set_pin_function} (gnutls_pin_callback_t @var{fn}, void * @var{userdata})
 797 @var{fn}: The PIN callback, a @code{gnutls_pin_callback_t()}  function.
 798
 799 @var{userdata}: data to be supplied to callback
 800
 801 This function will set a callback function to be used when a PIN is
 802 required for PKCS 11 operations.  See
 803 @code{gnutls_pin_callback_t()}  on how the callback should behave.
 804
 805 @strong{Since:} 2.12.0
 806 @end deftypefun
 807
 808 @subheading gnutls_pkcs11_set_token_function
 809 @anchor{gnutls_pkcs11_set_token_function}
 810 @deftypefun {void} {gnutls_pkcs11_set_token_function} (gnutls_pkcs11_token_callback_t @var{fn}, void * @var{userdata})
 811 @var{fn}: The token callback
 812
 813 @var{userdata}: data to be supplied to callback
 814
 815 This function will set a callback function to be used when a token
 816 needs to be inserted to continue PKCS 11 operations.
 817
 818 @strong{Since:} 2.12.0
 819 @end deftypefun
 820
 821 @subheading gnutls_pkcs11_token_get_flags
 822 @anchor{gnutls_pkcs11_token_get_flags}
 823 @deftypefun {int} {gnutls_pkcs11_token_get_flags} (const char * @var{url}, unsigned int * @var{flags})
 824 @var{url}: should contain a PKCS 11 URL
 825
 826 @var{flags}: The output flags (GNUTLS_PKCS11_TOKEN_*)
 827
 828 This function will return information about the PKCS 11 token flags.
 829
 830 The supported flags are: @code{GNUTLS_PKCS11_TOKEN_HW}  and @code{GNUTLS_PKCS11_TOKEN_TRUSTED} .
 831
 832 @strong{Returns:} @code{GNUTLS_E_SUCCESS}  (0) on success or a negative error code on error.
 833
 834 @strong{Since:} 2.12.0
 835 @end deftypefun
 836
 837 @subheading gnutls_pkcs11_token_get_info
 838 @anchor{gnutls_pkcs11_token_get_info}
 839 @deftypefun {int} {gnutls_pkcs11_token_get_info} (const char * @var{url}, gnutls_pkcs11_token_info_t @var{ttype}, void * @var{output}, size_t * @var{output_size})
 840 @var{url}: should contain a PKCS 11 URL
 841
 842 @var{ttype}: Denotes the type of information requested
 843
 844 @var{output}: where output will be stored
 845
 846 @var{output_size}: contains the maximum size of the output and will be overwritten with actual
 847
 848 This function will return information about the PKCS 11 token such
 849 as the label, id, etc.
 850
 851 @strong{Returns:} @code{GNUTLS_E_SUCCESS}  (0) on success or a negative error code
 852 on error.
 853
 854 @strong{Since:} 2.12.0
 855 @end deftypefun
 856
 857 @subheading gnutls_pkcs11_token_get_mechanism
 858 @anchor{gnutls_pkcs11_token_get_mechanism}
 859 @deftypefun {int} {gnutls_pkcs11_token_get_mechanism} (const char * @var{url}, unsigned int @var{idx}, unsigned long * @var{mechanism})
 860 @var{url}: should contain a PKCS 11 URL
 861
 862 @var{idx}: The index of the mechanism
 863
 864 @var{mechanism}: The PKCS @code{11}  mechanism ID
 865
 866 This function will return the names of the supported mechanisms
 867 by the token. It should be called with an increasing index until
 868 it return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE.
 869
 870 @strong{Returns:} @code{GNUTLS_E_SUCCESS}  (0) on success or a negative error code on error.
 871
 872 @strong{Since:} 2.12.0
 873 @end deftypefun
 874
 875 @subheading gnutls_pkcs11_token_get_random
 876 @anchor{gnutls_pkcs11_token_get_random}
 877 @deftypefun {int} {gnutls_pkcs11_token_get_random} (const char * @var{token_url}, void * @var{rnddata}, size_t @var{len})
 878 @var{token_url}: A PKCS @code{11}  URL specifying a token
 879
 880 @var{rnddata}: A pointer to the memory area to be filled with random data
 881
 882 @var{len}: The number of bytes of randomness to request
 883
 884 This function will get random data from the given token.
 885 It will store rnddata and fill the memory pointed to by rnddata with
 886 len random bytes from the token.
 887
 888 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 889 negative error value.
 890 @end deftypefun
 891
 892 @subheading gnutls_pkcs11_token_get_url
 893 @anchor{gnutls_pkcs11_token_get_url}
 894 @deftypefun {int} {gnutls_pkcs11_token_get_url} (unsigned int @var{seq}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url})
 895 @var{seq}: sequence number starting from 0
 896
 897 @var{detailed}: non zero if a detailed URL is required
 898
 899 @var{url}: will contain an allocated url
 900
 901 This function will return the URL for each token available
 902 in system. The url has to be released using @code{gnutls_free()}
 903
 904 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned,
 905 @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}  if the sequence number
 906 exceeds the available tokens, otherwise a negative error value.
 907
 908 @strong{Since:} 2.12.0
 909 @end deftypefun
 910
 911 @subheading gnutls_pkcs11_token_init
 912 @anchor{gnutls_pkcs11_token_init}
 913 @deftypefun {int} {gnutls_pkcs11_token_init} (const char * @var{token_url}, const char * @var{so_pin}, const char * @var{label})
 914 @var{token_url}: A PKCS @code{11}  URL specifying a token
 915
 916 @var{so_pin}: Security Officer's PIN
 917
 918 @var{label}: A name to be used for the token
 919
 920 This function will initialize (format) a token. If the token is
 921 at a factory defaults state the security officer's PIN given will be
 922 set to be the default. Otherwise it should match the officer's PIN.
 923
 924 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 925 negative error value.
 926 @end deftypefun
 927
 928 @subheading gnutls_pkcs11_token_set_pin
 929 @anchor{gnutls_pkcs11_token_set_pin}
 930 @deftypefun {int} {gnutls_pkcs11_token_set_pin} (const char * @var{token_url}, const char * @var{oldpin}, const char * @var{newpin}, unsigned int @var{flags})
 931 @var{token_url}: A PKCS @code{11}  URL specifying a token
 932
 933 @var{oldpin}: old user's PIN
 934
 935 @var{newpin}: new user's PIN
 936
 937 @var{flags}: one of @code{gnutls_pin_flag_t} .
 938
 939 This function will modify or set a user's PIN for the given token.
 940 If it is called to set a user pin for first time the oldpin must
 941 be NULL.
 942
 943 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 944 negative error value.
 945 @end deftypefun
 946
 947 @subheading gnutls_pkcs11_type_get_name
 948 @anchor{gnutls_pkcs11_type_get_name}
 949 @deftypefun {const char *} {gnutls_pkcs11_type_get_name} (gnutls_pkcs11_obj_type_t @var{type})
 950 @var{type}: Holds the PKCS 11 object type, a @code{gnutls_pkcs11_obj_type_t} .
 951
 952 This function will return a human readable description of the
 953 PKCS11 object type  @code{obj} .  It will return "Unknown" for unknown
 954 types.
 955
 956 @strong{Returns:} human readable string labeling the PKCS11 object type
 957  @code{type} .
 958
 959 @strong{Since:} 2.12.0
 960 @end deftypefun
 961
 962 @subheading gnutls_x509_crt_import_pkcs11
 963 @anchor{gnutls_x509_crt_import_pkcs11}
 964 @deftypefun {int} {gnutls_x509_crt_import_pkcs11} (gnutls_x509_crt_t @var{crt}, gnutls_pkcs11_obj_t @var{pkcs11_crt})
 965 @var{crt}: A certificate of type @code{gnutls_x509_crt_t}
 966
 967 @var{pkcs11_crt}: A PKCS 11 object that contains a certificate
 968
 969 This function will import a PKCS 11 certificate to a @code{gnutls_x509_crt_t}
 970 structure.
 971
 972 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 973 negative error value.
 974
 975 @strong{Since:} 2.12.0
 976 @end deftypefun
 977
 978 @subheading gnutls_x509_crt_import_pkcs11_url
 979 @anchor{gnutls_x509_crt_import_pkcs11_url}
 980 @deftypefun {int} {gnutls_x509_crt_import_pkcs11_url} (gnutls_x509_crt_t @var{crt}, const char * @var{url}, unsigned int @var{flags})
 981 @var{crt}: A certificate of type @code{gnutls_x509_crt_t}
 982
 983 @var{url}: A PKCS 11 url
 984
 985 @var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
 986
 987 This function will import a PKCS 11 certificate directly from a token
 988 without involving the @code{gnutls_pkcs11_obj_t}  structure. This function will
 989 fail if the certificate stored is not of X.509 type.
 990
 991 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 992 negative error value.
 993
 994 @strong{Since:} 2.12.0
 995 @end deftypefun
 996
 997 @subheading gnutls_x509_crt_list_import_pkcs11
 998 @anchor{gnutls_x509_crt_list_import_pkcs11}
 999 @deftypefun {int} {gnutls_x509_crt_list_import_pkcs11} (gnutls_x509_crt_t * @var{certs}, unsigned int @var{cert_max}, gnutls_pkcs11_obj_t * const @var{objs}, unsigned int @var{flags})
1000 @var{certs}: A list of certificates of type @code{gnutls_x509_crt_t}
1001
1002 @var{cert_max}: The maximum size of the list
1003
1004 @var{objs}: A list of PKCS 11 objects
1005
1006 @var{flags}: 0 for now
1007
1008 This function will import a PKCS 11 certificate list to a list of
1009 @code{gnutls_x509_crt_t}  structure. These must not be initialized.
1010
1011 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
1012 negative error value.
1013
1014 @strong{Since:} 2.12.0
1015 @end deftypefun
1016