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.
+Contents:
-char * BUF_strdup(char *str)
+ OpenSSL X509V3 extension configuration
+ X509V3 Extension code: programmers guide
+ PKCS#12 Library
-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
email.2=steve@there
This is because the configuration file code cannot handle the same name
-occurring twice in the same extension.
+occurring twice in the same section.
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.
+There are two ways to encode arbitrary extensions.
+
+The first way is to use the word ASN1 followed by the extension content
+using the same syntax as ASN1_generate_nconf(). For example:
+
+1.2.3.4=critical,ASN1:UTF8String:Some random data
+
+1.2.3.4=ASN1:SEQUENCE:seq_sect
+
+[seq_sect]
+
+field1 = UTF8:field1
+field2 = UTF8:field2
+
+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
According to PKIX recommendations it should exclude the extension entirely,
however some software may require CA set to FALSE for end entity certificates.
+Extended Key Usage.
+
+This extensions consists of a list of usages.
+
+These can either be object short names of the dotted numerical form of OIDs.
+While any OID can be used only certain values make sense. In particular the
+following PKIX, NS and MS values are meaningful:
+
+Value Meaning
+----- -------
+serverAuth SSL/TLS Web Server Authentication.
+clientAuth SSL/TLS Web Client Authentication.
+codeSigning Code signing.
+emailProtection E-mail Protection (S/MIME).
+timeStamping Trusted Timestamping
+msCodeInd Microsoft Individual Code Signing (authenticode)
+msCodeCom Microsoft Commercial Code Signing (authenticode)
+msCTLSign Microsoft Trust List Signing
+msSGC Microsoft Server Gated Crypto
+msEFS Microsoft Encrypted File System
+nsSGC Netscape Server Gated Crypto
+
+For example, under IE5 a CA can be used for any purpose: by including a list
+of the above usages the CA can be restricted to only authorised uses.
+
+Note: software packages may place additional interpretations on certificate
+use, in particular some usages may only work for selected CAs. Don't for example
+expect just including msSGC or nsSGC will automatically mean that a certificate
+can be used for SGC ("step up" encryption) otherwise anyone could use it.
+
+Examples:
+
+extendedKeyUsage=critical,codeSigning,1.2.3.4
+extendedKeyUsage=nsSGC,msSGC
+
Subject Key Identifier.
This is really a string extension and can take two possible values. Either
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).
+registered ID: OBJECT IDENTIFIER), IP (and IP address) and otherName.
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.
+otherName can include arbitrary data associated with an OID: the value
+should be the OID followed by a semicolon and the content in standard
+ASN1_generate_nconf() format.
+
Examples:
-subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/
+subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/
subjectAltName=email:my@other.address,RID:1.2.3.4
+subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
Issuer Alternative Name.
that will copy all the subject alternative name values from the issuer
certificate (if possible).
+Example:
+
+issuserAltName = issuer:copy
+
+Authority Info Access.
+
+The authority information access extension gives details about how to access
+certain information relating to the CA. Its syntax is accessOID;location
+where 'location' has the same syntax as subject alternative name (except
+that email:copy is not supported). accessOID can be any valid OID but only
+certain values are meaningful for example OCSP and caIssuers. OCSP gives the
+location of an OCSP responder: this is used by Netscape PSM and other software.
+
+Example:
+
+authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
+authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
+
CRL distribution points.
This is a multi-valued extension that supports all the literal options of
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).
+No special initialisation is needed before calling the extension functions.
+You used to have to call X509V3_add_standard_extensions(); but this is no longer
+required and this function no longer does anything.
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.
+This function should be called to cleanup the extension code if any custom
+extensions have been added. If no custom extensions have been added then this
+call does nothing. After this call all custom extension code is freed up but
+you can still use the standard extensions.
2. Printing and parsing extensions.
after use using the relevant free function, BASIC_CONSTRAINTS_free() for
example.
+void * X509_get_ext_d2i(X509 *x, int nid, int *crit, int *idx);
+void * X509_CRL_get_ext_d2i(X509_CRL *x, int nid, int *crit, int *idx);
+void * X509_REVOKED_get_ext_d2i(X509_REVOKED *x, int nid, int *crit, int *idx);
+void * X509V3_get_d2i(STACK_OF(X509_EXTENSION) *x, int nid, int *crit, int *idx);
+
+These functions combine the operations of searching for extensions and
+parsing them. They search a certificate, a CRL a CRL entry or a stack
+of extensions respectively for extension whose NID is 'nid' and return
+the parsed result of NULL if an error occurred. For example:
+
+BASIC_CONSTRAINTS *bs;
+bs = X509_get_ext_d2i(cert, NID_basic_constraints, NULL, NULL);
+
+This will search for the basicConstraints extension and either return
+it value or NULL. NULL can mean either the extension was not found, it
+occurred more than once or it could not be parsed.
+
+If 'idx' is NULL then an extension is only parsed if it occurs precisely
+once. This is standard behaviour because extensions normally cannot occur
+more than once. If however more than one extension of the same type can
+occur it can be used to parse successive extensions for example:
+
+int i;
+void *ext;
+
+i = -1;
+for(;;) {
+ ext = X509_get_ext_d2i(x, nid, crit, &idx);
+ if(ext == NULL) break;
+ /* Do something with ext */
+}
+
+If 'crit' is not NULL and the extension was found then the int it points to
+is set to 1 for critical extensions and 0 for non critical. Therefore if the
+function returns NULL but 'crit' is set to 0 or 1 then the extension was
+found but it could not be parsed.
+
+The int pointed to by crit will be set to -1 if the extension was not found
+and -2 if the extension occurred more than once (this will only happen if
+idx is NULL). In both cases the function will return NULL.
+
3. Generating extensions.
An extension will typically be generated from a configuration file, or some
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.
+See the 'context functions' section for a description of the ctx parameter.
X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *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");
+x = X509V3_EXT_conf_nid(NULL, NULL, NID_basic_constraints,"CA:TRUE,pathlen:10");
X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc);
This function frees up the string returned by the above function.
-STACK * X509V3_get_section(X509V3_CTX *ctx, char *section);
+STACK_OF(CONF_VALUE) * X509V3_get_section(X509V3_CTX *ctx, char *section);
-This function returns a whole section as a STACK of CONF_VALUE structures.
+This function returns a whole section as a STACK_OF(CONF_VALUE) .
-void X509V3_section_free( X509V3_CTX *ctx, STACK *section);
+void X509V3_section_free( X509V3_CTX *ctx, STACK_OF(CONF_VALUE) *section);
This function frees up the STACK returned by the above function.
function pointers:
char * (*get_string)(void *db, char *section, char *value);
-STACK * (*get_section)(void *db, char *section);
+STACK_OF(CONF_VALUE) * (*get_section)(void *db, char *section);
void (*free_string)(void *db, char * string);
-void (*free_section)(void *db, STACK *section);
+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
This accepts a decimal integer of arbitrary length and sets an ASN1_INTEGER.
-int X509V3_add_value(const char *name, const char *value, STACK **extlist);
+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 **extlist);
+ 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 **extlist);
+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'
+This adds either "TRUE" or "FALSE" depending on the value of 'asn1_bool'
-int X509V3_add_value_bool_nf(char *name, int asn1_bool, STACK **extlist);
+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 **extlist);
+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.
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 name and value pairs or return
-such a STACK.
+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.
+responsibility 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
an allocated internal structure: ext_free() will be used on this internal
structure after use.
-i2v and v2i handle a stack of CONF_VALUE structures:
+i2v and v2i handle a STACK_OF(CONF_VALUE):
typedef struct
{
Only the name and value members are currently used.
-STACK * i2v(struct v3_ext_method *method, void *ext);
+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 *values);
+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
+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
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
+parameter 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 the same but for a FILE pointer.
-3. Parsing and creation functions.
+3. High level functions.
3.1 Parsing with PKCS12_parse().
i2d_PKCS12_fp(fp, p12);
PKCS12_free(p12);
+3.3 Changing a PKCS#12 structure password.
+
+int PKCS12_newpass(PKCS12 *p12, char *oldpass, char *newpass);
+
+This changes the password of an already existing PKCS#12 structure. oldpass
+is the old password and newpass is the new one. An error occurs if the old
+password is incorrect.
+
LOW LEVEL FUNCTIONS.
In some cases the high level functions do not provide the necessary
projects / openssl.git / blobdiff