Add BIO_read() (etc.) docs.

* Why does the linker complain about undefined symbols?

* Where can I get a compiled version of OpenSSL?

* I've compiled a program under Windows and it crashes: why?

* How do I read or write a DER encoded buffer using the ASN1 functions?

* I've tried using <M_some_evil_pkcs12_macro> and I get errors why?

* I've called <some function> and it fails, why?

* I just get a load of numbers for the error output, what do they mean?

first BIO related read or write operation.

* How do I read or write a DER encoded buffer using the ASN1 functions?

You have two options. You can either use a memory BIO in conjunction

with the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the

i2d_XXX(), d2i_XXX() functions directly. Since these are often the

cause of grief here are some code fragments using PKCS7 as an example:

unsigned char *buf, *p;

int len;

len = i2d_PKCS7(p7, NULL);

buf = OPENSSL_Malloc(len); /* or Malloc, error checking omitted */

p = buf;

i2d_PKCS7(p7, &p);

At this point buf contains the len bytes of the DER encoding of

p7.

The opposite assumes we already have len bytes in buf:

unsigned char *p;

p = buf;

p7 = d2i_PKCS7(NULL, &p, len);

At this point p7 contains a valid PKCS7 structure of NULL if an error

occurred. If an error occurred ERR_print_errors(bio) should give more

information.

The reason for the temporary variable 'p' is that the ASN1 functions

increment the passed pointer so it is ready to read or write the next

structure. This is often a cause of problems: without the temporary

variable the buffer pointer is changed to point just after the data

that has been read or written. This may well be uninitialized data

and attempts to free the buffer will have unpredictable results

because it no longer points to the same address.

* I've tried using <M_some_evil_pkcs12_macro> and I get errors why?

This usually happens when you try compiling something using the PKCS#12

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