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