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)
+Contents:
-This frees up an already existing buffer. The data is zeroed before freeing
-up in case the buffer contains sensitive data.
+ OpenSSL X509V3 extension configuration
+ X509V3 Extension code: programmers guide
+ PKCS#12 Library
-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
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
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
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
The X509V3_EXT_METHOD structure is described below.
-strut {
+struct {
int ext_nid;
int ext_flags;
X509V3_EXT_NEW ext_new;
projects / openssl.git / blobdiff