From 027351f729b9e837200dae6e1520cda6577ab930 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Wed, 15 May 2002 02:29:24 +0000 Subject: This commit was manufactured by cvs2git to create branch 'unlabeled-1.1.1'. --- src/lib/libssl/LICENSE | 127 ++++ src/lib/libssl/doc/openssl.cnf | 214 +++++++ src/lib/libssl/doc/openssl.txt | 1174 ++++++++++++++++++++++++++++++++++ src/lib/libssl/doc/standards.txt | 121 ++++ src/lib/libssl/test/VMSca-response.1 | 1 + src/lib/libssl/test/VMSca-response.2 | 2 + src/lib/libssl/test/bctest | 111 ++++ 7 files changed, 1750 insertions(+) create mode 100644 src/lib/libssl/LICENSE create mode 100644 src/lib/libssl/doc/openssl.cnf create mode 100644 src/lib/libssl/doc/openssl.txt create mode 100644 src/lib/libssl/doc/standards.txt create mode 100644 src/lib/libssl/test/VMSca-response.1 create mode 100644 src/lib/libssl/test/VMSca-response.2 create mode 100644 src/lib/libssl/test/bctest (limited to 'src/lib/libssl') diff --git a/src/lib/libssl/LICENSE b/src/lib/libssl/LICENSE new file mode 100644 index 0000000000..b9e18d5e7b --- /dev/null +++ b/src/lib/libssl/LICENSE @@ -0,0 +1,127 @@ + + LICENSE ISSUES + ============== + + The OpenSSL toolkit stays under a dual license, i.e. both the conditions of + the OpenSSL License and the original SSLeay license apply to the toolkit. + See below for the actual license texts. Actually both licenses are BSD-style + Open Source licenses. In case of any license issues related to OpenSSL + please contact openssl-core@openssl.org. + + OpenSSL License + --------------- + +/* ==================================================================== + * Copyright (c) 1998-1999 The OpenSSL Project. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. All advertising materials mentioning features or use of this + * software must display the following acknowledgment: + * "This product includes software developed by the OpenSSL Project + * for use in the OpenSSL Toolkit. (http://www.openssl.org/)" + * + * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to + * endorse or promote products derived from this software without + * prior written permission. For written permission, please contact + * openssl-core@openssl.org. + * + * 5. Products derived from this software may not be called "OpenSSL" + * nor may "OpenSSL" appear in their names without prior written + * permission of the OpenSSL Project. + * + * 6. Redistributions of any form whatsoever must retain the following + * acknowledgment: + * "This product includes software developed by the OpenSSL Project + * for use in the OpenSSL Toolkit (http://www.openssl.org/)" + * + * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY + * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + * OF THE POSSIBILITY OF SUCH DAMAGE. + * ==================================================================== + * + * This product includes cryptographic software written by Eric Young + * (eay@cryptsoft.com). This product includes software written by Tim + * Hudson (tjh@cryptsoft.com). + * + */ + + Original SSLeay License + ----------------------- + +/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) + * All rights reserved. + * + * This package is an SSL implementation written + * by Eric Young (eay@cryptsoft.com). + * The implementation was written so as to conform with Netscapes SSL. + * + * This library is free for commercial and non-commercial use as long as + * the following conditions are aheared to. The following conditions + * apply to all code found in this distribution, be it the RC4, RSA, + * lhash, DES, etc., code; not just the SSL code. The SSL documentation + * included with this distribution is covered by the same copyright terms + * except that the holder is Tim Hudson (tjh@cryptsoft.com). + * + * Copyright remains Eric Young's, and as such any Copyright notices in + * the code are not to be removed. + * If this package is used in a product, Eric Young should be given attribution + * as the author of the parts of the library used. + * This can be in the form of a textual message at program startup or + * in documentation (online or textual) provided with the package. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. All advertising materials mentioning features or use of this software + * must display the following acknowledgement: + * "This product includes cryptographic software written by + * Eric Young (eay@cryptsoft.com)" + * The word 'cryptographic' can be left out if the rouines from the library + * being used are not cryptographic related :-). + * 4. If you include any Windows specific code (or a derivative thereof) from + * the apps directory (application code) you must include an acknowledgement: + * "This product includes software written by Tim Hudson (tjh@cryptsoft.com)" + * + * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * + * The licence and distribution terms for any publically available version or + * derivative of this code cannot be changed. i.e. this code cannot simply be + * copied and put under another distribution licence + * [including the GNU Public Licence.] + */ + diff --git a/src/lib/libssl/doc/openssl.cnf b/src/lib/libssl/doc/openssl.cnf new file mode 100644 index 0000000000..d70dd25622 --- /dev/null +++ b/src/lib/libssl/doc/openssl.cnf @@ -0,0 +1,214 @@ +# +# OpenSSL example configuration file. +# This is mostly being used for generation of certificate requests. +# + +RANDFILE = $ENV::HOME/.rnd +oid_file = $ENV::HOME/.oid +oid_section = new_oids + +# To use this configuration file with the "-extfile" option of the +# "openssl x509" utility, name here the section containing the +# X.509v3 extensions to use: +# extensions = +# (Alternatively, use a configuration file that has only +# X.509v3 extensions in its main [= default] section.) + +[ new_oids ] + +# We can add new OIDs in here for use by 'ca' and 'req'. +# Add a simple OID like this: +# testoid1=1.2.3.4 +# Or use config file substitution like this: +# testoid2=${testoid1}.5.6 + +#################################################################### +[ ca ] +default_ca = CA_default # The default ca section + +#################################################################### +[ CA_default ] + +dir = ./demoCA # Where everything is kept +certs = $dir/certs # Where the issued certs are kept +crl_dir = $dir/crl # Where the issued crl are kept +database = $dir/index.txt # database index file. +new_certs_dir = $dir/newcerts # default place for new certs. + +certificate = $dir/cacert.pem # The CA certificate +serial = $dir/serial # The current serial number +crl = $dir/crl.pem # The current CRL +private_key = $dir/private/cakey.pem# The private key +RANDFILE = $dir/private/.rand # private random number file + +x509_extensions = usr_cert # The extentions to add to the cert + +# Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs +# so this is commented out by default to leave a V1 CRL. +# crl_extensions = crl_ext + +default_days = 365 # how long to certify for +default_crl_days= 30 # how long before next CRL +default_md = md5 # which md to use. +preserve = no # keep passed DN ordering + +# A few difference way of specifying how similar the request should look +# For type CA, the listed attributes must be the same, and the optional +# and supplied fields are just that :-) +policy = policy_match + +# For the CA policy +[ policy_match ] +countryName = match +stateOrProvinceName = match +organizationName = match +organizationalUnitName = optional +commonName = supplied +emailAddress = optional + +# For the 'anything' policy +# At this point in time, you must list all acceptable 'object' +# types. +[ policy_anything ] +countryName = optional +stateOrProvinceName = optional +localityName = optional +organizationName = optional +organizationalUnitName = optional +commonName = supplied +emailAddress = optional + +#################################################################### +[ req ] +default_bits = 1024 +default_keyfile = privkey.pem +distinguished_name = req_distinguished_name +attributes = req_attributes +x509_extensions = v3_ca # The extentions to add to the self signed cert + +[ req_distinguished_name ] +countryName = Country Name (2 letter code) +countryName_default = AU +countryName_min = 2 +countryName_max = 2 + +stateOrProvinceName = State or Province Name (full name) +stateOrProvinceName_default = Some-State + +localityName = Locality Name (eg, city) + +0.organizationName = Organization Name (eg, company) +0.organizationName_default = Internet Widgits Pty Ltd + +# we can do this but it is not needed normally :-) +#1.organizationName = Second Organization Name (eg, company) +#1.organizationName_default = World Wide Web Pty Ltd + +organizationalUnitName = Organizational Unit Name (eg, section) +#organizationalUnitName_default = + +commonName = Common Name (eg, YOUR name) +commonName_max = 64 + +emailAddress = Email Address +emailAddress_max = 40 + +# SET-ex3 = SET extension number 3 + +[ req_attributes ] +challengePassword = A challenge password +challengePassword_min = 4 +challengePassword_max = 20 + +unstructuredName = An optional company name + +[ usr_cert ] + +# These extensions are added when 'ca' signs a request. + +# This goes against PKIX guidelines but some CAs do it and some software +# requires this to avoid interpreting an end user certificate as a CA. + +basicConstraints=CA:FALSE + +# Here are some examples of the usage of nsCertType. If it is omitted +# the certificate can be used for anything *except* object signing. + +# This is OK for an SSL server. +# nsCertType = server + +# For an object signing certificate this would be used. +# nsCertType = objsign + +# For normal client use this is typical +# nsCertType = client, email + +# and for everything including object signing: +# nsCertType = client, email, objsign + +# This is typical in keyUsage for a client certificate. +# keyUsage = nonRepudiation, digitalSignature, keyEncipherment + +# This will be displayed in Netscape's comment listbox. +nsComment = "OpenSSL Generated Certificate" + +# PKIX recommendations harmless if included in all certificates. +subjectKeyIdentifier=hash +authorityKeyIdentifier=keyid,issuer:always + +# This stuff is for subjectAltName and issuerAltname. +# Import the email address. +# subjectAltName=email:copy + +# Copy subject details +# issuerAltName=issuer:copy + +#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem +#nsBaseUrl +#nsRevocationUrl +#nsRenewalUrl +#nsCaPolicyUrl +#nsSslServerName + +[ v3_ca ] + +# Extensions for a typical CA + + +# PKIX recommendation. + +subjectKeyIdentifier=hash + +authorityKeyIdentifier=keyid:always,issuer:always + +# This is what PKIX recommends but some broken software chokes on critical +# extensions. +#basicConstraints = critical,CA:true +# So we do this instead. +basicConstraints = CA:true + +# Key usage: this is typical for a CA certificate. However since it will +# prevent it being used as an test self-signed certificate it is best +# left out by default. +# keyUsage = cRLSign, keyCertSign + +# Some might want this also +# nsCertType = sslCA, emailCA + +# Include email address in subject alt name: another PKIX recommendation +# subjectAltName=email:copy +# Copy issuer details +# issuerAltName=issuer:copy + +# RAW DER hex encoding of an extension: beware experts only! +# 1.2.3.5=RAW:02:03 +# You can even override a supported extension: +# basicConstraints= critical, RAW:30:03:01:01:FF + +[ crl_ext ] + +# CRL extensions. +# Only issuerAltName and authorityKeyIdentifier make any sense in a CRL. + +# issuerAltName=issuer:copy +authorityKeyIdentifier=keyid:always,issuer:always diff --git a/src/lib/libssl/doc/openssl.txt b/src/lib/libssl/doc/openssl.txt new file mode 100644 index 0000000000..91b85e5f14 --- /dev/null +++ b/src/lib/libssl/doc/openssl.txt @@ -0,0 +1,1174 @@ + +This is some preliminary documentation for OpenSSL. + +============================================================================== + BUFFER Library +============================================================================== + +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 "miscellaneous" 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. + +BEGINNERS NOTE + +For most simple applications you don't need to know too much about extensions: +the default openssl.cnf values will usually do sensible things. + +If you want to know more you can initially quickly look through the sections +describing how the standard OpenSSL utilities display and add extensions and +then the list of supported extensions. + +For more technical 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. + +The 'x509' utility also supports extensions when it signs a certificate. +The -extfile option is used to set the configuration file containing the +extensions. In this case a line with: + +extensions = extension_section + +in the nameless (default) section is used. If no such line is included then +it uses the default section. + +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. + +NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL +you should not include a crl_extensions line in the configuration file. + +As with all configuration files you can use the inbuilt environment expansion +to allow the values to be passed in the environment. Therefore if you have +several extension sections used for different purposes you can have a line: + +x509_extensions = $ENV::ENV_EXT + +and set the ENV_EXT environment variable before calling the relevant utility. + +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 contains either the value itself +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. + +The syntax of raw extensions is governed by the extension code: it can +for example contain data in multiple sections. The correct syntax to +use is defined by the extension code itself: check out the certificate +policies extension for an example. + +In addition it is also possible to use the word DER to include arbitrary +data in any extension. + +1.2.3.4=critical,DER:01:02:03:04 +1.2.3.4=DER:01020304 + +The value following DER is a hex dump of the DER encoding of the extension +Any extension can be placed in this form to override the default behaviour. +For example: + +basicConstraints=critical,DER:00:01:02:03 + +WARNING: DER should be used with caution. It is possible to create totally +invalid extensions unless care is taken. + +CURRENTLY SUPPORTED EXTENSIONS. + +If you aren't sure about extensions then they can be largely ignored: its only +when you want to do things like restrict certificate usage when you need to +worry about them. + +The only extension that a beginner might want to look at is Basic Constraints. +If in addition you want to try Netscape object signing the you should also +look at Netscape Certificate Type. + +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 supported 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, cRLSign, +encipherOnly, decipherOnly. + +For example: + +nsCertType=server + +keyUsage=digitalSignature, nonRepudiation + +Hints on Netscape Certificate Type. + +Other than Basic Constraints this is the only extension a beginner might +want to use, if you want to try Netscape object signing, otherwise it can +be ignored. + +If you want a certificate that can be used just for object signing then: + +nsCertType=objsign + +will do the job. If you want to use it as a normal end user and server +certificate as well then + +nsCertType=objsign,email,server + +is more appropriate. You cannot use a self signed certificate for object +signing (well Netscape signtool can but it cheats!) so you need to create +a CA certificate and sign an end user certificate with it. + +Side note: If you want to conform to the Netscape specifications then you +should really also set: + +nsCertType=objCA + +in the *CA* certificate for just an object signing CA and + +nsCertType=objCA,emailCA,sslCA + +for everything. Current Netscape software doesn't enforce this so it can +be omitted. + +Basic Constraints. + +This is generally the only extension you need to worry about for simple +applications. If you want your certificate to be usable as a CA certificate +(in addition to an end user certificate) then you set this to: + +basicConstraints=CA:TRUE + +if you want to be certain the certificate cannot be used as a CA then do: + +basicConstraints=CA:FALSE + +The rest of this section describes more advanced usage. + +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. + +The pathlen parameter indicates the maximum number of CAs that can appear +below this one in a chain. So if you have a CA with a pathlen of zero it can +only be used to sign end user certificates and not further CAs. This all +assumes that the software correctly interprets this extension of course. + +Examples: + +basicConstraints=CA:TRUE +basicConstraints=critical,CA:TRUE, pathlen:0 + +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 an additional issuer:copy option +that will copy all the subject alternative name values from the issuer +certificate (if possible). + +CRL distribution points. + +This is a multi-valued extension that supports all the literal options of +subject alternative name. Of the few software packages that currently interpret +this extension most only interpret the URI option. + +Currently each option will set a new DistributionPoint with the fullName +field set to the given value. + +Other fields like cRLissuer and reasons cannot currently be set or displayed: +at this time no examples were available that used these fields. + +If you see this extension with when you attempt to print it out +or it doesn't appear to display correctly then let me know, including the +certificate (mail me at steve@openssl.org) . + +Examples: + +crlDistributionPoints=URI:http://www.myhost.com/myca.crl +crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl + +Certificate Policies. + +This is a RAW extension. It attempts to display the contents of this extension: +unfortunately this extension is often improperly encoded. + +The certificate policies extension will rarely be used in practice: few +software packages interpret it correctly or at all. IE5 does partially +support this extension: but it needs the 'ia5org' option because it will +only correctly support a broken encoding. Of the options below only the +policy OID, explicitText and CPS options are displayed with IE5. + +All the fields of this extension can be set by using the appropriate syntax. + +If you follow the PKIX recommendations of not including any qualifiers and just +using only one OID then you just include the value of that OID. Multiple OIDs +can be set separated by commas, for example: + +certificatePolicies= 1.2.4.5, 1.1.3.4 + +If you wish to include qualifiers then the policy OID and qualifiers need to +be specified in a separate section: this is done by using the @section syntax +instead of a literal OID value. + +The section referred to must include the policy OID using the name +policyIdentifier, cPSuri qualifiers can be included using the syntax: + +CPS.nnn=value + +userNotice qualifiers can be set using the syntax: + +userNotice.nnn=@notice + +The value of the userNotice qualifier is specified in the relevant section. +This section can include explicitText, organization and noticeNumbers +options. explicitText and organization are text strings, noticeNumbers is a +comma separated list of numbers. The organization and noticeNumbers options +(if included) must BOTH be present. If you use the userNotice option with IE5 +then you need the 'ia5org' option at the top level to modify the encoding: +otherwise it will not be interpreted properly. + +Example: + +certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect + +[polsect] + +policyIdentifier = 1.3.5.8 +CPS.1="http://my.host.name/" +CPS.2="http://my.your.name/" +userNotice.1=@notice + +[notice] + +explicitText="Explicit Text Here" +organization="Organisation Name" +noticeNumbers=1,2,3,4 + +TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field, +according to PKIX it should be of type DisplayText but Verisign uses an +IA5STRING and IE5 needs this too. + +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. + +============================================================================== + X509V3 Extension code: programmers guide +============================================================================== + +The purpose of the extension code is twofold. It allows an extension to be +created from a string or structure describing its contents and it prints out an +extension in a human or machine readable form. + +1. Initialisation and cleanup. + +X509V3_add_standard_extensions(); + +This function should be called before any other extension code. It adds support +for some common PKIX and Netscape extensions. Additional custom extensions can +be added as well (see later). + +void X509V3_EXT_cleanup(void); + +This function should be called last to cleanup the extension code. After this +call no other extension calls should be made. + +2. Printing and parsing extensions. + +The simplest way to print out extensions is via the standard X509 printing +routines: if you use the standard X509_print() function, the supported +extensions will be printed out automatically. + +The following functions allow finer control over extension display: + +int X509V3_EXT_print(BIO *out, X509_EXTENSION *ext, int flag, int indent); +int X509V3_EXT_print_fp(FILE *out, X509_EXTENSION *ext, int flag, int indent); + +These two functions print out an individual extension to a BIO or FILE pointer. +Currently the flag argument is unused and should be set to 0. The 'indent' +argument is the number of spaces to indent each line. + +void *X509V3_EXT_d2i(X509_EXTENSION *ext); + +This function parses an extension and returns its internal structure. The +precise structure you get back depends on the extension being parsed. If the +extension if basicConstraints you will get back a pointer to a +BASIC_CONSTRAINTS structure. Check out the source in crypto/x509v3 for more +details about the structures returned. The returned structure should be freed +after use using the relevant free function, BASIC_CONSTRAINTS_free() for +example. + +3. Generating extensions. + +An extension will typically be generated from a configuration file, or some +other kind of configuration database. + +int X509V3_EXT_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section, + X509 *cert); +int X509V3_EXT_CRL_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section, + X509_CRL *crl); + +These functions add all the extensions in the given section to the given +certificate or CRL. They will normally be called just before the certificate +or CRL is due to be signed. Both return 0 on error on non zero for success. + +In each case 'conf' is the LHASH pointer of the configuration file to use +and 'section' is the section containing the extension details. + +See the 'context functions' section for a description of the ctx paramater. + + +X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *name, + char *value); + +This function returns an extension based on a name and value pair, if the +pair will not need to access other sections in a config file (or there is no +config file) then the 'conf' parameter can be set to NULL. + +X509_EXTENSION *X509V3_EXT_conf_nid(char *conf, X509V3_CTX *ctx, int nid, + char *value); + +This function creates an extension in the same way as X509V3_EXT_conf() but +takes the NID of the extension rather than its name. + +For example to produce basicConstraints with the CA flag and a path length of +10: + +x = X509V3_EXT_conf_nid(NULL, NULL, NID_basicConstraints, "CA:TRUE,pathlen:10"); + + +X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc); + +This function sets up an extension from its internal structure. The ext_nid +parameter is the NID of the extension and 'crit' is the critical flag. + +4. Context functions. + +The following functions set and manipulate an extension context structure. +The purpose of the extension context is to allow the extension code to +access various structures relating to the "environment" of the certificate: +for example the issuers certificate or the certificate request. + +void X509V3_set_ctx(X509V3_CTX *ctx, X509 *issuer, X509 *subject, + X509_REQ *req, X509_CRL *crl, int flags); + +This function sets up an X509V3_CTX structure with details of the certificate +environment: specifically the issuers certificate, the subject certificate, +the certificate request and the CRL: if these are not relevant or not +available then they can be set to NULL. The 'flags' parameter should be set +to zero. + +X509V3_set_ctx_test(ctx) + +This macro is used to set the 'ctx' structure to a 'test' value: this is to +allow the syntax of an extension (or configuration file) to be tested. + +X509V3_set_ctx_nodb(ctx) + +This macro is used when no configuration database is present. + +void X509V3_set_conf_lhash(X509V3_CTX *ctx, LHASH *lhash); + +This function is used to set the configuration database when it is an LHASH +structure: typically a configuration file. + +The following functions are used to access a configuration database: they +should only be used in RAW extensions. + +char * X509V3_get_string(X509V3_CTX *ctx, char *name, char *section); + +This function returns the value of the parameter "name" in "section", or NULL +if there has been an error. + +void X509V3_string_free(X509V3_CTX *ctx, char *str); + +This function frees up the string returned by the above function. + +STACK_OF(CONF_VALUE) * X509V3_get_section(X509V3_CTX *ctx, char *section); + +This function returns a whole section as a STACK_OF(CONF_VALUE) . + +void X509V3_section_free( X509V3_CTX *ctx, STACK_OF(CONF_VALUE) *section); + +This function frees up the STACK returned by the above function. + +Note: it is possible to use the extension code with a custom configuration +database. To do this the "db_meth" element of the X509V3_CTX structure should +be set to an X509V3_CTX_METHOD structure. This structure contains the following +function pointers: + +char * (*get_string)(void *db, char *section, char *value); +STACK_OF(CONF_VALUE) * (*get_section)(void *db, char *section); +void (*free_string)(void *db, char * string); +void (*free_section)(void *db, STACK_OF(CONF_VALUE) *section); + +these will be called and passed the 'db' element in the X509V3_CTX structure +to access the database. If a given function is not implemented or not required +it can be set to NULL. + +5. String helper functions. + +There are several "i2s" and "s2i" functions that convert structures to and +from ASCII strings. In all the "i2s" cases the returned string should be +freed using Free() after use. Since some of these are part of other extension +code they may take a 'method' parameter. Unless otherwise stated it can be +safely set to NULL. + +char *i2s_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, ASN1_OCTET_STRING *oct); + +This returns a hex string from an ASN1_OCTET_STRING. + +char * i2s_ASN1_INTEGER(X509V3_EXT_METHOD *meth, ASN1_INTEGER *aint); +char * i2s_ASN1_ENUMERATED(X509V3_EXT_METHOD *meth, ASN1_ENUMERATED *aint); + +These return a string decimal representations of an ASN1_INTEGER and an +ASN1_ENUMERATED type, respectively. + +ASN1_OCTET_STRING *s2i_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, + X509V3_CTX *ctx, char *str); + +This converts an ASCII hex string to an ASN1_OCTET_STRING. + +ASN1_INTEGER * s2i_ASN1_INTEGER(X509V3_EXT_METHOD *meth, char *value); + +This converts a decimal ASCII string into an ASN1_INTEGER. + +6. Multi valued extension helper functions. + +The following functions can be used to manipulate STACKs of CONF_VALUE +structures, as used by multi valued extensions. + +int X509V3_get_value_bool(CONF_VALUE *value, int *asn1_bool); + +This function expects a boolean value in 'value' and sets 'asn1_bool' to +it. That is it sets it to 0 for FALSE or 0xff for TRUE. The following +strings are acceptable: "TRUE", "true", "Y", "y", "YES", "yes", "FALSE" +"false", "N", "n", "NO" or "no". + +int X509V3_get_value_int(CONF_VALUE *value, ASN1_INTEGER **aint); + +This accepts a decimal integer of arbitrary length and sets an ASN1_INTEGER. + +int X509V3_add_value(const char *name, const char *value, + STACK_OF(CONF_VALUE) **extlist); + +This simply adds a string name and value pair. + +int X509V3_add_value_uchar(const char *name, const unsigned char *value, + STACK_OF(CONF_VALUE) **extlist); + +The same as above but for an unsigned character value. + +int X509V3_add_value_bool(const char *name, int asn1_bool, + STACK_OF(CONF_VALUE) **extlist); + +This adds either "TRUE" or "FALSE" depending on the value of 'ans1_bool' + +int X509V3_add_value_bool_nf(char *name, int asn1_bool, + STACK_OF(CONF_VALUE) **extlist); + +This is the same as above except it adds nothing if asn1_bool is FALSE. + +int X509V3_add_value_int(const char *name, ASN1_INTEGER *aint, + STACK_OF(CONF_VALUE) **extlist); + +This function adds the value of the ASN1_INTEGER in decimal form. + +7. Other helper functions. + + + +ADDING CUSTOM EXTENSIONS. + +Currently there are three types of supported extensions. + +String extensions are simple strings where the value is placed directly in the +extensions, and the string returned is printed out. + +Multi value extensions are passed a STACK_OF(CONF_VALUE) name and value pairs +or return a STACK_OF(CONF_VALUE). + +Raw extensions are just passed a BIO or a value and it is the extensions +responsiblity to handle all the necessary printing. + +There are two ways to add an extension. One is simply as an alias to an already +existing extension. An alias is an extension that is identical in ASN1 structure +to an existing extension but has a different OBJECT IDENTIFIER. This can be +done by calling: + +int X509V3_EXT_add_alias(int nid_to, int nid_from); + +'nid_to' is the new extension NID and 'nid_from' is the already existing +extension NID. + +Alternatively an extension can be written from scratch. This involves writing +the ASN1 code to encode and decode the extension and functions to print out and +generate the extension from strings. The relevant functions are then placed in +a X509V3_EXT_METHOD structure and int X509V3_EXT_add(X509V3_EXT_METHOD *ext); +called. + +The X509V3_EXT_METHOD structure is described below. + +strut { +int ext_nid; +int ext_flags; +X509V3_EXT_NEW ext_new; +X509V3_EXT_FREE ext_free; +X509V3_EXT_D2I d2i; +X509V3_EXT_I2D i2d; +X509V3_EXT_I2S i2s; +X509V3_EXT_S2I s2i; +X509V3_EXT_I2V i2v; +X509V3_EXT_V2I v2i; +X509V3_EXT_R2I r2i; +X509V3_EXT_I2R i2r; + +void *usr_data; +}; + +The elements have the following meanings. + +ext_nid is the NID of the object identifier of the extension. + +ext_flags is set of flags. Currently the only external flag is + X509V3_EXT_MULTILINE which means a multi valued extensions + should be printed on separate lines. + +usr_data is an extension specific pointer to any relevant data. This + allows extensions to share identical code but have different + uses. An example of this is the bit string extension which uses + usr_data to contain a list of the bit names. + +All the remaining elements are function pointers. + +ext_new is a pointer to a function that allocates memory for the + extension ASN1 structure: for example ASN1_OBJECT_new(). + +ext_free is a pointer to a function that free up memory of the extension + ASN1 structure: for example ASN1_OBJECT_free(). + +d2i is the standard ASN1 function that converts a DER buffer into + the internal ASN1 structure: for example d2i_ASN1_IA5STRING(). + +i2d is the standard ASN1 function that converts the internal + structure into the DER representation: for example + i2d_ASN1_IA5STRING(). + +The remaining functions are depend on the type of extension. One i2X and +one X2i should be set and the rest set to NULL. The types set do not need +to match up, for example the extension could be set using the multi valued +v2i function and printed out using the raw i2r. + +All functions have the X509V3_EXT_METHOD passed to them in the 'method' +parameter and an X509V3_CTX structure. Extension code can then access the +parent structure via the 'method' parameter to for example make use of the value +of usr_data. If the code needs to use detail relating to the request it can +use the 'ctx' parameter. + +A note should be given here about the 'flags' member of the 'ctx' parameter. +If it has the value CTX_TEST then the configuration syntax is being checked +and no actual certificate or CRL exists. Therefore any attempt in the config +file to access such information should silently succeed. If the syntax is OK +then it should simply return a (possibly bogus) extension, otherwise it +should return NULL. + +char *i2s(struct v3_ext_method *method, void *ext); + +This function takes the internal structure in the ext parameter and returns +a Malloc'ed string representing its value. + +void * s2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); + +This function takes the string representation in the ext parameter and returns +an allocated internal structure: ext_free() will be used on this internal +structure after use. + +i2v and v2i handle a STACK_OF(CONF_VALUE): + +typedef struct +{ + char *section; + char *name; + char *value; +} CONF_VALUE; + +Only the name and value members are currently used. + +STACK_OF(CONF_VALUE) * i2v(struct v3_ext_method *method, void *ext); + +This function is passed the internal structure in the ext parameter and +returns a STACK of CONF_VALUE structures. The values of name, value, +section and the structure itself will be freed up with Free after use. +Several helper functions are available to add values to this STACK. + +void * v2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, + STACK_OF(CONF_VALUE) *values); + +This function takes a STACK_OF(CONF_VALUE) structures and should set the +values of the external structure. This typically uses the name element to +determine which structure element to set and the value element to determine +what to set it to. Several helper functions are available for this +purpose (see above). + +int i2r(struct v3_ext_method *method, void *ext, BIO *out, int indent); + +This function is passed the internal extension structure in the ext parameter +and sends out a human readable version of the extension to out. The 'indent' +paremeter should be noted to determine the necessary amount of indentation +needed on the output. + +void * r2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); + +This is just passed the string representation of the extension. It is intended +to be used for more elaborate extensions where the standard single and multi +valued options are insufficient. They can use the 'ctx' parameter to parse the +configuration database themselves. See the context functions section for details +of how to do this. + +Note: although this type takes the same parameters as the "r2s" function there +is a subtle difference. Whereas an "r2i" function can access a configuration +database an "s2i" function MUST NOT. This is so the internal code can safely +assume that an "s2i" function will work without a configuration database. + +============================================================================== + PKCS#12 Library +============================================================================== + +This section describes the internal PKCS#12 support. There are very few +differences between the old external library and the new internal code at +present. This may well change because the external library will not be updated +much in future. + +This version now includes a couple of high level PKCS#12 functions which +generally "do the right thing" and should make it much easier to handle PKCS#12 +structures. + +HIGH LEVEL FUNCTIONS. + +For most applications you only need concern yourself with the high level +functions. They can parse and generate simple PKCS#12 files as produced by +Netscape and MSIE or indeed any compliant PKCS#12 file containing a single +private key and certificate pair. + +1. Initialisation and cleanup. + +No special initialisation is needed for the internal PKCS#12 library: the +standard SSLeay_add_all_algorithms() is sufficient. If you do not wish to +add all algorithms (you should at least add SHA1 though) then you can manually +initialise the PKCS#12 library with: + +PKCS12_PBE_add(); + +The memory allocated by the PKCS#12 library is freed up when EVP_cleanup() is +called or it can be directly freed with: + +EVP_PBE_cleanup(); + +after this call (or EVP_cleanup() ) no more PKCS#12 library functions should +be called. + +2. I/O functions. + +i2d_PKCS12_bio(bp, p12) + +This writes out a PKCS12 structure to a BIO. + +i2d_PKCS12_fp(fp, p12) + +This is the same but for a FILE pointer. + +d2i_PKCS12_bio(bp, p12) + +This reads in a PKCS12 structure from a BIO. + +d2i_PKCS12_fp(fp, p12) + +This is the same but for a FILE pointer. + +3. Parsing and creation functions. + +3.1 Parsing with PKCS12_parse(). + +int PKCS12_parse(PKCS12 *p12, char *pass, EVP_PKEY **pkey, X509 **cert, + STACK **ca); + +This function takes a PKCS12 structure and a password (ASCII, null terminated) +and returns the private key, the corresponding certificate and any CA +certificates. If any of these is not required it can be passed as a NULL. +The 'ca' parameter should be either NULL, a pointer to NULL or a valid STACK +structure. Typically to read in a PKCS#12 file you might do: + +p12 = d2i_PKCS12_fp(fp, NULL); +PKCS12_parse(p12, password, &pkey, &cert, NULL); /* CAs not wanted */ +PKCS12_free(p12); + +3.2 PKCS#12 creation with PKCS12_create(). + +PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert, + STACK *ca, int nid_key, int nid_cert, int iter, + int mac_iter, int keytype); + +This function will create a PKCS12 structure from a given password, name, +private key, certificate and optional STACK of CA certificates. The remaining +5 parameters can be set to 0 and sensible defaults will be used. + +The parameters nid_key and nid_cert are the key and certificate encryption +algorithms, iter is the encryption iteration count, mac_iter is the MAC +iteration count and keytype is the type of private key. If you really want +to know what these last 5 parameters do then read the low level section. + +Typically to create a PKCS#12 file the following could be used: + +p12 = PKCS12_create(pass, "My Certificate", pkey, cert, NULL, 0,0,0,0,0); +i2d_PKCS12_fp(fp, p12); +PKCS12_free(p12); + +LOW LEVEL FUNCTIONS. + +In some cases the high level functions do not provide the necessary +functionality. For example if you want to generate or parse more complex +PKCS#12 files. The sample pkcs12 application uses the low level functions +to display details about the internal structure of a PKCS#12 file. + +Introduction. + +This is a brief description of how a PKCS#12 file is represented internally: +some knowledge of PKCS#12 is assumed. + +A PKCS#12 object contains several levels. + +At the lowest level is a PKCS12_SAFEBAG. This can contain a certificate, a +CRL, a private key, encrypted or unencrypted, a set of safebags (so the +structure can be nested) or other secrets (not documented at present). +A safebag can optionally have attributes, currently these are: a unicode +friendlyName (a Unicode string) or a localKeyID (a string of bytes). + +At the next level is an authSafe which is a set of safebags collected into +a PKCS#7 ContentInfo. This can be just plain data, or encrypted itself. + +At the top level is the PKCS12 structure itself which contains a set of +authSafes in an embedded PKCS#7 Contentinfo of type data. In addition it +contains a MAC which is a kind of password protected digest to preserve +integrity (so any unencrypted stuff below can't be tampered with). + +The reason for these levels is so various objects can be encrypted in various +ways. For example you might want to encrypt a set of private keys with +triple-DES and then include the related certificates either unencrypted or +with lower encryption. Yes it's the dreaded crypto laws at work again which +allow strong encryption on private keys and only weak encryption on other +stuff. + +To build one of these things you turn all certificates and keys into safebags +(with optional attributes). You collect the safebags into (one or more) STACKS +and convert these into authsafes (encrypted or unencrypted). The authsafes +are collected into a STACK and added to a PKCS12 structure. Finally a MAC +inserted. + +Pulling one apart is basically the reverse process. The MAC is verified against +the given password. The authsafes are extracted and each authsafe split into +a set of safebags (possibly involving decryption). Finally the safebags are +decomposed into the original keys and certificates and the attributes used to +match up private key and certificate pairs. + +Anyway here are the functions that do the dirty work. + +1. Construction functions. + +1.1 Safebag functions. + +M_PKCS12_x5092certbag(x509) + +This macro takes an X509 structure and returns a certificate bag. The +X509 structure can be freed up after calling this function. + +M_PKCS12_x509crl2certbag(crl) + +As above but for a CRL. + +PKCS8_PRIV_KEY_INFO *PKEY2PKCS8(EVP_PKEY *pkey) + +Take a private key and convert it into a PKCS#8 PrivateKeyInfo structure. +Works for both RSA and DSA private keys. NB since the PKCS#8 PrivateKeyInfo +structure contains a private key data in plain text form it should be free'd +up as soon as it has been encrypted for security reasons (freeing up the +structure zeros out the sensitive data). This can be done with +PKCS8_PRIV_KEY_INFO_free(). + +PKCS8_add_keyusage(PKCS8_PRIV_KEY_INFO *p8, int usage) + +This sets the key type when a key is imported into MSIE or Outlook 98. Two +values are currently supported: KEY_EX and KEY_SIG. KEY_EX is an exchange type +key that can also be used for signing but its size is limited in the export +versions of MS software to 512 bits, it is also the default. KEY_SIG is a +signing only key but the keysize is unlimited (well 16K is supposed to work). +If you are using the domestic version of MSIE then you can ignore this because +KEY_EX is not limited and can be used for both. + +PKCS12_SAFEBAG *PKCS12_MAKE_KEYBAG(PKCS8_PRIV_KEY_INFO *p8) + +Convert a PKCS8 private key structure into a keybag. This routine embeds the +p8 structure in the keybag so p8 should not be freed up or used after it is +called. The p8 structure will be freed up when the safebag is freed. + +PKCS12_SAFEBAG *PKCS12_MAKE_SHKEYBAG(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8) + +Convert a PKCS#8 structure into a shrouded key bag (encrypted). p8 is not +embedded and can be freed up after use. + +int PKCS12_add_localkeyid(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) +int PKCS12_add_friendlyname(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) + +Add a local key id or a friendlyname to a safebag. + +1.2 Authsafe functions. + +PKCS7 *PKCS12_pack_p7data(STACK *sk) +Take a stack of safebags and convert them into an unencrypted authsafe. The +stack of safebags can be freed up after calling this function. + +PKCS7 *PKCS12_pack_p7encdata(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, STACK *bags); + +As above but encrypted. + +1.3 PKCS12 functions. + +PKCS12 *PKCS12_init(int mode) + +Initialise a PKCS12 structure (currently mode should be NID_pkcs7_data). + +M_PKCS12_pack_authsafes(p12, safes) + +This macro takes a STACK of authsafes and adds them to a PKCS#12 structure. + +int PKCS12_set_mac(PKCS12 *p12, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, EVP_MD *md_type); + +Add a MAC to a PKCS12 structure. If EVP_MD is NULL use SHA-1, the spec suggests +that SHA-1 should be used. + +2. Extraction Functions. + +2.1 Safebags. + +M_PKCS12_bag_type(bag) + +Return the type of "bag". Returns one of the following + +NID_keyBag +NID_pkcs8ShroudedKeyBag 7 +NID_certBag 8 +NID_crlBag 9 +NID_secretBag 10 +NID_safeContentsBag 11 + +M_PKCS12_cert_bag_type(bag) + +Returns type of certificate bag, following are understood. + +NID_x509Certificate 14 +NID_sdsiCertificate 15 + +M_PKCS12_crl_bag_type(bag) + +Returns crl bag type, currently only NID_crlBag is recognised. + +M_PKCS12_certbag2x509(bag) + +This macro extracts an X509 certificate from a certificate bag. + +M_PKCS12_certbag2x509crl(bag) + +As above but for a CRL. + +EVP_PKEY * PKCS82PKEY(PKCS8_PRIV_KEY_INFO *p8) + +Extract a private key from a PKCS8 private key info structure. + +M_PKCS12_decrypt_skey(bag, pass, passlen) + +Decrypt a shrouded key bag and return a PKCS8 private key info structure. +Works with both RSA and DSA keys + +char *PKCS12_get_friendlyname(bag) + +Returns the friendlyName of a bag if present or NULL if none. The returned +string is a null terminated ASCII string allocated with Malloc(). It should +thus be freed up with Free() after use. + +2.2 AuthSafe functions. + +M_PKCS12_unpack_p7data(p7) + +Extract a STACK of safe bags from a PKCS#7 data ContentInfo. + +#define M_PKCS12_unpack_p7encdata(p7, pass, passlen) + +As above but for an encrypted content info. + +2.3 PKCS12 functions. + +M_PKCS12_unpack_authsafes(p12) + +Extract a STACK of authsafes from a PKCS12 structure. + +M_PKCS12_mac_present(p12) + +Check to see if a MAC is present. + +int PKCS12_verify_mac(PKCS12 *p12, unsigned char *pass, int passlen) + +Verify a MAC on a PKCS12 structure. Returns an error if MAC not present. + + +Notes. + +1. All the function return 0 or NULL on error. +2. Encryption based functions take a common set of parameters. These are +described below. + +pass, passlen +ASCII password and length. The password on the MAC is called the "integrity +password" the encryption password is called the "privacy password" in the +PKCS#12 documentation. The passwords do not have to be the same. If -1 is +passed for the length it is worked out by the function itself (currently +this is sometimes done whatever is passed as the length but that may change). + +salt, saltlen +A 'salt' if salt is NULL a random salt is used. If saltlen is also zero a +default length is used. + +iter +Iteration count. This is a measure of how many times an internal function is +called to encrypt the data. The larger this value is the longer it takes, it +makes dictionary attacks on passwords harder. NOTE: Some implementations do +not support an iteration count on the MAC. If the password for the MAC and +encryption is the same then there is no point in having a high iteration +count for encryption if the MAC has no count. The MAC could be attacked +and the password used for the main decryption. + +pbe_nid +This is the NID of the password based encryption method used. The following are +supported. +NID_pbe_WithSHA1And128BitRC4 +NID_pbe_WithSHA1And40BitRC4 +NID_pbe_WithSHA1And3_Key_TripleDES_CBC +NID_pbe_WithSHA1And2_Key_TripleDES_CBC +NID_pbe_WithSHA1And128BitRC2_CBC +NID_pbe_WithSHA1And40BitRC2_CBC + +Which you use depends on the implementation you are exporting to. "Export +grade" (i.e. cryptographically challenged) products cannot support all +algorithms. Typically you may be able to use any encryption on shrouded key +bags but they must then be placed in an unencrypted authsafe. Other authsafes +may only support 40bit encryption. Of course if you are using SSLeay +throughout you can strongly encrypt everything and have high iteration counts +on everything. + +3. For decryption routines only the password and length are needed. + +4. Unlike the external version the nid's of objects are the values of the +constants: that is NID_certBag is the real nid, therefore there is no +PKCS12_obj_offset() function. Note the object constants are not the same as +those of the external version. If you use these constants then you will need +to recompile your code. + +5. With the exception of PKCS12_MAKE_KEYBAG(), after calling any function or +macro of the form PKCS12_MAKE_SOMETHING(other) the "other" structure can be +reused or freed up safely. + diff --git a/src/lib/libssl/doc/standards.txt b/src/lib/libssl/doc/standards.txt new file mode 100644 index 0000000000..61ccc5d7e0 --- /dev/null +++ b/src/lib/libssl/doc/standards.txt @@ -0,0 +1,121 @@ +Standards related to OpenSSL +============================ + +[Please, this is currently a draft. I made a first try at finding + documents that describe parts of what OpenSSL implements. There are + big gaps, and I've most certainly done something wrong. Please + correct whatever is... Also, this note should be removed when this + file is reaching a somewhat correct state. -- Richard Levitte] + + +All pointers in here will be either URL's or blobs of text borrowed +from miscellaneous indexes, like rfc-index.txt (index of RFCs), +1id-index.txt (index of Internet drafts) and the like. + +To find the latest possible RFCs, it's recommended to either browse +ftp://ftp.isi.edu/in-notes/ or go to http://www.rfc-editor.org/ and +use the search mechanism found there. +To find the latest possible Internet drafts, it's recommended to +browse ftp://ftp.isi.edu/internet-drafts/. +To find the latest possible PKCS, it's recommended to browse +http://www.rsasecurity.com/rsalabs/pkcs/. + + +Implemented: +------------ + +These are documents that describe things that are implemented in OpenSSL. + +1319 The MD2 Message-Digest Algorithm. B. Kaliski. April 1992. + (Format: TXT=25661 bytes) (Status: INFORMATIONAL) + +1320 The MD4 Message-Digest Algorithm. R. Rivest. April 1992. (Format: + TXT=32407 bytes) (Status: INFORMATIONAL) + +1321 The MD5 Message-Digest Algorithm. R. Rivest. April 1992. (Format: + TXT=35222 bytes) (Status: INFORMATIONAL) + +2246 The TLS Protocol Version 1.0. T. Dierks, C. Allen. January 1999. + (Format: TXT=170401 bytes) (Status: PROPOSED STANDARD) + +2268 A Description of the RC2(r) Encryption Algorithm. R. Rivest. + January 1998. (Format: TXT=19048 bytes) (Status: INFORMATIONAL) + +2314 PKCS 10: Certification Request Syntax Version 1.5. B. Kaliski. + March 1998. (Format: TXT=15814 bytes) (Status: INFORMATIONAL) + +2315 PKCS 7: Cryptographic Message Syntax Version 1.5. B. Kaliski. + March 1998. (Format: TXT=69679 bytes) (Status: INFORMATIONAL) + +2437 PKCS #1: RSA Cryptography Specifications Version 2.0. B. Kaliski, + J. Staddon. October 1998. (Format: TXT=73529 bytes) (Obsoletes + RFC2313) (Status: INFORMATIONAL) + +2459 Internet X.509 Public Key Infrastructure Certificate and CRL + Profile. R. Housley, W. Ford, W. Polk, D. Solo. January 1999. + (Format: TXT=278438 bytes) (Status: PROPOSED STANDARD) + +PKCS#8: Private-Key Information Syntax Standard + +PKCS#12: Personal Information Exchange Syntax Standard, version 1.0. + + +Related: +-------- + +These are documents that are close to OpenSSL, for example the +STARTTLS documents. + +1421 Privacy Enhancement for Internet Electronic Mail: Part I: Message + Encryption and Authentication Procedures. J. Linn. February 1993. + (Format: TXT=103894 bytes) (Obsoletes RFC1113) (Status: PROPOSED + STANDARD) + +1422 Privacy Enhancement for Internet Electronic Mail: Part II: + Certificate-Based Key Management. S. Kent. February 1993. (Format: + TXT=86085 bytes) (Obsoletes RFC1114) (Status: PROPOSED STANDARD) + +1423 Privacy Enhancement for Internet Electronic Mail: Part III: + Algorithms, Modes, and Identifiers. D. Balenson. February 1993. + (Format: TXT=33277 bytes) (Obsoletes RFC1115) (Status: PROPOSED + STANDARD) + +1424 Privacy Enhancement for Internet Electronic Mail: Part IV: Key + Certification and Related Services. B. Kaliski. February 1993. + (Format: TXT=17537 bytes) (Status: PROPOSED STANDARD) + +2487 SMTP Service Extension for Secure SMTP over TLS. P. Hoffman. + January 1999. (Format: TXT=15120 bytes) (Status: PROPOSED STANDARD) + +2585 Internet X.509 Public Key Infrastructure Operational Protocols: + FTP and HTTP. R. Housley, P. Hoffman. May 1999. (Format: TXT=14813 + bytes) (Status: PROPOSED STANDARD) + +2595 Using TLS with IMAP, POP3 and ACAP. C. Newman. June 1999. + (Format: TXT=32440 bytes) (Status: PROPOSED STANDARD) + +2712 Addition of Kerberos Cipher Suites to Transport Layer Security + (TLS). A. Medvinsky, M. Hur. October 1999. (Format: TXT=13763 bytes) + (Status: PROPOSED STANDARD) + +2817 Upgrading to TLS Within HTTP/1.1. R. Khare, S. Lawrence. May + 2000. (Format: TXT=27598 bytes) (Updates RFC2616) (Status: PROPOSED + STANDARD) + +2818 HTTP Over TLS. E. Rescorla. May 2000. (Format: TXT=15170 bytes) + (Status: INFORMATIONAL) + + "Securing FTP with TLS", 01/27/2000, + + +To be implemented: +------------------ + +These are documents that describe things that are planed to be +implemented in the hopefully short future. + +2560 X.509 Internet Public Key Infrastructure Online Certificate + Status Protocol - OCSP. M. Myers, R. Ankney, A. Malpani, S. Galperin, + C. Adams. June 1999. (Format: TXT=43243 bytes) (Status: PROPOSED + STANDARD) + diff --git a/src/lib/libssl/test/VMSca-response.1 b/src/lib/libssl/test/VMSca-response.1 new file mode 100644 index 0000000000..8b13789179 --- /dev/null +++ b/src/lib/libssl/test/VMSca-response.1 @@ -0,0 +1 @@ + diff --git a/src/lib/libssl/test/VMSca-response.2 b/src/lib/libssl/test/VMSca-response.2 new file mode 100644 index 0000000000..9b48ee4cf9 --- /dev/null +++ b/src/lib/libssl/test/VMSca-response.2 @@ -0,0 +1,2 @@ +y +y diff --git a/src/lib/libssl/test/bctest b/src/lib/libssl/test/bctest new file mode 100644 index 0000000000..bdb3218f7a --- /dev/null +++ b/src/lib/libssl/test/bctest @@ -0,0 +1,111 @@ +#!/bin/sh + +# This script is used by test/Makefile.ssl to check whether a sane 'bc' +# is installed. +# ('make test_bn' should not try to run 'bc' if it does not exist or if +# it is a broken 'bc' version that is known to cause trouble.) +# +# If 'bc' works, we also test if it knows the 'print' command. +# +# In any case, output an appropriate command line for running (or not +# running) bc. + + +IFS=: +try_without_dir=true +# First we try "bc", then "$dir/bc" for each item in $PATH. +for dir in dummy:$PATH; do + if [ "$try_without_dir" = true ]; then + # first iteration + bc=bc + try_without_dir=false + else + # second and later iterations + bc="$dir/bc" + if [ ! -f "$bc" ]; then # '-x' is not available on Ultrix + bc='' + fi + fi + + if [ ! "$bc" = '' ]; then + failure=none + + + # Test for SunOS 5.[78] bc bug + "$bc" >tmp.bctest <<\EOF +obase=16 +ibase=16 +a=AD88C418F31B3FC712D0425001D522B3AE9134FF3A98C13C1FCC1682211195406C1A6C66C6A\ +CEEC1A0EC16950233F77F1C2F2363D56DD71A36C57E0B2511FC4BA8F22D261FE2E9356D99AF57\ +10F3817C0E05BF79C423C3F66FDF321BE8D3F18F625D91B670931C1EF25F28E489BDA1C5422D1\ +C3F6F7A1AD21585746ECC4F10A14A778AF56F08898E965E9909E965E0CB6F85B514150C644759\ +3BE731877B16EA07B552088FF2EA728AC5E0FF3A23EB939304519AB8B60F2C33D6BA0945B66F0\ +4FC3CADF855448B24A9D7640BCF473E +b=DCE91E7D120B983EA9A104B5A96D634DD644C37657B1C7860B45E6838999B3DCE5A555583C6\ +9209E41F413422954175A06E67FFEF6746DD652F0F48AEFECC3D8CAC13523BDAAD3F5AF4212BD\ +8B3CD64126E1A82E190228020C05B91C8B141F1110086FC2A4C6ED631EBA129D04BB9A19FC53D\ +3ED0E2017D60A68775B75481449 +(a/b)*b + (a%b) - a +EOF + if [ 0 != "`cat tmp.bctest`" ]; then + failure=SunOStest + fi + + + if [ "$failure" = none ]; then + # Test for SCO bc bug. + "$bc" >tmp.bctest <<\EOF +obase=16 +ibase=16 +-FFDD63BA1A4648F0D804F8A1C66C53F0D2110590E8A3907EC73B4AEC6F15AC177F176F2274D2\ +9DC8022EA0D7DD3ABE9746D2D46DD3EA5B5F6F69DF12877E0AC5E7F5ADFACEE54573F5D256A06\ +11B5D2BC24947724E22AE4EC3FB0C39D9B4694A01AFE5E43B4D99FB9812A0E4A5773D8B254117\ +1239157EC6E3D8D50199 * -FFDD63BA1A4648F0D804F8A1C66C53F0D2110590E8A3907EC73B4\ +AEC6F15AC177F176F2274D29DC8022EA0D7DD3ABE9746D2D46DD3EA5B5F6F69DF12877E0AC5E7\ +F5ADFACEE54573F5D256A0611B5D2BC24947724E22AE4EC3FB0C39D9B4694A01AFE5E43B4D99F\ +B9812A0E4A5773D8B2541171239157EC6E3D8D50199 - FFBACC221682DA464B6D7F123482522\ +02EDAEDCA38C3B69E9B7BBCD6165A9CD8716C4903417F23C09A85B851961F92C217258CEEB866\ +85EFCC5DD131853A02C07A873B8E2AF2E40C6D5ED598CD0E8F35AD49F3C3A17FDB7653E4E2DC4\ +A8D23CC34686EE4AD01F7407A7CD74429AC6D36DBF0CB6A3E302D0E5BDFCD048A3B90C1BE5AA8\ +E16C3D5884F9136B43FF7BB443764153D4AEC176C681B078F4CC53D6EB6AB76285537DDEE7C18\ +8C72441B52EDBDDBC77E02D34E513F2AABF92F44109CAFE8242BD0ECBAC5604A94B02EA44D43C\ +04E9476E6FBC48043916BFA1485C6093603600273C9C33F13114D78064AE42F3DC466C7DA543D\ +89C8D71 +AD534AFBED2FA39EE9F40E20FCF9E2C861024DB98DDCBA1CD118C49CA55EEBC20D6BA51B2271C\ +928B693D6A73F67FEB1B4571448588B46194617D25D910C6A9A130CC963155CF34079CB218A44\ +8A1F57E276D92A33386DDCA3D241DB78C8974ABD71DD05B0FA555709C9910D745185E6FE108E3\ +37F1907D0C56F8BFBF52B9704 % -E557905B56B13441574CAFCE2BD257A750B1A8B2C88D0E36\ +E18EF7C38DAC80D3948E17ED63AFF3B3467866E3B89D09A81B3D16B52F6A3C7134D3C6F5123E9\ +F617E3145BBFBE9AFD0D6E437EA4FF6F04BC67C4F1458B4F0F47B64 - 1C2BBBB19B74E86FD32\ +9E8DB6A8C3B1B9986D57ED5419C2E855F7D5469E35E76334BB42F4C43E3F3A31B9697C171DAC4\ +D97935A7E1A14AD209D6CF811F55C6DB83AA9E6DFECFCD6669DED7171EE22A40C6181615CAF3F\ +5296964 +EOF + if [ "0 +0" != "`cat tmp.bctest`" ]; then + failure=SCOtest + fi + fi + + + if [ "$failure" = none ]; then + # bc works; now check if it knows the 'print' command. + if [ "OK" = "`echo 'print \"OK\"' | $bc 2>/dev/null`" ] + then + echo "$bc" + else + echo "sed 's/print.*//' | $bc" + fi + exit 0 + fi + + echo "$bc does not work properly ('$failure' failed). Looking for another bc ..." >&2 + fi +done + +echo "No working bc found. Consider installing GNU bc." >&2 +if [ "$1" = ignore ]; then + echo "cat >/dev/null" + exit 0 +fi +exit 1 -- cgit v1.2.3-55-g6feb