242 lines
11 KiB
HTML
Executable File
242 lines
11 KiB
HTML
Executable File
<?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_srp_password</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="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#examples">EXAMPLES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#history">HISTORY</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_srp_username,
|
|
SSL_CTX_set_srp_password,
|
|
SSL_CTX_set_srp_strength,
|
|
SSL_CTX_set_srp_cb_arg,
|
|
SSL_CTX_set_srp_username_callback,
|
|
SSL_CTX_set_srp_client_pwd_callback,
|
|
SSL_CTX_set_srp_verify_param_callback,
|
|
SSL_set_srp_server_param,
|
|
SSL_set_srp_server_param_pw,
|
|
SSL_get_srp_g,
|
|
SSL_get_srp_N,
|
|
SSL_get_srp_username,
|
|
SSL_get_srp_userinfo
|
|
- SRP control operations</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/ssl.h></pre>
|
|
<pre>
|
|
int SSL_CTX_set_srp_username(SSL_CTX *ctx, char *name);
|
|
int SSL_CTX_set_srp_password(SSL_CTX *ctx, char *password);
|
|
int SSL_CTX_set_srp_strength(SSL_CTX *ctx, int strength);
|
|
int SSL_CTX_set_srp_cb_arg(SSL_CTX *ctx, void *arg);
|
|
int SSL_CTX_set_srp_username_callback(SSL_CTX *ctx,
|
|
int (*cb) (SSL *s, int *ad, void *arg));
|
|
int SSL_CTX_set_srp_client_pwd_callback(SSL_CTX *ctx,
|
|
char *(*cb) (SSL *s, void *arg));
|
|
int SSL_CTX_set_srp_verify_param_callback(SSL_CTX *ctx,
|
|
int (*cb) (SSL *s, void *arg));</pre>
|
|
<pre>
|
|
int SSL_set_srp_server_param(SSL *s, const BIGNUM *N, const BIGNUM *g,
|
|
BIGNUM *sa, BIGNUM *v, char *info);
|
|
int SSL_set_srp_server_param_pw(SSL *s, const char *user, const char *pass,
|
|
const char *grp);</pre>
|
|
<pre>
|
|
BIGNUM *SSL_get_srp_g(SSL *s);
|
|
BIGNUM *SSL_get_srp_N(SSL *s);</pre>
|
|
<pre>
|
|
char *SSL_get_srp_username(SSL *s);
|
|
char *SSL_get_srp_userinfo(SSL *s);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>These functions provide access to SRP (Secure Remote Password) parameters,
|
|
an alternate authentication mechanism for TLS. SRP allows the use of user names
|
|
and passwords over unencrypted channels without revealing the password to an
|
|
eavesdropper. SRP also supplies a shared secret at the end of the authentication
|
|
sequence that can be used to generate encryption keys.</p>
|
|
<p>The SRP protocol, version 3 is specified in <a href="http://www.ietf.org/rfc/rfc2945.txt" class="rfc">RFC 2945</a>. SRP version 6 is described
|
|
in <a href="http://www.ietf.org/rfc/rfc5054.txt" class="rfc">RFC 5054</a> with applications to TLS authentication.</p>
|
|
<p>The <code>SSL_CTX_set_srp_username()</code> function sets the SRP username for <strong>ctx</strong>. This
|
|
should be called on the client prior to creating a connection to the server.
|
|
The length of <strong>name</strong> must be shorter or equal to 255 characters.</p>
|
|
<p>The <code>SSL_CTX_set_srp_password()</code> function sets the SRP password for <strong>ctx</strong>. This
|
|
may be called on the client prior to creating a connection to the server.
|
|
This overrides the effect of <code>SSL_CTX_set_srp_client_pwd_callback()</code>.</p>
|
|
<p>The <code>SSL_CTX_set_srp_strength()</code> function sets the SRP strength for <strong>ctx</strong>. This
|
|
is the minimal length of the SRP prime in bits. If not specified 1024 is used.
|
|
If not satisfied by the server key exchange the connection will be rejected.</p>
|
|
<p>The <code>SSL_CTX_set_srp_cb_arg()</code> function sets an extra parameter that will
|
|
be passed to all following callbacks as <strong>arg</strong>.</p>
|
|
<p>The <code>SSL_CTX_set_srp_username_callback()</code> function sets the server side callback
|
|
that is invoked when an SRP username is found in a ClientHello.
|
|
The callback parameters are the SSL connection <strong>s</strong>, a writable error flag <strong>ad</strong>
|
|
and the extra argument <strong>arg</strong> set by <code>SSL_CTX_set_srp_cb_arg()</code>.
|
|
This callback should setup the server for the key exchange by calling
|
|
<code>SSL_set_srp_server_param()</code> with the appropriate parameters for the received
|
|
username. The username can be obtained by calling <code>SSL_get_srp_username()</code>.
|
|
See <em>SRP_VBASE_init(3)</em> to parse the verifier file created by <em>openssl-srp(1)</em> or
|
|
<em>SRP_create_verifier(3)</em> to generate it.
|
|
The callback should return <strong>SSL_ERROR_NONE</strong> to proceed with the server key exchange,
|
|
<strong>SSL3_AL_FATAL</strong> for a fatal error or any value < 0 for a retryable error.
|
|
In the event of a <strong>SSL3_AL_FATAL</strong> the alert flag given by <strong>*al</strong> will be sent
|
|
back. By default this will be <strong>SSL_AD_UNKNOWN_PSK_IDENTITY</strong>.</p>
|
|
<p>The <code>SSL_CTX_set_srp_client_pwd_callback()</code> function sets the client password
|
|
callback on the client.
|
|
The callback parameters are the SSL connection <strong>s</strong> and the extra argument <strong>arg</strong>
|
|
set by <code>SSL_CTX_set_srp_cb_arg()</code>.
|
|
The callback will be called as part of the generation of the client secrets.
|
|
It should return the client password in text form or NULL to abort the connection.
|
|
The resulting memory will be freed by the library as part of the callback resolution.
|
|
This overrides the effect of <code>SSL_CTX_set_srp_password()</code>.</p>
|
|
<p>The <code>SSL_CTX_set_srp_verify_param_callback()</code> sets the SRP gN parameter verification
|
|
callback on the client. This allows the client to perform custom verification when
|
|
receiving the server SRP proposed parameters.
|
|
The callback parameters are the SSL connection <strong>s</strong> and the extra argument <strong>arg</strong>
|
|
set by <code>SSL_CTX_set_srp_cb_arg()</code>.
|
|
The callback should return a positive value to accept the server parameters.
|
|
Returning 0 or a negative value will abort the connection. The server parameters
|
|
can be obtained by calling <code>SSL_get_srp_N()</code> and <code>SSL_get_srp_g()</code>.
|
|
Sanity checks are already performed by the library after the handshake
|
|
(B % N non zero, check against the strength parameter) and are not necessary.
|
|
If no callback is set the g and N parameters will be checked against
|
|
known <a href="http://www.ietf.org/rfc/rfc5054.txt" class="rfc">RFC 5054</a> values.</p>
|
|
<p>The <code>SSL_set_srp_server_param()</code> function sets all SRP parameters for
|
|
the connection <strong>s</strong>. <strong>N</strong> and <strong>g</strong> are the SRP group parameters, <strong>sa</strong> is the
|
|
user salt, <strong>v</strong> the password verifier and <strong>info</strong> is the optional user info.</p>
|
|
<p>The <code>SSL_set_srp_server_param_pw()</code> function sets all SRP parameters for the
|
|
connection <strong>s</strong> by generating a random salt and a password verifier.
|
|
<strong>user</strong> is the username, <strong>pass</strong> the password and <strong>grp</strong> the SRP group parameters
|
|
identifier for <em>SRP_get_default_gN(3)</em>.</p>
|
|
<p>The <code>SSL_get_srp_g()</code> function returns the SRP group generator for <strong>s</strong>, or from
|
|
the underlying SSL_CTX if it is NULL.</p>
|
|
<p>The <code>SSL_get_srp_N()</code> function returns the SRP prime for <strong>s</strong>, or from
|
|
the underlying SSL_CTX if it is NULL.</p>
|
|
<p>The <code>SSL_get_srp_username()</code> function returns the SRP username for <strong>s</strong>, or from
|
|
the underlying SSL_CTX if it is NULL.</p>
|
|
<p>The <code>SSL_get_srp_userinfo()</code> function returns the SRP user info for <strong>s</strong>, or from
|
|
the underlying SSL_CTX if it is NULL.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p>All SSL_CTX_set_* functions return 1 on success and 0 on failure.</p>
|
|
<p><code>SSL_set_srp_server_param()</code> returns 1 on success and -1 on failure.</p>
|
|
<p>The SSL_get_SRP_* functions return a pointer to the requested data, the memory
|
|
is owned by the library and should not be freed by the caller.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="examples">EXAMPLES</a></h1>
|
|
<p>Setup SRP parameters on the client:</p>
|
|
<pre>
|
|
#include <openssl/ssl.h></pre>
|
|
<pre>
|
|
const char *username = "username";
|
|
const char *password = "password";</pre>
|
|
<pre>
|
|
SSL_CTX *ctx = SSL_CTX_new(TLS_client_method());
|
|
if (!ctx)
|
|
/* Error */
|
|
if (!SSL_CTX_set_srp_username(ctx, username))
|
|
/* Error */
|
|
if (!SSL_CTX_set_srp_password(ctx, password))
|
|
/* Error */</pre>
|
|
<p>Setup SRP server with verifier file:</p>
|
|
<pre>
|
|
#include <openssl/srp.h>
|
|
#include <openssl/ssl.h></pre>
|
|
<pre>
|
|
const char *srpvfile = "password.srpv";</pre>
|
|
<pre>
|
|
int srpServerCallback(SSL *s, int *ad, void *arg)
|
|
{
|
|
SRP_VBASE *srpData = (SRP_VBASE*) arg;
|
|
char *username = SSL_get_srp_username(s);</pre>
|
|
<pre>
|
|
SRP_user_pwd *user_pwd = SRP_VBASE_get1_by_user(srpData, username);
|
|
if (!user_pwd)
|
|
/* Error */
|
|
return SSL3_AL_FATAL;</pre>
|
|
<pre>
|
|
if (SSL_set_srp_server_param(s, user_pwd->N, user_pwd->g,
|
|
user_pwd->s, user_pwd->v, user_pwd->info) < 0)
|
|
/* Error */</pre>
|
|
<pre>
|
|
SRP_user_pwd_free(user_pwd);
|
|
return SSL_ERROR_NONE;
|
|
}</pre>
|
|
<pre>
|
|
SSL_CTX *ctx = SSL_CTX_new(TLS_server_method());
|
|
if (!ctx)
|
|
/* Error */</pre>
|
|
<pre>
|
|
/*
|
|
* seedKey should contain a NUL terminated sequence
|
|
* of random non NUL bytes
|
|
*/
|
|
const char *seedKey;</pre>
|
|
<pre>
|
|
SRP_VBASE *srpData = SRP_VBASE_new(seedKey);
|
|
if (SRP_VBASE_init(srpData, (char*) srpvfile) != SRP_NO_ERROR)
|
|
/* Error */</pre>
|
|
<pre>
|
|
SSL_CTX_set_srp_cb_arg(ctx, srpData);
|
|
SSL_CTX_set_srp_username_callback(ctx, srpServerCallback);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>ssl(7)</em>,
|
|
<em>openssl-srp(1)</em>,
|
|
<em>SRP_VBASE_new(3)</em>,
|
|
<em>SRP_create_verifier(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>These functions were added in OpenSSL 1.0.1.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 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>
|