aboutsummaryrefslogtreecommitdiffstats
path: root/doc/HOWTO
diff options
context:
space:
mode:
authorSimon L. B. Nielsen <simon@FreeBSD.org>2008-08-23 10:51:00 +0000
committerSimon L. B. Nielsen <simon@FreeBSD.org>2008-08-23 10:51:00 +0000
commitc4a78426bef17a0a7c81195c2b2399e7441f14ad (patch)
tree596c39f00d5968b1519e8cd7f0546412b14c20f0 /doc/HOWTO
parenta0ddfe4e7233d81e88a86217b7653708db2720fa (diff)
downloadsrc-c4a78426bef17a0a7c81195c2b2399e7441f14ad.tar.gz
src-c4a78426bef17a0a7c81195c2b2399e7441f14ad.zip
Flatten OpenSSL vendor tree.
Notes
Notes: svn path=/vendor-crypto/openssl/dist/; revision=182044
Diffstat (limited to 'doc/HOWTO')
-rw-r--r--doc/HOWTO/certificates.txt105
-rw-r--r--doc/HOWTO/keys.txt73
-rw-r--r--doc/HOWTO/proxy_certificates.txt322
3 files changed, 500 insertions, 0 deletions
diff --git a/doc/HOWTO/certificates.txt b/doc/HOWTO/certificates.txt
new file mode 100644
index 000000000000..a8a34c7abc51
--- /dev/null
+++ b/doc/HOWTO/certificates.txt
@@ -0,0 +1,105 @@
+<DRAFT!>
+ HOWTO certificates
+
+1. Introduction
+
+How you handle certificates depend a great deal on what your role is.
+Your role can be one or several of:
+
+ - User of some client software
+ - User of some server software
+ - Certificate authority
+
+This file is for users who wish to get a certificate of their own.
+Certificate authorities should read ca.txt.
+
+In all the cases shown below, the standard configuration file, as
+compiled into openssl, will be used. You may find it in /etc/,
+/usr/local/ssl/ or somewhere else. The name is openssl.cnf, and
+is better described in another HOWTO <config.txt?>. If you want to
+use a different configuration file, use the argument '-config {file}'
+with the command shown below.
+
+
+2. Relationship with keys
+
+Certificates are related to public key cryptography by containing a
+public key. To be useful, there must be a corresponding private key
+somewhere. With OpenSSL, public keys are easily derived from private
+keys, so before you create a certificate or a certificate request, you
+need to create a private key.
+
+Private keys are generated with 'openssl genrsa' if you want a RSA
+private key, or 'openssl gendsa' if you want a DSA private key.
+Further information on how to create private keys can be found in
+another HOWTO <keys.txt?>. The rest of this text assumes you have
+a private key in the file privkey.pem.
+
+
+3. Creating a certificate request
+
+To create a certificate, you need to start with a certificate
+request (or, as some certificate authorities like to put
+it, "certificate signing request", since that's exactly what they do,
+they sign it and give you the result back, thus making it authentic
+according to their policies). A certificate request can then be sent
+to a certificate authority to get it signed into a certificate, or if
+you have your own certificate authority, you may sign it yourself, or
+if you need a self-signed certificate (because you just want a test
+certificate or because you are setting up your own CA).
+
+The certificate request is created like this:
+
+ openssl req -new -key privkey.pem -out cert.csr
+
+Now, cert.csr can be sent to the certificate authority, if they can
+handle files in PEM format. If not, use the extra argument '-outform'
+followed by the keyword for the format to use (see another HOWTO
+<formats.txt?>). In some cases, that isn't sufficient and you will
+have to be more creative.
+
+When the certificate authority has then done the checks the need to
+do (and probably gotten payment from you), they will hand over your
+new certificate to you.
+
+Section 5 will tell you more on how to handle the certificate you
+received.
+
+
+4. Creating a self-signed test certificate
+
+If you don't want to deal with another certificate authority, or just
+want to create a test certificate for yourself. This is similar to
+creating a certificate request, but creates a certificate instead of
+a certificate request. This is NOT the recommended way to create a
+CA certificate, see ca.txt.
+
+ openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095
+
+
+5. What to do with the certificate
+
+If you created everything yourself, or if the certificate authority
+was kind enough, your certificate is a raw DER thing in PEM format.
+Your key most definitely is if you have followed the examples above.
+However, some (most?) certificate authorities will encode them with
+things like PKCS7 or PKCS12, or something else. Depending on your
+applications, this may be perfectly OK, it all depends on what they
+know how to decode. If not, There are a number of OpenSSL tools to
+convert between some (most?) formats.
+
+So, depending on your application, you may have to convert your
+certificate and your key to various formats, most often also putting
+them together into one file. The ways to do this is described in
+another HOWTO <formats.txt?>, I will just mention the simplest case.
+In the case of a raw DER thing in PEM format, and assuming that's all
+right for yor applications, simply concatenating the certificate and
+the key into a new file and using that one should be enough. With
+some applications, you don't even have to do that.
+
+
+By now, you have your cetificate and your private key and can start
+using the software that depend on it.
+
+--
+Richard Levitte
diff --git a/doc/HOWTO/keys.txt b/doc/HOWTO/keys.txt
new file mode 100644
index 000000000000..7ae2a3a11833
--- /dev/null
+++ b/doc/HOWTO/keys.txt
@@ -0,0 +1,73 @@
+<DRAFT!>
+ HOWTO keys
+
+1. Introduction
+
+Keys are the basis of public key algorithms and PKI. Keys usually
+come in pairs, with one half being the public key and the other half
+being the private key. With OpenSSL, the private key contains the
+public key information as well, so a public key doesn't need to be
+generated separately.
+
+Public keys come in several flavors, using different cryptographic
+algorithms. The most popular ones associated with certificates are
+RSA and DSA, and this HOWTO will show how to generate each of them.
+
+
+2. To generate a RSA key
+
+A RSA key can be used both for encryption and for signing.
+
+Generating a key for the RSA algorithm is quite easy, all you have to
+do is the following:
+
+ openssl genrsa -des3 -out privkey.pem 2048
+
+With this variant, you will be prompted for a protecting password. If
+you don't want your key to be protected by a password, remove the flag
+'-des3' from the command line above.
+
+ NOTE: if you intend to use the key together with a server
+ certificate, it may be a good thing to avoid protecting it
+ with a password, since that would mean someone would have to
+ type in the password every time the server needs to access
+ the key.
+
+The number 2048 is the size of the key, in bits. Today, 2048 or
+higher is recommended for RSA keys, as fewer amount of bits is
+consider insecure or to be insecure pretty soon.
+
+
+3. To generate a DSA key
+
+A DSA key can be used for signing only. This is important to keep
+in mind to know what kind of purposes a certificate request with a
+DSA key can really be used for.
+
+Generating a key for the DSA algorithm is a two-step process. First,
+you have to generate parameters from which to generate the key:
+
+ openssl dsaparam -out dsaparam.pem 2048
+
+The number 2048 is the size of the key, in bits. Today, 2048 or
+higher is recommended for DSA keys, as fewer amount of bits is
+consider insecure or to be insecure pretty soon.
+
+When that is done, you can generate a key using the parameters in
+question (actually, several keys can be generated from the same
+parameters):
+
+ openssl gendsa -des3 -out privkey.pem dsaparam.pem
+
+With this variant, you will be prompted for a protecting password. If
+you don't want your key to be protected by a password, remove the flag
+'-des3' from the command line above.
+
+ NOTE: if you intend to use the key together with a server
+ certificate, it may be a good thing to avoid protecting it
+ with a password, since that would mean someone would have to
+ type in the password every time the server needs to access
+ the key.
+
+--
+Richard Levitte
diff --git a/doc/HOWTO/proxy_certificates.txt b/doc/HOWTO/proxy_certificates.txt
new file mode 100644
index 000000000000..3d36b02f6b31
--- /dev/null
+++ b/doc/HOWTO/proxy_certificates.txt
@@ -0,0 +1,322 @@
+<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