diff options
author | Richard Levitte <levitte@openssl.org> | 2019-11-23 10:36:16 +0100 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2019-11-27 16:21:15 +0100 |
commit | 40d422fd3a685c3e1e62ab37eda1189567d000b5 (patch) | |
tree | 5621fc25e6be2b1aecfe186143a8cb72bc728b6b | |
parent | 984cff6ba52655cf8242b3ef6b4e97a5e8b33266 (diff) |
doc/man7/proxy-certificates.pod: New guide for proxy certificates
This replaces doc/HOWTO/proxy_certificates.txt
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10507)
(cherry picked from commit 2a03823606b2d7e73e5dc890c3202e186511151f)
-rw-r--r-- | doc/HOWTO/proxy_certificates.txt | 319 | ||||
-rw-r--r-- | doc/man7/proxy-certificates.pod | 363 |
2 files changed, 363 insertions, 319 deletions
diff --git a/doc/HOWTO/proxy_certificates.txt b/doc/HOWTO/proxy_certificates.txt deleted file mode 100644 index 3c42349261..0000000000 --- a/doc/HOWTO/proxy_certificates.txt +++ /dev/null @@ -1,319 +0,0 @@ - HOWTO proxy certificates - -0. WARNING - -NONE OF THE CODE PRESENTED HERE HAS BEEN CHECKED! The code is just examples to -show you how things could be done. There might be typos or type conflicts, and -you will have to resolve them. - -1. Introduction - -Proxy certificates are defined in RFC 3820. They are really usual certificates -with the mandatory extension proxyCertInfo. - -Proxy certificates are issued by an End Entity (typically a user), either -directly with the EE certificate as issuing certificate, or by extension through -an already issued proxy certificate. Proxy certificates 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 certificate. - -See https://www.ietf.org/rfc/rfc3820.txt for more information. - - -2. A warning about proxy certificates - -No one seems to have tested proxy certificates with security in mind. To this -date, it seems that proxy certificates have only been used in a context highly -aware of them. - -Existing applications might misbehave when trying to validate a chain of -certificates which use a proxy certificate. They might incorrectly consider the -leaf to be the certificate to check for authorisation data, which is controlled -by the EE certificate owner. - -subjectAltName and issuerAltName 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. - -Possible threats we can think of at this time include: - - - impersonation through commonName (think server certificates). - - use of additional extensions, possibly non-standard ones used in certain - environments, that would grant extra or different authorisation rights. - -For these reasons, OpenSSL requires that the use of proxy certificates be -explicitly allowed. Currently, this can be done using the following methods: - - - if the application directly calls X509_verify_cert(), it can first call: - - X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS); - - Where ctx is the pointer which then gets passed to X509_verify_cert(). - - - proxy certificate validation can be enabled before starting the application - by setting the environment variable OPENSSL_ALLOW_PROXY_CERTS. - -In the future, it might be possible to enable proxy certificates by editing -openssl.cnf. - - -3. How to create proxy certificates - -Creating proxy certificates is quite easy, by taking advantage of a lack of -checks in the 'openssl x509' application (*ahem*). You must first create a -configuration section that contains a definition of the proxyCertInfo extension, -for example: - - [ v3_proxy ] - # A proxy certificate MUST NEVER be a CA certificate. - basicConstraints=CA:FALSE - - # Usual authority key ID - authorityKeyIdentifier=keyid,issuer:always - - # The extension which marks this certificate as a proxy - proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB - -It's also possible to specify the proxy extension in a separate section: - - proxyCertInfo=critical,@proxy_ext - - [ proxy_ext ] - language=id-ppl-anyLanguage - pathlen=0 - policy=text:BC - -The policy value has a specific syntax, {syntag}:{string}, where the syntag -determines what will be done with the string. The following syntags are -recognised: - - text indicates that the string is simply bytes, without any encoding: - - policy=text:räksmörgås - - Previous versions of this design had a specific tag for UTF-8 text. - However, since the bytes are copied as-is anyway, there is no need for - such a specific tag. - - hex indicates the string is encoded in hex, with colons between each byte - (every second hex digit): - - policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73 - - Previous versions of this design had a tag to insert a complete DER - blob. However, the only legal use for this would be to surround the - bytes that would go with the hex: tag with whatever is needed to - construct a correct OCTET STRING. The DER tag therefore felt - superfluous, and was removed. - - file indicates that the text of the policy should really be taken from a - file. The string is then really a file name. This is useful for - policies that are large (more than a few lines, e.g. XML documents). - -The 'policy' setting can be split up in multiple lines like this: - - 0.policy=This is - 1.policy= a multi- - 2.policy=line policy. - -NOTE: the proxy policy value is the part which determines the rights granted to -the process using the proxy certificate. The value is completely dependent on -the application reading and interpreting it! - -Now that you have created an extension section for your proxy certificate, you -can easily create a proxy certificate by doing: - - openssl req -new -config openssl.cnf -out proxy.req -keyout proxy.key - openssl x509 -req -CAcreateserial -in proxy.req -days 7 -out proxy.crt \ - -CA user.crt -CAkey user.key -extfile openssl.cnf -extensions v3_proxy - -You can also create a proxy certificate using another proxy certificate as -issuer (note: I'm using a different configuration section for it): - - openssl req -new -config openssl.cnf -out proxy2.req -keyout proxy2.key - openssl x509 -req -CAcreateserial -in proxy2.req -days 7 -out proxy2.crt \ - -CA proxy.crt -CAkey proxy.key -extfile openssl.cnf -extensions v3_proxy2 - - -4. How to have your application interpret the policy? - -The basic way to interpret proxy policies is to start with some default rights, -then compute the resulting rights by checking the proxy certificate against -the chain of proxy certificates, user certificate and CA certificates. You then -use the final computed rights. Sounds easy, huh? It almost is. - -The slightly complicated part is figuring out how to pass data between your -application and the certificate validation procedure. - -You need the following ingredients: - - - a callback function that will be called for every certificate being - validated. The callback be 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. - - - a data structure that is shared between your application code and the - callback. - - - a wrapper function that sets it all up. - - - an ex_data index function that creates an index into the generic ex_data - store that is attached to an X509 validation context. - -Here is some skeleton code you can fill in: - - #include <string.h> - #include <netdb.h> - #include <openssl/x509.h> - #include <openssl/x509v3.h> - - #define total_rights 25 - - /* - * 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; - - /* - * 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; - 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; - } - - /* 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); - - 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); - - 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)); - - /* - * 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); - - 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)); - - /* 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; - } - - 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; - - 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); - - if (ok == 1) { - ok = check_needed_rights(rights, needed_rights); - } - - X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb); - - return ok; - } - - -If you use SSL or TLS, you can easily set up a callback to have the -certificates checked properly, using the code above: - - SSL_CTX_set_cert_verify_callback(s_ctx, my_X509_verify_cert, &needed_rights); - - --- -Richard Levitte diff --git a/doc/man7/proxy-certificates.pod b/doc/man7/proxy-certificates.pod new file mode 100644 index 0000000000..df5ee1b4b5 --- /dev/null +++ b/doc/man7/proxy-certificates.pod @@ -0,0 +1,363 @@ +=pod + +=encoding UTF-8 + +=head1 NAME + +proxy-certificates - Proxy certificates in OpenSSL + +=head1 DESCRIPTION + +Proxy certificates are defined in RFC 3820. 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. + +The requirements for a valid proxy certificate are: + +=over 4 + +=item * + +They are issued by an End Entity, either a normal EE certificate, or +another proxy certificate. + +=item * + +They must not have the B<subjectAltName> or B<issuerAltName> +extensions. + +=item * + +They must have the B<proxyCertInfo> extension. + +=item * + +They must have the subject of their issuer, with one B<commonName> +added. + +=back + +=head2 Enabling proxy certificate verification + +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: + + X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS); + +or + + X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_ALLOW_PROXY_CERTS); + +See L</NOTES> for a discussion on this requirement. + +=head2 Creating proxy certificates + +Creating proxy certificates can be done using the L<openssl-x509(1)> +command, with some extra extensions: + + [ v3_proxy ] + # A proxy certificate MUST NEVER be a CA certificate. + basicConstraints=CA:FALSE + + # Usual authority key ID + authorityKeyIdentifier=keyid,issuer:always + + # The extension which marks this certificate as a proxy + proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB + +It's also possible to specify the proxy extension in a separate section: + + proxyCertInfo=critical,@proxy_ext + + [ proxy_ext ] + language=id-ppl-anyLanguage + pathlen=0 + policy=text:BC + +The policy value has a specific syntax, I<syntag>:I<string>, where the +I<syntag> determines what will be done with the string. The following +I<syntag>s are recognised: + +=over 4 + +=item B<text> + +indicates that the string is a byte sequence, without any encoding: + + policy=text:räksmörgås + +=item B<hex> + +indicates the string is encoded hexadecimal encoded binary data, with +colons between each byte (every second hex digit): + + policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73 + +=item B<file> + +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). + +=back + +I<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.> + +With a proxy extension, creating a proxy certificate is a matter of +two commands: + + openssl req -new -config proxy.cnf \ + -out proxy.req -keyout proxy.key \ + -subj "/DC=org/DC=openssl/DC=users/CN=proxy 1" + + openssl x509 -req -CAcreateserial -in proxy.req -out proxy.crt \ + -CA user.crt -CAkey user.key -days 7 \ + -extfile proxy.cnf -extensions v3_proxy1 + +You can also create a proxy certificate using another proxy +certificate as issuer (note: using a different configuration +section for the proxy extensions): + + 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" + + openssl x509 -req -CAcreateserial -in proxy2.req -out proxy2.crt \ + -CA proxy.crt -CAkey proxy.key -days 7 \ + -extfile proxy.cnf -extensions v3_proxy2 + +=head2 Using proxy certs in applications + +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. + +The complicated part is figuring out how to pass data between your +application and the certificate validation procedure. + +The following ingredients are needed for such processing: + +=over 4 + +=item * + +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. + +=item * + +a data structure that is shared between your application code and the +callback. + +=item * + +a wrapper function that sets it all up. + +=item * + +an ex_data index function that creates an index into the generic +ex_data store that is attached to an X509 validation context. + +=back + +The following skeleton code can be used as a starting point: + + #include <string.h> + #include <netdb.h> + #include <openssl/x509.h> + #include <openssl/x509v3.h> + + #define total_rights 25 + + /* + * 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; + + /* + * 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; + + 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; + } + + /* 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); + + 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); + + 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)); + + /* + * 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); + + 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)); + + /* + * 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; + } + + 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; + + 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); + + if (ok == 1) { + ok = check_needed_rights(rights, needed_rights); + } + + X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb); + + return ok; + } + +If you use SSL or TLS, you can easily set up a callback to have the +certificates checked properly, using the code above: + + SSL_CTX_set_cert_verify_callback(s_ctx, my_X509_verify_cert, + &needed_rights); + +=head1 NOTES + +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. + +For that reason, OpenSSL requires that applications aware of proxy +certificates must also make that explicit. + +B<subjectAltName> and B<issuerAltName> 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. + +=head1 SEE ALSO + +L<X509_STORE_CTX_set_flags(3)>, +L<X509_STORE_CTX_set_verify_cb(3)>, +L<X509_VERIFY_PARAM_set_flags(3)>, +L<SSL_CTX_set_cert_verify_callback(3)>, +L<openssl-req(1)>, L<openssl-x509(1)>, +L<RFC 3820|https://tools.ietf.org/html/rfc3820> + +=head1 COPYRIGHT + +Copyright 2019 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 +L<https://www.openssl.org/source/license.html>. + +=cut |