diff options
author | Ralf S. Engelschall <rse@openssl.org> | 1999-03-22 15:55:01 +0000 |
---|---|---|
committer | Ralf S. Engelschall <rse@openssl.org> | 1999-03-22 15:55:01 +0000 |
commit | f5904406d0438175fb3e131fc0b3792343e5ad8e (patch) | |
tree | 2b0c831169aa727cd23ae6597abde7fc49cd8fa7 /doc/openssl.txt | |
parent | 6e9f108dd7ccea98fb13a6fe5cb316afa4c46508 (diff) |
Merge ext-conf.txt and buffer.txt into a global openssl.txt because we
shouldn't again start with thousend little text files or we quickly come back
to the old SSLeay days ;-)
Diffstat (limited to 'doc/openssl.txt')
-rw-r--r-- | doc/openssl.txt | 284 |
1 files changed, 284 insertions, 0 deletions
diff --git a/doc/openssl.txt b/doc/openssl.txt new file mode 100644 index 0000000000..a23373e34f --- /dev/null +++ b/doc/openssl.txt @@ -0,0 +1,284 @@ + +This is some preliminary documentation for OpenSSL. + +============================================================================== + BUFFER Library +============================================================================== + +[Note: I wrote this when I saw a Malloc version of strdup() in there which + I'd written myself anyway. I was so annoyed at not noticing this I decided to + document it :-) Steve.] + +The buffer library handles simple character arrays. Buffers are used for various +purposes in the library, most notably memory BIOs. + +The library uses the BUF_MEM structure defined in buffer.h: + +typedef struct buf_mem_st + { + int length; /* current number of bytes */ + char *data; + int max; /* size of buffer */ + } BUF_MEM; + +'length' is the current size of the buffer in bytes, 'max' is the amount of +memory allocated to the buffer. There are three functions which handle these +and one "miscelanous" function. + +BUF_MEM *BUF_MEM_new() + +This allocates a new buffer of zero size. Returns the buffer or NULL on error. + +void BUF_MEM_free(BUF_MEM *a) + +This frees up an already existing buffer. The data is zeroed before freeing +up in case the buffer contains sensitive data. + +int BUF_MEM_grow(BUF_MEM *str, int len) + +This changes the size of an already existing buffer. It returns zero on error +or the new size (i.e. 'len'). Any data already in the buffer is preserved if +it increases in size. + +char * BUF_strdup(char *str) + +This is the previously mentioned strdup function: like the standard library +strdup() it copies a null terminated string into a block of allocated memory +and returns a pointer to the allocated block. + +Unlike the standard C library strdup() this function uses Malloc() and so +should be used in preference to the standard library strdup() because it can +be used for memory leak checking or replacing the malloc() function. + +The memory allocated from BUF_strdup() should be freed up using the Free() +function. + +============================================================================== + OpenSSL X509V3 extension configuration +============================================================================== + +OpenSSL X509V3 extension configuration: preliminary documentation. + +INTRODUCTION. + +For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now +possible to add and print out common X509 V3 certificate and CRL extensions. + +For more information about the meaning of extensions see: + +http://www.imc.org/ietf-pkix/ +http://home.netscape.com/eng/security/certs.html + +PRINTING EXTENSIONS. + +Extension values are automatically printed out for supported extensions. + +openssl x509 -in cert.pem -text +openssl crl -in crl.pem -text + +will give information in the extension printout, for example: + + + X509v3 extensions: + X509v3 Basic Constraints: + CA:TRUE + X509v3 Subject Key Identifier: + 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15 + X509v3 Authority Key Identifier: + keyid:73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15, DirName:/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/Email=email@1.address/Email=email@2.address, serial:00 + X509v3 Key Usage: + Certificate Sign, CRL Sign + X509v3 Subject Alternative Name: + email:email@1.address, email:email@2.address + +CONFIGURATION FILES. + +The OpenSSL utilities 'ca' and 'req' can now have extension sections listing +which certificate extensions to include. In each case a line: + +x509_extensions = extension_section + +indicates which section contains the extensions. In the case of 'req' the +extension section is used when the -x509 option is present to create a +self signed root certificate. + +You can also add extensions to CRLs: a line + +crl_extensions = crl_extension_section + +will include extensions when the -gencrl option is used with the 'ca' utility. +You can add any extension to a CRL but of the supported extensions only +issuerAltName and authorityKeyIdentifier make any real sense. Note: these are +CRL extensions NOT CRL *entry* extensions which cannot currently be generated. +CRL entry extensions can be displayed. + +EXTENSION SYNTAX. + +Extensions have the basic form: + +extension_name=[critical,] extension_options + +the use of the critical option makes the extension critical. Extreme caution +should be made when using the critical flag. If an extension is marked +as critical then any client that does not understand the extension should +reject it as invalid. Some broken software will reject certificates which +have *any* critical extensions (these violates PKIX but we have to live +with it). + +There are three main types of extension, string extensions, multi valued +extensions, and raw extensions. + +String extensions simply have a string which defines the value of the or how +it is obtained. + +For example: + +nsComment="This is a Comment" + +Multi valued extensions have a short form and a long form. The short form +is a list of names and values: + +basicConstraints=critical,CA:true,pathlen:1 + +The long form allows the values to be placed in a separate section: + +basicConstraints=critical,@bs_section + +[bs_section] + +CA=true +pathlen=1 + +Both forms are equivalent. However it should be noted that in some cases the +same name can appear multiple times, for example, + +subjectAltName=email:steve@here,email:steve@there + +in this case an equivalent long form is: + +subjectAltName=@alt_section + +[alt_section] + +email.1=steve@here +email.2=steve@there + +This is because the configuration file code cannot handle the same name +occurring twice in the same extension. + +Raw extensions allow arbitrary data to be placed in an extension. For +example + +1.2.3.4=critical,RAW:01:02:03:04 +1.2.3.4=RAW:01020304 + +The value following RAW is a hex dump of the extension contents. Any extension +can be placed in this form to override the default behaviour. For example: + +basicConstraints=critical,RAW:00:01:02:03 + +WARNING: raw extensions should be used with caution. It is possible to create +totally invalid extensions unless care is taken. + +CURRENTLY SUPPORTED EXTENSIONS. + +Literal String extensions. + +In each case the 'value' of the extension is placed directly in the extension. +Currently supported extensions in this category are: nsBaseUrl, nsRevocationUrl +nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, nsSslServerName and +nsComment. + +For example: + +nsComment="This is a test comment" + +Bit Strings. + +Bit string extensions just consist of a list of suppported bits, currently +two extensions are in this category: PKIX keyUsage and the Netscape specific +nsCertType. + +nsCertType (netscape certificate type) takes the flags: client, server, email, +objsign, reserved, sslCA, emailCA, objCA. + +keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation, +keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLCertSign, +encipherOnly, decipherOnly. + +For example: + +nsCertType=server + +keyUsage=critical, digitalSignature, nonRepudiation + + +Basic Constraints. + +Basic constraints is a multi valued extension that supports a CA and an +optional pathlen option. The CA option takes the values true and false and +pathlen takes an integer. Note if the CA option is false the pathlen option +should be omitted. + +Examples: + +basicConstraints=CA:TRUE +basicConstraints=critical,CA:TRUE, pathlen:10 + +NOTE: for a CA to be considered valid it must have the CA option set to +TRUE. An end user certificate MUST NOT have the CA value set to true. +According to PKIX recommendations it should exclude the extension entirely +however some software may require CA set to FALSE for end entity certificates. + +Subject Key Identifier. + +This is really a string extension and can take two possible values. Either +a hex string giving details of the extension value to include or the word +'hash' which then automatically follow PKIX guidelines in selecting and +appropriate key identifier. The use of the hex string is strongly discouraged. + +Example: subjectKeyIdentifier=hash + +Authority Key Identifier. + +The authority key identifier extension permits two options. keyid and issuer: +both can take the optional value "always". + +If the keyid option is present an attempt is made to copy the subject key +identifier from the parent certificate. If the value "always" is present +then an error is returned if the option fails. + +The issuer option copies the issuer and serial number from the issuer +certificate. Normally this will only be done if the keyid option fails or +is not included: the "always" flag will always include the value. + +Subject Alternative Name. + +The subject alternative name extension allows various literal values to be +included in the configuration file. These include "email" (an email address) +"URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a +registered ID: OBJECT IDENTIFIER) and IP (and IP address). + +Also the email option include a special 'copy' value. This will automatically +include and email addresses contained in the certificate subject name in +the extension. + +Examples: + +subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/ +subjectAltName=email:my@other.address,RID:1.2.3.4 + +Issuer Alternative Name. + +The issuer alternative name option supports all the literal options of +subject alternative name. It does *not* support the email:copy option because +that would not make sense. It does support and additional issuer:copy option +that will copy all the subject alternative name values from the issuer +certificate (if possible). + +Display only extensions. + +Some extensions are only partially supported and currently are only displayed +but cannot be set. These include private key usage period, CRL number, and +CRL reason. + |