From: Ralf S. Engelschall Date: Mon, 22 Mar 1999 15:55:01 +0000 (+0000) Subject: Merge ext-conf.txt and buffer.txt into a global openssl.txt because we X-Git-Tag: OpenSSL_0_9_2b~2 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=f5904406d0438175fb3e131fc0b3792343e5ad8e;p=oweals%2Fopenssl.git 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 ;-) --- diff --git a/doc/buffer.txt b/doc/buffer.txt deleted file mode 100644 index 06d821cba0..0000000000 --- a/doc/buffer.txt +++ /dev/null @@ -1,49 +0,0 @@ -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. diff --git a/doc/ext-conf.txt b/doc/ext-conf.txt deleted file mode 100644 index 1d0f6fb3c3..0000000000 --- a/doc/ext-conf.txt +++ /dev/null @@ -1,224 +0,0 @@ -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. 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. +