From 948b14a55ded39aea589e34e23c19085fd99cac5 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sat, 14 Feb 2015 13:54:59 +0000 Subject: While doing development work on pod2mdoc(1), profit of the occasion to start the conversion of LibreSSL libcrypto manuals from perlpod(1) to mdoc(7). miod@ jmc@ bentley@ agreed to the process when shown this patch. --- src/lib/libssl/src/doc/crypto/ASN1_OBJECT_new.pod | 46 ---- .../libssl/src/doc/crypto/ASN1_STRING_length.pod | 83 ------- src/lib/libssl/src/doc/crypto/ASN1_STRING_new.pod | 42 ---- .../libssl/src/doc/crypto/ASN1_STRING_print_ex.pod | 95 -------- .../libssl/src/doc/crypto/ASN1_generate_nconf.pod | 265 --------------------- 5 files changed, 531 deletions(-) delete mode 100644 src/lib/libssl/src/doc/crypto/ASN1_OBJECT_new.pod delete mode 100644 src/lib/libssl/src/doc/crypto/ASN1_STRING_length.pod delete mode 100644 src/lib/libssl/src/doc/crypto/ASN1_STRING_new.pod delete mode 100644 src/lib/libssl/src/doc/crypto/ASN1_STRING_print_ex.pod delete mode 100644 src/lib/libssl/src/doc/crypto/ASN1_generate_nconf.pod (limited to 'src/lib/libssl') diff --git a/src/lib/libssl/src/doc/crypto/ASN1_OBJECT_new.pod b/src/lib/libssl/src/doc/crypto/ASN1_OBJECT_new.pod deleted file mode 100644 index 1c43494c7d..0000000000 --- a/src/lib/libssl/src/doc/crypto/ASN1_OBJECT_new.pod +++ /dev/null @@ -1,46 +0,0 @@ -=pod - -=head1 NAME - -ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions - -=head1 SYNOPSIS - - #include - - 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 structure B. - -=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 and sets an error -code that can be obtained by L. -Otherwise it returns a pointer to the newly allocated structure. - -ASN1_OBJECT_free() returns no value. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of -SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/ASN1_STRING_length.pod b/src/lib/libssl/src/doc/crypto/ASN1_STRING_length.pod deleted file mode 100644 index f9a47a47dc..0000000000 --- a/src/lib/libssl/src/doc/crypto/ASN1_STRING_length.pod +++ /dev/null @@ -1,83 +0,0 @@ -=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_to_UTF8 - -ASN1_STRING utility functions - -=head1 SYNOPSIS - - #include - - 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 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 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/ASN1_STRING_print_ex.pod b/src/lib/libssl/src/doc/crypto/ASN1_STRING_print_ex.pod deleted file mode 100644 index a93047a040..0000000000 --- a/src/lib/libssl/src/doc/crypto/ASN1_STRING_print_ex.pod +++ /dev/null @@ -1,95 +0,0 @@ -=pod - -=head1 NAME - -ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - 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 "\UXXXX" is -used using exactly four characters for the hex representation. If it is 32 bits -then "\WXXXXXXXX" 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 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/ASN1_generate_nconf.pod b/src/lib/libssl/src/doc/crypto/ASN1_generate_nconf.pod deleted file mode 100644 index 4b8a937a66..0000000000 --- a/src/lib/libssl/src/doc/crypto/ASN1_generate_nconf.pod +++ /dev/null @@ -1,265 +0,0 @@ -=pod - -=head1 NAME - -ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions - -=head1 SYNOPSIS - - #include - - ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf); - ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf); - -=head1 DESCRIPTION - -These functions generate the ASN1 encoding of a string -in an B structure. - -B contains the string to encode B or B contains -the optional configuration information where additional strings -will be read from. B will typically come from a config -file wherease B is obtained from an B structure -which will typically be used by X509 v3 certificate extension -functions. B or B can be set to B if no additional -configuration will be used. - -=head1 GENERATION STRING FORMAT - -The actual data encoded is determined by the string B and -the configuration information. The general format of the string -is: - -=over 2 - -=item B<[modifier,]type[:value]> - -=back - -That is zero or more comma separated modifiers followed by a type -followed by an optional colon and a value. The formats of B, -B and B are explained below. - -=head2 SUPPORTED TYPES - -The supported types are listed below. Unless otherwise specified -only the B format is permissible. - -=over 2 - -=item B, B - -This encodes a boolean type. The B string is mandatory and -should be B or B. Additionally B, B, B, -B, B, B, B, B, B, B, B and B -are acceptable. - -=item B - -Encode the B type, the B string must not be present. - -=item B, B - -Encodes an ASN1 B type. The B string represents -the value of the integer, it can be prefaced by a minus sign and -is normally interpreted as a decimal value unless the prefix B<0x> -is included. - -=item B, B - -Encodes the ASN1 B type, it is otherwise identical to -B. - -=item B, B - -Encodes an ASN1 B, the B string can be -a short name, a long name or numerical format. - -=item B, B - -Encodes an ASN1 B structure, the value should be in -the format B. - -=item B, B - -Encodes an ASN1 B structure, the value should be in -the format B. - -=item B, B - -Encodes an ASN1 B. B represents the contents -of this structure, the format strings B and B can be -used to specify the format of B. - -=item B, B - -Encodes an ASN1 B. B represents the contents -of this structure, the format strings B, B and B -can be used to specify the format of B. - -If the format is anything other than B the number of unused -bits is set to zero. - -=item B, B, B, B, B, -B, B, B, B, -B, B, B, B, -B, B, B, B, -B - -These encode the corresponding string types. B represents the -contents of this structure. The format can be B or B. - -=item B, B, B - -Formats the result as an ASN1 B or B type. B -should be a section name which will contain the contents. The -field names in the section are ignored and the values are in the -generated string format. If B is absent then an empty SEQUENCE -will be encoded. - -=back - -=head2 MODIFIERS - -Modifiers affect the following structure, they can be used to -add EXPLICIT or IMPLICIT tagging, add wrappers or to change -the string format of the final type and value. The supported -formats are documented below. - -=over 2 - -=item B, B - -Add an explicit tag to the following structure. This string -should be followed by a colon and the tag value to use as a -decimal value. - -By following the number with B, B, B

