2792
2898
@strong{Since:} 2.6.0
2793
2899
@end deftypefun
2901
@subheading gnutls_pkcs11_add_provider
2902
@anchor{gnutls_pkcs11_add_provider}
2903
@deftypefun {int} {gnutls_pkcs11_add_provider} (const char * @var{name}, const char * @var{params})
2904
@var{name}: The filename of the module
2906
@var{params}: should be NULL
2908
This function will load and add a PKCS 11 module to the module
2909
list used in gnutls. After this function is called the module will
2910
be used for PKCS 11 operations.
2912
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
2913
negative error value.
2916
@subheading gnutls_pkcs11_copy_secret_key
2917
@anchor{gnutls_pkcs11_copy_secret_key}
2918
@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})
2919
@var{token_url}: A PKCS @code{11} URL specifying a token
2921
@var{key}: The raw key
2923
@var{label}: A name to be used for the stored data
2925
@var{key_usage}: One of GNUTLS_KEY_*
2927
@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_*
2929
This function will copy a raw secret (symmetric) key into a PKCS @code{11}
2930
token specified by a URL. The key can be marked as sensitive or not.
2932
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
2933
negative error value.
2936
@subheading gnutls_pkcs11_copy_x509_crt
2937
@anchor{gnutls_pkcs11_copy_x509_crt}
2938
@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})
2939
@var{token_url}: A PKCS @code{11} URL specifying a token
2941
@var{crt}: A certificate
2943
@var{label}: A name to be used for the stored data
2945
@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_*
2947
This function will copy a certificate into a PKCS @code{11} token specified by
2948
a URL. The certificate can be marked as trusted or not.
2950
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
2951
negative error value.
2954
@subheading gnutls_pkcs11_copy_x509_privkey
2955
@anchor{gnutls_pkcs11_copy_x509_privkey}
2956
@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})
2957
@var{token_url}: A PKCS @code{11} URL specifying a token
2959
@var{key}: A private key
2961
@var{label}: A name to be used for the stored data
2963
@var{key_usage}: One of GNUTLS_KEY_*
2965
@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
2967
This function will copy a private key into a PKCS @code{11} token specified by
2968
a URL. It is highly recommended flags to contain @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE}
2969
unless there is a strong reason not to.
2971
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
2972
negative error value.
2975
@subheading gnutls_pkcs11_deinit
2976
@anchor{gnutls_pkcs11_deinit}
2977
@deftypefun {void} {gnutls_pkcs11_deinit} ( @var{void})
2979
This function will deinitialize the PKCS 11 subsystem in gnutls.
2982
@subheading gnutls_pkcs11_delete_url
2983
@anchor{gnutls_pkcs11_delete_url}
2984
@deftypefun {int} {gnutls_pkcs11_delete_url} (const char * @var{object_url}, unsigned int @var{flags})
2985
@var{object_url}: The URL of the object to delete.
2987
@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
2989
This function will delete objects matching the given URL.
2991
@strong{Returns:} On success, the number of objects deleted is returned, otherwise a
2992
negative error value.
2995
@subheading gnutls_pkcs11_init
2996
@anchor{gnutls_pkcs11_init}
2997
@deftypefun {int} {gnutls_pkcs11_init} (unsigned int @var{flags}, const char * @var{deprecated_config_file})
2998
@var{flags}: @code{GNUTLS_PKCS11_FLAG_MANUAL} or @code{GNUTLS_PKCS11_FLAG_AUTO}
3000
@var{deprecated_config_file}: either NULL or the location of a deprecated
3003
This function will initialize the PKCS 11 subsystem in gnutls. It will
3004
read configuration files if @code{GNUTLS_PKCS11_FLAG_AUTO} is used or allow
3005
you to independently load PKCS 11 modules using @code{gnutls_pkcs11_add_provider()}
3006
if @code{GNUTLS_PKCS11_FLAG_MANUAL} is specified.
3008
Using a custom configfile is deprecated and will not be supported in future
3011
Normally you don't need to call this function since it is being called
3012
by @code{gnutls_global_init()} using the @code{GNUTLS_PKCS11_FLAG_AUTO}. If you need to
3013
call this function, you must call it before @code{gnutls_global_init()}.
3015
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3016
negative error value.
3019
@subheading gnutls_pkcs11_obj_deinit
3020
@anchor{gnutls_pkcs11_obj_deinit}
3021
@deftypefun {void} {gnutls_pkcs11_obj_deinit} (gnutls_pkcs11_obj_t @var{obj})
3022
@var{obj}: The structure to be initialized
3024
This function will deinitialize a certificate structure.
3027
@subheading gnutls_pkcs11_obj_export_url
3028
@anchor{gnutls_pkcs11_obj_export_url}
3029
@deftypefun {int} {gnutls_pkcs11_obj_export_url} (gnutls_pkcs11_obj_t @var{obj}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url})
3030
@var{obj}: Holds the PKCS 11 certificate
3032
@var{detailed}: non zero if a detailed URL is required
3034
@var{url}: will contain an allocated url
3036
This function will export a URL identifying the given certificate.
3038
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3039
negative error value.
3042
@subheading gnutls_pkcs11_obj_export
3043
@anchor{gnutls_pkcs11_obj_export}
3044
@deftypefun {int} {gnutls_pkcs11_obj_export} (gnutls_pkcs11_obj_t @var{obj}, void * @var{output_data}, size_t * @var{output_data_size})
3045
@var{obj}: Holds the object
3047
@var{output_data}: will contain a certificate PEM or DER encoded
3049
@var{output_data_size}: holds the size of output_data (and will be
3050
replaced by the actual size of parameters)
3052
This function will export the pkcs11 object data. It is normal
3053
for PKCS @code{11} data to be inaccesible and in that case @code{GNUTLS_E_INVALID_REQUEST}
3056
If the buffer provided is not long enough to hold the output, then
3057
*output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
3060
If the structure is PEM encoded, it will have a header
3061
of "BEGIN CERTIFICATE".
3063
@strong{Return value:} In case of failure a negative value will be
3064
returned, and 0 on success.
3067
@subheading gnutls_pkcs11_obj_get_info
3068
@anchor{gnutls_pkcs11_obj_get_info}
3069
@deftypefun {int} {gnutls_pkcs11_obj_get_info} (gnutls_pkcs11_obj_t @var{crt}, gnutls_pkcs11_obj_info_t @var{itype}, void * @var{output}, size_t * @var{output_size})
3070
@var{crt}: should contain a @code{gnutls_pkcs11_obj_t} structure
3072
@var{itype}: Denotes the type of information requested
3074
@var{output}: where output will be stored
3076
@var{output_size}: contains the maximum size of the output and will be overwritten with actual
3078
This function will return information about the PKCS 11 certificatesuch
3079
as the label, id as well as token information where the key is stored. When
3080
output is text it returns null terminated string although @code{output_size} contains
3081
the size of the actual data only.
3083
@strong{Returns:} zero on success or a negative value on error.
3086
@subheading gnutls_pkcs11_obj_get_type
3087
@anchor{gnutls_pkcs11_obj_get_type}
3088
@deftypefun {gnutls_pkcs11_obj_type_t} {gnutls_pkcs11_obj_get_type} (gnutls_pkcs11_obj_t @var{obj})
3089
This function will return the type of the certificate being
3090
stored in the structure.
3092
@strong{Returns:} The type of the certificate.
3095
@subheading gnutls_pkcs11_obj_import_url
3096
@anchor{gnutls_pkcs11_obj_import_url}
3097
@deftypefun {int} {gnutls_pkcs11_obj_import_url} (gnutls_pkcs11_obj_t @var{cert}, const char * @var{url}, unsigned int @var{flags})
3098
@var{cert}: The structure to store the parsed certificate
3100
@var{url}: a PKCS 11 url identifying the key
3102
@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
3104
This function will "import" a PKCS 11 URL identifying a certificate
3105
key to the @code{gnutls_pkcs11_obj_t} structure. This does not involve any
3106
parsing (such as X.509 or OpenPGP) since the @code{gnutls_pkcs11_obj_t} is
3107
format agnostic. Only data are transferred.
3109
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3110
negative error value.
3113
@subheading gnutls_pkcs11_obj_init
3114
@anchor{gnutls_pkcs11_obj_init}
3115
@deftypefun {int} {gnutls_pkcs11_obj_init} (gnutls_pkcs11_obj_t * @var{obj})
3116
@var{obj}: The structure to be initialized
3118
This function will initialize a pkcs11 certificate structure.
3120
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3121
negative error value.
3124
@subheading gnutls_pkcs11_obj_list_import_url
3125
@anchor{gnutls_pkcs11_obj_list_import_url}
3126
@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})
3127
@var{p_list}: An uninitialized object list (may be NULL)
3129
@var{n_list}: initially should hold the maximum size of the list. Will contain the actual size.
3131
@var{url}: A PKCS 11 url identifying a set of objects
3133
@var{attrs}: Attributes of type @code{gnutls_pkcs11_obj_attr_t} that can be used to limit output
3135
@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
3137
This function will initialize and set values to an object list
3138
by using all objects identified by a PKCS 11 URL.
3140
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3141
negative error value.
3144
@subheading gnutls_pkcs11_privkey_deinit
3145
@anchor{gnutls_pkcs11_privkey_deinit}
3146
@deftypefun {void} {gnutls_pkcs11_privkey_deinit} (gnutls_pkcs11_privkey_t @var{key})
3147
@var{key}: The structure to be initialized
3149
This function will deinitialize a private key structure.
3152
@subheading gnutls_pkcs11_privkey_export_url
3153
@anchor{gnutls_pkcs11_privkey_export_url}
3154
@deftypefun {int} {gnutls_pkcs11_privkey_export_url} (gnutls_pkcs11_privkey_t @var{key}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url})
3155
@var{key}: Holds the PKCS 11 key
3157
@var{detailed}: non zero if a detailed URL is required
3159
@var{url}: will contain an allocated url
3161
This function will export a URL identifying the given key.
3163
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3164
negative error value.
3167
@subheading gnutls_pkcs11_privkey_get_info
3168
@anchor{gnutls_pkcs11_privkey_get_info}
3169
@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})
3170
@var{pkey}: should contain a @code{gnutls_pkcs11_privkey_t} structure
3172
@var{itype}: Denotes the type of information requested
3174
@var{output}: where output will be stored
3176
@var{output_size}: contains the maximum size of the output and will be overwritten with actual
3178
This function will return information about the PKCS 11 private key such
3179
as the label, id as well as token information where the key is stored. When
3180
output is text it returns null terminated string although @code{output_size} contains
3181
the size of the actual data only.
3183
@strong{Returns:} zero on success or a negative value on error.
3186
@subheading gnutls_pkcs11_privkey_get_pk_algorithm
3187
@anchor{gnutls_pkcs11_privkey_get_pk_algorithm}
3188
@deftypefun {int} {gnutls_pkcs11_privkey_get_pk_algorithm} (gnutls_pkcs11_privkey_t @var{key}, unsigned int * @var{bits})
3189
@var{key}: should contain a @code{gnutls_pkcs11_privkey_t} structure
3191
This function will return the public key algorithm of a private
3194
@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
3195
success, or a negative value on error.
3198
@subheading gnutls_pkcs11_privkey_import_url
3199
@anchor{gnutls_pkcs11_privkey_import_url}
3200
@deftypefun {int} {gnutls_pkcs11_privkey_import_url} (gnutls_pkcs11_privkey_t @var{pkey}, const char * @var{url}, unsigned int @var{flags})
3201
@var{pkey}: The structure to store the parsed key
3203
@var{url}: a PKCS 11 url identifying the key
3205
@var{flags}: sequence of GNUTLS_PKCS_PRIVKEY_*
3207
This function will "import" a PKCS 11 URL identifying a private
3208
key to the @code{gnutls_pkcs11_privkey_t} structure. In reality since
3209
in most cases keys cannot be exported, the private key structure
3210
is being associated with the available operations on the token.
3212
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3213
negative error value.
3216
@subheading gnutls_pkcs11_privkey_init
3217
@anchor{gnutls_pkcs11_privkey_init}
3218
@deftypefun {int} {gnutls_pkcs11_privkey_init} (gnutls_pkcs11_privkey_t * @var{key})
3219
@var{key}: The structure to be initialized
3221
This function will initialize an private key structure.
3223
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3224
negative error value.
3227
@subheading gnutls_pkcs11_set_pin_function
3228
@anchor{gnutls_pkcs11_set_pin_function}
3229
@deftypefun {void} {gnutls_pkcs11_set_pin_function} (gnutls_pkcs11_pin_callback_t @var{fn}, void * @var{userdata})
3230
@var{fn}: The PIN callback
3232
@var{userdata}: data to be supplied to callback
3234
This function will set a callback function to be used when a PIN
3235
is required for PKCS 11 operations.
3237
Callback for PKCS@code{11} PIN entry. The callback provides the PIN code
3238
to unlock the token with label 'token_label', specified by the URL
3241
The PIN code, as a NUL-terminated ASCII string, should be copied
3242
into the 'pin' buffer (of maximum size pin_max), and
3243
return 0 to indicate success. Alternatively, the callback may
3244
return a negative gnutls error code to indicate failure and cancel
3245
PIN entry (in which case, the contents of the 'pin' parameter are ignored).
3247
When a PIN is required, the callback will be invoked repeatedly
3248
(and indefinitely) until either the returned PIN code is correct,
3249
the callback returns failure, or the token refuses login (e.g. when
3250
the token is locked due to too many incorrect PINs!). For the
3251
first such invocation, the 'attempt' counter will have value zero;
3252
it will increase by one for each subsequent attempt.
3254
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3255
negative error value.
3258
@subheading gnutls_pkcs11_set_token_function
3259
@anchor{gnutls_pkcs11_set_token_function}
3260
@deftypefun {void} {gnutls_pkcs11_set_token_function} (gnutls_pkcs11_token_callback_t @var{fn}, void * @var{userdata})
3261
@var{fn}: The token callback
3263
@var{userdata}: data to be supplied to callback
3265
This function will set a callback function to be used when a token
3266
needs to be inserted to continue PKCS 11 operations.
3268
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3269
negative error value.
3272
@subheading gnutls_pkcs11_token_get_flags
3273
@anchor{gnutls_pkcs11_token_get_flags}
3274
@deftypefun {int} {gnutls_pkcs11_token_get_flags} (const char * @var{url}, unsigned int * @var{flags})
3275
@var{url}: should contain a PKCS 11 URL
3277
@var{flags}: The output flags (GNUTLS_PKCS11_TOKEN_*)
3279
This function will return information about the PKCS 11 token flags.
3281
@strong{Returns:} zero on success or a negative value on error.
3284
@subheading gnutls_pkcs11_token_get_info
3285
@anchor{gnutls_pkcs11_token_get_info}
3286
@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})
3287
@var{url}: should contain a PKCS 11 URL
3289
@var{ttype}: Denotes the type of information requested
3291
@var{output}: where output will be stored
3293
@var{output_size}: contains the maximum size of the output and will be overwritten with actual
3295
This function will return information about the PKCS 11 token such
3296
as the label, id as well as token information where the key is stored.
3298
@strong{Returns:} zero on success or a negative value on error.
3301
@subheading gnutls_pkcs11_token_get_mechanism
3302
@anchor{gnutls_pkcs11_token_get_mechanism}
3303
@deftypefun {int} {gnutls_pkcs11_token_get_mechanism} (const char * @var{url}, int @var{idx}, unsigned long * @var{mechanism})
3304
@var{url}: should contain a PKCS 11 URL
3306
@var{idx}: The index of the mechanism
3308
@var{mechanism}: The PKCS @code{11} mechanism ID
3310
This function will return the names of the supported mechanisms
3311
by the token. It should be called with an increasing index until
3312
it return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE.
3314
@strong{Returns:} zero on success or a negative value on error.
3317
@subheading gnutls_pkcs11_token_get_url
3318
@anchor{gnutls_pkcs11_token_get_url}
3319
@deftypefun {int} {gnutls_pkcs11_token_get_url} (unsigned int @var{seq}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url})
3320
@var{seq}: sequence number starting from 0
3322
@var{detailed}: non zero if a detailed URL is required
3324
@var{url}: will contain an allocated url
3326
This function will return the URL for each token available
3327
in system. The url has to be released using @code{gnutls_free()}
3329
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE}
3330
if the sequence number exceeds the available tokens, otherwise a negative error value.
3333
@subheading gnutls_pkcs11_token_init
3334
@anchor{gnutls_pkcs11_token_init}
3335
@deftypefun {int} {gnutls_pkcs11_token_init} (const char * @var{token_url}, const char * @var{so_pin}, const char * @var{label})
3336
@var{token_url}: A PKCS @code{11} URL specifying a token
3338
@var{so_pin}: Security Officer's PIN
3340
@var{label}: A name to be used for the token
3342
This function will initialize (format) a token. If the token is
3343
at a factory defaults state the security officer's PIN given will be
3344
set to be the default. Otherwise it should match the officer's PIN.
3346
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3347
negative error value.
3350
@subheading gnutls_pkcs11_token_set_pin
3351
@anchor{gnutls_pkcs11_token_set_pin}
3352
@deftypefun {int} {gnutls_pkcs11_token_set_pin} (const char * @var{token_url}, const char * @var{oldpin}, const char * @var{newpin}, unsigned int @var{flags})
3353
@var{token_url}: A PKCS @code{11} URL specifying a token
3355
@var{oldpin}: old user's PIN
3357
@var{newpin}: new user's PIN
3359
@var{flags}: one of gnutls_pkcs11_pin_flag_t
3361
This function will modify or set a user's PIN for the given token.
3362
If it is called to set a user pin for first time the oldpin must
3365
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3366
negative error value.
2795
3369
@subheading gnutls_prf_raw
2796
3370
@anchor{gnutls_prf_raw}
2797
3371
@deftypefun {int} {gnutls_prf_raw} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{seed_size}, const char * @var{seed}, size_t @var{outsize}, char * @var{out})
3014
3541
@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code.
3015
3542
@end deftypefun
3544
@subheading gnutls_privkey_decrypt_data
3545
@anchor{gnutls_privkey_decrypt_data}
3546
@deftypefun {int} {gnutls_privkey_decrypt_data} (gnutls_privkey_t @var{key}, unsigned int @var{flags}, const gnutls_datum_t * @var{ciphertext}, gnutls_datum_t * @var{plaintext})
3547
@var{key}: Holds the key
3549
@var{flags}: zero for now
3551
@var{ciphertext}: holds the data to be decrypted
3553
@var{plaintext}: will contain the decrypted data, allocated with @code{gnutls_malloc()}
3555
This function will decrypt the given data using the algorithm
3556
supported by the private key.
3558
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3559
negative error value.
3562
@subheading gnutls_privkey_deinit
3563
@anchor{gnutls_privkey_deinit}
3564
@deftypefun {void} {gnutls_privkey_deinit} (gnutls_privkey_t @var{key})
3565
@var{key}: The structure to be deinitialized
3567
This function will deinitialize a private key structure.
3570
@subheading gnutls_privkey_get_pk_algorithm
3571
@anchor{gnutls_privkey_get_pk_algorithm}
3572
@deftypefun {int} {gnutls_privkey_get_pk_algorithm} (gnutls_privkey_t @var{key}, unsigned int * @var{bits})
3573
@var{key}: should contain a @code{gnutls_privkey_t} structure
3575
@var{bits}: If set will return the number of bits of the parameters (may be NULL)
3577
This function will return the public key algorithm of a private
3578
key and if possible will return a number of bits that indicates
3579
the security parameter of the key.
3581
@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
3582
success, or a negative value on error.
3585
@subheading gnutls_privkey_get_type
3586
@anchor{gnutls_privkey_get_type}
3587
@deftypefun {gnutls_privkey_type_t} {gnutls_privkey_get_type} (gnutls_privkey_t @var{key})
3588
@var{key}: should contain a @code{gnutls_privkey_t} structure
3590
This function will return the type of the private key. This is
3591
actually the type of the subsystem used to set this private key.
3593
@strong{Returns:} a member of the @code{gnutls_privkey_type_t} enumeration on
3594
success, or a negative value on error.
3597
@subheading gnutls_privkey_import_openpgp
3598
@anchor{gnutls_privkey_import_openpgp}
3599
@deftypefun {int} {gnutls_privkey_import_openpgp} (gnutls_privkey_t @var{pkey}, gnutls_openpgp_privkey_t @var{key}, unsigned int @var{flags})
3600
@var{pkey}: The private key
3602
@var{key}: The private key to be imported
3604
@var{flags}: should be zero
3606
This function will import the given private key to the abstract
3607
@code{gnutls_privkey_t} structure.
3609
The @code{gnutls_openpgp_privkey_t} object must not be deallocated
3610
during the lifetime of this structure. The subkey set as
3611
preferred will be used, or the master key otherwise.
3613
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3614
negative error value.
3617
@subheading gnutls_privkey_import_pkcs11
3618
@anchor{gnutls_privkey_import_pkcs11}
3619
@deftypefun {int} {gnutls_privkey_import_pkcs11} (gnutls_privkey_t @var{pkey}, gnutls_pkcs11_privkey_t @var{key}, unsigned int @var{flags})
3620
@var{pkey}: The private key
3622
@var{key}: The private key to be imported
3624
@var{flags}: should be zero
3626
This function will import the given private key to the abstract
3627
@code{gnutls_privkey_t} structure.
3629
The @code{gnutls_pkcs11_privkey_t} object must not be deallocated
3630
during the lifetime of this structure.
3632
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3633
negative error value.
3636
@subheading gnutls_privkey_import_x509
3637
@anchor{gnutls_privkey_import_x509}
3638
@deftypefun {int} {gnutls_privkey_import_x509} (gnutls_privkey_t @var{pkey}, gnutls_x509_privkey_t @var{key}, unsigned int @var{flags})
3639
@var{pkey}: The private key
3641
@var{key}: The private key to be imported
3643
@var{flags}: should be zero
3645
This function will import the given private key to the abstract
3646
@code{gnutls_privkey_t} structure.
3648
The @code{gnutls_x509_privkey_t} object must not be deallocated
3649
during the lifetime of this structure.
3651
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3652
negative error value.
3655
@subheading gnutls_privkey_init
3656
@anchor{gnutls_privkey_init}
3657
@deftypefun {int} {gnutls_privkey_init} (gnutls_privkey_t * @var{key})
3658
@var{key}: The structure to be initialized
3660
This function will initialize an private key structure.
3662
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3663
negative error value.
3666
@subheading gnutls_privkey_sign_data
3667
@anchor{gnutls_privkey_sign_data}
3668
@deftypefun {int} {gnutls_privkey_sign_data} (gnutls_privkey_t @var{signer}, gnutls_digest_algorithm_t @var{hash}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, gnutls_datum_t * @var{signature})
3669
@var{signer}: Holds the key
3671
@var{hash}: should be a digest algorithm
3673
@var{flags}: should be 0 for now
3675
@var{data}: holds the data to be signed
3677
@var{signature}: will contain the signature allocate with @code{gnutls_malloc()}
3679
This function will sign the given data using a signature algorithm
3680
supported by the private key. Signature algorithms are always used
3681
together with a hash functions. Different hash functions may be
3682
used for the RSA algorithm, but only SHA-1 for the DSA keys.
3684
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3685
negative error value.
3687
@strong{Since:} 2.12.0
3690
@subheading gnutls_privkey_sign_hash
3691
@anchor{gnutls_privkey_sign_hash}
3692
@deftypefun {int} {gnutls_privkey_sign_hash} (gnutls_privkey_t @var{signer}, gnutls_digest_algorithm_t @var{hash_algo}, unsigned int @var{flags}, const gnutls_datum_t * @var{hash_data}, gnutls_datum_t * @var{signature})
3693
@var{signer}: Holds the signer's key
3695
@var{hash_algo}: The hash algorithm used
3697
@var{flags}: zero for now
3699
@var{hash_data}: holds the data to be signed
3701
@var{signature}: will contain newly allocated signature
3703
This function will sign the given hashed data using a signature algorithm
3704
supported by the private key. Signature algorithms are always used
3705
together with a hash functions. Different hash functions may be
3706
used for the RSA algorithm, but only SHA-XXX for the DSA keys.
3708
Use @code{gnutls_x509_crt_get_preferred_hash_algorithm()} to determine
3711
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
3712
negative error value.
3714
@strong{Since:} 2.12.0
3017
3717
@subheading gnutls_protocol_get_id
3018
3718
@anchor{gnutls_protocol_get_id}
3019
3719
@deftypefun {gnutls_protocol_t} {gnutls_protocol_get_id} (const char * @var{name})
3286
3990
should return zero on success.
3287
3991
@end deftypefun
3993
@subheading gnutls_pubkey_deinit
3994
@anchor{gnutls_pubkey_deinit}
3995
@deftypefun {void} {gnutls_pubkey_deinit} (gnutls_pubkey_t @var{key})
3996
@var{key}: The structure to be deinitialized
3998
This function will deinitialize a public key structure.
4001
@subheading gnutls_pubkey_export
4002
@anchor{gnutls_pubkey_export}
4003
@deftypefun {int} {gnutls_pubkey_export} (gnutls_pubkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size})
4004
@var{key}: Holds the certificate
4006
@var{format}: the format of output params. One of PEM or DER.
4008
@var{output_data}: will contain a certificate PEM or DER encoded
4010
@var{output_data_size}: holds the size of output_data (and will be
4011
replaced by the actual size of parameters)
4013
This function will export the certificate to DER or PEM format.
4015
If the buffer provided is not long enough to hold the output, then
4016
*output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
4019
If the structure is PEM encoded, it will have a header
4020
of "BEGIN CERTIFICATE".
4022
@strong{Return value:} In case of failure a negative value will be
4023
returned, and 0 on success.
4026
@subheading gnutls_pubkey_get_key_id
4027
@anchor{gnutls_pubkey_get_key_id}
4028
@deftypefun {int} {gnutls_pubkey_get_key_id} (gnutls_pubkey_t @var{key}, unsigned int @var{flags}, unsigned char * @var{output_data}, size_t * @var{output_data_size})
4029
@var{key}: Holds the public key
4031
@var{flags}: should be 0 for now
4033
@var{output_data}: will contain the key ID
4035
@var{output_data_size}: holds the size of output_data (and will be
4036
replaced by the actual size of parameters)
4038
This function will return a unique ID the depends on the public
4039
key parameters. This ID can be used in checking whether a
4040
certificate corresponds to the given public key.
4042
If the buffer provided is not long enough to hold the output, then
4043
*output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
4044
be returned. The output will normally be a SHA-1 hash output,
4047
@strong{Return value:} In case of failure a negative value will be
4048
returned, and 0 on success.
4051
@subheading gnutls_pubkey_get_key_usage
4052
@anchor{gnutls_pubkey_get_key_usage}
4053
@deftypefun {int} {gnutls_pubkey_get_key_usage} (gnutls_pubkey_t @var{key}, unsigned int * @var{usage})
4054
@var{key}: should contain a @code{gnutls_pubkey_t} structure
4056
@var{usage}: If set will return the number of bits of the parameters (may be NULL)
4058
This function will return the key usage of the public key.
4060
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4061
negative error value.
4064
@subheading gnutls_pubkey_get_pk_algorithm
4065
@anchor{gnutls_pubkey_get_pk_algorithm}
4066
@deftypefun {int} {gnutls_pubkey_get_pk_algorithm} (gnutls_pubkey_t @var{key}, unsigned int * @var{bits})
4067
@var{key}: should contain a @code{gnutls_pubkey_t} structure
4069
@var{bits}: If set will return the number of bits of the parameters (may be NULL)
4071
This function will return the public key algorithm of a public
4072
key and if possible will return a number of bits that indicates
4073
the security parameter of the key.
4075
@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
4076
success, or a negative value on error.
4079
@subheading gnutls_pubkey_get_pk_dsa_raw
4080
@anchor{gnutls_pubkey_get_pk_dsa_raw}
4081
@deftypefun {int} {gnutls_pubkey_get_pk_dsa_raw} (gnutls_pubkey_t @var{key}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y})
4082
@var{key}: Holds the public key
4084
@var{p}: will hold the p
4086
@var{q}: will hold the q
4088
@var{g}: will hold the g
4090
@var{y}: will hold the y
4092
This function will export the DSA public key's parameters found in
4093
the given certificate. The new parameters will be allocated using
4094
@code{gnutls_malloc()} and will be stored in the appropriate datum.
4096
@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
4099
@subheading gnutls_pubkey_get_pk_rsa_raw
4100
@anchor{gnutls_pubkey_get_pk_rsa_raw}
4101
@deftypefun {int} {gnutls_pubkey_get_pk_rsa_raw} (gnutls_pubkey_t @var{key}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e})
4102
@var{key}: Holds the certificate
4104
@var{m}: will hold the modulus
4106
@var{e}: will hold the public exponent
4108
This function will export the RSA public key's parameters found in
4109
the given structure. The new parameters will be allocated using
4110
@code{gnutls_malloc()} and will be stored in the appropriate datum.
4112
@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise an error.
4115
@subheading gnutls_pubkey_get_preferred_hash_algorithm
4116
@anchor{gnutls_pubkey_get_preferred_hash_algorithm}
4117
@deftypefun {int} {gnutls_pubkey_get_preferred_hash_algorithm} (gnutls_pubkey_t @var{key}, gnutls_digest_algorithm_t * @var{hash}, unsigned int * @var{mand})
4118
@var{key}: Holds the certificate
4120
@var{hash}: The result of the call with the hash algorithm used for signature
4122
@var{mand}: If non zero it means that the algorithm MUST use this hash. May be NULL.
4124
This function will read the certifcate and return the appropriate digest
4125
algorithm to use for signing with this certificate. Some certificates (i.e.
4126
DSA might not be able to sign without the preferred algorithm).
4128
@strong{Returns:} the 0 if the hash algorithm is found. A negative value is
4131
@strong{Since:} 2.11.0
4134
@subheading gnutls_pubkey_get_verify_algorithm
4135
@anchor{gnutls_pubkey_get_verify_algorithm}
4136
@deftypefun {int} {gnutls_pubkey_get_verify_algorithm} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{signature}, gnutls_digest_algorithm_t * @var{hash})
4137
@var{key}: Holds the certificate
4139
@var{signature}: contains the signature
4141
@var{hash}: The result of the call with the hash algorithm used for signature
4143
This function will read the certifcate and the signed data to
4144
determine the hash algorithm used to generate the signature.
4146
@strong{Returns:} the 0 if the hash algorithm is found. A negative value is
4150
@subheading gnutls_pubkey_import_dsa_raw
4151
@anchor{gnutls_pubkey_import_dsa_raw}
4152
@deftypefun {int} {gnutls_pubkey_import_dsa_raw} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{p}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{g}, const gnutls_datum_t * @var{y})
4153
@var{key}: The structure to store the parsed key
4155
@var{p}: holds the p
4157
@var{q}: holds the q
4159
@var{g}: holds the g
4161
@var{y}: holds the y
4163
This function will convert the given DSA raw parameters to the
4164
native @code{gnutls_pubkey_t} format. The output will be stored
4167
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4168
negative error value.
4171
@subheading gnutls_pubkey_import_openpgp
4172
@anchor{gnutls_pubkey_import_openpgp}
4173
@deftypefun {int} {gnutls_pubkey_import_openpgp} (gnutls_pubkey_t @var{key}, gnutls_openpgp_crt_t @var{crt}, unsigned int @var{flags})
4174
@var{key}: The public key
4176
@var{crt}: The certificate to be imported
4178
@var{flags}: should be zero
4180
This function will import the given public key to the abstract
4181
@code{gnutls_pubkey_t} structure. The subkey set as preferred will be
4182
imported or the master key otherwise.
4184
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4185
negative error value.
4188
@subheading gnutls_pubkey_import_pkcs11_url
4189
@anchor{gnutls_pubkey_import_pkcs11_url}
4190
@deftypefun {int} {gnutls_pubkey_import_pkcs11_url} (gnutls_pubkey_t @var{key}, const char * @var{url}, unsigned int @var{flags})
4191
@var{key}: A key of type @code{gnutls_pubkey_t}
4193
@var{url}: A PKCS 11 url
4195
@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
4197
This function will import a PKCS 11 certificate to a @code{gnutls_pubkey_t}
4200
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4201
negative error value.
4204
@subheading gnutls_pubkey_import_pkcs11
4205
@anchor{gnutls_pubkey_import_pkcs11}
4206
@deftypefun {int} {gnutls_pubkey_import_pkcs11} (gnutls_pubkey_t @var{key}, gnutls_pkcs11_obj_t @var{obj}, unsigned int @var{flags})
4207
@var{key}: The public key
4209
@var{obj}: The parameters to be imported
4211
@var{flags}: should be zero
4213
This function will import the given public key to the abstract
4214
@code{gnutls_pubkey_t} structure.
4216
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4217
negative error value.
4220
@subheading gnutls_pubkey_import_privkey
4221
@anchor{gnutls_pubkey_import_privkey}
4222
@deftypefun {int} {gnutls_pubkey_import_privkey} (gnutls_pubkey_t @var{key}, gnutls_privkey_t @var{pkey}, unsigned int @var{usage}, unsigned int @var{flags})
4223
@var{key}: The public key
4225
@var{pkey}: The private key
4227
@var{usage}: GNUTLS_KEY_* key usage flags.
4229
@var{flags}: should be zero
4231
This function will import the given public key to the abstract
4232
@code{gnutls_pubkey_t} structure.
4234
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4235
negative error value.
4237
@strong{Since:} 2.12.0
4240
@subheading gnutls_pubkey_import_rsa_raw
4241
@anchor{gnutls_pubkey_import_rsa_raw}
4242
@deftypefun {int} {gnutls_pubkey_import_rsa_raw} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{m}, const gnutls_datum_t * @var{e})
4243
@var{key}: Is a structure will hold the parameters
4245
@var{m}: holds the modulus
4247
@var{e}: holds the public exponent
4249
This function will replace the parameters in the given structure.
4250
The new parameters should be stored in the appropriate
4253
@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an negative error code.
4256
@subheading gnutls_pubkey_import_x509
4257
@anchor{gnutls_pubkey_import_x509}
4258
@deftypefun {int} {gnutls_pubkey_import_x509} (gnutls_pubkey_t @var{key}, gnutls_x509_crt_t @var{crt}, unsigned int @var{flags})
4259
@var{key}: The public key
4261
@var{crt}: The certificate to be imported
4263
@var{flags}: should be zero
4265
This function will import the given public key to the abstract
4266
@code{gnutls_pubkey_t} structure.
4268
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4269
negative error value.
4272
@subheading gnutls_pubkey_import
4273
@anchor{gnutls_pubkey_import}
4274
@deftypefun {int} {gnutls_pubkey_import} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format})
4275
@var{key}: The structure to store the parsed public key.
4277
@var{data}: The DER or PEM encoded certificate.
4279
@var{format}: One of DER or PEM
4281
This function will convert the given DER or PEM encoded Public key
4282
to the native gnutls_pubkey_t format.The output will be stored * in @ key.
4283
If the Certificate is PEM encoded it should have a header of "PUBLIC KEY".
4285
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4286
negative error value.
4289
@subheading gnutls_pubkey_init
4290
@anchor{gnutls_pubkey_init}
4291
@deftypefun {int} {gnutls_pubkey_init} (gnutls_pubkey_t * @var{key})
4292
@var{key}: The structure to be initialized
4294
This function will initialize an public key structure.
4296
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4297
negative error value.
4300
@subheading gnutls_pubkey_set_key_usage
4301
@anchor{gnutls_pubkey_set_key_usage}
4302
@deftypefun {int} {gnutls_pubkey_set_key_usage} (gnutls_pubkey_t @var{key}, unsigned int @var{usage})
4303
@var{key}: a certificate of type @code{gnutls_x509_crt_t}
4305
@var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
4307
This function will set the key usage flags of the public key. This
4308
is only useful if the key is to be exported to a certificate or
4309
certificate request.
4311
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
4312
negative error value.
4315
@subheading gnutls_pubkey_verify_data
4316
@anchor{gnutls_pubkey_verify_data}
4317
@deftypefun {int} {gnutls_pubkey_verify_data} (gnutls_pubkey_t @var{pubkey}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, const gnutls_datum_t * @var{signature})
4318
@var{pubkey}: Holds the public key
4320
@var{flags}: should be 0 for now
4322
@var{data}: holds the data to be signed
4324
@var{signature}: contains the signature
4326
This function will verify the given signed data, using the
4327
parameters from the certificate.
4329
@strong{Returns:} In case of a verification failure
4330
@code{GNUTLS_E_PK_SIG_VERIFY_FAILED} is returned, and a positive code
4333
@strong{Since:} 2.12.0
4336
@subheading gnutls_pubkey_verify_hash
4337
@anchor{gnutls_pubkey_verify_hash}
4338
@deftypefun {int} {gnutls_pubkey_verify_hash} (gnutls_pubkey_t @var{key}, unsigned int @var{flags}, const gnutls_datum_t * @var{hash}, const gnutls_datum_t * @var{signature})
4339
@var{key}: Holds the certificate
4341
@var{flags}: should be 0 for now
4343
@var{hash}: holds the hash digest to be verified
4345
@var{signature}: contains the signature
4347
This function will verify the given signed digest, using the
4348
parameters from the certificate.
4350
@strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
4351
is returned, and a positive code on success.
3289
4354
@subheading gnutls_record_check_pending
3290
4355
@anchor{gnutls_record_check_pending}
3291
4356
@deftypefun {size_t} {gnutls_record_check_pending} (gnutls_session_t @var{session})
4572
5639
PUSH_FUNC is of the form,
4573
5640
ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t);
5643
@subheading gnutls_transport_set_vec_push_function
5644
@anchor{gnutls_transport_set_vec_push_function}
5645
@deftypefun {void} {gnutls_transport_set_vec_push_function} (gnutls_session_t @var{session}, gnutls_vec_push_func @var{vec_func})
5646
@var{session}: is a @code{gnutls_session_t} structure.
5648
@var{vec_func}: a callback function similar to @code{writev()}
5650
This is the function where you set a push function for gnutls to
5651
use in order to send data. If you are going to use berkeley style
5652
sockets, you do not need to use this function since the default
5653
(send(2)) will probably be ok. Otherwise you should specify this
5654
function for gnutls to be able to send data.
5656
PUSH_FUNC is of the form,
5657
ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t);
5660
@subheading gnutls_x509_crq_set_pubkey
5661
@anchor{gnutls_x509_crq_set_pubkey}
5662
@deftypefun {int} {gnutls_x509_crq_set_pubkey} (gnutls_x509_crq_t @var{crq}, gnutls_pubkey_t @var{key})
5663
@var{crq}: should contain a @code{gnutls_x509_crq_t} structure
5665
@var{key}: holds a public key
5667
This function will set the public parameters from the given public
5670
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
5671
negative error value.
5674
@subheading gnutls_x509_crt_import_pkcs11_url
5675
@anchor{gnutls_x509_crt_import_pkcs11_url}
5676
@deftypefun {int} {gnutls_x509_crt_import_pkcs11_url} (gnutls_x509_crt_t @var{crt}, const char * @var{url}, unsigned int @var{flags})
5677
@var{crt}: A certificate of type @code{gnutls_x509_crt_t}
5679
@var{url}: A PKCS 11 url
5681
@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
5683
This function will import a PKCS 11 certificate directly from a token
5684
without involving the @code{gnutls_pkcs11_obj_t} structure. This function will
5685
fail if the certificate stored is not of X.509 type.
5687
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
5688
negative error value.
5691
@subheading gnutls_x509_crt_import_pkcs11
5692
@anchor{gnutls_x509_crt_import_pkcs11}
5693
@deftypefun {int} {gnutls_x509_crt_import_pkcs11} (gnutls_x509_crt_t @var{crt}, gnutls_pkcs11_obj_t @var{pkcs11_crt})
5694
@var{crt}: A certificate of type @code{gnutls_x509_crt_t}
5696
@var{pkcs11_crt}: A PKCS 11 object that contains a certificate
5698
This function will import a PKCS 11 certificate to a @code{gnutls_x509_crt_t}
5701
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
5702
negative error value.
5705
@subheading gnutls_x509_crt_list_import_pkcs11
5706
@anchor{gnutls_x509_crt_list_import_pkcs11}
5707
@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})
5708
@var{certs}: A list of certificates of type @code{gnutls_x509_crt_t}
5710
@var{cert_max}: The maximum size of the list
5712
@var{objs}: A list of PKCS 11 objects
5714
@var{flags}: 0 for now
5716
This function will import a PKCS 11 certificate list to a list of
5717
@code{gnutls_x509_crt_t} structure. These must not be initialized.
5719
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
5720
negative error value.
5723
@subheading gnutls_x509_crt_set_pubkey
5724
@anchor{gnutls_x509_crt_set_pubkey}
5725
@deftypefun {int} {gnutls_x509_crt_set_pubkey} (gnutls_x509_crt_t @var{crt}, gnutls_pubkey_t @var{key})
5726
@var{crt}: should contain a @code{gnutls_x509_crt_t} structure
5728
@var{key}: holds a public key
5730
This function will set the public parameters from the given public
5733
@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} is returned, otherwise a
5734
negative error value.
4574
5735
@end deftypefun
b'\\ No newline at end of file'
added
removed
doc/gnutls-api.texi
