[thirdparty/openssl.git] / doc / HOWTO / proxy_certificates.txt

<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_CERTS 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:
Commit	Line	Data
d18685d9 RL	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
d9bfe4f9 RL	25	2. A warning about proxy certificates
	26
	27	Noone seems to have tested proxy certificates with security in mind.
	28	Basically, to this date, it seems that proxy certificates have only
	29	been used in a world that's highly aware of them. What would happen
	30	if an unsuspecting application is to validate a chain of certificates
	31	that contains proxy certificates? It would usually consider the leaf
	32	to be the certificate to check for authorisation data, and since proxy
	33	certificates are controlled by the EE certificate owner alone, it's
	34	would be normal to consider what the EE certificate owner could do
	35	with them.
	36
	37	subjectAltName and issuerAltName are forbidden in proxy certificates,
	38	and this is enforced in OpenSSL. The subject must be the same as the
	39	issuer, with one commonName added on.
	40
	41	Possible threats are, as far as has been imagined so far:
	42
	43	- impersonation through commonName (think server certificates).
	44	- use of additional extensions, possibly non-standard ones used in
	45	certain environments, that would grant extra or different
	46	authorisation rights.
	47
	48	For this reason, OpenSSL requires that the use of proxy certificates
	49	be explicitely allowed. Currently, this can be done using the
	50	following methods:
	51
	52	- if the application calls X509_verify_cert() itself, it can do the
	53	following prior to that call (ctx is the pointer passed in the call
	54	to X509_verify_cert()):
	55
	56	X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
	57
	58	- in all other cases, proxy certificate validation can be enabled
	59	before starting the application by setting the envirnoment variable
e0311481	60	OPENSSL_ALLOW_PROXY_CERTS with some non-empty value.
d9bfe4f9 RL	61
	62	There are thoughts to allow proxy certificates with a line in the
	63	default openssl.cnf, but that's still in the future.
	64
	65
	66	3. How to create proxy cerificates
d18685d9 RL	67
	68	It's quite easy to create proxy certificates, by taking advantage of
	69	the lack of checks of the 'openssl x509' application (ahem). But
	70	first, you need to create a configuration section that contains a
	71	definition of the proxyCertInfo extension, a little like this:
	72
	73	[ v3_proxy ]
	74	# A proxy certificate MUST NEVER be a CA certificate.
	75	basicConstraints=CA:FALSE
	76
	77	# Usual authority key ID
	78	authorityKeyIdentifier=keyid,issuer:always
	79
	80	# Now, for the extension that marks this certificate as a proxy one
	81	proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB
	82
	83	It's also possible to give the proxy extension in a separate section:
	84
	85	proxyCertInfo=critical,@proxy_ext
	86
	87	[ proxy_ext ]
	88	language=id-ppl-anyLanguage
	89	pathlen=0
	90	policy=text:BC
	91
	92	The policy value has a specific syntax, {syntag}:{string}, where the
	93	syntag determines what will be done with the string. The recognised
	94	syntags are as follows:
	95
	96	text indicates that the string is simply the bytes, not
	97	encoded in any kind of way:
	98
	99