or B UNIVERSAL, -APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used, -the default is CONTEXT SPECIFIC. - -=item B, B - -This is the same as B except IMPLICIT tagging is used -instead. - -=item B, B, B, B - -The following structure is surrounded by an OCTET STRING, a SEQUENCE, -a SET or a BIT STRING respectively. For a BIT STRING the number of unused -bits is set to zero. - -=item B - -This specifies the format of the ultimate value. It should be followed -by a colon and one of the strings B, B, B or B. - -If no format specifier is included then B is used. If B is -specified then the value string must be a valid B string. For B the -output must be a set of hex digits. B (which is only valid for a BIT -STRING) is a comma separated list of the indices of the set bits, all other -bits are zero. - -=back - -=head1 EXAMPLES - -A simple IA5String: - - IA5STRING:Hello World - -An IA5String explicitly tagged: - - EXPLICIT:0,IA5STRING:Hello World - -An IA5String explicitly tagged using APPLICATION tagging: - - EXPLICIT:0A,IA5STRING:Hello World - -A BITSTRING with bits 1 and 5 set and all others zero: - - FORMAT:BITLIST,BITSTRING:1,5 - -A more complex example using a config file to produce a -SEQUENCE consiting of a BOOL an OID and a UTF8String: - - asn1 = SEQUENCE:seq_section - - [seq_section] - - field1 = BOOLEAN:TRUE - field2 = OID:commonName - field3 = UTF8:Third field - -This example produces an RSAPrivateKey structure, this is the -key contained in the file client.pem in all OpenSSL distributions -(note: the field names such as 'coeff' are ignored and are present just -for clarity): - - asn1=SEQUENCE:private_key - [private_key] - version=INTEGER:0 - - n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\ - D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 - - e=INTEGER:0x010001 - - d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\ - F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D - - p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\ - D4BD57 - - q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\ - 46EC4F - - exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\ - 9C0A39B9 - - exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\ - E7B2458F - - coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\ - 628657053A - -This example is the corresponding public key in a SubjectPublicKeyInfo -structure: - - # Start with a SEQUENCE - asn1=SEQUENCE:pubkeyinfo - - # pubkeyinfo contains an algorithm identifier and the public key wrapped - # in a BIT STRING - [pubkeyinfo] - algorithm=SEQUENCE:rsa_alg - pubkey=BITWRAP,SEQUENCE:rsapubkey - - # algorithm ID for RSA is just an OID and a NULL - [rsa_alg] - algorithm=OID:rsaEncryption - parameter=NULL - - # Actual public key: modulus and exponent - [rsapubkey] - n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\ - D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 - - e=INTEGER:0x010001 - -=head1 RETURN VALUES - -ASN1_generate_nconf() and ASN1_generate_v3() return the encoded -data as an B structure or B if an error occurred. - -The error codes that can be obtained by L. - -=head1 SEE ALSO - -L - -=head1 HISTORY - -ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8 - -=cut -- cgit v1.2.3-55-g6feb