wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

This commit was manufactured by cvs2svn to create branch

Browse source 
'OpenSSL_0_9_7-stable'.
This commit is contained in:
cvs2svn 2002-10-20 13:20:58 +00:00
commit 76dcae8020
6 changed files with 508 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

81
doc/crypto/ASN1_STRING_length.pod Normal file
View file

@ -0,0 +1,81 @@
=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

44
doc/crypto/ASN1_STRING_new.pod Normal file
View file

@ -0,0 +1,44 @@
=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

96
doc/crypto/ASN1_STRING_print_ex.pod Normal file
View file

@ -0,0 +1,96 @@
=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

72
doc/crypto/X509_NAME_ENTRY_get_object.pod Normal file
View file

@ -0,0 +1,72 @@
=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

110
doc/crypto/X509_NAME_add_entry_by_txt.pod Normal file
View file

@ -0,0 +1,110 @@
=pod
X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID,
X509_NAME_add_entry, X509_NAME_delete_entry - X509_NAME modification functions
=head1 NAME
=head1 SYNOPSIS
int X509_NAME_add_entry_by_txt(X509_NAME *name, char *field, int type, unsigned char *bytes, int len, int loc, int set);
int X509_NAME_add_entry_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, int type, unsigned char *bytes, int len, int loc, int set);
int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set);
int X509_NAME_add_entry(X509_NAME *name,X509_NAME_ENTRY *ne, int loc, int set);
X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc);
=head1 DESCRIPTION
X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ() and
X509_NAME_add_entry_by_NID() add a field whose name is defined
by a string B<field>, an object B<obj> or a NID B<nid> respectively.
The field value to be added is in B<bytes> of length B<len>. If
B<len> is -1 then the field length is calculated internally using
strlen(bytes).
The type of field is determined by B<type> which can either be a
definition of the type of B<bytes> (such as B<MBSTRING_ASC>) or a
standard ASN1 type (such as B<V_ASN1_IA5STRING>). The new entry is
added to a position determined by B<loc> and B<set>.
X509_NAME_add_entry() adds a copy of B<X509_NAME_ENTRY> structure B<ne>
to B<name>. The new entry is added to a position determined by B<loc>
and B<set>. Since a copy of B<ne> is added B<ne> must be freed up after
the call.
X509_NAME_delete_entry() deletes an entry from B<name> at position
B<loc>. The deleted entry is returned and must be freed up.
=head1 NOTES
The use of string types such as B<MBSTRING_ASC> or B<MBSTRING_UTF8>
is strongly recommened for the B<type> parameter. This allows the
internal code to correctly determine the type of the field and to
apply length checks according to the relevant standards. This is
done using ASN1_STRING_set_by_NID().
If instead an ASN1 type is used no checks are performed and the
supplied data in B<bytes> is used directly.
In X509_NAME_add_entry_by_txt() the B<field> string represents
the field name using OBJ_txt2obj(field, 0).
The B<loc> and B<set> parameters determine where a new entry should
be added. For almost all applications B<loc> can be set to -1 and B<set>
to 0. This adds a new entry to the end of B<name> as a single valued
RelativeDistinguishedName (RDN).
B<loc> actually determines the index where the new entry is inserted:
if it is -1 it is appended.
B<set> determines how the new type is added. If it is zero a
new RDN is created.
If B<set> is -1 or 1 it is added to the previous or next RDN
structure respectively. This will then be a multivalued RDN:
since multivalues RDNs are very seldom used B<set> is almost
always set to zero.
=head1 EXAMPLES
Create an B<X509_NAME> structure:
"C=UK, O=Disorganized Organization, CN=Joe Bloggs"
X509_NAME *nm;
nm = X509_NAME_new();
if (nm == NULL)
/* Some error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"C", "UK", -1, -1, 0))
/* Error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"O", "Disorganized Organization", -1, -1, 0))
/* Error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"CN", "Joe Bloggs", -1, -1, 0))
/* Error */
=head1 RETURN VALUES
X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(),
X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for
success of 0 if an error occurred.
X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY>
structure of B<NULL> if an error occurred.
=head1 BUGS
B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a
different algorithm to determine field types. Since this form does
not understand multicharacter types, performs no length checks and
can result in invalid field types its use is strongly discouraged.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>
=head1 HISTORY
=cut

105
doc/crypto/X509_NAME_print_ex.pod Normal file
View file

