New docs.

=pod

=head1 NAME

ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,

ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data -

ASN1_STRING utility functions

=head1 SYNOPSIS

 int ASN1_STRING_length(ASN1_STRING *x);

 unsigned char * ASN1_STRING_data(ASN1_STRING *x);

 ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);

 int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);

 int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);

 int ASN1_STRING_type(ASN1_STRING *x);

 int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in);

=head1 DESCRIPTION

These functions allow an B<ASN1_STRING> structure to be manipulated.

ASN1_STRING_length() returns the length of the content of B<x>.

ASN1_STRING_data() returns an internal pointer to the data of B<x>.

Since this is an internal pointer it should B<not> be freed or

modified in any way.

ASN1_STRING_dup() returns a copy of the structure B<a>.

ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two

are identical. The string types and content are compared.

ASN1_STRING_set() sets the data of string B<str> to the buffer

B<data> or length B<len>. The supplied data is copied. If B<len>

is -1 then the length is determined by strlen(data).

ASN1_STRING_type() returns the type of B<x>, using standard constants

such as B<V_ASN1_OCTET_STRING>.

ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the

converted data is allocated in a buffer in B<*out>. The length of

B<out> is returned or a negative error code. The buffer B<*out>

should be free using OPENSSL_free().

=head1 NOTES

Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING>

structure. Other types such as B<ASN1_OCTET_STRING> are simply typedefed

to B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents.

B<ASN1_STRING> is also used for some B<CHOICE> types which consist

entirely of primitive string types such as B<DirectoryString> and

B<Time>.

These functions should B<not> be used to examine or modify B<ASN1_INTEGER>

or B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED>

utility functions should be used instead.

In general it cannot be assumed that the data returned by ASN1_STRING_data()

is null terminated or does not contain embedded nulls. The actual format

of the data will depend on the actual string type itself: for example

for and IA5String the data will be ASCII, for a BMPString two bytes per

character in big endian format, UTF8String will be in UTF8 format.

Similar care should be take to ensure the data is in the correct format

when calling ASN1_STRING_set().

=head1 RETURN VALUES

=head1 SEE ALSO

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

=head1 HISTORY

=cut

=pod

=head1 NAME

ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free -

ASN1_STRING allocation functions

=head1 SYNOPSIS

 ASN1_STRING * ASN1_STRING_new(void);

 ASN1_STRING * ASN1_STRING_type_new(int type);

 void ASN1_STRING_free(ASN1_STRING *a);

=head1 DESCRIPTION

ASN1_STRING_new() returns an allocated B<ASN1_STRING> structure. Its type

is undefined.

ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of

type B<type>.

ASN1_STRING_free() frees up B<a>.

=head1 NOTES

Other string types call the B<ASN1_STRING> functions. For example

ASN1_OCTET_STRING_new() calls ASN1_STRING_type(V_ASN1_OCTET_STRING).

=head1 RETURN VALUES

ASN1_STRING_new() and ASN1_STRING_type_new() return a valid

ASN1_STRING structure or B<NULL> if an error occurred.

ASN1_STRING_free() does not return a value.

=head1 SEE ALSO

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

=head1 HISTORY

TBA

=cut

=pod

=head1 NAME

ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp - ASN1_STRING output routines.

=head1 SYNOPSIS

 #include <openssl/asn1.h>

 int ASN1_STRING_print_ex(BIO *out, ASN1_STRING *str, unsigned long flags);

 int ASN1_STRING_print_ex_fp(FILE *fp, ASN1_STRING *str, unsigned long flags);

 int ASN1_STRING_print(BIO *out, ASN1_STRING *str);

=head1 DESCRIPTION

These functions output an B<ASN1_STRING> structure. B<ASN1_STRING> is used to

represent all the ASN1 string types.

ASN1_STRING_print_ex() outputs B<str> to B<out>, the format is determined by

the options B<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs

to B<fp> instead.

ASN1_STRING_print() prints B<str> to B<out> but using a different format to

ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF)

with '.'.

=head1 NOTES

ASN1_STRING_print() is a legacy function which should be avoided in new applications.

Although there are a large number of options frequently B<ASN1_STRFLAGS_RFC2253> is 

suitable, or on UTF8 terminals B<ASN1_STRFLAGS_RFC2253 & ~ASN1_STRFLAGS_ESC_MSB>.

The complete set of supported options for B<flags> is listed below.

Various characters can be escaped. If B<ASN1_STRFLGS_ESC_2253> is set the characters

determined by RFC2253 are escaped. If B<ASN1_STRFLGS_ESC_CTRL> is set control

characters are escaped. If B<ASN1_STRFLGS_ESC_MSB> is set characters with the

MSB set are escaped: this option should B<not> be used if the terminal correctly

interprets UTF8 sequences.

Escaping takes several forms.

If the character being escaped is a 16 bit character then the form "\WXXXX" is used

using exactly four characters for the hex representation. If it is 32 bits then

"\UXXXXXXXX" is used using eight characters of its hex representation. These forms

