This commit was manufactured by cvs2git to create tag 'OPENBSD_2_6_BASE'.OPENBSD_2_6_BASE

1 files changed, 0 insertions, 1174 deletions

diff --git a/src/lib/libssl/doc/openssl.txt b/src/lib/libssl/doc/openssl.txt
deleted file mode 100644
index 91b85e5f14..0000000000
--- a/src/lib/libssl/doc/openssl.txt
+++ /dev/null
@@ -1,1174 +0,0 @@
-
-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 <UNSUPPORTED> 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.
-
-<to be added>
-
-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.
-