From 0711be16968194d6fe83b57de8af722ac0bc4622 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Sun, 20 Oct 2002 13:20:57 +0000 Subject: [PATCH] New docs. --- doc/crypto/ASN1_STRING_length.pod | 81 ++++++++++++++++ doc/crypto/ASN1_STRING_new.pod | 44 +++++++++ doc/crypto/ASN1_STRING_print_ex.pod | 96 +++++++++++++++++++ doc/crypto/OBJ_nid2obj.pod | 6 +- doc/crypto/X509_NAME_ENTRY_get_object.pod | 72 ++++++++++++++ doc/crypto/X509_NAME_add_entry_by_txt.pod | 110 ++++++++++++++++++++++ doc/crypto/X509_NAME_print_ex.pod | 105 +++++++++++++++++++++ 7 files changed, 511 insertions(+), 3 deletions(-) create mode 100644 doc/crypto/ASN1_STRING_length.pod create mode 100644 doc/crypto/ASN1_STRING_new.pod create mode 100644 doc/crypto/ASN1_STRING_print_ex.pod create mode 100644 doc/crypto/X509_NAME_ENTRY_get_object.pod create mode 100644 doc/crypto/X509_NAME_add_entry_by_txt.pod create mode 100644 doc/crypto/X509_NAME_print_ex.pod diff --git a/doc/crypto/ASN1_STRING_length.pod b/doc/crypto/ASN1_STRING_length.pod new file mode 100644 index 0000000000..c4ec693f17 --- /dev/null +++ b/doc/crypto/ASN1_STRING_length.pod @@ -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 structure to be manipulated. + +ASN1_STRING_length() returns the length of the content of B. + +ASN1_STRING_data() returns an internal pointer to the data of B. +Since this is an internal pointer it should B be freed or +modified in any way. + +ASN1_STRING_dup() returns a copy of the structure B. + +ASN1_STRING_cmp() compares B and B returning 0 if the two +are identical. The string types and content are compared. + +ASN1_STRING_set() sets the data of string B to the buffer +B or length B. The supplied data is copied. If B +is -1 then the length is determined by strlen(data). + +ASN1_STRING_type() returns the type of B, using standard constants +such as B. + +ASN1_STRING_to_UTF8() converts the string B to UTF8 format, the +converted data is allocated in a buffer in B<*out>. The length of +B 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 +structure. Other types such as B are simply typedefed +to B and the functions call the B equivalents. +B is also used for some B types which consist +entirely of primitive string types such as B and +B. + +=head1 NOTES + +Other string types call the B 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 if an error occurred. + +ASN1_STRING_free() does not return a value. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +TBA + +=cut diff --git a/doc/crypto/ASN1_STRING_print_ex.pod b/doc/crypto/ASN1_STRING_print_ex.pod new file mode 100644 index 0000000000..d6bb48582c --- /dev/null +++ b/doc/crypto/ASN1_STRING_print_ex.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + +ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp - ASN1_STRING output routines. + +=head1 SYNOPSIS + + #include + + 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 structure. B is used to +represent all the ASN1 string types. + +ASN1_STRING_print_ex() outputs B to B, the format is determined by +the options B. ASN1_STRING_print_ex_fp() is identical except it outputs +to B instead. + +ASN1_STRING_print() prints B to B 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 is +suitable, or on UTF8 terminals B. + +The complete set of supported options for B is listed below. + +Various characters can be escaped. If B is set the characters +determined by RFC2253 are escaped. If B is set control +characters are escaped. If B is set characters with the +MSB set are escaped: this option should B 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 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 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 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 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 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 is set then they will +be dumped instead. + +When a type is dumped normally just the content octets are printed, if +B is set then the complete encoding is dumped +instead (including tag and length octets). + +B 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, +L + +=head1 HISTORY + +TBA + +=cut diff --git a/doc/crypto/OBJ_nid2obj.pod b/doc/crypto/OBJ_nid2obj.pod index 50650bdbce..7dcc07923f 100644 --- a/doc/crypto/OBJ_nid2obj.pod +++ b/doc/crypto/OBJ_nid2obj.pod @@ -101,7 +101,7 @@ Create an object for B: ASN1_OBJECT *o; o = OBJ_nid2obj(NID_commonName); -Check is an object is B +Check if an object is B if (OBJ_obj2nid(obj) == NID_commonName) /* Do something */ @@ -129,14 +129,14 @@ than enough to handle any OID encountered in practice. =head1 RETURN VALUES -OBJ_nid2obj() returns an ASN1_OBJECT structure or B is an +OBJ_nid2obj() returns an B structure or B is an error occurred. OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B on error. OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return -a NID or NID_undef on error. +a NID or B on error. =head1 SEE ALSO diff --git a/doc/crypto/X509_NAME_ENTRY_get_object.pod b/doc/crypto/X509_NAME_ENTRY_get_object.pod new file mode 100644 index 0000000000..35f13ec8c2 --- /dev/null +++ b/doc/crypto/X509_NAME_ENTRY_get_object.pod @@ -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 in +and B structure. + +X509_NAME_ENTRY_get_data() retrieves the field value of B in +and B structure. + +X509_NAME_ENTRY_set_object() sets the field name of B to B. + +X509_NAME_ENTRY_set_data() sets the field value of B to string type +B and value determined by B and B. + +X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID() +and X509_NAME_ENTRY_create_by_OBJ() create and return an +B structure. + +=head1 NOTES + +X509_NAME_ENTRY_get_object() and X509_NAME_ENTRY_get_data() can be +used to examine an B 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 structures +are almost always part of B structures and the +corresponding B 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 functions such as +X509_NAME_add_entry_by_txt(). So for example B can be set to +B 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, L, +L + +=head1 HISTORY + +TBA + +=cut diff --git a/doc/crypto/X509_NAME_add_entry_by_txt.pod b/doc/crypto/X509_NAME_add_entry_by_txt.pod new file mode 100644 index 0000000000..68b3d6e5eb --- /dev/null +++ b/doc/crypto/X509_NAME_add_entry_by_txt.pod @@ -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, an object B or a NID B respectively. +The field value to be added is in B of length B. If +B is -1 then the field length is calculated internally using +strlen(bytes). + +The type of field is determined by B which can either be a +definition of the type of B (such as B) or a +standard ASN1 type (such as B). The new entry is +added to a position determined by B and B. + +X509_NAME_add_entry() adds a copy of B structure B +to B. The new entry is added to a position determined by B +and B. Since a copy of B is added B must be freed up after +the call. + +X509_NAME_delete_entry() deletes an entry from B at position +B. The deleted entry is returned and must be freed up. + +=head1 NOTES + +The use of string types such as B or B +is strongly recommened for the B 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 is used directly. + +In X509_NAME_add_entry_by_txt() the B string represents +the field name using OBJ_txt2obj(field, 0). + +The B and B parameters determine where a new entry should +be added. For almost all applications B can be set to -1 and B +to 0. This adds a new entry to the end of B as a single valued +RelativeDistinguishedName (RDN). + +B actually determines the index where the new entry is inserted: +if it is -1 it is appended. + +B determines how the new type is added. If it is zero a +new RDN is created. + +If B 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 is almost +always set to zero. + +=head1 EXAMPLES + +Create an B 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 +structure of B if an error occurred. + +=head1 BUGS + +B can still be set to B 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, L + +=head1 HISTORY + +=cut diff --git a/doc/crypto/X509_NAME_print_ex.pod b/doc/crypto/X509_NAME_print_ex.pod new file mode 100644 index 0000000000..907c04f684 --- /dev/null +++ b/doc/crypto/X509_NAME_print_ex.pod @@ -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 + + 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 to BIO B. Each +line (for multiline formats) is indented by B spaces. The output format +can be extensively customised by use of the B parameter. + +X509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output is +written to FILE pointer B. + +X509_NAME_oneline() prints an ASCII version of B to B. At most B +bytes will be written. If B is B then a buffer is dynamically allocated +and returned, otherwise B is returned. + +X509_NAME_print() prints out B to B indenting each line by B +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, B or B will suffice. +As noted on the L manual page +for UTF8 terminals the B should be unset: so for example +B 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, B, +B and B 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 uses comma and plus as separators. B +uses comma and plus with spaces: this is more readable that plain comma and plus. +B uses spaced semicolon and plus. B uses +spaced newline and plus respectively. + +If B is set the whole DN is printed in reversed order. + +The fields B, B, B, +B 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 is set then spaces will be placed around the '=' character +separating field names and values. + +If B is set then the encoding of unknown fields is +printed instead of the values. + +If B 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 sets options which produce an output compatible with RFC2253 it +is equivalent to: + B + + +B is a more readable one line format it is the same as: + B + +B is a multiline format is is the same as: + B + +B uses a format identical to X509_NAME_print(): in fact it calls X509_NAME_print() internally. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +TBA + +=cut -- 2.25.1