proxy_certificates.txt revision 285830
1 HOWTO proxy certificates 2 30. WARNING 4 5NONE OF THE CODE PRESENTED HERE HAS BEEN CHECKED! The code is just examples to 6show you how things could be done. There might be typos or type conflicts, and 7you will have to resolve them. 8 91. Introduction 10 11Proxy certificates are defined in RFC 3820. They are really usual certificates 12with the mandatory extension proxyCertInfo. 13 14Proxy certificates are issued by an End Entity (typically a user), either 15directly with the EE certificate as issuing certificate, or by extension through 16an already issued proxy certificate. Proxy certificates are used to extend 17rights to some other entity (a computer process, typically, or sometimes to the 18user itself). This allows the entity to perform operations on behalf of the 19owner of the EE certificate. 20 21See http://www.ietf.org/rfc/rfc3820.txt for more information. 22 23 242. A warning about proxy certificates 25 26No one seems to have tested proxy certificates with security in mind. To this 27date, it seems that proxy certificates have only been used in a context highly 28aware of them. 29 30Existing applications might misbehave when trying to validate a chain of 31certificates which use a proxy certificate. They might incorrectly consider the 32leaf to be the certificate to check for authorisation data, which is controlled 33by the EE certificate owner. 34 35subjectAltName and issuerAltName are forbidden in proxy certificates, and this 36is enforced in OpenSSL. The subject must be the same as the issuer, with one 37commonName added on. 38 39Possible threats we can think of at this time include: 40 41 - impersonation through commonName (think server certificates). 42 - use of additional extensions, possibly non-standard ones used in certain 43 environments, that would grant extra or different authorisation rights. 44 45For these reasons, OpenSSL requires that the use of proxy certificates be 46explicitly allowed. Currently, this can be done using the following methods: 47 48 - if the application directly calls X509_verify_cert(), it can first call: 49 50 X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS); 51 52 Where ctx is the pointer which then gets passed to X509_verify_cert(). 53 54 - proxy certificate validation can be enabled before starting the application 55 by setting the environment variable OPENSSL_ALLOW_PROXY_CERTS. 56 57In the future, it might be possible to enable proxy certificates by editing 58openssl.cnf. 59 60 613. How to create proxy certificates 62 63Creating proxy certificates is quite easy, by taking advantage of a lack of 64checks in the 'openssl x509' application (*ahem*). You must first create a 65configuration section that contains a definition of the proxyCertInfo extension, 66for example: 67 68 [ v3_proxy ] 69 # A proxy certificate MUST NEVER be a CA certificate. 70 basicConstraints=CA:FALSE 71 72 # Usual authority key ID 73 authorityKeyIdentifier=keyid,issuer:always 74 75 # The extension which marks this certificate as a proxy 76 proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB 77 78It's also possible to specify the proxy extension in a separate section: 79 80 proxyCertInfo=critical,@proxy_ext 81 82 [ proxy_ext ] 83 language=id-ppl-anyLanguage 84 pathlen=0 85 policy=text:BC 86 87The policy value has a specific syntax, {syntag}:{string}, where the syntag 88determines what will be done with the string. The following syntags are 89recognised: 90 91 text indicates that the string is simply bytes, without any encoding: 92 93 policy=text:r��ksm��rg��s 94 95 Previous versions of this design had a specific tag for UTF-8 text. 96 However, since the bytes are copied as-is anyway, there is no need for 97 such a specific tag. 98 99 hex indicates the string is encoded in hex, with colons between each byte 100 (every second hex digit): 101 102 policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73 103 104 Previous versions of this design had a tag to insert a complete DER 105 blob. However, the only legal use for this would be to surround the 106 bytes that would go with the hex: tag with whatever is needed to 107 construct a correct OCTET STRING. The DER tag therefore felt 108 superfluous, and was removed. 109 110 file indicates that the text of the policy should really be taken from a 111 file. The string is then really a file name. This is useful for 112 policies that are large (more than a few lines, e.g. XML documents). 113 114The 'policy' setting can be split up in multiple lines like this: 115 116 0.policy=This is 117 1.policy= a multi- 118 2.policy=line policy. 119 120NOTE: the proxy policy value is the part which determines the rights granted to 121the process using the proxy certificate. The value is completely dependent on 122the application reading and interpreting it! 123 124Now that you have created an extension section for your proxy certificate, you 125can easily create a proxy certificate by doing: 126 127 openssl req -new -config openssl.cnf -out proxy.req -keyout proxy.key 128 openssl x509 -req -CAcreateserial -in proxy.req -days 7 -out proxy.crt \ 129 -CA user.crt -CAkey user.key -extfile openssl.cnf -extensions v3_proxy 130 131You can also create a proxy certificate using another proxy certificate as 132issuer (note: I'm using a different configuration section for it): 133 134 openssl req -new -config openssl.cnf -out proxy2.req -keyout proxy2.key 135 openssl x509 -req -CAcreateserial -in proxy2.req -days 7 -out proxy2.crt \ 136 -CA proxy.crt -CAkey proxy.key -extfile openssl.cnf -extensions v3_proxy2 137 138 1394. How to have your application interpret the policy? 140 141The basic way to interpret proxy policies is to start with some default rights, 142then compute the resulting rights by checking the proxy certificate against 143the chain of proxy certificates, user certificate and CA certificates. You then 144use the final computed rights. Sounds easy, huh? It almost is. 145 146The slightly complicated part is figuring out how to pass data between your 147application and the certificate validation procedure. 148 149You need the following ingredients: 150 151 - a callback function that will be called for every certificate being 152 validated. The callback be called several times for each certificate, 153 so you must be careful to do the proxy policy interpretation at the right 154 time. You also need to fill in the defaults when the EE certificate is 155 checked. 156 157 - a data structure that is shared between your application code and the 158 callback. 159 160 - a wrapper function that sets it all up. 161 162 - an ex_data index function that creates an index into the generic ex_data 163 store that is attached to an X509 validation context. 164 165Here is some skeleton code you can fill in: 166 167 /* In this example, I will use a view of granted rights as a bit 168 array, one bit for each possible right. */ 169 typedef struct your_rights { 170 unsigned char rights[total_rights / 8]; 171 } YOUR_RIGHTS; 172 173 /* The following procedure will create an index for the ex_data 174 store in the X509 validation context the first time it's called. 175 Subsequent calls will return the same index. */ 176 static int get_proxy_auth_ex_data_idx(void) 177 { 178 static volatile int idx = -1; 179 if (idx < 0) 180 { 181 CRYPTO_w_lock(CRYPTO_LOCK_X509_STORE); 182 if (idx < 0) 183 { 184 idx = X509_STORE_CTX_get_ex_new_index(0, 185 "for verify callback", 186 NULL,NULL,NULL); 187 } 188 CRYPTO_w_unlock(CRYPTO_LOCK_X509_STORE); 189 } 190 return idx; 191 } 192 193 /* Callback to be given to the X509 validation procedure. */ 194 static int verify_callback(int ok, X509_STORE_CTX *ctx) 195 { 196 if (ok == 1) /* It's REALLY important you keep the proxy policy 197 check within this section. It's important to know 198 that when ok is 1, the certificates are checked 199 from top to bottom. You get the CA root first, 200 followed by the possible chain of intermediate 201 CAs, followed by the EE certificate, followed by 202 the possible proxy certificates. */ 203 { 204 X509 *xs = ctx->current_cert; 205 206 if (xs->ex_flags & EXFLAG_PROXY) 207 { 208 YOUR_RIGHTS *rights = 209 (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx, 210 get_proxy_auth_ex_data_idx()); 211 PROXY_CERT_INFO_EXTENSION *pci = 212 X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL); 213 214 switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage)) 215 { 216 case NID_Independent: 217 /* Do whatever you need to grant explicit rights to 218 this particular proxy certificate, usually by 219 pulling them from some database. If there are none 220 to be found, clear all rights (making this and any 221 subsequent proxy certificate void of any rights). 222 */ 223 memset(rights->rights, 0, sizeof(rights->rights)); 224 break; 225 case NID_id_ppl_inheritAll: 226 /* This is basically a NOP, we simply let the current 227 rights stand as they are. */ 228 break; 229 default: 230 /* This is usually the most complex section of code. 231 You really do whatever you want as long as you 232 follow RFC 3820. In the example we use here, the 233 simplest thing to do is to build another, temporary 234 bit array and fill it with the rights granted by 235 the current proxy certificate, then use it as a 236 mask on the accumulated rights bit array, and 237 voil��, you now have a new accumulated rights bit 238 array. */ 239 { 240 int i; 241 YOUR_RIGHTS tmp_rights; 242 memset(tmp_rights.rights, 0, sizeof(tmp_rights.rights)); 243 244 /* process_rights() is supposed to be a procedure 245 that takes a string and it's length, interprets 246 it and sets the bits in the YOUR_RIGHTS pointed 247 at by the third argument. */ 248 process_rights((char *) pci->proxyPolicy->policy->data, 249 pci->proxyPolicy->policy->length, 250 &tmp_rights); 251 252 for(i = 0; i < total_rights / 8; i++) 253 rights->rights[i] &= tmp_rights.rights[i]; 254 } 255 break; 256 } 257 PROXY_CERT_INFO_EXTENSION_free(pci); 258 } 259 else if (!(xs->ex_flags & EXFLAG_CA)) 260 { 261 /* We have a EE certificate, let's use it to set default! 262 */ 263 YOUR_RIGHTS *rights = 264 (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx, 265 get_proxy_auth_ex_data_idx()); 266 267 /* The following procedure finds out what rights the owner 268 of the current certificate has, and sets them in the 269 YOUR_RIGHTS structure pointed at by the second 270 argument. */ 271 set_default_rights(xs, rights); 272 } 273 } 274 return ok; 275 } 276 277 static int my_X509_verify_cert(X509_STORE_CTX *ctx, 278 YOUR_RIGHTS *needed_rights) 279 { 280 int i; 281 int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) = ctx->verify_cb; 282 YOUR_RIGHTS rights; 283 284 X509_STORE_CTX_set_verify_cb(ctx, verify_callback); 285 X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(), &rights); 286 X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS); 287 ok = X509_verify_cert(ctx); 288 289 if (ok == 1) 290 { 291 ok = check_needed_rights(rights, needed_rights); 292 } 293 294 X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb); 295 296 return ok; 297 } 298 299If you use SSL or TLS, you can easily set up a callback to have the 300certificates checked properly, using the code above: 301 302 SSL_CTX_set_cert_verify_callback(s_ctx, my_X509_verify_cert, &needed_rights); 303 304 305-- 306Richard Levitte 307