@ -0,0 +1,105 @@
=pod
=head1 NAME
X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print,
X509_NAME_oneline - X509_NAME printing routines.
=head1 SYNOPSIS
#include <openssl/x509.h>
int X509_NAME_print_ex(BIO *out, X509_NAME *nm, int indent, unsigned long flags);
int X509_NAME_print_ex_fp(FILE *fp, X509_NAME *nm, int indent, unsigned long flags);
char * X509_NAME_oneline(X509_NAME *a,char *buf,int size);
int X509_NAME_print(BIO *bp, X509_NAME *name, int obase);
=head1 DESCRIPTION
X509_NAME_print_ex() prints a human readable version of B<nm> to BIO B<out>. Each
line (for multiline formats) is indented by B<indent> spaces. The output format
can be extensively customised by use of the B<flags> parameter.
X509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output is
written to FILE pointer B<fp>.
X509_NAME_oneline() prints an ASCII version of B<a> to B<buf>. At most B<size>
bytes will be written. If B<buf> is B<NULL> then a buffer is dynamically allocated
and returned, otherwise B<buf> is returned.
X509_NAME_print() prints out B<name> to B<bp> indenting each line by B<obase>
characters. Multiple lines are used if the output (including indent) exceeds
80 characters.
=head1 NOTES
The functions X509_NAME_oneline() and X509_NAME_print() are legacy functions which
produce a non standard output form, they don't handle multi character fields and
have various quirks and inconsistencies. Their use is strongly discouraged in new
applications.
Although there are a large number of possible flags for most purposes
B<XN_FLAG_ONELINE>, B<XN_FLAG_MULTILINE> or B<XN_FLAG_RFC2253> will suffice.
As noted on the L<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)> manual page
for UTF8 terminals the B<ASN1_STRFLAGS_ESC_MSB> should be unset: so for example
B<XN_FLAG_ONELINE & ~ASN1_STRFLAGS_ESC_MSB> would be used.
The complete set of the flags supported by X509_NAME_print_ex() is listed below.
Several options can be ored together.
The options B<XN_FLAG_SEP_COMMA_PLUS>, B<XN_FLAG_SEP_CPLUS_SPC>,
B<XN_FLAG_SEP_SPLUS_SPC> and B<XN_FLAG_SEP_MULTILINE> determine the field separators
to use. Two distinct separators are used between distinct RelativeDistinguishedName
components and separate values in the same RDN for a multi-valued RDN. Multi-valued
RDNs are currently very rare so the second separator will hardly ever be used.
B<XN_FLAG_SEP_COMMA_PLUS> uses comma and plus as separators. B<XN_FLAG_SEP_CPLUS_SPC>
uses comma and plus with spaces: this is more readable that plain comma and plus.
B<XN_FLAG_SEP_SPLUS_SPC> uses spaced semicolon and plus. B<XN_FLAG_SEP_MULTILINE> uses
spaced newline and plus respectively.
If B<XN_FLAG_DN_REV> is set the whole DN is printed in reversed order.
The fields B<XN_FLAG_FN_SN>, B<XN_FLAG_FN_LN>, B<XN_FLAG_FN_OID>,
B<XN_FLAG_FN_NONE> determine how a field name is displayed. It will
use the short name (e.g. CN) the long name (e.g. commonName) always
use OID numerical form (normally OIDs are only used if the field name is not
recognised) and no field name respectively.
If B<XN_FLAG_SPC_EQ> is set then spaces will be placed around the '=' character
separating field names and values.
If B<XN_FLAG_DUMP_UNKNOWN_FIELDS> is set then the encoding of unknown fields is
printed instead of the values.
If B<XN_FLAG_FN_ALIGN> is set then field names are padded to 20 characters: this
is only of use for multiline format.
Additionally all the options supported by ASN1_STRING_print_ex() can be used to
control how each field value is displayed.
In addition a number options can be set for commonly used formats.
B<XN_FLAG_RFC2253> sets options which produce an output compatible with RFC2253 it
is equivalent to:
B<ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS>
B<XN_FLAG_ONELINE> is a more readable one line format it is the same as:
B<ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN>
B<XN_FLAG_MULTILINE> is a multiline format is is the same as:
B<ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE | XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN>
B<XN_FLAG_COMPAT> uses a format identical to X509_NAME_print(): in fact it calls X509_NAME_print() internally.
=head1 SEE ALSO
L<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)>
=head1 HISTORY
TBA
=cut