147 lines
6.3 KiB
HTML
147 lines
6.3 KiB
HTML
|
<?xml version="1.0" ?>
|
||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
<head>
|
||
|
<title>SSL_CTX_set_client_cert_cb</title>
|
||
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||
|
<link rev="made" href="mailto:root@localhost" />
|
||
|
</head>
|
||
|
|
||
|
<body style="background-color: white">
|
||
|
|
||
|
|
||
|
<!-- INDEX BEGIN -->
|
||
|
<div name="index">
|
||
|
<p><a name="__index__"></a></p>
|
||
|
|
||
|
<ul>
|
||
|
|
||
|
<li><a href="#name">NAME</a></li>
|
||
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
||
|
<li><a href="#description">DESCRIPTION</a></li>
|
||
|
<li><a href="#notes">NOTES</a></li>
|
||
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
||
|
<li><a href="#bugs">BUGS</a></li>
|
||
|
<li><a href="#see_also">SEE ALSO</a></li>
|
||
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
||
|
</ul>
|
||
|
|
||
|
<hr name="index" />
|
||
|
</div>
|
||
|
<!-- INDEX END -->
|
||
|
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="name">NAME</a></h1>
|
||
|
<p>SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
||
|
<pre>
|
||
|
#include <openssl/ssl.h></pre>
|
||
|
<pre>
|
||
|
void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx,
|
||
|
int (*client_cert_cb)(SSL *ssl, X509 **x509,
|
||
|
EVP_PKEY **pkey));
|
||
|
int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509,
|
||
|
EVP_PKEY **pkey);
|
||
|
int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey);</pre>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="description">DESCRIPTION</a></h1>
|
||
|
<p><code>SSL_CTX_set_client_cert_cb()</code> sets the <code>client_cert_cb()</code> callback, that is
|
||
|
called when a client certificate is requested by a server and no certificate
|
||
|
was yet set for the SSL object.</p>
|
||
|
<p>When <code>client_cert_cb()</code> is NULL, no callback function is used.</p>
|
||
|
<p><code>SSL_CTX_get_client_cert_cb()</code> returns a pointer to the currently set callback
|
||
|
function.</p>
|
||
|
<p><code>client_cert_cb()</code> is the application defined callback. If it wants to
|
||
|
set a certificate, a certificate/private key combination must be set
|
||
|
using the <strong>x509</strong> and <strong>pkey</strong> arguments and "1" must be returned. The
|
||
|
certificate will be installed into <strong>ssl</strong>, see the NOTES and BUGS sections.
|
||
|
If no certificate should be set, "0" has to be returned and no certificate
|
||
|
will be sent. A negative return value will suspend the handshake and the
|
||
|
handshake function will return immediately. <em>SSL_get_error(3)</em>
|
||
|
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 <code>client_cert_cb()</code>. It is the job of the <code>client_cert_cb()</code> to store information
|
||
|
about the state of the last call, if required to continue.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="notes">NOTES</a></h1>
|
||
|
<p>During a handshake (or renegotiation) a server may request a certificate
|
||
|
from the client. A client certificate must only be sent, when the server
|
||
|
did send the request.</p>
|
||
|
<p>When a certificate was set using the
|
||
|
<em>SSL_CTX_use_certificate(3)</em> family of functions,
|
||
|
it will be sent to the server. The TLS standard requires that only a
|
||
|
certificate is sent, if it matches the list of acceptable CAs sent by the
|
||
|
server. This constraint is violated by the default behavior of the OpenSSL
|
||
|
library. Using the callback function it is possible to implement a proper
|
||
|
selection routine or to allow a user interaction to choose the certificate to
|
||
|
be sent.</p>
|
||
|
<p>If a callback function is defined and no certificate was yet defined for the
|
||
|
SSL object, the callback function will be called.
|
||
|
If the callback function returns a certificate, the OpenSSL library
|
||
|
will try to load the private key and certificate data into the SSL
|
||
|
object using the <code>SSL_use_certificate()</code> and <code>SSL_use_private_key()</code> functions.
|
||
|
Thus it will permanently install the certificate and key for this SSL
|
||
|
object. It will not be reset by calling <em>SSL_clear(3)</em>.
|
||
|
If the callback returns no certificate, the OpenSSL library will not send
|
||
|
a certificate.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
||
|
<p><code>SSL_CTX_get_client_cert_cb()</code> returns function pointer of <code>client_cert_cb()</code> or
|
||
|
NULL if the callback is not set.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="bugs">BUGS</a></h1>
|
||
|
<p>The <code>client_cert_cb()</code> cannot return a complete certificate chain, it can
|
||
|
only return one client certificate. If the chain only has a length of 2,
|
||
|
the root CA certificate may be omitted according to the TLS standard and
|
||
|
thus a standard conforming answer can be sent to the server. For a
|
||
|
longer chain, the client must send the complete chain (with the option
|
||
|
to leave out the root CA certificate). This can only be accomplished by
|
||
|
either adding the intermediate CA certificates into the trusted
|
||
|
certificate store for the SSL_CTX object (resulting in having to add
|
||
|
CA certificates that otherwise maybe would not be trusted), or by adding
|
||
|
the chain certificates using the
|
||
|
<em>SSL_CTX_add_extra_chain_cert(3)</em>
|
||
|
function, which is only available for the SSL_CTX object as a whole and that
|
||
|
therefore probably can only apply for one client certificate, making
|
||
|
the concept of the callback function (to allow the choice from several
|
||
|
certificates) questionable.</p>
|
||
|
<p>Once the SSL object has been used in conjunction with the callback function,
|
||
|
the certificate will be set for the SSL object and will not be cleared
|
||
|
even when <em>SSL_clear(3)</em> is being called. It is therefore
|
||
|
mandatory to destroy the SSL object using <em>SSL_free(3)</em>
|
||
|
and create a new one to return to the previous state.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
||
|
<p><em>ssl(7)</em>, <em>SSL_CTX_use_certificate(3)</em>,
|
||
|
<em>SSL_CTX_add_extra_chain_cert(3)</em>,
|
||
|
<em>SSL_get_client_CA_list(3)</em>,
|
||
|
<em>SSL_clear(3)</em>, <em>SSL_free(3)</em></p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
||
|
<p>Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
||
|
<p>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
|
||
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
||
|
|
||
|
</body>
|
||
|
|
||
|
</html>
|