Update docs

[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 bdee4067c754bb7cb889a367d600d8add171a877..c9af7e49b7864e4567dd2ca9a30394681fb0c1c1 100644 (file)
--- a/doc/crypto/ASN1_generate_nconf.pod
+++ b/doc/crypto/ASN1_generate_nconf.pod
@@ -36,6 +36,9 @@ B<value> and B<modifier> is explained below.
 
 =head2 SUPPORTED TYPES
 
+The supported types are listed below. Unless otherwise specified
+only the B<ASCII> format is permissible.
+
 =over 2
 
 =item B<BOOLEAN>, B<BOOL>
@@ -110,7 +113,126 @@ string format. If B<value> is absent the the content will be empty.
 
 =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<EXPLICIT>, B<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.
+
+By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL,
+APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used,
+the default is CONTEXT SPECIFIC.
+
+=item B<IMPLICIT>, B<IMP>
+
+This is the same as B<EXPLICIT> except IMPLICIT tagging is used
+instead.
+
+=item B<OCTWRAP>, B<SEQWRAP>, B<BITWRAP>
+
+The following structure is surrounded by an OCTET STRING, a SEQUENCE
+or a BIT STRING respectively. For a BIT STRING the number of unused
+bits is set to zero.
+
+=item B<FORMAT>
+
+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.
+
+=cut
+
+=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 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
 
@@ -119,11 +241,9 @@ 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)>.
 
-X509_free() returns no value.
-
 =head1 SEE ALSO
 
-L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509(3)|d2i_X509(3)>
+L<ERR_get_error(3)|ERR_get_error(3)>
 
 =head1 HISTORY