projects / openssl.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Constify two internal methods
[openssl.git] / doc / crypto / ASN1_generate_nconf.pod
diff --git a/doc/crypto/ASN1_generate_nconf.pod b/doc/crypto/ASN1_generate_nconf.pod
index b4c89377f6a331d38db2a02aaec4072415c4ce86..92f624fa24d39b10ff75f8cea57d8be04943fed1 100644 (file)
--- a/doc/crypto/ASN1_generate_nconf.pod
+++ b/doc/crypto/ASN1_generate_nconf.pod
@@ -6,8 +6,10 @@ ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 
- ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
- ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
+ #include <openssl/asn1.h>
+
+ ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
+ ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 
@@ -17,7 +19,7 @@ in an B<ASN1_TYPE> structure.
 B<str> contains the string to encode B<nconf> or B<cnf> contains
 the optional configuration information where additional strings
 will be read from. B<nconf> will typically come from a config
 B<str> contains the string to encode B<nconf> or B<cnf> contains
 the optional configuration information where additional strings
 will be read from. B<nconf> will typically come from a config
-file wherease B<cnf> is obtained from an B<X509V3_CTX> structure
+file whereas B<cnf> is obtained from an B<X509V3_CTX> structure
 which will typically be used by X509 v3 certificate extension
 functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
 configuration will be used.
 which will typically be used by X509 v3 certificate extension
 functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
 configuration will be used.
@@ -28,13 +30,17 @@ The actual data encoded is determined by the string B<str> and
 the configuration information. The general format of the string
 is:
 
 the configuration information. The general format of the string
 is:
 
- B<[modifier,]type[:value]>
+=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<type>,
 B<value> and B<modifier> are explained below.
 
 
 That is zero or more comma separated modifiers followed by a type
 followed by an optional colon and a value. The formats of B<type>,
 B<value> and B<modifier> are explained below.
 
-=head2 SUPPORTED TYPES
+=head2 Supported Types
 
 The supported types are listed below. Unless otherwise specified
 only the B<ASCII> format is permissible.
 
 The supported types are listed below. Unless otherwise specified
 only the B<ASCII> format is permissible.
@@ -46,7 +52,7 @@ only the B<ASCII> format is permissible.
 This encodes a boolean type. The B<value> string is mandatory and
 should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
 B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no>
 This encodes a boolean type. The B<value> string is mandatory and
 should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
 B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no>
-are acceptable. 
+are acceptable.
 
 =item B<NULL>
 
 
 =item B<NULL>
 
@@ -55,7 +61,7 @@ Encode the B<NULL> type, the B<value> string must not be present.
 =item B<INTEGER>, B<INT>
 
 Encodes an ASN1 B<INTEGER> type. The B<value> string represents
 =item B<INTEGER>, B<INT>
 
 Encodes an ASN1 B<INTEGER> type. The B<value> string represents
-the value of the integer, it can be preceeded by a minus sign and
+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.
 
 is normally interpreted as a decimal value unless the prefix B<0x>
 is included.
 
@@ -72,22 +78,22 @@ a short name, a long name or numerical format.
 =item B<UTCTIME>, B<UTC>
 
 Encodes an ASN1 B<UTCTime> structure, the value should be in
 =item B<UTCTIME>, B<UTC>
 
 Encodes an ASN1 B<UTCTime> structure, the value should be in
-the format B<YYMMDDHHMMSSZ>. 
+the format B<YYMMDDHHMMSSZ>.
 
 =item B<GENERALIZEDTIME>, B<GENTIME>
 
 Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
 
 =item B<GENERALIZEDTIME>, B<GENTIME>
 
 Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
-the format B<YYYYMMDDHHMMSSZ>. 
+the format B<YYYYMMDDHHMMSSZ>.
 
 =item B<OCTETSTRING>, B<OCT>
 
 
 =item B<OCTETSTRING>, B<OCT>
 
-Emcodes an ASN1 B<OCTET STRING>. B<value> represents the contents
+Encodes an ASN1 B<OCTET STRING>. B<value> represents the contents
 of this structure, the format strings B<ASCII> and B<HEX> can be
 used to specify the format of B<value>.
 
 of this structure, the format strings B<ASCII> and B<HEX> can be
 used to specify the format of B<value>.
 
-=item B<BITSRING>, B<BITSTR>
+=item B<BITSTRING>, B<BITSTR>
 
 
-Emcodes an ASN1 B<BIT STRING>. B<value> represents the contents
+Encodes an ASN1 B<BIT STRING>. B<value> represents the contents
 of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
 can be used to specify the format of B<value>.
 
 of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
 can be used to specify the format of B<value>.
 
@@ -97,7 +103,8 @@ bits is set to zero.
 =item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
 B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
 B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
 =item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
 B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
 B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
-B<T61STRING>, B<TELETEXSTRING>
+B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>,
+B<NUMERIC>
 
 These encode the corresponding string types. B<value> represents the
 contents of this structure. The format can be B<ASCII> or B<UTF8>.
 
 These encode the corresponding string types. B<value> represents the
 contents of this structure. The format can be B<ASCII> or B<UTF8>.
@@ -112,7 +119,7 @@ will be encoded.
 
 =back
 
 
 =back
 
-=head2 MODIFIERS
+=head2 Modifiers
 
 Modifiers affect the following structure, they can be used to
 add EXPLICIT or IMPLICIT tagging, add wrappers or to change
 
 Modifiers affect the following structure, they can be used to
 add EXPLICIT or IMPLICIT tagging, add wrappers or to change
@@ -147,10 +154,11 @@ bits is set to zero.
 This specifies the format of the ultimate value. It should be followed
 by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>.
 
 This specifies the format of the ultimate value. It should be followed
 by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>.
 
-If no format specifier is included then B<ASCII> is used. If B<UTF8> is specified
-then the value string must be a valid B<UTF8> string. For B<HEX> the output must
-be a set of hex digits. B<BITLIST> (which is only valid for a BIT STRING) is a
-comma separated list of set bits.
+If no format specifier is included then B<ASCII> is used. If B<UTF8> is
+specified then the value string must be a valid B<UTF8> string. For B<HEX> the
+output must be a set of hex digits. B<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.
 
 =back
 
 
 =back
 
@@ -168,16 +176,20 @@ An IA5String explicitly tagged using APPLICATION tagging:
 
  EXPLICIT:0A,IA5STRING:Hello World
 
 
  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
 A more complex example using a config file to produce a
-SEQUENCE consiting of a BOOL an OID and a UTF8String:
+SEQUENCE consisting of a BOOL an OID and a UTF8String:
 
 
-asn1 = SEQUENCE:seq_section
+ asn1 = SEQUENCE:seq_section
 
 
-[seq_section]
+ [seq_section]
 
 
-field1 = BOOLEAN:TRUE
-field2 = OID:commonName
-field3 = UTF8:Third field
+ 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
 
 This example produces an RSAPrivateKey structure, this is the
 key contained in the file client.pem in all OpenSSL distributions
@@ -240,14 +252,19 @@ structure:
 ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
 data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
 
 ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
 data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
 
-The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+The error codes that can be obtained by L<ERR_get_error(3)>.
 
 =head1 SEE ALSO
 
 
 =head1 SEE ALSO
 
-L<ERR_get_error(3)|ERR_get_error(3)>
+L<ERR_get_error(3)>
+
+=head1 COPYRIGHT
 
 
-=head1 HISTORY
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
 
 
-ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
 
 =cut
 
 =cut
Unnamed repository; edit this file 'description' to name the repository.