Adding upstream version 3.7.9.upstream/3.7.9upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 62 insertions, 0 deletions

diff --git a/doc/functions/gnutls_certificate_set_retrieve_function3 b/doc/functions/gnutls_certificate_set_retrieve_function3
new file mode 100644
index 0000000..af53ca2
--- /dev/null
+++ b/doc/functions/gnutls_certificate_set_retrieve_function3
@@ -0,0 +1,62 @@
+
+
+
+
+@deftypefun {void} {gnutls_certificate_set_retrieve_function3} (gnutls_certificate_credentials_t @var{cred}, gnutls_certificate_retrieve_function3 * @var{func})
+@var{cred}: is a @code{gnutls_certificate_credentials_t}  type.
+
+@var{func}: is the callback function
+
+This function sets a callback to be called in order to retrieve the
+certificate and OCSP responses to be used in the handshake.  @code{func} will
+be called only if the peer requests a certificate either during handshake
+or during post-handshake authentication.
+
+The callback's function prototype is defined in `abstract.h':
+
+int gnutls_certificate_retrieve_function3(
+gnutls_session_t,
+const struct gnutls_cert_retr_st *info,
+gnutls_pcert_st **certs,
+unsigned int *certs_length,
+gnutls_ocsp_data_st **ocsp,
+unsigned int *ocsp_length,
+gnutls_privkey_t *privkey,
+unsigned int *flags);
+
+The info field of the callback contains:
+ @code{req_ca_dn} which is a list with the CA names that the server considers trusted.
+This is a hint and typically the client should send a certificate that is signed
+by one of these CAs. These names, when available, are DER encoded. To get a more
+meaningful value use the function @code{gnutls_x509_rdn_get()} .
+ @code{pk_algos} contains a list with server's acceptable public key algorithms.
+The certificate returned should support the server's given algorithms.
+
+The callback should fill-in the following values:
+
+ @code{certs} should contain an allocated list of certificates and public keys.
+ @code{certs_length} is the size of the previous list.
+ @code{ocsp} should contain an allocated list of OCSP responses.
+ @code{ocsp_length} is the size of the previous list.
+ @code{privkey} is the private key.
+
+If flags in the callback are set to @code{GNUTLS_CERT_RETR_DEINIT_ALL}  then
+all provided values must be allocated using @code{gnutls_malloc()} , and will
+be released by gnutls; otherwise they will not be touched by gnutls.
+
+The callback function should set the certificate and OCSP response
+list to be sent, and return 0 on success. If no certificates are available,
+the  @code{certs_length} and  @code{ocsp_length} should be set to zero. The return
+value (-1) indicates error and the handshake will be terminated. If both
+certificates are set in the credentials and a callback is available, the
+callback takes predence.
+
+Raw public-keys:
+In case raw public-keys are negotiated as certificate type, certificates
+that would normally hold the public-key material are not available. In that case,
+ @code{certs} contains an allocated list with only the public key. Since there is no
+certificate, there is also no certificate status. Therefore, OCSP information
+should not be set.
+
+@strong{Since:} 3.6.3
+@end deftypefun