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/libcrypto/man/ASN1_OBJECT_new.3 | 61 ++++ src/lib/libcrypto/man/ASN1_STRING_length.3 | 165 ++++++++++ src/lib/libcrypto/man/ASN1_STRING_new.3 | 58 ++++ src/lib/libcrypto/man/ASN1_STRING_print_ex.3 | 151 ++++++++++ src/lib/libcrypto/man/ASN1_generate_nconf.3 | 331 +++++++++++++++++++++ src/lib/libcrypto/man/Makefile | 10 +- 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 ----------------- 11 files changed, 773 insertions(+), 534 deletions(-) create mode 100644 src/lib/libcrypto/man/ASN1_OBJECT_new.3 create mode 100644 src/lib/libcrypto/man/ASN1_STRING_length.3 create mode 100644 src/lib/libcrypto/man/ASN1_STRING_new.3 create mode 100644 src/lib/libcrypto/man/ASN1_STRING_print_ex.3 create mode 100644 src/lib/libcrypto/man/ASN1_generate_nconf.3 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 diff --git a/src/lib/libcrypto/man/ASN1_OBJECT_new.3 b/src/lib/libcrypto/man/ASN1_OBJECT_new.3 new file mode 100644 index 0000000000..a636e7182e --- /dev/null +++ b/src/lib/libcrypto/man/ASN1_OBJECT_new.3 @@ -0,0 +1,61 @@ +.Dd August 12, 2014 +.Dt ASN1_OBJECT_NEW 3 +.Os +.Sh NAME +.Nm ASN1_OBJECT_new , +.Nm ASN1_OBJECT_free +.Nd ASN1 object allocation functions +.Sh SYNOPSIS +.In openssl/asn1.h +.Ft ASN1_OBJECT * +.Fo ASN1_OBJECT_new +.Fa void +.Fc +.Ft void +.Fo ASN1_OBJECT_free +.Fa "ASN1_OBJECT *a" +.Fc +.Sh DESCRIPTION +The ASN1_OBJECT allocation routines allocate and free an +.Vt ASN1_OBJECT +structure, which represents an ASN1 OBJECT IDENTIFIER. +.Pp +.Fn ASN1_OBJECT_new +allocates and initializes an +.Vt ASN1_OBJECT +structure. +.Pp +.Fn ASN1_OBJECT_free +frees up the +.Vt ASN1_OBJECT +structure +.Fa a . +.Sh NOTES +Although +.Fn ASN1_OBJECT_new +allocates a new +.Vt ASN1_OBJECT +structure, it is almost never used in applications. +The ASN1 object utility functions such as +.Xr OBJ_nid2obj 3 +are used instead. +.Sh RETURN VALUES +If the allocation fails, +.Fn ASN1_OBJECT_new +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +Otherwise it returns a pointer to the newly allocated structure. +.Pp +.Fn ASN1_OBJECT_free +returns no value. +.Sh SEE ALSO +.Xr d2i_ASN1_OBJECT 3 , +.Xr ERR_get_error 3 , +.Xr OBJ_nid2obj 3 +.Sh HISTORY +.Fn ASN1_OBJECT_new +and +.Fn ASN1_OBJECT_free +are available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/ASN1_STRING_length.3 b/src/lib/libcrypto/man/ASN1_STRING_length.3 new file mode 100644 index 0000000000..71744587be --- /dev/null +++ b/src/lib/libcrypto/man/ASN1_STRING_length.3 @@ -0,0 +1,165 @@ +.Dd July 17, 2014 +.Dt ASN1_STRING_LENGTH 3 +.Os +.Sh NAME +.Nm ASN1_STRING_cmp , +.Nm ASN1_STRING_data , +.Nm ASN1_STRING_dup , +.Nm ASN1_STRING_length , +.Nm ASN1_STRING_length_set , +.Nm ASN1_STRING_set , +.Nm ASN1_STRING_to_UTF8 , +.Nm ASN1_STRING_type +.Nd ASN1_STRING utility functions +.Sh SYNOPSIS +.In openssl/asn1.h +.Ft int +.Fo ASN1_STRING_cmp +.Fa "ASN1_STRING *a" +.Fa "ASN1_STRING *b" +.Fc +.Ft unsigned char * +.Fo ASN1_STRING_data +.Fa "ASN1_STRING *x" +.Fc +.Ft ASN1_STRING * +.Fo ASN1_STRING_dup +.Fa "ASN1_STRING *a" +.Fc +.Ft int +.Fo ASN1_STRING_length +.Fa "ASN1_STRING *x" +.Fc +.Ft void +.Fo ASN1_STRING_length_set +.Fa "ASN1_STRING *x" +.Fa "int len" +.Fc +.Ft int +.Fo ASN1_STRING_set +.Fa "ASN1_STRING *str" +.Fa "const void *data" +.Fa "int len" +.Fc +.Ft int +.Fo ASN1_STRING_to_UTF8 +.Fa "unsigned char **out" +.Fa "ASN1_STRING *in" +.Fc +.Ft int +.Fo ASN1_STRING_type +.Fa "ASN1_STRING *x" +.Fc +.Sh DESCRIPTION +These functions manipulate +.Vt ASN1_STRING +structures. +.Pp +.Fn ASN1_STRING_cmp +compares +.Fa a +and +.Fa b +and returns 0 if the two are identical. +The string types and the content are compared. +.Pp +.Fn ASN1_STRING_data +returns an internal pointer to the data of +.Fa x . +Since this is an internal pointer, it should +.Em not +be freed or modified in any way. +.Pp +.Fn ASN1_STRING_dup +returns a copy of the structure +.Fa a . +.Pp +.Fn ASN1_STRING_length +returns the length of the content of +.Fa x . +.Pp +.Fn ASN1_STRING_length_set +sets the length attribute of +.Fa x +to +.Fa len . +It may put +.Fa x +into an inconsistent internal state. +.Pp +.Fn ASN1_STRING_set +sets the data of the string +.Fa str +to the buffer +.Fa data +of length +.Fa len . +The supplied data is copied. +If +.Fa len +is -1 then the length is determined by +.Fn strlen data . +.Pp +.Fn ASN1_STRING_to_UTF8 +converts the string +.Fa in +to UTF8 format. +The converted data is copied into a newly allocated buffer +.Fa out . +The length of +.Fa out +is returned or a negative error code. +The buffer +.Fa out +should be freed using +.Xr free 3 . +.Pp +.Fn ASN1_STRING_type +returns the type of +.Fa x , +using standard constants such as +.Dv V_ASN1_OCTET_STRING . +.Sh NOTES +Almost all ASN1 types in OpenSSL are represented as +.Vt ASN1_STRING +structures. +Other types such as +.Vt ASN1_OCTET_STRING +are simply typedefed to +.Vt ASN1_STRING +and the functions call the +.Vt ASN1_STRING +equivalents. +.Vt ASN1_STRING +is also used for some +.Sy CHOICE +types which consist entirely of primitive string types such as +.Sy DirectoryString +and +.Sy Time . +.Pp +These functions should +.Em not +be used to examine or modify +.Vt ASN1_INTEGER +or +.Vt ASN1_ENUMERATED +types: the relevant +.Sy INTEGER +or +.Sy ENUMERATED +utility functions should be used instead. +.Pp +In general it cannot be assumed that the data returned by +.Fn ASN1_STRING_data +is NUL terminated, and it may contain embedded NUL characters. +The actual format of the data will depend on the actual string type itself: +for example for an IA5String the data will be ASCII, +for a BMPString two bytes per character in big endian format, +UTF8String will be in UTF8 format. +.Pp +Similar care should be take to ensure the data is in the correct format +when calling +.Fn ASN1_STRING_set . +.Sh SEE ALSO +.Xr ERR_get_error 3 diff --git a/src/lib/libcrypto/man/ASN1_STRING_new.3 b/src/lib/libcrypto/man/ASN1_STRING_new.3 new file mode 100644 index 0000000000..cd28b98af6 --- /dev/null +++ b/src/lib/libcrypto/man/ASN1_STRING_new.3 @@ -0,0 +1,58 @@ +.Dd July 17, 2014 +.Dt ASN1_STRING_NEW 3 +.Os +.Sh NAME +.Nm ASN1_STRING_new , +.Nm ASN1_STRING_type_new , +.Nm ASN1_STRING_free +.Nd ASN1_STRING allocation functions +.Sh SYNOPSIS +.In openssl/asn1.h +.Ft ASN1_STRING * +.Fo ASN1_STRING_new +.Fa void +.Fc +.Ft ASN1_STRING * +.Fo ASN1_STRING_type_new +.Fa "int type" +.Fc +.Ft void +.Fo ASN1_STRING_free +.Fa "ASN1_STRING *a" +.Fc +.Sh DESCRIPTION +.Fn ASN1_STRING_new +returns an allocated +.Vt ASN1_STRING +structure. +Its type is undefined. +.Pp +.Fn ASN1_STRING_type_new +returns an allocated +.Vt ASN1_STRING +structure of type +.Fa type . +.Pp +.Fn ASN1_STRING_free +frees up +.Fa a . +.Sh NOTES +Other string types call the ASN1_STRING functions. +For example +.Fn ASN1_OCTET_STRING_new +calls +.Fn ASN1_STRING_type V_ASN1_OCTET_STRING . +.Sh RETURN VALUES +.Fn ASN1_STRING_new +and +.Fn ASN1_STRING_type_new +return a valid +.Vt ASN1_STRING +structure or +.Dv NULL +if an error occurred. +.Pp +.Fn ASN1_STRING_free +does not return a value. +.Sh SEE ALSO +.Xr ERR_get_error 3 diff --git a/src/lib/libcrypto/man/ASN1_STRING_print_ex.3 b/src/lib/libcrypto/man/ASN1_STRING_print_ex.3 new file mode 100644 index 0000000000..1d6495d199 --- /dev/null +++ b/src/lib/libcrypto/man/ASN1_STRING_print_ex.3 @@ -0,0 +1,151 @@ +.Dd July 17, 2014 +.Dt ASN1_STRING_PRINT_EX 3 +.Os +.Sh NAME +.Nm ASN1_STRING_print_ex , +.Nm ASN1_STRING_print_ex_fp , +.Nm ASN1_STRING_print +.Nd ASN1_STRING output routines +.Sh SYNOPSIS +.In openssl/asn1.h +.Ft int +.Fo ASN1_STRING_print_ex +.Fa "BIO *out" +.Fa "ASN1_STRING *str" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo ASN1_STRING_print_ex_fp +.Fa "FILE *fp" +.Fa "ASN1_STRING *str" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo ASN1_STRING_print +.Fa "BIO *out" +.Fa "ASN1_STRING *str" +.Fc +.Sh DESCRIPTION +These functions output an +.Vt ASN1_STRING +structure. +.Vt ASN1_STRING +is used to +represent all the ASN1 string types. +.Pp +.Fn ASN1_STRING_print_ex +outputs +.Fa str +to +.Fa out , +the format is determined by the options +.Fa flags . +.Fn ASN1_STRING_print_ex_fp +is identical except it outputs to +.Fa fp +instead. +.Pp +.Fn ASN1_STRING_print +prints +.Fa str +to +.Fa out +but using a different format to +.Fn ASN1_STRING_print_ex . +It replaces unprintable characters (other than CR, LF) with +.Sq \&. . +.Sh NOTES +.Fn ASN1_STRING_print +is a legacy function which should be avoided in new +applications. +.Pp +Although there are a large number of options frequently +.Dv ASN1_STRFLGS_RFC2253 +is suitable, or on UTF8 terminals +.Dv ASN1_STRFLGS_RFC2253 No & +.Pf ~ Dv ASN1_STRFLGS_ESC_MSB . +.Pp +The complete set of supported options for +.Fa flags +is listed below. +.Pp +Various characters can be escaped. +If +.Dv ASN1_STRFLGS_ESC_2253 +is set, the characters determined by RFC2253 are escaped. +If +.Dv ASN1_STRFLGS_ESC_CTRL +is set, control characters are escaped. +If +.Dv ASN1_STRFLGS_ESC_MSB +is set, characters with the MSB set are escaped: this option should +.Em not +be used if the terminal correctly interprets UTF8 sequences. +.Pp +Escaping takes several forms. +.Pp +If the character being escaped is a 16 bit character then the form "\eUXXXX" +is used using exactly four characters for the hex representation. +If it is 32 bits then "\eWXXXXXXXX" is used using eight characters +of its hex representation. +These forms will only be used if UTF8 conversion is not set (see below). +.Pp +Printable characters are normally escaped using the backslash +.Pq Sq \e +character. +If +.Dv 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 "\eXX" using exactly two characters of the hex +representation. +.Pp +If +.Dv 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. +.Pp +If +.Dv 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. +.Pp +If +.Dv ASN1_STRFLGS_SHOW_TYPE +is set, then the string type itself is printed out before its value +(for example "BMPSTRING"), this actually uses +.Fn ASN1_tag2str . +.Pp +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. +.Pp +If +.Dv ASN1_STRFLGS_DUMP_ALL +is set, then any type is dumped. +.Pp +Normally non character string types (such as OCTET STRING) +are assumed to be one byte per character; if +.Dv ASN1_STRFLGS_DUMP_UNKNOWN +is set, then they will be dumped instead. +.Pp +When a type is dumped normally just the content octets are printed; if +.Dv ASN1_STRFLGS_DUMP_DER +is set, then the complete encoding is dumped +instead (including tag and length octets). +.Pp +.Dv ASN1_STRFLGS_RFC2253 +includes all the flags required by RFC2253. +It is equivalent to +.Dv ASN1_STRFLGS_ESC_2253 | +.Dv ASN1_STRFLGS_ESC_CTRL | +.Dv ASN1_STRFLGS_ESC_MSB | +.Dv ASN1_STRFLGS_UTF8_CONVERT | +.Dv ASN1_STRFLGS_DUMP_UNKNOWN | +.Dv ASN1_STRFLGS_DUMP_DER . +.Sh SEE ALSO +.Xr ASN1_tag2str 3 , +.Xr X509_NAME_print_ex 3 diff --git a/src/lib/libcrypto/man/ASN1_generate_nconf.3 b/src/lib/libcrypto/man/ASN1_generate_nconf.3 new file mode 100644 index 0000000000..0f0d3727d4 --- /dev/null +++ b/src/lib/libcrypto/man/ASN1_generate_nconf.3 @@ -0,0 +1,331 @@ +.Dd July 17, 2014 +.Dt ASN1_GENERATE_NCONF 3 +.Os +.Sh NAME +.Nm ASN1_generate_nconf , +.Nm ASN1_generate_v3 +.Nd ASN1 generation functions +.Sh SYNOPSIS +.In openssl/asn1.h +.Ft ASN1_TYPE * +.Fo ASN1_generate_nconf +.Fa "char *str" +.Fa "CONF *nconf" +.Fc +.Ft ASN1_TYPE * +.Fo ASN1_generate_v3 +.Fa "char *str" +.Fa "X509V3_CTX *cnf" +.Fc +.Sh DESCRIPTION +These functions generate the ASN1 encoding of a string in an +.Vt ASN1_TYPE +structure. +.Pp +.Fa str +contains the string to encode +.Fa nconf +or +.Fa cnf +contains the optional configuration information +where additional strings will be read from. +.Fa nconf +will typically come from a config file whereas +.Fa cnf +is obtained from an +.Vt X509V3_CTX +structure which will typically be used +by X509 v3 certificate extension functions. +.Fa cnf +or +.Fa nconf +can be set to +.Dv NULL +if no additional configuration will be used. +.Sh GENERATION STRING FORMAT +The actual data encoded is determined by the string +.Fa str +and the configuration information. +The general format of the string is: +.Pp +.D1 Oo Ar modifier , Oc Ns Ar type Ns Op : Ns Ar value +.Pp +That is zero or more comma separated modifiers followed by a type +followed by an optional colon and a value. +The formats of +.Ar type , +.Ar value +and +.Ar modifier +are explained below. +.Ss Supported types +The supported types are listed below. +Unless otherwise specified, only the +.Cm ASCII +format is permissible. +.Bl -tag -width Ds +.It Cm BOOLEAN , BOOL +This encodes a boolean type. +The +.Ar value +string is mandatory and should be +.Cm TRUE +or +.Cm FALSE . +Additionally +.Cm true , +.Cm Y , +.Cm y , +.Cm YES , +.Cm yes , +.Cm false , +.Cm N , +.Cm n , +.Cm NO +and +.Cm no +are acceptable. +.It Cm NULL +Encode the NULL type. +The +.Ar value +string must not be present. +.It Cm INTEGER , INT +Encodes an ASN1 INTEGER type. +The +.Ar value +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 +.Cm 0x +is included. +.It Cm ENUMERATED , ENUM +Encodes the ASN1 ENUMERATED type. +It is otherwise identical to +.Cm INTEGER . +.It Cm OBJECT , OID +Encodes an ASN1 OBJECT IDENTIFIER. +The +.Ar value +string can be a short name, a long name, or numerical format. +.It Cm UTCTIME , UTC +Encodes an ASN1 UTCTime structure. +The value should be in the format +.Ar YYMMDDHHMMSSZ . +.It Cm GENERALIZEDTIME , GENTIME +Encodes an ASN1 GeneralizedTime structure. +The value should be in the format +.Ar YYYYMMDDHHMMSSZ . +.It Cm OCTETSTRING , OCT +Encodes an ASN1 OCTET STRING. +.Ar value +represents the contents of this structure. +The format strings +.Cm ASCII +and +.Cm HEX +can be used to specify the format of +.Ar value . +.It Cm BITSTRING , BITSTR +Encodes an ASN1 BIT STRING. +.Ar value +represents the contents of this structure. +The format strings +.Cm ASCII , +.Cm HEX , +and +.Cm BITLIST +can be used to specify the format of +.Ar value . +.Pp +If the format is anything other than +.Cm BITLIST , +the number of unused bits is set to zero. +.It Xo +.Cm BMPSTRING , BMP , +.Cm GeneralString , +.Cm IA5STRING , IA5 , +.Cm NUMERICSTRING , NUMERIC , +.Cm PRINTABLESTRING , PRINTABLE , +.Cm T61STRING , T61 , +.Cm TELETEXSTRING , +.Cm UNIVERSALSTRING , UNIV , +.Cm UTF8String , UTF8 , +.Cm VISIBLESTRING , VISIBLE +.Xc +These encode the corresponding string types. +.Ar value +represents the contents of this structure. +The format can be +.Cm ASCII +or +.Cm UTF8 . +.It Cm SEQUENCE , SEQ , SET +Formats the result as an ASN1 SEQUENCE or SET type. +.Ar value +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 +.Ar value +is absent, then an empty SEQUENCE will be encoded. +.El +.Ss 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: +.Bl -tag -width Ds +.It Cm EXPLICIT , EXP +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. +.Pp +By following the number with +.Cm U , +.Cm A , +.Cm P +or +.Cm C , +UNIVERSAL, APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used. +The default is CONTEXT SPECIFIC. +.It Cm IMPLICIT , IMP +This is the same as +.Cm EXPLICIT +except IMPLICIT tagging is used instead. +.It Cm OCTWRAP , SEQWRAP , SETWRAP , BITWRAP +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. +.It Cm FORMAT +This specifies the format of the ultimate value. +It should be followed by a colon and one of the strings +.Cm ASCII , +.Cm UTF8 , +.Cm HEX , +or +.Cm BITLIST . +.Pp +If no format specifier is included, then +.Cm ASCII +is used. +If +.Cm UTF8 +is specified, then the +.Ar value +string must be a valid UTF8 string. +For +.Cm HEX , +the output must be a set of hex digits. +.Cm BITLIST +(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. +.El +.Sh RETURN VALUES +.Fn ASN1_generate_nconf +and +.Fn ASN1_generate_v3 +return the encoded data as an +.Vt ASN1_TYPE +structure or +.Dv NULL +if an error occurred. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh EXAMPLES +A simple IA5String: +.Pp +.Dl IA5STRING:Hello World +.Pp +An IA5String explicitly tagged: +.Pp +.Dl EXPLICIT:0,IA5STRING:Hello World +.Pp +An IA5String explicitly tagged using APPLICATION tagging: +.Pp +.Dl EXPLICIT:0A,IA5STRING:Hello World +.Pp +A BITSTRING with bits 1 and 5 set and all others zero: +.Pp +.Dl FORMAT:BITLIST,BITSTRING:1,5 +.Pp +A more complex example using a config file to produce a +SEQUENCE consiting of a BOOL an OID and a UTF8String: +.Bd -literal -offset indent +asn1 = SEQUENCE:seq_section + +[seq_section] + +field1 = BOOLEAN:TRUE +field2 = OID:commonName +field3 = UTF8:Third field +.Ed +.Pp +This example produces an RSAPrivateKey structure. +This is the key contained in the file +.Pa client.pem +in all OpenSSL distributions. +Note that the field names such as +.Qq coeff +are ignored and are present just for clarity. +.Bd -literal -offset 2n +asn1=SEQUENCE:private_key +[private_key] +version=INTEGER:0 + +n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e +D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 + +e=INTEGER:0x010001 + +d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e +F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D + +p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e +D4BD57 + +q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e +46EC4F + +exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e +9C0A39B9 + +exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e +E7B2458F + +coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e +628657053A +.Ed +.Pp +This example is the corresponding public key in a SubjectPublicKeyInfo +structure: +.Bd -literal -offset 2n +# 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\e +D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 + +e=INTEGER:0x010001 +.Ed +.Sh SEE ALSO +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn ASN1_generate_nconf +and +.Fn ASN1_generate_v3 +were added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index c6dc286934..5edbf7e394 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.15 2015/01/16 01:58:18 schwarze Exp $ +# $OpenBSD: Makefile,v 1.16 2015/02/14 13:54:59 schwarze Exp $ .include # for NOMAN @@ -10,7 +10,9 @@ MAN= \ ASN1_STRING_length.3 \ ASN1_STRING_new.3 \ ASN1_STRING_print_ex.3 \ - ASN1_generate_nconf.3 \ + ASN1_generate_nconf.3 + +GENMAN= \ BF_set_key.3 \ BIO.3 \ BIO_ctrl.3 \ @@ -195,6 +197,8 @@ MAN= \ ui_compat.3 \ x509.3 \ +MAN+= ${GENMAN} + #MAN+= BIO_new_CMS.3 \ # CMS_add0_cert.3 \ # CMS_add1_recipient_cert.3 \ @@ -1146,4 +1150,4 @@ maninstall: .include clean cleandir: - rm -f ${MAN} + rm -f ${GENMAN} 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