proxy_certificates.txt revision 279264 
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