will only be used if UTF8 conversion is not set (see below).

Printable characters are normally escaped using the backslash '\' character. If

B<ASN1_STRFLGS_ESC_QUOTE> is set then the whole string is instead surrounded by

double quote characters: this is arguably more readable than the backslash

notation. Other characters use the "\XX" using exactly two characters of the hex

representation.

If B<ASN1_STRFLGS_UTF8_CONVERT> is set then characters are converted to UTF8

format first. If the terminal supports the display of UTF8 sequences then this

option will correctly display multi byte characters.

If B<ASN1_STRFLGS_IGNORE_TYPE> is set then the string type is not interpreted at

all: everything is assumed to be one byte per character. This is primarily for

debugging purposes and can result in confusing output in multi character strings.

If B<ASN1_STRFLGS_SHOW_TYPE> is set then the string type itself is printed out

before its value (for example "BMPSTRING"), this actually uses ASN1_tag2str().

The content of a string instead of being interpreted can be "dumped": this just

outputs the value of the string using the form #XXXX using hex format for each

octet.

If B<ASN1_STRFLGS_DUMP_ALL> is set then any type is dumped.

Normally non character string types (such as OCTET STRING) are assumed to be

one byte per character, if B<ASN1_STRFLAGS_DUMP_UNKNOWN> is set then they will

be dumped instead.

When a type is dumped normally just the content octets are printed, if 

B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped

instead (including tag and length octets).

B<ASN1_STRFLGS_RFC2253> includes all the flags required by RFC2253. It is

equivalent to:

 ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB |

 ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER

=head1 SEE ALSO

L<X509_NAME_print_ex(3)|L<X509_NAME_print_ex(3)>,

L<ASN1_tag2str(3)|ASN1_tag2str(3)>

=head1 HISTORY

TBA

=cut

 ASN1_OBJECT *o;

 o = OBJ_nid2obj(NID_commonName);

Check is an object is B<commonName>

Check if an object is B<commonName>

 if (OBJ_obj2nid(obj) == NID_commonName)

	/* Do something */

=head1 RETURN VALUES

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

OBJ_nid2obj() returns an B<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.

a NID or B<NID_undef> on error.

=head1 SEE ALSO

=pod

X509_NAME_ENTRY_get_object, X509_NAME_ENTRY_get_data,

X509_NAME_ENTRY_set_object, X509_NAME_ENTRY_set_data,

X509_NAME_ENTRY_create_by_txt, X509_NAME_ENTRY_create_by_NID,

X509_NAME_ENTRY_create_by_OBJ - X509_NAME_ENTRY utility functions

=head1 NAME

=head1 SYNOPSIS

ASN1_OBJECT * X509_NAME_ENTRY_get_object(X509_NAME_ENTRY *ne);

ASN1_STRING * X509_NAME_ENTRY_get_data(X509_NAME_ENTRY *ne);

int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, ASN1_OBJECT *obj);

int X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *ne, int type, unsigned char *bytes, int len);

X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY **ne, char *field, int type, unsigned char *bytes, int len);

X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY **ne, int nid, int type,unsigned char *bytes, int len);

X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, ASN1_OBJECT *obj, int type,unsigned char *bytes, int len);

=head1 DESCRIPTION

X509_NAME_ENTRY_get_object() retrieves the field name of B<ne> in

and B<ASN1_OBJECT> structure.

X509_NAME_ENTRY_get_data() retrieves the field value of B<ne> in

and B<ASN1_STRING> structure.

X509_NAME_ENTRY_set_object() sets the field name of B<ne> to B<obj>.

X509_NAME_ENTRY_set_data() sets the field value of B<ne> to string type

B<type> and value determined by B<bytes> and B<len>.

X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID()

and X509_NAME_ENTRY_create_by_OBJ() create and return an 

B<X509_NAME_ENTRY> structure.

=head1 NOTES

X509_NAME_ENTRY_get_object() and X509_NAME_ENTRY_get_data() can be

used to examine an B<X509_NAME_ENTRY> function as returned by 

X509_NAME_get_entry() for example.

X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID(),

and X509_NAME_ENTRY_create_by_OBJ() create and return an 

X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_OBJ(),

X509_NAME_ENTRY_create_by_NID() and X509_NAME_ENTRY_set_data()

are seldom used in practice because B<X509_NAME_ENTRY> structures

are almost always part of B<X509_NAME> structures and the

corresponding B<X509_NAME> functions are typically used to

create and add new entries in a single operation.

The arguments of these functions support similar options to the similarly

named ones of the corresponding B<X509_NAME> functions such as

X509_NAME_add_entry_by_txt(). So for example B<type> can be set to

B<MBSTRING_ASC> but in the case of X509_set_data() the field name must be

set first so the relevant field information can be looked up internally.

=head1 RETURN VALUES

=head1 SEE ALSO

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

L<OBJ_nid2obj(3),OBJ_nid2obj(3)>

=head1 HISTORY

TBA

=cut