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 or a known string (see description) 8 9This function will load and add a PKCS 11 module to the module 10list used in gnutls. After this function is called the module will 11be used for PKCS 11 operations. 12 13When loading a module to be used for certificate verification, 14use the string 'trusted' as @code{params} . 15 16Note that this function is not thread safe. 17 18@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 19negative error value. 20 21@strong{Since:} 2.12.0 22@end deftypefun 23 24@subheading gnutls_pkcs11_copy_attached_extension 25@anchor{gnutls_pkcs11_copy_attached_extension} 26@deftypefun {int} {gnutls_pkcs11_copy_attached_extension} (const char * @var{token_url}, gnutls_x509_crt_t @var{crt}, gnutls_datum_t * @var{data}, const char * @var{label}, unsigned int @var{flags}) 27@var{token_url}: A PKCS @code{11} URL specifying a token 28 29@var{crt}: An X.509 certificate object 30 31@var{data}: the attached extension 32 33@var{label}: A name to be used for the attached extension (may be @code{NULL} ) 34 35@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_* 36 37This function will copy an the attached extension in @code{data} for 38the certificate provided in @code{crt} in the PKCS @code{11} token specified 39by the URL (typically a trust module). The extension must be in 40RFC5280 Extension format. 41 42@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 43negative error value. 44 45@strong{Since:} 3.3.8 46@end deftypefun 47 48@subheading gnutls_pkcs11_copy_pubkey 49@anchor{gnutls_pkcs11_copy_pubkey} 50@deftypefun {int} {gnutls_pkcs11_copy_pubkey} (const char * @var{token_url}, gnutls_pubkey_t @var{pubkey}, const char * @var{label}, const gnutls_datum_t * @var{cid}, unsigned int @var{key_usage}, unsigned int @var{flags}) 51@var{token_url}: A PKCS @code{11} URL specifying a token 52 53@var{pubkey}: The public key to copy 54 55@var{label}: The name to be used for the stored data 56 57@var{cid}: The CKA_ID to set for the object -if NULL, the ID will be derived from the public key 58 59@var{key_usage}: One of GNUTLS_KEY_* 60 61@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_* 62 63This function will copy a public key object into a PKCS @code{11} token specified by 64a URL. Valid flags to mark the key: @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED} , 65@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE} , @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_CA} , 66@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_ALWAYS_AUTH} . 67 68@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 69negative error value. 70 71@strong{Since:} 3.4.6 72@end deftypefun 73 74@subheading gnutls_pkcs11_copy_secret_key 75@anchor{gnutls_pkcs11_copy_secret_key} 76@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}) 77@var{token_url}: A PKCS @code{11} URL specifying a token 78 79@var{key}: The raw key 80 81@var{label}: A name to be used for the stored data 82 83@var{key_usage}: One of GNUTLS_KEY_* 84 85@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_* 86 87This function will copy a raw secret (symmetric) key into a PKCS @code{11} 88token specified by a URL. The key can be marked as sensitive or not. 89 90@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 91negative error value. 92 93@strong{Since:} 2.12.0 94@end deftypefun 95 96@subheading gnutls_pkcs11_copy_x509_crt 97@anchor{gnutls_pkcs11_copy_x509_crt} 98@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}) 99@var{token_url}: A PKCS @code{11} URL specifying a token 100 101@var{crt}: A certificate 102 103@var{label}: A name to be used for the stored data 104 105@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_* 106 107This function will copy a certificate into a PKCS @code{11} token specified by 108a URL. The certificate can be marked as trusted or not. 109 110@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 111negative error value. 112 113@strong{Since:} 2.12.0 114@end deftypefun 115 116@subheading gnutls_pkcs11_copy_x509_crt2 117@anchor{gnutls_pkcs11_copy_x509_crt2} 118@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}) 119@var{token_url}: A PKCS @code{11} URL specifying a token 120 121@var{crt}: The certificate to copy 122 123@var{label}: The name to be used for the stored data 124 125@var{cid}: The CKA_ID to set for the object -if NULL, the ID will be derived from the public key 126 127@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_* 128 129This function will copy a certificate into a PKCS @code{11} token specified by 130a URL. Valid flags to mark the certificate: @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED} , 131@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE} , @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_CA} , 132@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_ALWAYS_AUTH} . 133 134@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 135negative error value. 136 137@strong{Since:} 3.4.0 138@end deftypefun 139 140@subheading gnutls_pkcs11_copy_x509_privkey 141@anchor{gnutls_pkcs11_copy_x509_privkey} 142@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}) 143@var{token_url}: A PKCS @code{11} URL specifying a token 144 145@var{key}: A private key 146 147@var{label}: A name to be used for the stored data 148 149@var{key_usage}: One of GNUTLS_KEY_* 150 151@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags 152 153This function will copy a private key into a PKCS @code{11} token specified by 154a URL. 155 156Since 3.6.3 the objects are marked as sensitive by default unless 157@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE} is specified. 158 159@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 160negative error value. 161 162@strong{Since:} 2.12.0 163@end deftypefun 164 165@subheading gnutls_pkcs11_copy_x509_privkey2 166@anchor{gnutls_pkcs11_copy_x509_privkey2} 167@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}) 168@var{token_url}: A PKCS @code{11} URL specifying a token 169 170@var{key}: A private key 171 172@var{label}: A name to be used for the stored data 173 174@var{cid}: The CKA_ID to set for the object -if NULL, the ID will be derived from the public key 175 176@var{key_usage}: One of GNUTLS_KEY_* 177 178@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags 179 180This function will copy a private key into a PKCS @code{11} token specified by 181a URL. 182 183Since 3.6.3 the objects are marked as sensitive by default unless 184@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE} is specified. 185 186@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 187negative error value. 188 189@strong{Since:} 3.4.0 190@end deftypefun 191 192@subheading gnutls_pkcs11_crt_is_known 193@anchor{gnutls_pkcs11_crt_is_known} 194@deftypefun {unsigned} {gnutls_pkcs11_crt_is_known} (const char * @var{url}, gnutls_x509_crt_t @var{cert}, unsigned int @var{flags}) 195@var{url}: A PKCS 11 url identifying a token 196 197@var{cert}: is the certificate to find issuer for 198 199@var{flags}: Use zero or flags from @code{GNUTLS_PKCS11_OBJ_FLAG} . 200 201This function will check whether the provided certificate is stored 202in the specified token. This is useful in combination with 203@code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_TRUSTED} or 204@code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED} , 205to check whether a CA is present or a certificate is blacklisted in 206a trust PKCS @code{11} module. 207 208This function can be used with a @code{url} of "pkcs11:", and in that case all modules 209will be searched. To restrict the modules to the marked as trusted in p11-kit 210use the @code{GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE} flag. 211 212Note that the flag @code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED} is 213specific to p11-kit trust modules. 214 215@strong{Returns:} If the certificate exists non-zero is returned, otherwise zero. 216 217@strong{Since:} 3.3.0 218@end deftypefun 219 220@subheading gnutls_pkcs11_deinit 221@anchor{gnutls_pkcs11_deinit} 222@deftypefun {void} {gnutls_pkcs11_deinit} ( @var{void}) 223 224This function will deinitialize the PKCS 11 subsystem in gnutls. 225This function is only needed if you need to deinitialize the 226subsystem without calling @code{gnutls_global_deinit()} . 227 228@strong{Since:} 2.12.0 229@end deftypefun 230 231@subheading gnutls_pkcs11_delete_url 232@anchor{gnutls_pkcs11_delete_url} 233@deftypefun {int} {gnutls_pkcs11_delete_url} (const char * @var{object_url}, unsigned int @var{flags}) 234@var{object_url}: The URL of the object to delete. 235 236@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags 237 238This function will delete objects matching the given URL. 239Note that not all tokens support the delete operation. 240 241@strong{Returns:} On success, the number of objects deleted is returned, otherwise a 242negative error value. 243 244@strong{Since:} 2.12.0 245@end deftypefun 246 247@subheading gnutls_pkcs11_get_pin_function 248@anchor{gnutls_pkcs11_get_pin_function} 249@deftypefun {gnutls_pin_callback_t} {gnutls_pkcs11_get_pin_function} (void ** @var{userdata}) 250@var{userdata}: data to be supplied to callback 251 252This function will return the callback function set using 253@code{gnutls_pkcs11_set_pin_function()} . 254 255@strong{Returns:} The function set or NULL otherwise. 256 257@strong{Since:} 3.1.0 258@end deftypefun 259 260@subheading gnutls_pkcs11_get_raw_issuer 261@anchor{gnutls_pkcs11_get_raw_issuer} 262@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}) 263@var{url}: A PKCS 11 url identifying a token 264 265@var{cert}: is the certificate to find issuer for 266 267@var{issuer}: Will hold the issuer if any in an allocated buffer. 268 269@var{fmt}: The format of the exported issuer. 270 271@var{flags}: Use zero or flags from @code{GNUTLS_PKCS11_OBJ_FLAG} . 272 273This function will return the issuer of a given certificate, if it 274is stored in the token. By default only marked as trusted issuers 275are returned. If any issuer should be returned specify 276@code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY} in @code{flags} . 277 278@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 279negative error value. 280 281@strong{Since:} 3.2.7 282@end deftypefun 283 284@subheading gnutls_pkcs11_get_raw_issuer_by_dn 285@anchor{gnutls_pkcs11_get_raw_issuer_by_dn} 286@deftypefun {int} {gnutls_pkcs11_get_raw_issuer_by_dn} (const char * @var{url}, const gnutls_datum_t * @var{dn}, gnutls_datum_t * @var{issuer}, gnutls_x509_crt_fmt_t @var{fmt}, unsigned int @var{flags}) 287@var{url}: A PKCS 11 url identifying a token 288 289@var{dn}: is the DN to search for 290 291@var{issuer}: Will hold the issuer if any in an allocated buffer. 292 293@var{fmt}: The format of the exported issuer. 294 295@var{flags}: Use zero or flags from @code{GNUTLS_PKCS11_OBJ_FLAG} . 296 297This function will return the certificate with the given DN, if it 298is stored in the token. By default only marked as trusted issuers 299are returned. If any issuer should be returned specify 300@code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY} in @code{flags} . 301 302The name of the function includes issuer because it can 303be used to discover issuers of certificates. 304 305@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 306negative error value. 307 308@strong{Since:} 3.4.0 309@end deftypefun 310 311@subheading gnutls_pkcs11_get_raw_issuer_by_subject_key_id 312@anchor{gnutls_pkcs11_get_raw_issuer_by_subject_key_id} 313@deftypefun {int} {gnutls_pkcs11_get_raw_issuer_by_subject_key_id} (const char * @var{url}, const gnutls_datum_t * @var{dn}, const gnutls_datum_t * @var{spki}, gnutls_datum_t * @var{issuer}, gnutls_x509_crt_fmt_t @var{fmt}, unsigned int @var{flags}) 314@var{url}: A PKCS 11 url identifying a token 315 316@var{dn}: is the DN to search for (may be @code{NULL} ) 317 318@var{spki}: is the subject key ID to search for 319 320@var{issuer}: Will hold the issuer if any in an allocated buffer. 321 322@var{fmt}: The format of the exported issuer. 323 324@var{flags}: Use zero or flags from @code{GNUTLS_PKCS11_OBJ_FLAG} . 325 326This function will return the certificate with the given DN and @code{spki} , if it 327is stored in the token. By default only marked as trusted issuers 328are returned. If any issuer should be returned specify 329@code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY} in @code{flags} . 330 331The name of the function includes issuer because it can 332be used to discover issuers of certificates. 333 334@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 335negative error value. 336 337@strong{Since:} 3.4.2 338@end deftypefun 339 340@subheading gnutls_pkcs11_init 341@anchor{gnutls_pkcs11_init} 342@deftypefun {int} {gnutls_pkcs11_init} (unsigned int @var{flags}, const char * @var{deprecated_config_file}) 343@var{flags}: An ORed sequence of @code{GNUTLS_PKCS11_FLAG_} * 344 345@var{deprecated_config_file}: either NULL or the location of a deprecated 346configuration file 347 348This function will initialize the PKCS 11 subsystem in gnutls. It will 349read configuration files if @code{GNUTLS_PKCS11_FLAG_AUTO} is used or allow 350you to independently load PKCS 11 modules using @code{gnutls_pkcs11_add_provider()} 351if @code{GNUTLS_PKCS11_FLAG_MANUAL} is specified. 352 353You don't need to call this function since GnuTLS 3.3.0 because it is being called 354during the first request PKCS 11 operation. That call will assume the @code{GNUTLS_PKCS11_FLAG_AUTO} 355flag. If another flags are required then it must be called independently 356prior to any PKCS 11 operation. 357 358@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 359negative error value. 360 361@strong{Since:} 2.12.0 362@end deftypefun 363 364@subheading gnutls_pkcs11_obj_deinit 365@anchor{gnutls_pkcs11_obj_deinit} 366@deftypefun {void} {gnutls_pkcs11_obj_deinit} (gnutls_pkcs11_obj_t @var{obj}) 367@var{obj}: The type to be deinitialized 368 369This function will deinitialize a certificate structure. 370 371@strong{Since:} 2.12.0 372@end deftypefun 373 374@subheading gnutls_pkcs11_obj_export 375@anchor{gnutls_pkcs11_obj_export} 376@deftypefun {int} {gnutls_pkcs11_obj_export} (gnutls_pkcs11_obj_t @var{obj}, void * @var{output_data}, size_t * @var{output_data_size}) 377@var{obj}: Holds the object 378 379@var{output_data}: will contain the object data 380 381@var{output_data_size}: holds the size of output_data (and will be 382replaced by the actual size of parameters) 383 384This function will export the PKCS11 object data. It is normal for 385data to be inaccessible and in that case @code{GNUTLS_E_INVALID_REQUEST} 386will be returned. 387 388If the buffer provided is not long enough to hold the output, then 389*output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will 390be returned. 391 392@strong{Returns:} In case of failure a negative error code will be 393returned, and @code{GNUTLS_E_SUCCESS} (0) on success. 394 395@strong{Since:} 2.12.0 396@end deftypefun 397 398@subheading gnutls_pkcs11_obj_export2 399@anchor{gnutls_pkcs11_obj_export2} 400@deftypefun {int} {gnutls_pkcs11_obj_export2} (gnutls_pkcs11_obj_t @var{obj}, gnutls_datum_t * @var{out}) 401@var{obj}: Holds the object 402 403@var{out}: will contain the object data 404 405This function will export the PKCS11 object data. It is normal for 406data to be inaccessible and in that case @code{GNUTLS_E_INVALID_REQUEST} 407will be returned. 408 409The output buffer is allocated using @code{gnutls_malloc()} . 410 411@strong{Returns:} In case of failure a negative error code will be 412returned, and @code{GNUTLS_E_SUCCESS} (0) on success. 413 414@strong{Since:} 3.1.3 415@end deftypefun 416 417@subheading gnutls_pkcs11_obj_export3 418@anchor{gnutls_pkcs11_obj_export3} 419@deftypefun {int} {gnutls_pkcs11_obj_export3} (gnutls_pkcs11_obj_t @var{obj}, gnutls_x509_crt_fmt_t @var{fmt}, gnutls_datum_t * @var{out}) 420@var{obj}: Holds the object 421 422@var{fmt}: The format of the exported data 423 424@var{out}: will contain the object data 425 426This function will export the PKCS11 object data. It is normal for 427data to be inaccessible and in that case @code{GNUTLS_E_INVALID_REQUEST} 428will be returned. 429 430The output buffer is allocated using @code{gnutls_malloc()} . 431 432@strong{Returns:} In case of failure a negative error code will be 433returned, and @code{GNUTLS_E_SUCCESS} (0) on success. 434 435@strong{Since:} 3.2.7 436@end deftypefun 437 438@subheading gnutls_pkcs11_obj_export_url 439@anchor{gnutls_pkcs11_obj_export_url} 440@deftypefun {int} {gnutls_pkcs11_obj_export_url} (gnutls_pkcs11_obj_t @var{obj}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url}) 441@var{obj}: Holds the PKCS 11 certificate 442 443@var{detailed}: non zero if a detailed URL is required 444 445@var{url}: will contain an allocated url 446 447This function will export a URL identifying the given object. 448 449@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 450negative error value. 451 452@strong{Since:} 2.12.0 453@end deftypefun 454 455@subheading gnutls_pkcs11_obj_flags_get_str 456@anchor{gnutls_pkcs11_obj_flags_get_str} 457@deftypefun {char *} {gnutls_pkcs11_obj_flags_get_str} (unsigned int @var{flags}) 458@var{flags}: holds the flags 459 460This function given an or-sequence of @code{GNUTLS_PKCS11_OBJ_FLAG_MARK} , 461will return an allocated string with its description. The string 462needs to be deallocated using @code{gnutls_free()} . 463 464@strong{Returns:} If flags is zero @code{NULL} is returned, otherwise an allocated string. 465 466@strong{Since:} 3.3.7 467@end deftypefun 468 469@subheading gnutls_pkcs11_obj_get_exts 470@anchor{gnutls_pkcs11_obj_get_exts} 471@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}) 472@var{obj}: should contain a @code{gnutls_pkcs11_obj_t} type 473 474@var{exts}: a pointer to a @code{gnutls_x509_ext_st} pointer 475 476@var{exts_size}: will be updated with the number of @code{exts} 477 478@var{flags}: Or sequence of @code{GNUTLS_PKCS11_OBJ_} * flags 479 480This function will return information about attached extensions 481that associate to the provided object (which should be a certificate). 482The extensions are the attached p11-kit trust module extensions. 483 484Each element of @code{exts} must be deinitialized using @code{gnutls_x509_ext_deinit()} 485while @code{exts} should be deallocated using @code{gnutls_free()} . 486 487@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. 488 489@strong{Since:} 3.3.8 490@end deftypefun 491 492@subheading gnutls_pkcs11_obj_get_flags 493@anchor{gnutls_pkcs11_obj_get_flags} 494@deftypefun {int} {gnutls_pkcs11_obj_get_flags} (gnutls_pkcs11_obj_t @var{obj}, unsigned int * @var{oflags}) 495@var{obj}: The pkcs11 object 496 497@var{oflags}: Will hold the output flags 498 499This function will return the flags of the object. 500The @code{oflags} will be flags from @code{gnutls_pkcs11_obj_flags} . That is, 501the @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_} * flags. 502 503@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 504negative error value. 505 506@strong{Since:} 3.3.7 507@end deftypefun 508 509@subheading gnutls_pkcs11_obj_get_info 510@anchor{gnutls_pkcs11_obj_get_info} 511@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}) 512@var{obj}: should contain a @code{gnutls_pkcs11_obj_t} type 513 514@var{itype}: Denotes the type of information requested 515 516@var{output}: where output will be stored 517 518@var{output_size}: contains the maximum size of the output buffer and will be 519overwritten with the actual size. 520 521This function will return information about the PKCS11 certificate 522such as the label, id as well as token information where the key is 523stored. 524 525When output is text, a null terminated string is written to @code{output} and its 526string length is written to @code{output_size} (without null terminator). If the 527buffer is too small, @code{output_size} will contain the expected buffer size 528(with null terminator for text) and return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} . 529 530In versions previously to 3.6.0 this function included the null terminator 531to @code{output_size} . After 3.6.0 the output size doesn't include the terminator character. 532 533@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. 534 535@strong{Since:} 2.12.0 536@end deftypefun 537 538@subheading gnutls_pkcs11_obj_get_ptr 539@anchor{gnutls_pkcs11_obj_get_ptr} 540@deftypefun {int} {gnutls_pkcs11_obj_get_ptr} (gnutls_pkcs11_obj_t @var{obj}, void ** @var{ptr}, void ** @var{session}, void ** @var{ohandle}, unsigned long * @var{slot_id}, unsigned int @var{flags}) 541@var{obj}: should contain a @code{gnutls_pkcs11_obj_t} type 542 543@var{ptr}: will contain the CK_FUNCTION_LIST_PTR pointer (may be @code{NULL} ) 544 545@var{session}: will contain the CK_SESSION_HANDLE of the object 546 547@var{ohandle}: will contain the CK_OBJECT_HANDLE of the object 548 549@var{slot_id}: the identifier of the slot (may be @code{NULL} ) 550 551@var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags 552 553Obtains the PKCS@code{11} session handles of an object. @code{session} and @code{ohandle} must be deinitialized by the caller. The returned pointers are 554independent of the @code{obj} lifetime. 555 556@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code 557on error. 558 559@strong{Since:} 3.6.3 560@end deftypefun 561 562@subheading gnutls_pkcs11_obj_get_type 563@anchor{gnutls_pkcs11_obj_get_type} 564@deftypefun {gnutls_pkcs11_obj_type_t} {gnutls_pkcs11_obj_get_type} (gnutls_pkcs11_obj_t @var{obj}) 565@var{obj}: Holds the PKCS 11 object 566 567This function will return the type of the object being 568stored in the structure. 569 570@strong{Returns:} The type of the object 571 572@strong{Since:} 2.12.0 573@end deftypefun 574 575@subheading gnutls_pkcs11_obj_import_url 576@anchor{gnutls_pkcs11_obj_import_url} 577@deftypefun {int} {gnutls_pkcs11_obj_import_url} (gnutls_pkcs11_obj_t @var{obj}, const char * @var{url}, unsigned int @var{flags}) 578@var{obj}: The structure to store the object 579 580@var{url}: a PKCS 11 url identifying the key 581 582@var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags 583 584This function will "import" a PKCS 11 URL identifying an object (e.g. certificate) 585to the @code{gnutls_pkcs11_obj_t} type. This does not involve any 586parsing (such as X.509 or OpenPGP) since the @code{gnutls_pkcs11_obj_t} is 587format agnostic. Only data are transferred. 588 589If the flag @code{GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT} is specified 590any certificate read, will have its extensions overwritten by any 591stapled extensions in the trust module. 592 593@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 594negative error value. 595 596@strong{Since:} 2.12.0 597@end deftypefun 598 599@subheading gnutls_pkcs11_obj_init 600@anchor{gnutls_pkcs11_obj_init} 601@deftypefun {int} {gnutls_pkcs11_obj_init} (gnutls_pkcs11_obj_t * @var{obj}) 602@var{obj}: A pointer to the type to be initialized 603 604This function will initialize a pkcs11 certificate structure. 605 606@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 607negative error value. 608 609@strong{Since:} 2.12.0 610@end deftypefun 611 612@subheading gnutls_pkcs11_obj_list_import_url3 613@anchor{gnutls_pkcs11_obj_list_import_url3} 614@deftypefun {int} {gnutls_pkcs11_obj_list_import_url3} (gnutls_pkcs11_obj_t * @var{p_list}, unsigned int * @var{n_list}, const char * @var{url}, unsigned int @var{flags}) 615@var{p_list}: An uninitialized object list (may be @code{NULL} ) 616 617@var{n_list}: Initially should hold the maximum size of the list. Will contain the actual size. 618 619@var{url}: A PKCS 11 url identifying a set of objects 620 621@var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags 622 623This function will initialize and set values to an object list 624by using all objects identified by a PKCS 11 URL. 625 626This function will enumerate all the objects specified by the PKCS@code{11} URL 627provided. It expects an already allocated @code{p_list} which has * @code{n_list} elements, 628and that value will be updated to the actual number of present objects. The 629 @code{p_list} objects will be initialized and set by this function. 630To obtain a list of all available objects use a @code{url} of 'pkcs11:'. 631 632All returned objects must be deinitialized using @code{gnutls_pkcs11_obj_deinit()} . 633 634The supported in this function @code{flags} are @code{GNUTLS_PKCS11_OBJ_FLAG_LOGIN} , 635@code{GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO} , @code{GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE} , 636@code{GNUTLS_PKCS11_OBJ_FLAG_CRT} , @code{GNUTLS_PKCS11_OBJ_FLAG_PUBKEY} , @code{GNUTLS_PKCS11_OBJ_FLAG_PRIVKEY} , 637@code{GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY} , @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_CA} , 638@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED} , and since 3.5.1 the @code{GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT} . 639 640On versions of GnuTLS prior to 3.4.0 the equivalent function was 641@code{gnutls_pkcs11_obj_list_import_url()} . That is also available on this version 642as a macro which maps to this function. 643 644@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 645negative error value. 646 647@strong{Since:} 3.4.0 648@end deftypefun 649 650@subheading gnutls_pkcs11_obj_list_import_url4 651@anchor{gnutls_pkcs11_obj_list_import_url4} 652@deftypefun {int} {gnutls_pkcs11_obj_list_import_url4} (gnutls_pkcs11_obj_t ** @var{p_list}, unsigned int * @var{n_list}, const char * @var{url}, unsigned int @var{flags}) 653@var{p_list}: An uninitialized object list (may be NULL) 654 655@var{n_list}: It will contain the size of the list. 656 657@var{url}: A PKCS 11 url identifying a set of objects 658 659@var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags 660 661This function will enumerate all the objects specified by the PKCS@code{11} URL 662provided. It will initialize and set values to the object pointer list ( @code{p_list} ) 663provided. To obtain a list of all available objects use a @code{url} of 'pkcs11:'. 664 665All returned objects must be deinitialized using @code{gnutls_pkcs11_obj_deinit()} , 666and @code{p_list} must be deinitialized using @code{gnutls_free()} . 667 668The supported in this function @code{flags} are @code{GNUTLS_PKCS11_OBJ_FLAG_LOGIN} , 669@code{GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO} , @code{GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE} , 670@code{GNUTLS_PKCS11_OBJ_FLAG_CRT} , @code{GNUTLS_PKCS11_OBJ_FLAG_PUBKEY} , @code{GNUTLS_PKCS11_OBJ_FLAG_PRIVKEY} , 671@code{GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY} , @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_CA} , 672@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED} , and since 3.5.1 the @code{GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT} . 673 674On versions of GnuTLS prior to 3.4.0 the equivalent function was 675@code{gnutls_pkcs11_obj_list_import_url2()} . That is also available on this version 676as a macro which maps to this function. 677 678@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 679negative error value. 680 681@strong{Since:} 3.4.0 682@end deftypefun 683 684@subheading gnutls_pkcs11_obj_set_info 685@anchor{gnutls_pkcs11_obj_set_info} 686@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}) 687@var{obj}: should contain a @code{gnutls_pkcs11_obj_t} type 688 689@var{itype}: Denotes the type of information to be set 690 691@var{data}: the data to set 692 693@var{data_size}: the size of data 694 695@var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags 696 697This function will set attributes on the provided object. 698Available options for @code{itype} are @code{GNUTLS_PKCS11_OBJ_LABEL} , 699@code{GNUTLS_PKCS11_OBJ_ID_HEX} , and @code{GNUTLS_PKCS11_OBJ_ID} . 700 701@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. 702 703@strong{Since:} 3.4.0 704@end deftypefun 705 706@subheading gnutls_pkcs11_obj_set_pin_function 707@anchor{gnutls_pkcs11_obj_set_pin_function} 708@deftypefun {void} {gnutls_pkcs11_obj_set_pin_function} (gnutls_pkcs11_obj_t @var{obj}, gnutls_pin_callback_t @var{fn}, void * @var{userdata}) 709@var{obj}: The object structure 710 711@var{fn}: the callback 712 713@var{userdata}: data associated with the callback 714 715This function will set a callback function to be used when 716required to access the object. This function overrides the global 717set using @code{gnutls_pkcs11_set_pin_function()} . 718 719@strong{Since:} 3.1.0 720@end deftypefun 721 722@subheading gnutls_pkcs11_privkey_cpy 723@anchor{gnutls_pkcs11_privkey_cpy} 724@deftypefun {int} {gnutls_pkcs11_privkey_cpy} (gnutls_pkcs11_privkey_t @var{dst}, gnutls_pkcs11_privkey_t @var{src}) 725@var{dst}: The destination key, which should be initialized. 726 727@var{src}: The source key 728 729This function will copy a private key from source to destination 730key. Destination has to be initialized. 731 732@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 733negative error value. 734 735@strong{Since:} 3.4.0 736@end deftypefun 737 738@subheading gnutls_pkcs11_privkey_deinit 739@anchor{gnutls_pkcs11_privkey_deinit} 740@deftypefun {void} {gnutls_pkcs11_privkey_deinit} (gnutls_pkcs11_privkey_t @var{key}) 741@var{key}: the key to be deinitialized 742 743This function will deinitialize a private key structure. 744@end deftypefun 745 746@subheading gnutls_pkcs11_privkey_export_pubkey 747@anchor{gnutls_pkcs11_privkey_export_pubkey} 748@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}) 749@var{pkey}: The private key 750 751@var{fmt}: the format of output params. PEM or DER. 752 753@var{data}: will hold the public key 754 755@var{flags}: should be zero 756 757This function will extract the public key (modulus and public 758exponent) from the private key specified by the @code{url} private key. 759This public key will be stored in @code{pubkey} in the format specified 760by @code{fmt} . @code{pubkey} should be deinitialized using @code{gnutls_free()} . 761 762@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 763negative error value. 764 765@strong{Since:} 3.3.7 766@end deftypefun 767 768@subheading gnutls_pkcs11_privkey_export_url 769@anchor{gnutls_pkcs11_privkey_export_url} 770@deftypefun {int} {gnutls_pkcs11_privkey_export_url} (gnutls_pkcs11_privkey_t @var{key}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url}) 771@var{key}: Holds the PKCS 11 key 772 773@var{detailed}: non zero if a detailed URL is required 774 775@var{url}: will contain an allocated url 776 777This function will export a URL identifying the given key. 778 779@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 780negative error value. 781@end deftypefun 782 783@subheading gnutls_pkcs11_privkey_generate 784@anchor{gnutls_pkcs11_privkey_generate} 785@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}) 786@var{url}: a token URL 787 788@var{pk}: the public key algorithm 789 790@var{bits}: the security bits 791 792@var{label}: a label 793 794@var{flags}: should be zero 795 796This function will generate a private key in the specified 797by the @code{url} token. The private key will be generate within 798the token and will not be exportable. 799 800@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 801negative error value. 802 803@strong{Since:} 3.0 804@end deftypefun 805 806@subheading gnutls_pkcs11_privkey_generate2 807@anchor{gnutls_pkcs11_privkey_generate2} 808@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}) 809@var{url}: a token URL 810 811@var{pk}: the public key algorithm 812 813@var{bits}: the security bits 814 815@var{label}: a label 816 817@var{fmt}: the format of output params. PEM or DER 818 819@var{pubkey}: will hold the public key (may be @code{NULL} ) 820 821@var{flags}: zero or an OR'ed sequence of @code{GNUTLS_PKCS11_OBJ_FLAGs} 822 823This function will generate a private key in the specified 824by the @code{url} token. The private key will be generate within 825the token and will not be exportable. This function will 826store the DER-encoded public key in the SubjectPublicKeyInfo format 827in @code{pubkey} . The @code{pubkey} should be deinitialized using @code{gnutls_free()} . 828 829Note that when generating an elliptic curve key, the curve 830can be substituted in the place of the bits parameter using the 831@code{GNUTLS_CURVE_TO_BITS()} macro. 832 833@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 834negative error value. 835 836@strong{Since:} 3.1.5 837@end deftypefun 838 839@subheading gnutls_pkcs11_privkey_generate3 840@anchor{gnutls_pkcs11_privkey_generate3} 841@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{key_usage}, unsigned int @var{flags}) 842@var{url}: a token URL 843 844@var{pk}: the public key algorithm 845 846@var{bits}: the security bits 847 848@var{label}: a label 849 850@var{cid}: The CKA_ID to use for the new object 851 852@var{fmt}: the format of output params. PEM or DER 853 854@var{pubkey}: will hold the public key (may be @code{NULL} ) 855 856@var{key_usage}: One of GNUTLS_KEY_* 857 858@var{flags}: zero or an OR'ed sequence of @code{GNUTLS_PKCS11_OBJ_FLAGs} 859 860This function will generate a private key in the specified 861by the @code{url} token. The private key will be generate within 862the token and will not be exportable. This function will 863store the DER-encoded public key in the SubjectPublicKeyInfo format 864in @code{pubkey} . The @code{pubkey} should be deinitialized using @code{gnutls_free()} . 865 866Note that when generating an elliptic curve key, the curve 867can be substituted in the place of the bits parameter using the 868@code{GNUTLS_CURVE_TO_BITS()} macro. 869 870Since 3.6.3 the objects are marked as sensitive by default unless 871@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE} is specified. 872 873@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 874negative error value. 875 876@strong{Since:} 3.4.0 877@end deftypefun 878 879@subheading gnutls_pkcs11_privkey_get_info 880@anchor{gnutls_pkcs11_privkey_get_info} 881@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}) 882@var{pkey}: should contain a @code{gnutls_pkcs11_privkey_t} type 883 884@var{itype}: Denotes the type of information requested 885 886@var{output}: where output will be stored 887 888@var{output_size}: contains the maximum size of the output and will be overwritten with actual 889 890This function will return information about the PKCS 11 private key such 891as the label, id as well as token information where the key is stored. When 892output is text it returns null terminated string although @code{output_size} contains 893the size of the actual data only. 894 895@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. 896@end deftypefun 897 898@subheading gnutls_pkcs11_privkey_get_pk_algorithm 899@anchor{gnutls_pkcs11_privkey_get_pk_algorithm} 900@deftypefun {int} {gnutls_pkcs11_privkey_get_pk_algorithm} (gnutls_pkcs11_privkey_t @var{key}, unsigned int * @var{bits}) 901@var{key}: should contain a @code{gnutls_pkcs11_privkey_t} type 902 903@var{bits}: if bits is non null it will hold the size of the parameters' in bits 904 905This function will return the public key algorithm of a private 906key. 907 908@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on 909success, or a negative error code on error. 910@end deftypefun 911 912@subheading gnutls_pkcs11_privkey_import_url 913@anchor{gnutls_pkcs11_privkey_import_url} 914@deftypefun {int} {gnutls_pkcs11_privkey_import_url} (gnutls_pkcs11_privkey_t @var{pkey}, const char * @var{url}, unsigned int @var{flags}) 915@var{pkey}: The private key 916 917@var{url}: a PKCS 11 url identifying the key 918 919@var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags 920 921This function will "import" a PKCS 11 URL identifying a private 922key to the @code{gnutls_pkcs11_privkey_t} type. In reality since 923in most cases keys cannot be exported, the private key structure 924is being associated with the available operations on the token. 925 926@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 927negative error value. 928@end deftypefun 929 930@subheading gnutls_pkcs11_privkey_init 931@anchor{gnutls_pkcs11_privkey_init} 932@deftypefun {int} {gnutls_pkcs11_privkey_init} (gnutls_pkcs11_privkey_t * @var{key}) 933@var{key}: A pointer to the type to be initialized 934 935This function will initialize an private key structure. This 936structure can be used for accessing an underlying PKCS@code{11} object. 937 938In versions of GnuTLS later than 3.5.11 the object is protected 939using locks and a single @code{gnutls_pkcs11_privkey_t} can be re-used 940by many threads. However, for performance it is recommended to utilize 941one object per key per thread. 942 943@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 944negative error value. 945@end deftypefun 946 947@subheading gnutls_pkcs11_privkey_set_pin_function 948@anchor{gnutls_pkcs11_privkey_set_pin_function} 949@deftypefun {void} {gnutls_pkcs11_privkey_set_pin_function} (gnutls_pkcs11_privkey_t @var{key}, gnutls_pin_callback_t @var{fn}, void * @var{userdata}) 950@var{key}: The private key 951 952@var{fn}: the callback 953 954@var{userdata}: data associated with the callback 955 956This function will set a callback function to be used when 957required to access the object. This function overrides the global 958set using @code{gnutls_pkcs11_set_pin_function()} . 959 960@strong{Since:} 3.1.0 961@end deftypefun 962 963@subheading gnutls_pkcs11_privkey_status 964@anchor{gnutls_pkcs11_privkey_status} 965@deftypefun {unsigned} {gnutls_pkcs11_privkey_status} (gnutls_pkcs11_privkey_t @var{key}) 966@var{key}: Holds the key 967 968Checks the status of the private key token. 969 970@strong{Returns:} this function will return non-zero if the token 971holding the private key is still available (inserted), and zero otherwise. 972 973@strong{Since:} 3.1.9 974@end deftypefun 975 976@subheading gnutls_pkcs11_reinit 977@anchor{gnutls_pkcs11_reinit} 978@deftypefun {int} {gnutls_pkcs11_reinit} ( @var{void}) 979 980This function will reinitialize the PKCS 11 subsystem in gnutls. 981This is required by PKCS 11 when an application uses @code{fork()} . The 982reinitialization function must be called on the child. 983 984Note that since GnuTLS 3.3.0, the reinitialization of the PKCS @code{11} 985subsystem occurs automatically after fork. 986 987@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 988negative error value. 989 990@strong{Since:} 3.0 991@end deftypefun 992 993@subheading gnutls_pkcs11_set_pin_function 994@anchor{gnutls_pkcs11_set_pin_function} 995@deftypefun {void} {gnutls_pkcs11_set_pin_function} (gnutls_pin_callback_t @var{fn}, void * @var{userdata}) 996@var{fn}: The PIN callback, a @code{gnutls_pin_callback_t()} function. 997 998@var{userdata}: data to be supplied to callback 999 1000This function will set a callback function to be used when a PIN is 1001required for PKCS 11 operations. See 1002@code{gnutls_pin_callback_t()} on how the callback should behave. 1003 1004@strong{Since:} 2.12.0 1005@end deftypefun 1006 1007@subheading gnutls_pkcs11_set_token_function 1008@anchor{gnutls_pkcs11_set_token_function} 1009@deftypefun {void} {gnutls_pkcs11_set_token_function} (gnutls_pkcs11_token_callback_t @var{fn}, void * @var{userdata}) 1010@var{fn}: The token callback 1011 1012@var{userdata}: data to be supplied to callback 1013 1014This function will set a callback function to be used when a token 1015needs to be inserted to continue PKCS 11 operations. 1016 1017@strong{Since:} 2.12.0 1018@end deftypefun 1019 1020@subheading gnutls_pkcs11_token_check_mechanism 1021@anchor{gnutls_pkcs11_token_check_mechanism} 1022@deftypefun {unsigned} {gnutls_pkcs11_token_check_mechanism} (const char * @var{url}, unsigned long @var{mechanism}, void * @var{ptr}, unsigned @var{psize}, unsigned @var{flags}) 1023@var{url}: should contain a PKCS 11 URL 1024 1025@var{mechanism}: The PKCS @code{11} mechanism ID 1026 1027@var{ptr}: if set it should point to a CK_MECHANISM_INFO struct 1028 1029@var{psize}: the size of CK_MECHANISM_INFO struct (for safety) 1030 1031@var{flags}: must be zero 1032 1033This function will return whether a mechanism is supported 1034by the given token. If the mechanism is supported and 1035 @code{ptr} is set, it will be updated with the token information. 1036 1037@strong{Returns:} Non-zero if the mechanism is supported or zero otherwise. 1038 1039@strong{Since:} 3.6.0 1040@end deftypefun 1041 1042@subheading gnutls_pkcs11_token_get_flags 1043@anchor{gnutls_pkcs11_token_get_flags} 1044@deftypefun {int} {gnutls_pkcs11_token_get_flags} (const char * @var{url}, unsigned int * @var{flags}) 1045@var{url}: should contain a PKCS 11 URL 1046 1047@var{flags}: The output flags (GNUTLS_PKCS11_TOKEN_*) 1048 1049This function will return information about the PKCS 11 token flags. 1050 1051The supported flags are: @code{GNUTLS_PKCS11_TOKEN_HW} and @code{GNUTLS_PKCS11_TOKEN_TRUSTED} . 1052 1053@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. 1054 1055@strong{Since:} 2.12.0 1056@end deftypefun 1057 1058@subheading gnutls_pkcs11_token_get_info 1059@anchor{gnutls_pkcs11_token_get_info} 1060@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}) 1061@var{url}: should contain a PKCS 11 URL 1062 1063@var{ttype}: Denotes the type of information requested 1064 1065@var{output}: where output will be stored 1066 1067@var{output_size}: contains the maximum size of the output buffer and will be 1068overwritten with the actual size. 1069 1070This function will return information about the PKCS 11 token such 1071as the label, id, etc. 1072 1073When output is text, a null terminated string is written to @code{output} and its 1074string length is written to @code{output_size} (without null terminator). If the 1075buffer is too small, @code{output_size} will contain the expected buffer size 1076(with null terminator for text) and return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} . 1077 1078@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code 1079on error. 1080 1081@strong{Since:} 2.12.0 1082@end deftypefun 1083 1084@subheading gnutls_pkcs11_token_get_mechanism 1085@anchor{gnutls_pkcs11_token_get_mechanism} 1086@deftypefun {int} {gnutls_pkcs11_token_get_mechanism} (const char * @var{url}, unsigned int @var{idx}, unsigned long * @var{mechanism}) 1087@var{url}: should contain a PKCS 11 URL 1088 1089@var{idx}: The index of the mechanism 1090 1091@var{mechanism}: The PKCS @code{11} mechanism ID 1092 1093This function will return the names of the supported mechanisms 1094by the token. It should be called with an increasing index until 1095it return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE. 1096 1097@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. 1098 1099@strong{Since:} 2.12.0 1100@end deftypefun 1101 1102@subheading gnutls_pkcs11_token_get_ptr 1103@anchor{gnutls_pkcs11_token_get_ptr} 1104@deftypefun {int} {gnutls_pkcs11_token_get_ptr} (const char * @var{url}, void ** @var{ptr}, unsigned long * @var{slot_id}, unsigned int @var{flags}) 1105@var{url}: should contain a PKCS@code{11} URL identifying a token 1106 1107@var{ptr}: will contain the CK_FUNCTION_LIST_PTR pointer 1108 1109@var{slot_id}: will contain the slot_id (may be @code{NULL} ) 1110 1111@var{flags}: should be zero 1112 1113This function will return the function pointer of the specified 1114token by the URL. The returned pointers are valid until 1115gnutls is deinitialized, c.f. @code{_global_deinit()} . 1116 1117@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code 1118on error. 1119 1120@strong{Since:} 3.6.3 1121@end deftypefun 1122 1123@subheading gnutls_pkcs11_token_get_random 1124@anchor{gnutls_pkcs11_token_get_random} 1125@deftypefun {int} {gnutls_pkcs11_token_get_random} (const char * @var{token_url}, void * @var{rnddata}, size_t @var{len}) 1126@var{token_url}: A PKCS @code{11} URL specifying a token 1127 1128@var{rnddata}: A pointer to the memory area to be filled with random data 1129 1130@var{len}: The number of bytes of randomness to request 1131 1132This function will get random data from the given token. 1133It will store rnddata and fill the memory pointed to by rnddata with 1134len random bytes from the token. 1135 1136@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1137negative error value. 1138@end deftypefun 1139 1140@subheading gnutls_pkcs11_token_get_url 1141@anchor{gnutls_pkcs11_token_get_url} 1142@deftypefun {int} {gnutls_pkcs11_token_get_url} (unsigned int @var{seq}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url}) 1143@var{seq}: sequence number starting from 0 1144 1145@var{detailed}: non zero if a detailed URL is required 1146 1147@var{url}: will contain an allocated url 1148 1149This function will return the URL for each token available 1150in system. The url has to be released using @code{gnutls_free()} 1151 1152@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, 1153@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if the sequence number 1154exceeds the available tokens, otherwise a negative error value. 1155 1156@strong{Since:} 2.12.0 1157@end deftypefun 1158 1159@subheading gnutls_pkcs11_token_init 1160@anchor{gnutls_pkcs11_token_init} 1161@deftypefun {int} {gnutls_pkcs11_token_init} (const char * @var{token_url}, const char * @var{so_pin}, const char * @var{label}) 1162@var{token_url}: A PKCS @code{11} URL specifying a token 1163 1164@var{so_pin}: Security Officer's PIN 1165 1166@var{label}: A name to be used for the token 1167 1168This function will initialize (format) a token. If the token is 1169at a factory defaults state the security officer's PIN given will be 1170set to be the default. Otherwise it should match the officer's PIN. 1171 1172@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1173negative error value. 1174@end deftypefun 1175 1176@subheading gnutls_pkcs11_token_set_pin 1177@anchor{gnutls_pkcs11_token_set_pin} 1178@deftypefun {int} {gnutls_pkcs11_token_set_pin} (const char * @var{token_url}, const char * @var{oldpin}, const char * @var{newpin}, unsigned int @var{flags}) 1179@var{token_url}: A PKCS @code{11} URL specifying a token 1180 1181@var{oldpin}: old user's PIN 1182 1183@var{newpin}: new user's PIN 1184 1185@var{flags}: one of @code{gnutls_pin_flag_t} . 1186 1187This function will modify or set a user or administrator's PIN for 1188the given token. If it is called to set a PIN for first time 1189the oldpin must be @code{NULL} . When setting the admin's PIN with the 1190@code{GNUTLS_PIN_SO} flag, the @code{oldpin} value must be provided (this requirement 1191is relaxed after GnuTLS 3.6.5 since which the PIN will be requested if missing). 1192 1193@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1194negative error value. 1195@end deftypefun 1196 1197@subheading gnutls_pkcs11_type_get_name 1198@anchor{gnutls_pkcs11_type_get_name} 1199@deftypefun {const char *} {gnutls_pkcs11_type_get_name} (gnutls_pkcs11_obj_type_t @var{type}) 1200@var{type}: Holds the PKCS 11 object type, a @code{gnutls_pkcs11_obj_type_t} . 1201 1202This function will return a human readable description of the 1203PKCS11 object type @code{obj} . It will return "Unknown" for unknown 1204types. 1205 1206@strong{Returns:} human readable string labeling the PKCS11 object type 1207 @code{type} . 1208 1209@strong{Since:} 2.12.0 1210@end deftypefun 1211 1212@subheading gnutls_x509_crt_import_pkcs11 1213@anchor{gnutls_x509_crt_import_pkcs11} 1214@deftypefun {int} {gnutls_x509_crt_import_pkcs11} (gnutls_x509_crt_t @var{crt}, gnutls_pkcs11_obj_t @var{pkcs11_crt}) 1215@var{crt}: A certificate of type @code{gnutls_x509_crt_t} 1216 1217@var{pkcs11_crt}: A PKCS 11 object that contains a certificate 1218 1219This function will import a PKCS 11 certificate to a @code{gnutls_x509_crt_t} 1220structure. 1221 1222@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1223negative error value. 1224 1225@strong{Since:} 2.12.0 1226@end deftypefun 1227 1228@subheading gnutls_x509_crt_list_import_pkcs11 1229@anchor{gnutls_x509_crt_list_import_pkcs11} 1230@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}) 1231@var{certs}: A list of certificates of type @code{gnutls_x509_crt_t} 1232 1233@var{cert_max}: The maximum size of the list 1234 1235@var{objs}: A list of PKCS 11 objects 1236 1237@var{flags}: 0 for now 1238 1239This function will import a PKCS 11 certificate list to a list of 1240@code{gnutls_x509_crt_t} type. These must not be initialized. 1241 1242@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a 1243negative error value. 1244 1245@strong{Since:} 2.12.0 1246@end deftypefun 1247 1248