| <DRAFT!> |
| 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. |
| |
| 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.. 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. |
| |
| See http://www.ietf.org/rfc/rfc3820.txt for more information. |
| |
| |
| 2. A warning about proxy certificates |
| |
| Noone seems to have tested proxy certificates with security in mind. |
| Basically, to this date, it seems that proxy certificates have only |
| been used in a world that's highly aware of them. What would happen |
| if an unsuspecting application is to validate a chain of certificates |
| that contains proxy certificates? It would usually consider the leaf |
| to be the certificate to check for authorisation data, and since proxy |
| certificates are controlled by the EE certificate owner alone, it's |
| would be normal to consider what the EE certificate owner could do |
| with them. |
| |
| 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 are, as far as has been imagined so far: |
| |
| - 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 this reason, OpenSSL requires that the use of proxy certificates |
| be explicitely allowed. Currently, this can be done using the |
| following methods: |
| |
| - if the application calls X509_verify_cert() itself, it can do the |
| following prior to that call (ctx is the pointer passed in the call |
| to X509_verify_cert()): |
| |
| X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS); |
| |
| - in all other cases, proxy certificate validation can be enabled |
| before starting the application by setting the envirnoment variable |
| OPENSSL_ALLOW_PROXY with some non-empty value. |
| |
| There are thoughts to allow proxy certificates with a line in the |
| default openssl.cnf, but that's still in the future. |
| |
| |
| 3. How to create proxy cerificates |
| |
| 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: |
| |
| [ v3_proxy ] |
| # A proxy certificate MUST NEVER be a CA certificate. |
| basicConstraints=CA:FALSE |
| |
| # Usual authority key ID |
| authorityKeyIdentifier=keyid,issuer:always |
| |
| # Now, for the extension that marks this certificate as a proxy one |
| proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB |
| |
| It's also possible to give 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 recognised |
| syntags are as follows: |
| |
| text indicates that the string is simply the bytes, not |
| encoded in any kind of way: |
| |
| 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: |
| |
| policy=text:räksmörgås |
| |
| 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 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. |
| |
| The 'policy' setting can be split up in multiple lines like this: |
| |
| 0.policy=This is |
| 1.polisy= 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! |
| |
| Now that you have created an extension section for your proxy |
| certificate, you can now easily create a proxy certificate like this: |
| |
| 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): |
| |
| 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 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 slightly complicated part is 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 structure of data that's 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. |
| |
| This is some cookbook code for you to fill in: |
| |
| /* 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]; |
| } 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) |
| { |
| 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); |
| } |
| CRYPTO_w_unlock(CRYPTO_LOCK_X509_STORE); |
| } |
| 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)) |
| { |
| 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 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); |
| } |
| } |
| 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); |
| 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 |