378 lines
14 KiB
HTML
Executable File
378 lines
14 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>proxy-certificates</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="#description">DESCRIPTION</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#enabling_proxy_certificate_verification">Enabling proxy certificate verification</a></li>
|
|
<li><a href="#creating_proxy_certificates">Creating proxy certificates</a></li>
|
|
<li><a href="#using_proxy_certs_in_applications">Using proxy certs in applications</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#notes">NOTES</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>proxy-certificates - Proxy certificates in OpenSSL</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>Proxy certificates are defined in <a href="http://www.ietf.org/rfc/rfc3820.txt" class="rfc">RFC 3820</a>. They are used to
|
|
extend rights to some other entity (a computer process, typically, or
|
|
sometimes to the user itself). This allows the entity to perform
|
|
operations on behalf of the owner of the EE (End Entity) certificate.</p>
|
|
<p>The requirements for a valid proxy certificate are:</p>
|
|
<ul>
|
|
<li>
|
|
<p>They are issued by an End Entity, either a normal EE certificate, or
|
|
another proxy certificate.</p>
|
|
</li>
|
|
<li>
|
|
<p>They must not have the <strong>subjectAltName</strong> or <strong>issuerAltName</strong>
|
|
extensions.</p>
|
|
</li>
|
|
<li>
|
|
<p>They must have the <strong>proxyCertInfo</strong> extension.</p>
|
|
</li>
|
|
<li>
|
|
<p>They must have the subject of their issuer, with one <strong>commonName</strong>
|
|
added.</p>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
</p>
|
|
<h2><a name="enabling_proxy_certificate_verification">Enabling proxy certificate verification</a></h2>
|
|
<p>OpenSSL expects applications that want to use proxy certificates to be
|
|
specially aware of them, and make that explicit. This is done by
|
|
setting an X509 verification flag:</p>
|
|
<pre>
|
|
X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);</pre>
|
|
<p>or</p>
|
|
<pre>
|
|
X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_ALLOW_PROXY_CERTS);</pre>
|
|
<p>See <a href="#notes">NOTES</a> for a discussion on this requirement.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="creating_proxy_certificates">Creating proxy certificates</a></h2>
|
|
<p>Creating proxy certificates can be done using the <em>openssl-x509(1)</em>
|
|
command, with some extra extensions:</p>
|
|
<pre>
|
|
[ v3_proxy ]
|
|
# A proxy certificate MUST NEVER be a CA certificate.
|
|
basicConstraints=CA:FALSE</pre>
|
|
<pre>
|
|
# Usual authority key ID
|
|
authorityKeyIdentifier=keyid,issuer:always</pre>
|
|
<pre>
|
|
# The extension which marks this certificate as a proxy
|
|
proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB</pre>
|
|
<p>It's also possible to specify the proxy extension in a separate section:</p>
|
|
<pre>
|
|
proxyCertInfo=critical,@proxy_ext</pre>
|
|
<pre>
|
|
[ proxy_ext ]
|
|
language=id-ppl-anyLanguage
|
|
pathlen=0
|
|
policy=text:BC</pre>
|
|
<p>The policy value has a specific syntax, <em>syntag</em>:<em>string</em>, where the
|
|
<em>syntag</em> determines what will be done with the string. The following
|
|
<em>syntag</em>s are recognised:</p>
|
|
<dl>
|
|
<dt><strong><a name="text" class="item"><strong>text</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>indicates that the string is a byte sequence, without any encoding:</p>
|
|
<pre>
|
|
policy=text:räksmörgås</pre>
|
|
</dd>
|
|
<dt><strong><a name="hex" class="item"><strong>hex</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>indicates the string is encoded hexadecimal encoded binary data, with
|
|
colons between each byte (every second hex digit):</p>
|
|
<pre>
|
|
policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73</pre>
|
|
</dd>
|
|
<dt><strong><a name="file" class="item"><strong>file</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>indicates that the text of the policy should be taken from a file.
|
|
The string is then a filename. This is useful for policies that are
|
|
large (more than a few lines, e.g. XML documents).</p>
|
|
</dd>
|
|
</dl>
|
|
<p><em>NOTE: The proxy policy value is what determines the rights granted
|
|
to the process during the proxy certificate. It's up to the
|
|
application to interpret and combine these policies.</em></p>
|
|
<p>With a proxy extension, creating a proxy certificate is a matter of
|
|
two commands:</p>
|
|
<pre>
|
|
openssl req -new -config proxy.cnf \
|
|
-out proxy.req -keyout proxy.key \
|
|
-subj "/DC=org/DC=openssl/DC=users/CN=proxy 1"</pre>
|
|
<pre>
|
|
openssl x509 -req -CAcreateserial -in proxy.req -out proxy.crt \
|
|
-CA user.crt -CAkey user.key -days 7 \
|
|
-extfile proxy.cnf -extensions v3_proxy1</pre>
|
|
<p>You can also create a proxy certificate using another proxy
|
|
certificate as issuer (note: using a different configuration
|
|
section for the proxy extensions):</p>
|
|
<pre>
|
|
openssl req -new -config proxy.cnf \
|
|
-out proxy2.req -keyout proxy2.key \
|
|
-subj "/DC=org/DC=openssl/DC=users/CN=proxy 1/CN=proxy 2"</pre>
|
|
<pre>
|
|
openssl x509 -req -CAcreateserial -in proxy2.req -out proxy2.crt \
|
|
-CA proxy.crt -CAkey proxy.key -days 7 \
|
|
-extfile proxy.cnf -extensions v3_proxy2</pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="using_proxy_certs_in_applications">Using proxy certs in applications</a></h2>
|
|
<p>To interpret proxy policies, the application would normally start with
|
|
some default rights (perhaps none at all), then compute the resulting
|
|
rights by checking the rights against the chain of proxy certificates,
|
|
user certificate and CA certificates.</p>
|
|
<p>The complicated part is figuring out how to pass data between your
|
|
application and the certificate validation procedure.</p>
|
|
<p>The following ingredients are needed for such processing:</p>
|
|
<ul>
|
|
<li>
|
|
<p>a callback function that will be called for every certificate being
|
|
validated. The callback is called several times for each certificate,
|
|
so you must be careful to do the proxy policy interpretation at the
|
|
right time. You also need to fill in the defaults when the EE
|
|
certificate is checked.</p>
|
|
</li>
|
|
<li>
|
|
<p>a data structure that is shared between your application code and the
|
|
callback.</p>
|
|
</li>
|
|
<li>
|
|
<p>a wrapper function that sets it all up.</p>
|
|
</li>
|
|
<li>
|
|
<p>an ex_data index function that creates an index into the generic
|
|
ex_data store that is attached to an X509 validation context.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The following skeleton code can be used as a starting point:</p>
|
|
<pre>
|
|
#include <string.h>
|
|
#include <netdb.h>
|
|
#include <openssl/x509.h>
|
|
#include <openssl/x509v3.h></pre>
|
|
<pre>
|
|
#define total_rights 25</pre>
|
|
<pre>
|
|
/*
|
|
* In this example, I will use a view of granted rights as a bit
|
|
* array, one bit for each possible right.
|
|
*/
|
|
typedef struct your_rights {
|
|
unsigned char rights[(total_rights + 7) / 8];
|
|
} YOUR_RIGHTS;</pre>
|
|
<pre>
|
|
/*
|
|
* The following procedure will create an index for the ex_data
|
|
* store in the X509 validation context the first time it's
|
|
* called. Subsequent calls will return the same index.
|
|
*/
|
|
static int get_proxy_auth_ex_data_idx(X509_STORE_CTX *ctx)
|
|
{
|
|
static volatile int idx = -1;</pre>
|
|
<pre>
|
|
if (idx < 0) {
|
|
X509_STORE_lock(X509_STORE_CTX_get0_store(ctx));
|
|
if (idx < 0) {
|
|
idx = X509_STORE_CTX_get_ex_new_index(0,
|
|
"for verify callback",
|
|
NULL,NULL,NULL);
|
|
}
|
|
X509_STORE_unlock(X509_STORE_CTX_get0_store(ctx));
|
|
}
|
|
return idx;
|
|
}</pre>
|
|
<pre>
|
|
/* Callback to be given to the X509 validation procedure. */
|
|
static int verify_callback(int ok, X509_STORE_CTX *ctx)
|
|
{
|
|
if (ok == 1) {
|
|
/*
|
|
* It's REALLY important you keep the proxy policy check
|
|
* within this section. It's important to know that when
|
|
* ok is 1, the certificates are checked from top to
|
|
* bottom. You get the CA root first, followed by the
|
|
* possible chain of intermediate CAs, followed by the EE
|
|
* certificate, followed by the possible proxy
|
|
* certificates.
|
|
*/
|
|
X509 *xs = X509_STORE_CTX_get_current_cert(ctx);</pre>
|
|
<pre>
|
|
if (X509_get_extension_flags(xs) & EXFLAG_PROXY) {
|
|
YOUR_RIGHTS *rights =
|
|
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
|
|
get_proxy_auth_ex_data_idx(ctx));
|
|
PROXY_CERT_INFO_EXTENSION *pci =
|
|
X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL);</pre>
|
|
<pre>
|
|
switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage)) {
|
|
case NID_Independent:
|
|
/*
|
|
* Do whatever you need to grant explicit rights
|
|
* to this particular proxy certificate, usually
|
|
* by pulling them from some database. If there
|
|
* are none to be found, clear all rights (making
|
|
* this and any subsequent proxy certificate void
|
|
* of any rights).
|
|
*/
|
|
memset(rights->rights, 0, sizeof(rights->rights));
|
|
break;
|
|
case NID_id_ppl_inheritAll:
|
|
/*
|
|
* This is basically a NOP, we simply let the
|
|
* current rights stand as they are.
|
|
*/
|
|
break;
|
|
default:
|
|
/*
|
|
* This is usually the most complex section of
|
|
* code. You really do whatever you want as long
|
|
* as you follow RFC 3820. In the example we use
|
|
* here, the simplest thing to do is to build
|
|
* another, temporary bit array and fill it with
|
|
* the rights granted by the current proxy
|
|
* certificate, then use it as a mask on the
|
|
* accumulated rights bit array, and voilà, you
|
|
* now have a new accumulated rights bit array.
|
|
*/
|
|
{
|
|
int i;
|
|
YOUR_RIGHTS tmp_rights;
|
|
memset(tmp_rights.rights, 0,
|
|
sizeof(tmp_rights.rights));</pre>
|
|
<pre>
|
|
/*
|
|
* process_rights() is supposed to be a
|
|
* procedure that takes a string and its
|
|
* length, interprets it and sets the bits
|
|
* in the YOUR_RIGHTS pointed at by the
|
|
* third argument.
|
|
*/
|
|
process_rights((char *) pci->proxyPolicy->policy->data,
|
|
pci->proxyPolicy->policy->length,
|
|
&tmp_rights);</pre>
|
|
<pre>
|
|
for(i = 0; i < total_rights / 8; i++)
|
|
rights->rights[i] &= tmp_rights.rights[i];
|
|
}
|
|
break;
|
|
}
|
|
PROXY_CERT_INFO_EXTENSION_free(pci);
|
|
} else if (!(X509_get_extension_flags(xs) & EXFLAG_CA)) {
|
|
/* We have an EE certificate, let's use it to set default! */
|
|
YOUR_RIGHTS *rights =
|
|
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
|
|
get_proxy_auth_ex_data_idx(ctx));</pre>
|
|
<pre>
|
|
/*
|
|
* The following procedure finds out what rights the
|
|
* owner of the current certificate has, and sets them
|
|
* in the YOUR_RIGHTS structure pointed at by the
|
|
* second argument.
|
|
*/
|
|
set_default_rights(xs, rights);
|
|
}
|
|
}
|
|
return ok;
|
|
}</pre>
|
|
<pre>
|
|
static int my_X509_verify_cert(X509_STORE_CTX *ctx,
|
|
YOUR_RIGHTS *needed_rights)
|
|
{
|
|
int ok;
|
|
int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) =
|
|
X509_STORE_CTX_get_verify_cb(ctx);
|
|
YOUR_RIGHTS rights;</pre>
|
|
<pre>
|
|
X509_STORE_CTX_set_verify_cb(ctx, verify_callback);
|
|
X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(ctx),
|
|
&rights);
|
|
X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
|
|
ok = X509_verify_cert(ctx);</pre>
|
|
<pre>
|
|
if (ok == 1) {
|
|
ok = check_needed_rights(rights, needed_rights);
|
|
}</pre>
|
|
<pre>
|
|
X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb);</pre>
|
|
<pre>
|
|
return ok;
|
|
}</pre>
|
|
<p>If you use SSL or TLS, you can easily set up a callback to have the
|
|
certificates checked properly, using the code above:</p>
|
|
<pre>
|
|
SSL_CTX_set_cert_verify_callback(s_ctx, my_X509_verify_cert,
|
|
&needed_rights);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>To this date, it seems that proxy certificates have only been used in
|
|
environments that are aware of them, and no one seems to have
|
|
investigated how they can be used or misused outside of such an
|
|
environment.</p>
|
|
<p>For that reason, OpenSSL requires that applications aware of proxy
|
|
certificates must also make that explicit.</p>
|
|
<p><strong>subjectAltName</strong> and <strong>issuerAltName</strong> are forbidden in proxy
|
|
certificates, and this is enforced in OpenSSL. The subject must be
|
|
the same as the issuer, with one commonName added on.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>X509_STORE_CTX_set_flags(3)</em>,
|
|
<em>X509_STORE_CTX_set_verify_cb(3)</em>,
|
|
<em>X509_VERIFY_PARAM_set_flags(3)</em>,
|
|
<em>SSL_CTX_set_cert_verify_callback(3)</em>,
|
|
<em>openssl-req(1)</em>, <em>openssl-x509(1)</em>,
|
|
<em>RFC 3820</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2019 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>
|