X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fopenssl.txt;h=37730b2cbd2f872c534c424677fb19dc0030ff5e;hp=73272509c0348041236cfba5ea43504bb2dc6042;hb=e88c57773873240edd96732112fcbf5a407e4a90;hpb=1f2f9224554223e043056e14dff0873121d23387 diff --git a/doc/openssl.txt b/doc/openssl.txt index 73272509c0..37730b2cbd 100644 --- a/doc/openssl.txt +++ b/doc/openssl.txt @@ -1,53 +1,12 @@ 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() +Contents: -This allocates a new buffer of zero size. Returns the buffer or NULL on error. + OpenSSL X509V3 extension configuration + X509V3 Extension code: programmers guide + PKCS#12 Library -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 @@ -195,8 +154,22 @@ 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 @@ -377,16 +350,21 @@ 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). +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. @@ -396,6 +374,24 @@ 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). +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 @@ -530,6 +526,47 @@ details about the structures returned. The returned structure should be freed 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