More man pages.

=pod

=head1 NAME

ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions

=head1 SYNOPSIS

 ASN1_OBJECT *ASN1_OBJECT_new(void);

 void ASN1_OBJECT_free(ASN1_OBJECT *a);

=head1 DESCRIPTION

The ASN1_OBJECT allocation routines, allocate and free an

ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.

ASN1_OBJECT_new() allocates and initializes a ASN1_OBJECT structure.

ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.

=head1 NOTES

Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it

is almost never used in applications. The ASN1 object utility functions

such as OBJ_nid2obj() are used instead.

=head1 RETURN VALUES

If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error

code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.

Otherwise it returns a pointer to the newly allocated structure.

ASN1_OBJECT_free() returns no value.

=head1 SEE ALSO

L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)|d2i_ASN1_OBJECT(3)>

=head1 HISTORY

ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and OpenSSL.

=cut

=pod

=head1 NAME

OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid,

OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup - ASN1 object utility

functions

=head1 SYNOPSIS

 ASN1_OBJECT * OBJ_nid2obj(int n);

 const char *  OBJ_nid2ln(int n);

 const char *  OBJ_nid2sn(int n);

 int OBJ_obj2nid(const ASN1_OBJECT *o);

 int OBJ_ln2nid(const char *ln);

 int OBJ_sn2nid(const char *sn);

 int OBJ_txt2nid(const char *s);

 ASN1_OBJECT * OBJ_txt2obj(const char *s, int no_name);

 int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name);

 int OBJ_cmp(const ASN1_OBJECT *a,const ASN1_OBJECT *b);

 ASN1_OBJECT * OBJ_dup(const ASN1_OBJECT *o);

 int OBJ_create(const char *oid,const char *sn,const char *ln);

 void OBJ_cleanup(void);

=head1 DESCRIPTION

The ASN1 object utility functions process ASN1_OBJECT structures which are

a representation of the ASN1 OBJECT IDENTIFIER (OID) type.

OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to 

an ASN1_OBJECT structure, its long name and its short name respectively,

or B<NULL> is an error occurred.

OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID

for the object B<o>, the long name <ln> or the short name <sn> respectively

or NID_undef if an error occurred.

OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be

a long name, a short name or the numerical respresentation of an object.

OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure.

If B<no_name> is 0 then long names and short names will be interpreted

as well as numerical forms. If B<no_name> is 1 only the numerical form

is acceptable.

OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation.

The representation is written as a null terminated string to B<buf>

at most B<buf_len> bytes are written, truncating the result if necessary.

The total amount of space required is returned. If B<no_name> is 0 then

if the object has a long or short name then that will be used, otherwise

the numerical form will be used. If B<no_name> is 1 then the numerical

form will always be used.

OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned.

OBJ_dup() returns a copy of B<o>.

OBJ_create() adds a new object to the internal table. B<oid> is the 

numerical form of the object, B<sn> the short name and B<ln> the

long name. A new NID is returned for the created object.

OBJ_cleanup() cleans up OpenSSLs internal object table: this should

be called before an application exits if any new objects were added

using OBJ_create().

=head1 NOTES

Objects in OpenSSL can have a short name, a long name and a numerical

identifier (NID) associated with them. A standard set of objects is

represented in an internal table. The appropriate values are defined

in the header file B<objects.h>.

For example the OID for commonName has the following definitions:

 #define SN_commonName                   "CN"

 #define LN_commonName                   "commonName"

 #define NID_commonName                  13

New objects can be added by calling OBJ_create().

Table objects have certain advantages over other objects: for example

their NIDs can be used in a C language switch statement. They are

also static constant structures which are shared: that is there

is only a single constant structure for each table object.

Objects which are not in the table have the NID value NID_undef.

Objects do not need to be in the internal tables to be processed,

the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical

form of an OID.

=head1 EXAMPLES

Create an object for B<commonName>:

 ASN1_OBJECT *o;

 o = OBJ_nid2obj(NID_commonName);

Check is an object is B<commonName>

 if (OBJ_obj2nid(obj) == NID_commonName)

	/* Do something */

Create a new NID and initialize an object from it:

 int new_nid;

 ASN1_OBJECT *obj;

 new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");

 obj = OBJ_nid2obj(new_nid);

Create a new object directly:

 obj = OBJ_txt2obj("1.2.3.4", 1);

=head1 BUGS

OBJ_obj2txt() is awkward and messy to use: it doesn't follow the 

convention of other OpenSSL functions where the buffer can be set

