X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2FHOWTO%2Fproxy_certificates.txt;h=642bec92876ec7720d88bb22e02b44cb683c8ec1;hp=fbb6e953b53f5f044e1efaa886fd7701bf5d3d32;hb=af7e05c7c60b87723efccc01f6d03ebc07cdd93c;hpb=d18685d9592144d395bb18d38a588824266415fc diff --git a/doc/HOWTO/proxy_certificates.txt b/doc/HOWTO/proxy_certificates.txt index fbb6e953b5..642bec9287 100644 --- a/doc/HOWTO/proxy_certificates.txt +++ b/doc/HOWTO/proxy_certificates.txt @@ -1,33 +1,69 @@ - HOWTO proxy certificates 0. WARNING -NONE OF THE CODE PRESENTED HERE HAVE BEEN CHECKED! They are just an -example to show you how things can be done. There may be typos or -type conflicts, and you will have to resolve them. +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 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.. They are used -to extend rights to some other entity (a computer process, typically, -or sometimes to the user itself), so it can perform operations in the -name of the owner of the EE certificate. +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 http://www.ietf.org/rfc/rfc3820.txt for more information. -2. How to create proxy cerificates +2. A warning about proxy certificates -It's quite easy to create proxy certificates, by taking advantage of -the lack of checks of the 'openssl x509' application (*ahem*). But -first, you need to create a configuration section that contains a -definition of the proxyCertInfo extension, a little like this: +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. @@ -36,10 +72,10 @@ definition of the proxyCertInfo extension, a little like this: # Usual authority key ID authorityKeyIdentifier=keyid,issuer:always - # Now, for the extension that marks this certificate as a proxy one + # 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 give the proxy extension in a separate section: +It's also possible to specify the proxy extension in a separate section: proxyCertInfo=critical,@proxy_ext @@ -48,228 +84,231 @@ It's also possible to give the proxy extension in a separate section: 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 recognised -syntags are as follows: +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 the bytes, not - encoded in any kind of way: + text indicates that the string is simply bytes, without any encoding: - policy=text:räksmörgås + 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's no need for it. Instead, use - the text: tag, like this: + 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. - policy=text:räksmörgÃ¥s + hex indicates the string is encoded in hex, with colons between each byte + (every second hex digit): - 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 - 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. - 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 what's needed to construct a correct - OCTET STRING. Since hex: does that, the DER tag felt - superfluous, and was therefore 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 of lines) XML documents, for example. + 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.polisy= a multi- + 1.policy= a multi- 2.policy=line policy. -NOTE: the proxy policy value is the part that determines the rights -granted to the process using the proxy certificate. The value is -completely dependent on the application reading and interpretting it! +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 now easily create a proxy certificate like this: +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 + 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 -It's just as easy to create a proxy certificate using another proxy -certificate as issuer (note that I'm using a different configuration -section for it): +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 + 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 -3. How to have your application interpret the policy? +4. How to have your application interpret the policy? -The basic way to interpret proxy policies is to prepare some default -rights, then do a check of the proxy certificate against the a chain -of proxy certificates, user certificate and CA certificates, and see -what rights came out by the end. Sounds easy, huh? It almost is. +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 how to pass data between your +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 routing that will be called for every certificate that's - validated. It will be called several times for each certificates, - so you must be attentive to when it's a good time to do the proxy - policy interpretation and check, as well as to fill in the defaults - when the EE certificate is checked. + - 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 structure of data that's shared between your application code and - the callback. + - 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's attached to an X509 validation context. + - 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: -This is some cookbook code for you to fill in: + #include + #include + #include + #include - /* In this example, I will use a view of granted rights as a bit - array, one bit for each possible right. */ + #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 / 8]; + 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(void) + /* + * 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) - { - CRYPTO_w_lock(CRYPTO_LOCK_X509_STORE); - if (idx < 0) - { - idx = X509_STORE_CTX_get_ex_new_index(0, - "for verify callback", - NULL,NULL,NULL); + 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); } - CRYPTO_w_unlock(CRYPTO_LOCK_X509_STORE); + X509_STORE_unlock(X509_STORE_CTX_get0_store(ctx)); } - return idx; + 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 secion. 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 = ctx->current_cert; - - if (xs->ex_flags & EXFLAG_PROXY) - { - YOUR_RIGHTS *rights = - (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx, - get_proxy_auth_ex_data_idx()); - PROXY_CERT_INFO_EXTENSION *pci = - X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL); - - switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage)) - { + 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; + /* + * 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; + /* + * 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 it's 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; + /* 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 it's 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 (!(xs->ex_flags & EXFLAG_CA)) - { - /* We have a 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()); - - /* 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); + 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; + return ok; } static int my_X509_verify_cert(X509_STORE_CTX *ctx, YOUR_RIGHTS *needed_rights) { - int i; - int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) = ctx->verify_cb; - 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(), &rights); - ok = X509_verify_cert(ctx); - - if (ok == 1) - { - ok = check_needed_rights(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); + X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb); - return ok; + 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: