This commit was manufactured by cvs2svn to create branch

=pod

=head1 NAME

PKCS12_create - create a PKCS#12 structure

=head1 SYNOPSIS

 #include <openssl/pkcs12.h>

 PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert, STACK_OF(X509) *ca,

				int nid_key, int nid_cert, int iter, int mac_iter, int keytype);

=head1 DESCRIPTION

PKCS12_create() creates a PKCS#12 structure.

B<pass> is the passphrase to use. B<name> is the B<friendlyName> to use for

the supplied certifictate and key. B<pkey> is the private key to include in

the structure and B<cert> its corresponding certificates. B<ca>, if not B<NULL>

is an optional set of certificates to also include in the structure.

B<nid_key> and B<nid_cert> are the encryption algorithms that should be used

for the key and certificate respectively. B<iter> is the encryption algorithm

iteration count to use and B<mac_iter> is the MAC iteration count to use.

B<keytype> is the type of key.

=head1 NOTES

The parameters B<nid_key>, B<nid_cert>, B<iter>, B<mac_iter> and B<keytype>

can all be set to zero and sensible defaults will be used.

These defaults are: 40 bit RC2 encryption for certificates, triple DES

encryption for private keys, a key iteration count of PKCS12_DEFAULT_ITER

(currently 2048) and a MAC iteration count of 1.

The default MAC iteration count is 1 in order to retain compatibility with

old software which did not interpret MAC iteration counts. If such compatibility

is not required then B<mac_iter> should be set to PKCS12_DEFAULT_ITER.

B<keytype> adds a flag to the store private key. This is a non standard extension

that is only currently interpreted by MSIE. If set to zero the flag is omitted,

if set to B<KEY_SIG> the key can be used for signing only, if set to B<KEY_EX>

it can be used for signing and encryption. This option was useful for old

export grade software which could use signing only keys of arbitrary size but

had restrictions on the permissible sizes of keys which could be used for

encryption.

=head1 NEW FUNCTIONALITY IN OPENSSL 0.9.8

Some additional functionality was added to PKCS12_create() in OpenSSL

0.9.8. These extensions are detailed below.

If a certificate contains an B<alias> or B<keyid> then this will be

used for the corresponding B<friendlyName> or B<localKeyID> in the

PKCS12 structure.

Either B<pkey>, B<cert> or both can be B<NULL> to indicate that no key or

certficate is required. In previous versions both hasves to be present or

a fatal error is returned.

B<nid_key> or B<nid_cert> can be set to -1 indicating that no encryption

should be used. 

B<mac_iter> can be set to -1 and the MAC will then be omitted entirely.

=head1 SEE ALSO

L<d2i_PKCS12(3)|d2i_PKCS12(3)>

=head1 HISTORY

PKCS12_create was added in OpenSSL 0.9.3

=cut

=pod

X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,

X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ -

X509_NAME lookup and enumeration functions

=head1 NAME

=head1 SYNOPSIS

int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos);

int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos);

int X509_NAME_entry_count(X509_NAME *name);

X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc);

int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len);

int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len);

=head1 DESCRIPTION

These functions allow an B<X509_NAME> structure to be examined. The

B<X509_NAME> structure is the same as the B<Name> type defined in

RFC2459 (and elsewhere) and used for example in certificate subject

and issuer names.

X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve

the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos>

should initially be set to -1. If there are no more entries -1 is returned.

X509_NAME_entry_count() returns the total number of entries in B<name>.

X509_NAME_get_entry() retrieves the B<X509_NAME_ENTRY> from B<name>

corresponding to index B<loc>. Acceptable values for B<loc> run from

0 to (X509_NAME_entry_count(name) - 1). The value returned is an

internal pointer which must not be freed.

X509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve

the "text" from the first entry in B<name> which matches B<nid> or

B<obj>, if no such entry exists -1 is returned. At most B<len> bytes

will be written and the text written to B<buf> will be null

terminated. The length of the output string written is returned

excluding the terminating null. If B<buf> is <NULL> then the amount

of space needed in B<buf> (excluding the final null) is returned. 

=head1 NOTES

X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are

legacy functions which have various limitations which make them

of minimal use in practice. They can only find the first matching

entry and will copy the contents of the field verbatim: this can

be highly confusing if the target is a muticharacter string type

like a BMPString or a UTF8String.

For a more general solution X509_NAME_get_index_by_NID() or

X509_NAME_get_index_by_OBJ() should be used followed by

X509_NAME_get_entry() on any matching indices and then the

various B<X509_NAME_ENTRY> utility functions on the result.

=head1 EXAMPLES

Process all entries:

 int i;

 X509_NAME_ENTRY *e;

 for (i = 0; i < X509_NAME_entry_count(nm); i++)

	{

	e = X509_NAME_get_entry(nm, i);

	/* Do something with e */

	}

Process all commonName entries:

 int loc;

 X509_NAME_ENTRY *e;

 loc = -1;

 for (;;)

	{

	lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);

	if (lastpos == -1)

		break;

	e = X509_NAME_get_entry(nm, lastpos);

	/* Do something with e */

	}

=head1 RETURN VALUES

X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ()

return the index of the next matching entry or -1 if not found.

X509_NAME_entry_count() returns the total number of entries.

X509_NAME_get_entry() returns an B<X509_NAME> pointer to the

requested entry or B<NULL> if the index is invalid.

=head1 SEE ALSO

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

=head1 HISTORY

TBA

=cut