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 for now
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 will return a unique ID the depends on the public
534 key parameters. This ID can be used in checking whether a
535 certificate corresponds to the given public key.
537 If the buffer provided is not long enough to hold the output, then
538 *output_data_size is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER} will
539 be returned. The output will normally be a SHA-1 hash output,
542 @strong{Returns:} In case of failure a negative error code will be
543 returned, and 0 on success.
548 @subheading gnutls_pubkey_get_pk_algorithm
549 @anchor{gnutls_pubkey_get_pk_algorithm}
550 @deftypefun {int} {gnutls_pubkey_get_pk_algorithm} (gnutls_pubkey_t @var{key}, unsigned int * @var{bits})
551 @var{key}: should contain a @code{gnutls_pubkey_t} structure
553 @var{bits}: If set will return the number of bits of the parameters (may be NULL)
555 This function will return the public key algorithm of a public
556 key and if possible will return a number of bits that indicates
557 the security parameter of the key.
559 @strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on
560 success, or a negative error code on error.
562 @strong{Since:} 2.12.0
565 @subheading gnutls_pubkey_get_pk_dsa_raw
566 @anchor{gnutls_pubkey_get_pk_dsa_raw}
567 @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})
568 @var{key}: Holds the public key
570 @var{p}: will hold the p
572 @var{q}: will hold the q
574 @var{g}: will hold the g
576 @var{y}: will hold the y
578 This function will export the DSA public key's parameters found in
579 the given certificate. The new parameters will be allocated using
580 @code{gnutls_malloc()} and will be stored in the appropriate datum.
582 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
584 @strong{Since:} 2.12.0
587 @subheading gnutls_pubkey_get_pk_ecc_raw
588 @anchor{gnutls_pubkey_get_pk_ecc_raw}
589 @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})
590 @var{key}: Holds the public key
592 @var{curve}: will hold the curve
598 This function will export the ECC public key's parameters found in
599 the given certificate. The new parameters will be allocated using
600 @code{gnutls_malloc()} and will be stored in the appropriate datum.
602 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
607 @subheading gnutls_pubkey_get_pk_ecc_x962
608 @anchor{gnutls_pubkey_get_pk_ecc_x962}
609 @deftypefun {int} {gnutls_pubkey_get_pk_ecc_x962} (gnutls_pubkey_t @var{key}, gnutls_datum_t* @var{parameters}, gnutls_datum_t * @var{ecpoint})
610 @var{key}: Holds the public key
612 @var{parameters}: DER encoding of an ANSI X9.62 parameters
614 @var{ecpoint}: DER encoding of ANSI X9.62 ECPoint
616 This function will export the ECC public key's parameters found in
617 the given certificate. The new parameters will be allocated using
618 @code{gnutls_malloc()} and will be stored in the appropriate datum.
620 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
625 @subheading gnutls_pubkey_get_pk_rsa_raw
626 @anchor{gnutls_pubkey_get_pk_rsa_raw}
627 @deftypefun {int} {gnutls_pubkey_get_pk_rsa_raw} (gnutls_pubkey_t @var{key}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e})
628 @var{key}: Holds the certificate
630 @var{m}: will hold the modulus
632 @var{e}: will hold the public exponent
634 This function will export the RSA public key's parameters found in
635 the given structure. The new parameters will be allocated using
636 @code{gnutls_malloc()} and will be stored in the appropriate datum.
638 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
640 @strong{Since:} 2.12.0
643 @subheading gnutls_pubkey_get_preferred_hash_algorithm
644 @anchor{gnutls_pubkey_get_preferred_hash_algorithm}
645 @deftypefun {int} {gnutls_pubkey_get_preferred_hash_algorithm} (gnutls_pubkey_t @var{key}, gnutls_digest_algorithm_t * @var{hash}, unsigned int * @var{mand})
646 @var{key}: Holds the certificate
648 @var{hash}: The result of the call with the hash algorithm used for signature
650 @var{mand}: If non zero it means that the algorithm MUST use this hash. May be NULL.
652 This function will read the certifcate and return the appropriate digest
653 algorithm to use for signing with this certificate. Some certificates (i.e.
654 DSA might not be able to sign without the preferred algorithm).
656 @strong{Returns:} the 0 if the hash algorithm is found. A negative error code is
659 @strong{Since:} 2.12.0
662 @subheading gnutls_pubkey_get_verify_algorithm
663 @anchor{gnutls_pubkey_get_verify_algorithm}
664 @deftypefun {int} {gnutls_pubkey_get_verify_algorithm} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{signature}, gnutls_digest_algorithm_t * @var{hash})
665 @var{key}: Holds the certificate
667 @var{signature}: contains the signature
669 @var{hash}: The result of the call with the hash algorithm used for signature
671 This function will read the certifcate and the signed data to
672 determine the hash algorithm used to generate the signature.
674 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
675 negative error value.
677 @strong{Since:} 2.12.0
680 @subheading gnutls_pubkey_import
681 @anchor{gnutls_pubkey_import}
682 @deftypefun {int} {gnutls_pubkey_import} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format})
683 @var{key}: The structure to store the parsed public key.
685 @var{data}: The DER or PEM encoded certificate.
687 @var{format}: One of DER or PEM
689 This function will import the provided public key in
690 a SubjectPublicKeyInfo X.509 structure to a native
691 @code{gnutls_pubkey_t} structure. The output will be stored
692 in @code{key} . If the public key is PEM encoded it should have a header
695 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
696 negative error value.
698 @strong{Since:} 2.12.0
701 @subheading gnutls_pubkey_import_dsa_raw
702 @anchor{gnutls_pubkey_import_dsa_raw}
703 @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})
704 @var{key}: The structure to store the parsed key
714 This function will convert the given DSA raw parameters to the
715 native @code{gnutls_pubkey_t} format. The output will be stored
718 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
719 negative error value.
721 @strong{Since:} 2.12.0
724 @subheading gnutls_pubkey_import_ecc_raw
725 @anchor{gnutls_pubkey_import_ecc_raw}
726 @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})
727 @var{key}: The structure to store the parsed key
729 @var{curve}: holds the curve
735 This function will convert the given elliptic curve parameters to a
736 @code{gnutls_pubkey_t} . The output will be stored in @code{key} .
738 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
739 negative error value.
744 @subheading gnutls_pubkey_import_ecc_x962
745 @anchor{gnutls_pubkey_import_ecc_x962}
746 @deftypefun {int} {gnutls_pubkey_import_ecc_x962} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{parameters}, const gnutls_datum_t * @var{ecpoint})
747 @var{key}: The structure to store the parsed key
749 @var{parameters}: DER encoding of an ANSI X9.62 parameters
751 @var{ecpoint}: DER encoding of ANSI X9.62 ECPoint
753 This function will convert the given elliptic curve parameters to a
754 @code{gnutls_pubkey_t} . The output will be stored in @code{key} .
756 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
757 negative error value.
762 @subheading gnutls_pubkey_import_openpgp
763 @anchor{gnutls_pubkey_import_openpgp}
764 @deftypefun {int} {gnutls_pubkey_import_openpgp} (gnutls_pubkey_t @var{key}, gnutls_openpgp_crt_t @var{crt}, unsigned int @var{flags})
765 @var{key}: The public key
767 @var{crt}: The certificate to be imported
769 @var{flags}: should be zero
771 Imports a public key from an openpgp key. This function will import
772 the given public key to the abstract @code{gnutls_pubkey_t}
773 structure. The subkey set as preferred will be imported or the
774 master key otherwise.
776 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
777 negative error value.
779 @strong{Since:} 2.12.0
782 @subheading gnutls_pubkey_import_pkcs11
783 @anchor{gnutls_pubkey_import_pkcs11}
784 @deftypefun {int} {gnutls_pubkey_import_pkcs11} (gnutls_pubkey_t @var{key}, gnutls_pkcs11_obj_t @var{obj}, unsigned int @var{flags})
785 @var{key}: The public key
787 @var{obj}: The parameters to be imported
789 @var{flags}: should be zero
791 Imports a public key from a pkcs11 key. This function will import
792 the given public key to the abstract @code{gnutls_pubkey_t} structure.
794 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
795 negative error value.
797 @strong{Since:} 2.12.0
800 @subheading gnutls_pubkey_import_pkcs11_url
801 @anchor{gnutls_pubkey_import_pkcs11_url}
802 @deftypefun {int} {gnutls_pubkey_import_pkcs11_url} (gnutls_pubkey_t @var{key}, const char * @var{url}, unsigned int @var{flags})
803 @var{key}: A key of type @code{gnutls_pubkey_t}
805 @var{url}: A PKCS 11 url
807 @var{flags}: One of GNUTLS_PKCS11_OBJ_* flags
809 This function will import a PKCS 11 certificate to a @code{gnutls_pubkey_t}
812 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
813 negative error value.
815 @strong{Since:} 2.12.0
818 @subheading gnutls_pubkey_import_privkey
819 @anchor{gnutls_pubkey_import_privkey}
820 @deftypefun {int} {gnutls_pubkey_import_privkey} (gnutls_pubkey_t @var{key}, gnutls_privkey_t @var{pkey}, unsigned int @var{usage}, unsigned int @var{flags})
821 @var{key}: The public key
823 @var{pkey}: The private key
825 @var{usage}: GNUTLS_KEY_* key usage flags.
827 @var{flags}: should be zero
829 Imports the public key from a private. This function will import
830 the given public key to the abstract @code{gnutls_pubkey_t} structure.
832 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
833 negative error value.
835 @strong{Since:} 2.12.0
838 @subheading gnutls_pubkey_import_rsa_raw
839 @anchor{gnutls_pubkey_import_rsa_raw}
840 @deftypefun {int} {gnutls_pubkey_import_rsa_raw} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{m}, const gnutls_datum_t * @var{e})
841 @var{key}: Is a structure will hold the parameters
843 @var{m}: holds the modulus
845 @var{e}: holds the public exponent
847 This function will replace the parameters in the given structure.
848 The new parameters should be stored in the appropriate
851 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an negative error code.
853 @strong{Since:} 2.12.0
856 @subheading gnutls_pubkey_import_x509
857 @anchor{gnutls_pubkey_import_x509}
858 @deftypefun {int} {gnutls_pubkey_import_x509} (gnutls_pubkey_t @var{key}, gnutls_x509_crt_t @var{crt}, unsigned int @var{flags})
859 @var{key}: The public key
861 @var{crt}: The certificate to be imported
863 @var{flags}: should be zero
865 This function will import the given public key to the abstract
866 @code{gnutls_pubkey_t} structure.
868 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
869 negative error value.
871 @strong{Since:} 2.12.0
874 @subheading gnutls_pubkey_init
875 @anchor{gnutls_pubkey_init}
876 @deftypefun {int} {gnutls_pubkey_init} (gnutls_pubkey_t * @var{key})
877 @var{key}: The structure to be initialized
879 This function will initialize an public key structure.
881 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
882 negative error value.
884 @strong{Since:} 2.12.0
887 @subheading gnutls_pubkey_set_key_usage
888 @anchor{gnutls_pubkey_set_key_usage}
889 @deftypefun {int} {gnutls_pubkey_set_key_usage} (gnutls_pubkey_t @var{key}, unsigned int @var{usage})
890 @var{key}: a certificate of type @code{gnutls_x509_crt_t}
892 @var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.
894 This function will set the key usage flags of the public key. This
895 is only useful if the key is to be exported to a certificate or
898 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
899 negative error value.
901 @strong{Since:} 2.12.0
904 @subheading gnutls_pubkey_verify_data
905 @anchor{gnutls_pubkey_verify_data}
906 @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})
907 @var{pubkey}: Holds the public key
909 @var{flags}: should be 0 for now
911 @var{data}: holds the signed data
913 @var{signature}: contains the signature
915 This function will verify the given signed data, using the
916 parameters from the certificate.
918 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
919 is returned, and zero or positive code on success.
921 @strong{Since:} 2.12.0
924 @subheading gnutls_pubkey_verify_data2
925 @anchor{gnutls_pubkey_verify_data2}
926 @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})
927 @var{pubkey}: Holds the public key
929 @var{algo}: The signature algorithm used
931 @var{flags}: should be 0 for now
933 @var{data}: holds the signed data
935 @var{signature}: contains the signature
937 This function will verify the given signed data, using the
938 parameters from the certificate.
940 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
941 is returned, and zero or positive code on success.
946 @subheading gnutls_pubkey_verify_hash
947 @anchor{gnutls_pubkey_verify_hash}
948 @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})
949 @var{key}: Holds the public key
951 @var{flags}: should be 0 for now
953 @var{hash}: holds the hash digest to be verified
955 @var{signature}: contains the signature
957 This function will verify the given signed digest, using the
958 parameters from the public key. Use @code{gnutls_pubkey_verify_hash2()}
959 instead of this function.
961 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
962 is returned, and zero or positive code on success.
964 @strong{Since:} 2.12.0
967 @subheading gnutls_pubkey_verify_hash2
968 @anchor{gnutls_pubkey_verify_hash2}
969 @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})
970 @var{key}: Holds the public key
972 @var{algo}: The signature algorithm used
974 @var{flags}: should be 0 for now
976 @var{hash}: holds the hash digest to be verified
978 @var{signature}: contains the signature
980 This function will verify the given signed digest, using the
981 parameters from the public key.
983 @strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}
984 is returned, and zero or positive code on success.
989 @subheading gnutls_x509_crl_privkey_sign
990 @anchor{gnutls_x509_crl_privkey_sign}
991 @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})
992 @var{crl}: should contain a gnutls_x509_crl_t structure
994 @var{issuer}: is the certificate of the certificate issuer
996 @var{issuer_key}: holds the issuer's private key
998 @var{dig}: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
1000 @var{flags}: must be 0
1002 This function will sign the CRL with the issuer's private key, and
1003 will copy the issuer's information into the CRL.
1005 This must be the last step in a certificate CRL since all
1006 the previously set parameters are now signed.
1008 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1009 negative error value.
1014 @subheading gnutls_x509_crq_privkey_sign
1015 @anchor{gnutls_x509_crq_privkey_sign}
1016 @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})
1017 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1019 @var{key}: holds a private key
1021 @var{dig}: The message digest to use, i.e., @code{GNUTLS_DIG_SHA1}
1023 @var{flags}: must be 0
1025 This function will sign the certificate request with a private key.
1026 This must be the same key as the one used in
1027 @code{gnutls_x509_crt_set_key()} since a certificate request is self
1030 This must be the last step in a certificate request generation
1031 since all the previously set parameters are now signed.
1033 @strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code.
1034 @code{GNUTLS_E_ASN1_VALUE_NOT_FOUND} is returned if you didn't set all
1035 information in the certificate request (e.g., the version using
1036 @code{gnutls_x509_crq_set_version()} ).
1038 @strong{Since:} 2.12.0
1041 @subheading gnutls_x509_crq_set_pubkey
1042 @anchor{gnutls_x509_crq_set_pubkey}
1043 @deftypefun {int} {gnutls_x509_crq_set_pubkey} (gnutls_x509_crq_t @var{crq}, gnutls_pubkey_t @var{key})
1044 @var{crq}: should contain a @code{gnutls_x509_crq_t} structure
1046 @var{key}: holds a public key
1048 This function will set the public parameters from the given public
1051 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1052 negative error value.
1054 @strong{Since:} 2.12.0
1057 @subheading gnutls_x509_crt_privkey_sign
1058 @anchor{gnutls_x509_crt_privkey_sign}
1059 @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})
1060 @var{crt}: a certificate of type @code{gnutls_x509_crt_t}
1062 @var{issuer}: is the certificate of the certificate issuer
1064 @var{issuer_key}: holds the issuer's private key
1066 @var{dig}: The message digest to use, @code{GNUTLS_DIG_SHA1} is a safe choice
1068 @var{flags}: must be 0
1070 This function will sign the certificate with the issuer's private key, and
1071 will copy the issuer's information into the certificate.
1073 This must be the last step in a certificate generation since all
1074 the previously set parameters are now signed.
1076 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1077 negative error value.
1080 @subheading gnutls_x509_crt_set_pubkey
1081 @anchor{gnutls_x509_crt_set_pubkey}
1082 @deftypefun {int} {gnutls_x509_crt_set_pubkey} (gnutls_x509_crt_t @var{crt}, gnutls_pubkey_t @var{key})
1083 @var{crt}: should contain a @code{gnutls_x509_crt_t} structure
1085 @var{key}: holds a public key
1087 This function will set the public parameters from the given public
1090 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a
1091 negative error value.
1093 @strong{Since:} 2.12.0