$NetBSD: SSL_CTX_set_cert_cb.3,v 1.10 2024/09/08 13:08:31 christos Exp $

-*- mode: troff; coding: utf-8 -*-
Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)

Standard preamble:
========================================================================
..

..

.. \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
. ds C` "" . ds C' "" 'br\} . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.

If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.

Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF ========================================================================

Title "SSL_CTX_set_cert_cb 3" For nroff, turn off justification. Always turn off hyphenation; it makes
way too many mistakes in technical documents.
SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function Header "SYNOPSIS" .Vb 1 #include <openssl/ssl.h> \& void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), void *arg); void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); .Ve Header "DESCRIPTION" \fBSSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the cert_cb callback, \fIarg value is pointer which is passed to the application callback.

When cert_cb is NULL, no callback function is used.

\fIcert_cb is the application defined callback. It is called before a certificate will be used by a client or server. The callback can then inspect the passed ssl structure and set or clear any appropriate certificates. If the callback is successful it MUST return 1 even if no certificates have been set. A zero is returned on error which will abort the handshake with a fatal internal error alert. A negative return value will suspend the handshake and the handshake function will return immediately. \fBSSL_get_error\|(3) will return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was suspended. The next call to the handshake function will again lead to the call of cert_cb. It is the job of the \fIcert_cb to store information about the state of the last call, if required to continue.

Header "NOTES" An application will typically call SSL_use_certificate() and \fBSSL_use_PrivateKey() to set the end entity certificate and private key. It can add intermediate and optionally the root CA certificates using \fBSSL_add1_chain_cert().

It might also call SSL_certs_clear() to delete any certificates associated with the SSL object.

The certificate callback functionality supersedes the (largely broken) functionality provided by the old client certificate callback interface. It is always called even is a certificate is already set so the callback can modify or delete the existing certificate.

A more advanced callback might examine the handshake parameters and set whatever chain is appropriate. For example a legacy client supporting only TLSv1.0 might receive a certificate chain signed using SHA1 whereas a TLSv1.2 or later client which advertises support for SHA256 could receive a chain using SHA256.

Normal server sanity checks are performed on any certificates set by the callback. So if an EC chain is set for a curve the client does not support it will not be used.

Header "RETURN VALUES" \fBSSL_CTX_set_cert_cb() and SSL_set_cert_cb() do not return values. Header "SEE ALSO" \fBssl\|(7), SSL_use_certificate\|(3), \fBSSL_add1_chain_cert\|(3), \fBSSL_get_client_CA_list\|(3), \fBSSL_clear\|(3), SSL_free\|(3) Header "COPYRIGHT" Copyright 2014-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.