to B<NULL> to determine the amount of data that should be written.

Instead B<buf> must point to a valid buffer and B<buf_len> should

be set to a positive value. A buffer length of 80 should be more

than enough to handle any OID encountered in practice.

=head1 RETURN VALUES

OBJ_nid2obj() returns an ASN1_OBJECT structure or B<NULL> is an

error occurred.

OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>

on error.

OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return

a NID or NID_undef on error.

=head1 SEE ALSO

L<ERR_get_error(3)|ERR_get_error(3)>

=head1 HISTORY

TBA

=cut

=pod

=head1 NAME

PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure

=head1 SYNOPSIS

int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags);

=head1 DESCRIPTION

PKCS7_decrypt() extracts and decrypts the content from a PKCS#7 envelopedData

structure. B<pkey> is the private key of the recipient, B<cert> is the

recipients certificate, B<data> is a BIO to write the content to and

B<flags> is an optional set of flags.

=head1 NOTES

OpenSSL_add_all_algorithms() (or equivalent) should be called before using this

function or errors about unknown algorithms will occur.

Although the recipients certificate is not needed to decrypt the data it is needed

to locate the appropriate (of possible several) recipients in the PKCS#7 structure.

The following flags can be passed in the B<flags> parameter.

If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted

from the content. If the content is not of type B<text/plain> then an error is

returned.

=head1 RETURN VALUES

PKCS7_decrypt() returns either 1 for success or 0 for failure.

The error can be obtained from ERR_get_error(3)

=head1 BUGS

PKCS7_decrypt() must be passed the correct recipient key and certificate. It would

be better if it could look up the correct key and certificate from a database.

The lack of single pass processing and need to hold all data in memory as

mentioned in PKCS7_sign() also applies to PKCS7_verify().

=head1 SEE ALSO

L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)>

=head1 HISTORY

PKCS7_decrypt() was added to OpenSSL 0.9.5

=cut

=pod

=head1 NAME

PKCS7_encrypt - create a PKCS#7 envelopedData structure

=head1 SYNOPSIS

PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags);

=head1 DESCRIPTION

PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B<certs>

is a list of recipient certificates. B<in> is the content to be encrypted.

B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.

=head1 NOTES

Only RSA keys are supported in PKCS#7 and envelopedData so the recipient certificates

supplied to this function must all contain RSA public keys, though they do not have to

be signed using the RSA algorithm.

EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use because

most clients will support it.

Some old "export grade" clients may only support weak encryption using 40 or 64 bit

RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc() respectively.

The algorithm passed in the B<cipher> parameter must support ASN1 encoding of its

parameters. 

The following flags can be passed in the B<flags> parameter.

If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended

to the data.

Normally the supplied content is translated into MIME canonical format (as required

by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation occurs. This

option should be used if the supplied data is in binary format otherwise the translation

will corrupt it. If B<PKCS7_BINARY> is set then B<PKCS7_TEXT> is ignored.

=head1 RETURN VALUES

PKCS7_encrypt() returns either a valid PKCS7 structure or NULL if an error occurred.

The error can be obtained from ERR_get_error(3).

=head1 BUGS

The lack of single pass processing and need to hold all data in memory as

mentioned in PKCS7_sign() also applies to PKCS7_verify().

=head1 SEE ALSO

L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>

=head1 HISTORY

PKCS7_decrypt() was added to OpenSSL 0.9.5

=cut

will be used. If B<PKCS7_NOSMIMECAP> is set then just the SMIMECapabilities are

omitted.

If present the SMIMECapabilities attribute indicates support for the following

algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any

of these algorithms is disabled then it will not be included.

=head1 BUGS

PKCS7_sign() is somewhat limited. It does not support multiple signers, some

advanced attributes such as counter signatures are not supported.

The SHA1 digest algorithm is currently always used.

When the signed data is not detached it will be stored in memory within the

B<PKCS7> structure. This effectively limits the size of messages which can be

signed due to memory restraints. There should be a way to sign data without

having to hold it all in memory, this would however require fairly major

revisions of the OpenSSL ASN1 code.

Clear text signing does not store the content in memory but the way PKCS7_sign()

operates means that two passes of the data must typically be made: one to compute

the signatures and a second to output the data along with the signature. There

should be a way to process the data with only a single pass.

=head1 RETURN VALUES

PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error occurred.

=head1 HISTORY

TBA

PKCS7_sign() was added to OpenSSL 0.9.5

=cut