2 @subheading gnutls_certificate_set_key
3 @anchor{gnutls_certificate_set_key}
4 @deftypefun {int} {gnutls_certificate_set_key} (gnutls_certificate_credentials_t @var{res}, const char** @var{names}, int @var{names_size}, gnutls_pcert_st * @var{pcert_list}, int @var{pcert_list_size}, gnutls_privkey_t @var{key})
5 @var{res}: is a @code{gnutls_certificate_credentials_t} structure.
7 @var{names}: is an array of DNS name of the certificate (NULL if none)
9 @var{names_size}: holds the size of the names list
11 @var{pcert_list}: contains a certificate list (path) for the specified private key
13 @var{pcert_list_size}: holds the size of the certificate list
15 @var{key}: is a gnutls_x509_privkey_t key
17 This function sets a certificate/private key pair in the
18 gnutls_certificate_credentials_t structure. This function may be
19 called more than once, in case multiple keys/certificates exist for
20 the server. For clients that wants to send more than its own end
21 entity certificate (e.g., also an intermediate CA cert) then put
22 the certificate chain in @code{pcert_list} . The @code{pcert_list} and @code{key} will
23 become part of the credentials structure and must not
24 be deallocated. They will be automatically deallocated when
25 @code{res} is deinitialized.
27 @strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success, or a negative error code.
32 @subheading gnutls_certificate_set_retrieve_function2
33 @anchor{gnutls_certificate_set_retrieve_function2}
34 @deftypefun {void} {gnutls_certificate_set_retrieve_function2} (gnutls_certificate_credentials_t @var{cred}, gnutls_certificate_retrieve_function2 * @var{func})
35 @var{cred}: is a @code{gnutls_certificate_credentials_t} structure.
37 @var{func}: is the callback function
39 This function sets a callback to be called in order to retrieve the
40 certificate to be used in the handshake.
42 The callback's function prototype is:
43 int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs,
44 const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_pcert_st** pcert,
45 unsigned int *pcert_length, gnutls_privkey_t * pkey);
47 @code{req_ca_cert} is only used in X.509 certificates.
48 Contains a list with the CA names that the server considers trusted.
49 Normally we should send a certificate that is signed
50 by one of these CAs. These names are DER encoded. To get a more
51 meaningful value use the function @code{gnutls_x509_rdn_get()} .
53 @code{pk_algos} contains a list with server's acceptable signature algorithms.
54 The certificate returned should support the server's given algorithms.
56 @code{pcert} should contain a single certificate and public or a list of them.
58 @code{pcert_length} is the size of the previous list.
60 @code{pkey} is the private key.
62 If the callback function is provided then gnutls will call it, in the
63 handshake, after the certificate request message has been received.
65 In server side pk_algos and req_ca_dn are NULL.
67 The callback function should set the certificate list to be sent,
68 and return 0 on success. If no certificate was selected then the
69 number of certificates should be set to zero. The value (-1)
70 indicates error and the handshake will be terminated.
75 @subheading gnutls_pcert_deinit
76 @anchor{gnutls_pcert_deinit}
77 @deftypefun {void} {gnutls_pcert_deinit} (gnutls_pcert_st * @var{pcert})
78 @var{pcert}: The structure to be deinitialized
80 This function will deinitialize a pcert structure.
85 @subheading gnutls_pcert_import_openpgp
86 @anchor{gnutls_pcert_import_openpgp}
87 @deftypefun {int} {gnutls_pcert_import_openpgp} (gnutls_pcert_st* @var{pcert}, gnutls_openpgp_crt_t @var{crt}, unsigned int @var{flags})
88 @var{pcert}: The pcert structure
90 @var{crt}: The raw certificate to be imported
92 @var{flags}: zero for now
94 This convenience function will import the given certificate to a
95 @code{gnutls_pcert_st} structure. The structure must be deinitialized
96 afterwards using @code{gnutls_pcert_deinit()} ;
98 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
104 @subheading gnutls_pcert_import_openpgp_raw
105 @anchor{gnutls_pcert_import_openpgp_raw}
106 @deftypefun {int} {gnutls_pcert_import_openpgp_raw} (gnutls_pcert_st * @var{pcert}, const gnutls_datum_t* @var{cert}, gnutls_openpgp_crt_fmt_t @var{format}, gnutls_openpgp_keyid_t @var{keyid}, unsigned int @var{flags})
107 @var{pcert}: The pcert structure
109 @var{cert}: The raw certificate to be imported
111 @var{format}: The format of the certificate
113 @var{keyid}: The key ID to use (NULL for the master key)
115 @var{flags}: zero for now
117 This convenience function will import the given certificate to a
118 @code{gnutls_pcert_st} structure. The structure must be deinitialized
119 afterwards using @code{gnutls_pcert_deinit()} ;
121 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
122 negative error value.
127 @subheading gnutls_pcert_import_x509
128 @anchor{gnutls_pcert_import_x509}
129 @deftypefun {int} {gnutls_pcert_import_x509} (gnutls_pcert_st* @var{pcert}, gnutls_x509_crt_t @var{crt}, unsigned int @var{flags})
130 @var{pcert}: The pcert structure
132 @var{crt}: The raw certificate to be imported
134 @var{flags}: zero for now
136 This convenience function will import the given certificate to a
137 @code{gnutls_pcert_st} structure. The structure must be deinitialized
138 afterwards using @code{gnutls_pcert_deinit()} ;
140 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
141 negative error value.
146 @subheading gnutls_pcert_import_x509_raw
147 @anchor{gnutls_pcert_import_x509_raw}
148 @deftypefun {int} {gnutls_pcert_import_x509_raw} (gnutls_pcert_st * @var{pcert}, const gnutls_datum_t* @var{cert}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags})
149 @var{pcert}: The pcert structure
151 @var{cert}: The raw certificate to be imported
153 @var{format}: The format of the certificate
155 @var{flags}: zero for now
157 This convenience function will import the given certificate to a
158 @code{gnutls_pcert_st} structure. The structure must be deinitialized
159 afterwards using @code{gnutls_pcert_deinit()} ;
161 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
162 negative error value.
167 @subheading gnutls_pcert_list_import_x509_raw
168 @anchor{gnutls_pcert_list_import_x509_raw}
169 @deftypefun {int} {gnutls_pcert_list_import_x509_raw} (gnutls_pcert_st * @var{pcerts}, unsigned int * @var{pcert_max}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags})
170 @var{pcerts}: The structures to store the parsed certificate. Must not be initialized.
172 @var{pcert_max}: Initially must hold the maximum number of certs. It will be updated with the number of certs available.
174 @var{data}: The certificates.
176 @var{format}: One of DER or PEM.
178 @var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
180 This function will convert the given PEM encoded certificate list
181 to the native gnutls_x509_crt_t format. The output will be stored
182 in @code{certs} . They will be automatically initialized.
184 If the Certificate is PEM encoded it should have a header of "X509
185 CERTIFICATE", or "CERTIFICATE".
187 @strong{Returns:} the number of certificates read or a negative error value.
192 @subheading gnutls_privkey_decrypt_data
193 @anchor{gnutls_privkey_decrypt_data}
194 @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})
195 @var{key}: Holds the key
197 @var{flags}: zero for now
199 @var{ciphertext}: holds the data to be decrypted
201 @var{plaintext}: will contain the decrypted data, allocated with @code{gnutls_malloc()}
203 This function will decrypt the given data using the algorithm
204 supported by the private key.
206 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
207 negative error value.
209 @strong{Since:} 2.12.0
212 @subheading gnutls_privkey_deinit
213 @anchor{gnutls_privkey_deinit}
214 @deftypefun {void} {gnutls_privkey_deinit} (gnutls_privkey_t @var{key})
215 @var{key}: The structure to be deinitialized
217 This function will deinitialize a private key structure.
219 @strong{Since:} 2.12.0
222 @subheading gnutls_privkey_get_pk_algorithm
223 @anchor{gnutls_privkey_get_pk_algorithm}
224 @deftypefun {int} {gnutls_privkey_get_pk_algorithm} (gnutls_privkey_t @var{key}, unsigned int * @var{bits})
225 @var{key}: should contain a @code{gnutls_privkey_t} structure
227 @var{bits}: If set will return the number of bits of the parameters (may be NULL)
229 This function will return the public key algorithm of a private
230 key and if possible will return a number of bits that indicates
231 the security parameter of the key.
233 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
234 success, or a negative error code on error.
236 @strong{Since:} 2.12.0
239 @subheading gnutls_privkey_get_type
240 @anchor{gnutls_privkey_get_type}
241 @deftypefun {gnutls_privkey_type_t} {gnutls_privkey_get_type} (gnutls_privkey_t @var{key})
242 @var{key}: should contain a @code{gnutls_privkey_t} structure
244 This function will return the type of the private key. This is
245 actually the type of the subsystem used to set this private key.
247 @strong{Returns:} a member of the @code{gnutls_privkey_type_t} enumeration on
248 success, or a negative error code on error.
250 @strong{Since:} 2.12.0
253 @subheading gnutls_privkey_import_ext
254 @anchor{gnutls_privkey_import_ext}
255 @deftypefun {int} {gnutls_privkey_import_ext} (gnutls_privkey_t @var{pkey}, gnutls_pk_algorithm_t @var{pk}, void* @var{userdata}, gnutls_privkey_sign_func @var{sign_func}, gnutls_privkey_decrypt_func @var{decrypt_func}, unsigned int @var{flags})
256 @var{pkey}: The private key
258 @var{pk}: The public key algorithm
260 @var{userdata}: private data to be provided to the callbacks
262 @var{sign_func}: callback for signature operations
264 @var{decrypt_func}: callback for decryption operations
266 @var{flags}: Flags for the import
268 This function will associate the given callbacks with the
269 @code{gnutls_privkey_t} structure. At least one of the two callbacks
272 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
273 negative error value.
278 @subheading gnutls_privkey_import_openpgp
279 @anchor{gnutls_privkey_import_openpgp}
280 @deftypefun {int} {gnutls_privkey_import_openpgp} (gnutls_privkey_t @var{pkey}, gnutls_openpgp_privkey_t @var{key}, unsigned int @var{flags})
281 @var{pkey}: The private key
283 @var{key}: The private key to be imported
285 @var{flags}: Flags for the import
287 This function will import the given private key to the abstract
288 @code{gnutls_privkey_t} structure.
290 The @code{gnutls_openpgp_privkey_t} object must not be deallocated
291 during the lifetime of this structure. The subkey set as
292 preferred will be used, or the master key otherwise.
294 @code{flags} might be zero or one of @code{GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE}
295 and @code{GNUTLS_PRIVKEY_IMPORT_COPY} .
297 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
298 negative error value.
300 @strong{Since:} 2.12.0
303 @subheading gnutls_privkey_import_pkcs11
304 @anchor{gnutls_privkey_import_pkcs11}
305 @deftypefun {int} {gnutls_privkey_import_pkcs11} (gnutls_privkey_t @var{pkey}, gnutls_pkcs11_privkey_t @var{key}, unsigned int @var{flags})
306 @var{pkey}: The private key
308 @var{key}: The private key to be imported
310 @var{flags}: Flags for the import
312 This function will import the given private key to the abstract
313 @code{gnutls_privkey_t} structure.
315 The @code{gnutls_pkcs11_privkey_t} object must not be deallocated
316 during the lifetime of this structure.
318 @code{flags} might be zero or one of @code{GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE}
319 and @code{GNUTLS_PRIVKEY_IMPORT_COPY} .
321 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
322 negative error value.
324 @strong{Since:} 2.12.0
327 @subheading gnutls_privkey_import_x509
328 @anchor{gnutls_privkey_import_x509}
329 @deftypefun {int} {gnutls_privkey_import_x509} (gnutls_privkey_t @var{pkey}, gnutls_x509_privkey_t @var{key}, unsigned int @var{flags})
330 @var{pkey}: The private key
332 @var{key}: The private key to be imported
334 @var{flags}: Flags for the import
336 This function will import the given private key to the abstract
337 @code{gnutls_privkey_t} structure.
339 The @code{gnutls_x509_privkey_t} object must not be deallocated
340 during the lifetime of this structure.
342 @code{flags} might be zero or one of @code{GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE}
343 and @code{GNUTLS_PRIVKEY_IMPORT_COPY} .
345 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
346 negative error value.
348 @strong{Since:} 2.12.0
351 @subheading gnutls_privkey_init
352 @anchor{gnutls_privkey_init}
353 @deftypefun {int} {gnutls_privkey_init} (gnutls_privkey_t * @var{key})
354 @var{key}: The structure to be initialized
356 This function will initialize an private key structure.
358 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
359 negative error value.
361 @strong{Since:} 2.12.0
364 @subheading gnutls_privkey_sign_data
365 @anchor{gnutls_privkey_sign_data}
366 @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})
367 @var{signer}: Holds the key
369 @var{hash}: should be a digest algorithm
371 @var{flags}: should be 0 for now
373 @var{data}: holds the data to be signed
375 @var{signature}: will contain the signature allocate with @code{gnutls_malloc()}
377 This function will sign the given data using a signature algorithm
378 supported by the private key. Signature algorithms are always used
379 together with a hash functions. Different hash functions may be
380 used for the RSA algorithm, but only the SHA family for the DSA keys.
382 Use @code{gnutls_pubkey_get_preferred_hash_algorithm()} to determine
385 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
386 negative error value.
388 @strong{Since:} 2.12.0
391 @subheading gnutls_privkey_sign_hash
392 @anchor{gnutls_privkey_sign_hash}
393 @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})
394 @var{signer}: Holds the signer's key
396 @var{hash_algo}: The hash algorithm used
398 @var{flags}: zero for now
400 @var{hash_data}: holds the data to be signed
402 @var{signature}: will contain newly allocated signature
404 This function will sign the given hashed data using a signature algorithm
405 supported by the private key. Signature algorithms are always used
406 together with a hash functions. Different hash functions may be
407 used for the RSA algorithm, but only SHA-XXX for the DSA keys.
409 Use @code{gnutls_pubkey_get_preferred_hash_algorithm()} to determine
412 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
413 negative error value.
415 @strong{Since:} 2.12.0
418 @subheading gnutls_pubkey_deinit
419 @anchor{gnutls_pubkey_deinit}
420 @deftypefun {void} {gnutls_pubkey_deinit} (gnutls_pubkey_t @var{key})
421 @var{key}: The structure to be deinitialized
423 This function will deinitialize a public key structure.
425 @strong{Since:} 2.12.0
428 @subheading gnutls_pubkey_encrypt_data
429 @anchor{gnutls_pubkey_encrypt_data}
430 @deftypefun {int} {gnutls_pubkey_encrypt_data} (gnutls_pubkey_t @var{key}, unsigned int @var{flags}, const gnutls_datum_t * @var{plaintext}, gnutls_datum_t * @var{ciphertext})
431 @var{key}: Holds the public key
433 @var{flags}: should be 0 for now
435 @var{plaintext}: The data to be encrypted
437 @var{ciphertext}: contains the encrypted data
439 This function will encrypt the given data, using the public
442 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
443 negative error value.
448 @subheading gnutls_pubkey_export
449 @anchor{gnutls_pubkey_export}
450 @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})
451 @var{key}: Holds the certificate
453 @var{format}: the format of output params. One of PEM or DER.
455 @var{output_data}: will contain a certificate PEM or DER encoded
457 @var{output_data_size}: holds the size of output_data (and will be
458 replaced by the actual size of parameters)
460 This function will export the public key to DER or PEM format.
461 The contents of the exported data is the SubjectPublicKeyInfo
464 If the buffer provided is not long enough to hold the output, then
465 *output_data_size is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will
468 If the structure is PEM encoded, it will have a header
469 of "BEGIN CERTIFICATE".
471 @strong{Returns:} In case of failure a negative error code will be
472 returned, and 0 on success.
474 @strong{Since:} 2.12.0
477 @subheading gnutls_pubkey_get_key_id
478 @anchor{gnutls_pubkey_get_key_id}
479 @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})
480 @var{key}: Holds the public key
482 @var{flags}: should be 0 for now
484 @var{output_data}: will contain the key ID
486 @var{output_data_size}: holds the size of output_data (and will be
487 replaced by the actual size of parameters)
489 This function will return a unique ID the depends on the public
490 key parameters. This ID can be used in checking whether a
491 certificate corresponds to the given public key.
493 If the buffer provided is not long enough to hold the output, then
494 *output_data_size is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will
495 be returned. The output will normally be a SHA-1 hash output,
498 @strong{Returns:} In case of failure a negative error code will be
499 returned, and 0 on success.
501 @strong{Since:} 2.12.0
504 @subheading gnutls_pubkey_get_key_usage
505 @anchor{gnutls_pubkey_get_key_usage}
506 @deftypefun {int} {gnutls_pubkey_get_key_usage} (gnutls_pubkey_t @var{key}, unsigned int * @var{usage})
507 @var{key}: should contain a @code{gnutls_pubkey_t} structure
509 @var{usage}: If set will return the number of bits of the parameters (may be NULL)
511 This function will return the key usage of the public key.
513 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
514 negative error value.
516 @strong{Since:} 2.12.0
519 @subheading gnutls_pubkey_get_openpgp_key_id
520 @anchor{gnutls_pubkey_get_openpgp_key_id}
521 @deftypefun {int} {gnutls_pubkey_get_openpgp_key_id} (gnutls_pubkey_t @var{key}, unsigned int @var{flags}, unsigned char * @var{output_data}, size_t * @var{output_data_size}, unsigned int * @var{subkey})
522 @var{key}: Holds the public key
524 @var{flags}: should be 0 or @code{GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT}
526 @var{output_data}: will contain the key ID
528 @var{output_data_size}: holds the size of output_data (and will be
529 replaced by the actual size of parameters)
531 @var{subkey}: Will be non zero if the key ID corresponds to a subkey
533 This function returns the OpenPGP key ID of the corresponding key.
534 The key is a unique ID that depends on the public
537 If the flag @code{GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT} is specified
538 this function returns the fingerprint of the master key.
540 If the buffer provided is not long enough to hold the output, then
541 *output_data_size is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will
542 be returned. The output is @code{GNUTLS_OPENPGP_KEYID_SIZE} bytes long.
544 @strong{Returns:} In case of failure a negative error code will be
545 returned, and 0 on success.
550 @subheading gnutls_pubkey_get_pk_algorithm
551 @anchor{gnutls_pubkey_get_pk_algorithm}
552 @deftypefun {int} {gnutls_pubkey_get_pk_algorithm} (gnutls_pubkey_t @var{key}, unsigned int * @var{bits})
553 @var{key}: should contain a @code{gnutls_pubkey_t} structure
555 @var{bits}: If set will return the number of bits of the parameters (may be NULL)
557 This function will return the public key algorithm of a public
558 key and if possible will return a number of bits that indicates
559 the security parameter of the key.
561 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
562 success, or a negative error code on error.
564 @strong{Since:} 2.12.0
567 @subheading gnutls_pubkey_get_pk_dsa_raw
568 @anchor{gnutls_pubkey_get_pk_dsa_raw}
569 @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})
570 @var{key}: Holds the public key
572 @var{p}: will hold the p
574 @var{q}: will hold the q
576 @var{g}: will hold the g
578 @var{y}: will hold the y
580 This function will export the DSA public key's parameters found in
581 the given certificate. The new parameters will be allocated using
582 @code{gnutls_malloc()} and will be stored in the appropriate datum.
584 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
586 @strong{Since:} 2.12.0
589 @subheading gnutls_pubkey_get_pk_ecc_raw
590 @anchor{gnutls_pubkey_get_pk_ecc_raw}
591 @deftypefun {int} {gnutls_pubkey_get_pk_ecc_raw} (gnutls_pubkey_t @var{key}, gnutls_ecc_curve_t * @var{curve}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y})
592 @var{key}: Holds the public key
594 @var{curve}: will hold the curve
600 This function will export the ECC public key's parameters found in
601 the given certificate. The new parameters will be allocated using
602 @code{gnutls_malloc()} and will be stored in the appropriate datum.
604 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
609 @subheading gnutls_pubkey_get_pk_ecc_x962
610 @anchor{gnutls_pubkey_get_pk_ecc_x962}
611 @deftypefun {int} {gnutls_pubkey_get_pk_ecc_x962} (gnutls_pubkey_t @var{key}, gnutls_datum_t* @var{parameters}, gnutls_datum_t * @var{ecpoint})
612 @var{key}: Holds the public key
614 @var{parameters}: DER encoding of an ANSI X9.62 parameters
616 @var{ecpoint}: DER encoding of ANSI X9.62 ECPoint
618 This function will export the ECC public key's parameters found in
619 the given certificate. The new parameters will be allocated using
620 @code{gnutls_malloc()} and will be stored in the appropriate datum.
622 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
627 @subheading gnutls_pubkey_get_pk_rsa_raw
628 @anchor{gnutls_pubkey_get_pk_rsa_raw}
629 @deftypefun {int} {gnutls_pubkey_get_pk_rsa_raw} (gnutls_pubkey_t @var{key}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e})
630 @var{key}: Holds the certificate
632 @var{m}: will hold the modulus
634 @var{e}: will hold the public exponent
636 This function will export the RSA public key's parameters found in
637 the given structure. The new parameters will be allocated using
638 @code{gnutls_malloc()} and will be stored in the appropriate datum.
640 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
642 @strong{Since:} 2.12.0
645 @subheading gnutls_pubkey_get_preferred_hash_algorithm
646 @anchor{gnutls_pubkey_get_preferred_hash_algorithm}
647 @deftypefun {int} {gnutls_pubkey_get_preferred_hash_algorithm} (gnutls_pubkey_t @var{key}, gnutls_digest_algorithm_t * @var{hash}, unsigned int * @var{mand})
648 @var{key}: Holds the certificate
650 @var{hash}: The result of the call with the hash algorithm used for signature
652 @var{mand}: If non zero it means that the algorithm MUST use this hash. May be NULL.
654 This function will read the certifcate and return the appropriate digest
655 algorithm to use for signing with this certificate. Some certificates (i.e.
656 DSA might not be able to sign without the preferred algorithm).
658 @strong{Returns:} the 0 if the hash algorithm is found. A negative error code is
661 @strong{Since:} 2.12.0
664 @subheading gnutls_pubkey_get_verify_algorithm
665 @anchor{gnutls_pubkey_get_verify_algorithm}
666 @deftypefun {int} {gnutls_pubkey_get_verify_algorithm} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{signature}, gnutls_digest_algorithm_t * @var{hash})
667 @var{key}: Holds the certificate
669 @var{signature}: contains the signature
671 @var{hash}: The result of the call with the hash algorithm used for signature
673 This function will read the certifcate and the signed data to
674 determine the hash algorithm used to generate the signature.
676 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
677 negative error value.
679 @strong{Since:} 2.12.0
682 @subheading gnutls_pubkey_import
683 @anchor{gnutls_pubkey_import}
684 @deftypefun {int} {gnutls_pubkey_import} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format})
685 @var{key}: The structure to store the parsed public key.
687 @var{data}: The DER or PEM encoded certificate.
689 @var{format}: One of DER or PEM
691 This function will import the provided public key in
692 a SubjectPublicKeyInfo X.509 structure to a native
693 @code{gnutls_pubkey_t} structure. The output will be stored
694 in @code{key} . If the public key is PEM encoded it should have a header
697 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
698 negative error value.
700 @strong{Since:} 2.12.0
703 @subheading gnutls_pubkey_import_dsa_raw
704 @anchor{gnutls_pubkey_import_dsa_raw}
705 @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})
706 @var{key}: The structure to store the parsed key
716 This function will convert the given DSA raw parameters to the
717 native @code{gnutls_pubkey_t} format. The output will be stored
720 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
721 negative error value.
723 @strong{Since:} 2.12.0
726 @subheading gnutls_pubkey_import_ecc_raw
727 @anchor{gnutls_pubkey_import_ecc_raw}
728 @deftypefun {int} {gnutls_pubkey_import_ecc_raw} (gnutls_pubkey_t @var{key}, gnutls_ecc_curve_t @var{curve}, const gnutls_datum_t * @var{x}, const gnutls_datum_t * @var{y})
729 @var{key}: The structure to store the parsed key
731 @var{curve}: holds the curve
737 This function will convert the given elliptic curve parameters to a
738 @code{gnutls_pubkey_t} . The output will be stored in @code{key} .
740 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
741 negative error value.
746 @subheading gnutls_pubkey_import_ecc_x962
747 @anchor{gnutls_pubkey_import_ecc_x962}
748 @deftypefun {int} {gnutls_pubkey_import_ecc_x962} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{parameters}, const gnutls_datum_t * @var{ecpoint})
749 @var{key}: The structure to store the parsed key
751 @var{parameters}: DER encoding of an ANSI X9.62 parameters
753 @var{ecpoint}: DER encoding of ANSI X9.62 ECPoint
755 This function will convert the given elliptic curve parameters to a
756 @code{gnutls_pubkey_t} . The output will be stored in @code{key} .
758 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
759 negative error value.
764 @subheading gnutls_pubkey_import_openpgp
765 @anchor{gnutls_pubkey_import_openpgp}
766 @deftypefun {int} {gnutls_pubkey_import_openpgp} (gnutls_pubkey_t @var{key}, gnutls_openpgp_crt_t @var{crt}, unsigned int @var{flags})
767 @var{key}: The public key
769 @var{crt}: The certificate to be imported
771 @var{flags}: should be zero
773 Imports a public key from an openpgp key. This function will import
774 the given public key to the abstract @code{gnutls_pubkey_t}
775 structure. The subkey set as preferred will be imported or the
776 master key otherwise.
778 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
779 negative error value.
781 @strong{Since:} 2.12.0
784 @subheading gnutls_pubkey_import_pkcs11
785 @anchor{gnutls_pubkey_import_pkcs11}
786 @deftypefun {int} {gnutls_pubkey_import_pkcs11} (gnutls_pubkey_t @var{key}, gnutls_pkcs11_obj_t @var{obj}, unsigned int @var{flags})
787 @var{key}: The public key
789 @var{obj}: The parameters to be imported
791 @var{flags}: should be zero
793 Imports a public key from a pkcs11 key. This function will import
794 the given public key to the abstract @code{gnutls_pubkey_t} structure.
796 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
797 negative error value.
799 @strong{Since:} 2.12.0
802 @subheading gnutls_pubkey_import_pkcs11_url
803 @anchor{gnutls_pubkey_import_pkcs11_url}
804 @deftypefun {int} {gnutls_pubkey_import_pkcs11_url} (gnutls_pubkey_t @var{key}, const char * @var{url}, unsigned int @var{flags})
805 @var{key}: A key of type @code{gnutls_pubkey_t}
807 @var{url}: A PKCS 11 url
809 @var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
811 This function will import a PKCS 11 certificate to a @code{gnutls_pubkey_t}
814 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
815 negative error value.
817 @strong{Since:} 2.12.0
820 @subheading gnutls_pubkey_import_privkey
821 @anchor{gnutls_pubkey_import_privkey}
822 @deftypefun {int} {gnutls_pubkey_import_privkey} (gnutls_pubkey_t @var{key}, gnutls_privkey_t @var{pkey}, unsigned int @var{usage}, unsigned int @var{flags})
823 @var{key}: The public key
825 @var{pkey}: The private key
827 @var{usage}: GNUTLS_KEY_* key usage flags.
829 @var{flags}: should be zero
831 Imports the public key from a private. This function will import
832 the given public key to the abstract @code{gnutls_pubkey_t} structure.
834 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
835 negative error value.
837 @strong{Since:} 2.12.0
840 @subheading gnutls_pubkey_import_rsa_raw
841 @anchor{gnutls_pubkey_import_rsa_raw}
842 @deftypefun {int} {gnutls_pubkey_import_rsa_raw} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{m}, const gnutls_datum_t * @var{e})
843 @var{key}: Is a structure will hold the parameters
845 @var{m}: holds the modulus
847 @var{e}: holds the public exponent
849 This function will replace the parameters in the given structure.
850 The new parameters should be stored in the appropriate
853 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an negative error code.
855 @strong{Since:} 2.12.0
858 @subheading gnutls_pubkey_import_x509
859 @anchor{gnutls_pubkey_import_x509}
860 @deftypefun {int} {gnutls_pubkey_import_x509} (gnutls_pubkey_t @var{key}, gnutls_x509_crt_t @var{crt}, unsigned int @var{flags})
861 @var{key}: The public key
863 @var{crt}: The certificate to be imported
865 @var{flags}: should be zero
867 This function will import the given public key to the abstract
868 @code{gnutls_pubkey_t} structure.
870 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
871 negative error value.
873 @strong{Since:} 2.12.0
876 @subheading gnutls_pubkey_init
877 @anchor{gnutls_pubkey_init}
878 @deftypefun {int} {gnutls_pubkey_init} (gnutls_pubkey_t * @var{key})
879 @var{key}: The structure to be initialized
881 This function will initialize an public key structure.
883 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
884 negative error value.
886 @strong{Since:} 2.12.0
889 @subheading gnutls_pubkey_set_key_usage
890 @anchor{gnutls_pubkey_set_key_usage}
891 @deftypefun {int} {gnutls_pubkey_set_key_usage} (gnutls_pubkey_t @var{key}, unsigned int @var{usage})
892 @var{key}: a certificate of type @code{gnutls_x509_crt_t}
894 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
896 This function will set the key usage flags of the public key. This
897 is only useful if the key is to be exported to a certificate or
900 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
901 negative error value.
903 @strong{Since:} 2.12.0
906 @subheading gnutls_pubkey_verify_data
907 @anchor{gnutls_pubkey_verify_data}
908 @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})
909 @var{pubkey}: Holds the public key
911 @var{flags}: should be 0 for now
913 @var{data}: holds the signed data
915 @var{signature}: contains the signature
917 This function will verify the given signed data, using the
918 parameters from the certificate.
920 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
921 is returned, and zero or positive code on success.
923 @strong{Since:} 2.12.0
926 @subheading gnutls_pubkey_verify_data2
927 @anchor{gnutls_pubkey_verify_data2}
928 @deftypefun {int} {gnutls_pubkey_verify_data2} (gnutls_pubkey_t @var{pubkey}, gnutls_sign_algorithm_t @var{algo}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, const gnutls_datum_t * @var{signature})
929 @var{pubkey}: Holds the public key
931 @var{algo}: The signature algorithm used
933 @var{flags}: should be 0 for now
935 @var{data}: holds the signed data
937 @var{signature}: contains the signature
939 This function will verify the given signed data, using the
940 parameters from the certificate.
942 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
943 is returned, and zero or positive code on success.
948 @subheading gnutls_pubkey_verify_hash
949 @anchor{gnutls_pubkey_verify_hash}
950 @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})
951 @var{key}: Holds the public key
953 @var{flags}: should be 0 for now
955 @var{hash}: holds the hash digest to be verified
957 @var{signature}: contains the signature
959 This function will verify the given signed digest, using the
960 parameters from the public key.
962 Deprecated. This function cannot be easily used securely.
963 Use @code{gnutls_pubkey_verify_hash2()} instead.
965 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
966 is returned, and zero or positive code on success.
968 @strong{Since:} 2.12.0
971 @subheading gnutls_pubkey_verify_hash2
972 @anchor{gnutls_pubkey_verify_hash2}
973 @deftypefun {int} {gnutls_pubkey_verify_hash2} (gnutls_pubkey_t @var{key}, gnutls_sign_algorithm_t @var{algo}, unsigned int @var{flags}, const gnutls_datum_t * @var{hash}, const gnutls_datum_t * @var{signature})
974 @var{key}: Holds the public key
976 @var{algo}: The signature algorithm used
978 @var{flags}: should be 0 for now
980 @var{hash}: holds the hash digest to be verified
982 @var{signature}: contains the signature
984 This function will verify the given signed digest, using the
985 parameters from the public key.
987 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
988 is returned, and zero or positive code on success.
993 @subheading gnutls_x509_crl_privkey_sign
994 @anchor{gnutls_x509_crl_privkey_sign}
995 @deftypefun {int} {gnutls_x509_crl_privkey_sign} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer}, gnutls_privkey_t @var{issuer_key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags})
996 @var{crl}: should contain a gnutls_x509_crl_t structure
998 @var{issuer}: is the certificate of the certificate issuer
1000 @var{issuer_key}: holds the issuer's private key
1002 @var{dig}: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
1004 @var{flags}: must be 0
1006 This function will sign the CRL with the issuer's private key, and
1007 will copy the issuer's information into the CRL.
1009 This must be the last step in a certificate CRL since all
1010 the previously set parameters are now signed.
1012 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1013 negative error value.
1018 @subheading gnutls_x509_crq_privkey_sign
1019 @anchor{gnutls_x509_crq_privkey_sign}
1020 @deftypefun {int} {gnutls_x509_crq_privkey_sign} (gnutls_x509_crq_t @var{crq}, gnutls_privkey_t @var{key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags})
1021 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1023 @var{key}: holds a private key
1025 @var{dig}: The message digest to use, i.e., @code{GNUTLS_DIG_SHA1}
1027 @var{flags}: must be 0
1029 This function will sign the certificate request with a private key.
1030 This must be the same key as the one used in
1031 @code{gnutls_x509_crt_set_key()} since a certificate request is self
1034 This must be the last step in a certificate request generation
1035 since all the previously set parameters are now signed.
1037 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
1038 @code{GNUTLS_E_ASN1_VALUE_NOT_FOUND} is returned if you didn't set all
1039 information in the certificate request (e.g., the version using
1040 @code{gnutls_x509_crq_set_version()} ).
1042 @strong{Since:} 2.12.0
1045 @subheading gnutls_x509_crq_set_pubkey
1046 @anchor{gnutls_x509_crq_set_pubkey}
1047 @deftypefun {int} {gnutls_x509_crq_set_pubkey} (gnutls_x509_crq_t @var{crq}, gnutls_pubkey_t @var{key})
1048 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1050 @var{key}: holds a public key
1052 This function will set the public parameters from the given public
1055 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1056 negative error value.
1058 @strong{Since:} 2.12.0
1061 @subheading gnutls_x509_crt_privkey_sign
1062 @anchor{gnutls_x509_crt_privkey_sign}
1063 @deftypefun {int} {gnutls_x509_crt_privkey_sign} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crt_t @var{issuer}, gnutls_privkey_t @var{issuer_key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags})
1064 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
1066 @var{issuer}: is the certificate of the certificate issuer
1068 @var{issuer_key}: holds the issuer's private key
1070 @var{dig}: The message digest to use, @code{GNUTLS_DIG_SHA1} is a safe choice
1072 @var{flags}: must be 0
1074 This function will sign the certificate with the issuer's private key, and
1075 will copy the issuer's information into the certificate.
1077 This must be the last step in a certificate generation since all
1078 the previously set parameters are now signed.
1080 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1081 negative error value.
1084 @subheading gnutls_x509_crt_set_pubkey
1085 @anchor{gnutls_x509_crt_set_pubkey}
1086 @deftypefun {int} {gnutls_x509_crt_set_pubkey} (gnutls_x509_crt_t @var{crt}, gnutls_pubkey_t @var{key})
1087 @var{crt}: should contain a @code{gnutls_x509_crt_t} structure
1089 @var{key}: holds a public key
1091 This function will set the public parameters from the given public
1094 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1095 negative error value.
1097 @strong{Since:} 2.12.0