1=pod 2 3=head1 NAME 4 5ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions 6 7=head1 SYNOPSIS 8 9 ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf); 10 ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf); 11 12=head1 DESCRIPTION 13 14These functions generate the ASN1 encoding of a string 15in an B<ASN1_TYPE> structure. 16 17B<str> contains the string to encode B<nconf> or B<cnf> contains 18the optional configuration information where additional strings 19will be read from. B<nconf> will typically come from a config 20file wherease B<cnf> is obtained from an B<X509V3_CTX> structure 21which will typically be used by X509 v3 certificate extension 22functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional 23configuration will be used. 24 25=head1 GENERATION STRING FORMAT 26 27The actual data encoded is determined by the string B<str> and 28the configuration information. The general format of the string 29is: 30 31 B<[modifier,]type[:value]> 32 33That is zero or more comma separated modifiers followed by a type 34followed by an optional colon and a value. The formats of B<type>, 35B<value> and B<modifier> are explained below. 36 37=head2 SUPPORTED TYPES 38 39The supported types are listed below. Unless otherwise specified 40only the B<ASCII> format is permissible. 41 42=over 2 43 44=item B<BOOLEAN>, B<BOOL> 45 46This encodes a boolean type. The B<value> string is mandatory and 47should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>, 48B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no> 49are acceptable. 50 51=item B<NULL> 52 53Encode the B<NULL> type, the B<value> string must not be present. 54 55=item B<INTEGER>, B<INT> 56 57Encodes an ASN1 B<INTEGER> type. The B<value> string represents 58the value of the integer, it can be preceeded by a minus sign and 59is normally interpreted as a decimal value unless the prefix B<0x> 60is included. 61 62=item B<ENUMERATED>, B<ENUM> 63 64Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to 65B<INTEGER>. 66 67=item B<OBJECT>, B<OID> 68 69Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be 70a short name, a long name or numerical format. 71 72=item B<UTCTIME>, B<UTC> 73 74Encodes an ASN1 B<UTCTime> structure, the value should be in 75the format B<YYMMDDHHMMSSZ>. 76 77=item B<GENERALIZEDTIME>, B<GENTIME> 78 79Encodes an ASN1 B<GeneralizedTime> structure, the value should be in 80the format B<YYYYMMDDHHMMSSZ>. 81 82=item B<OCTETSTRING>, B<OCT> 83 84Emcodes an ASN1 B<OCTET STRING>. B<value> represents the contents 85of this structure, the format strings B<ASCII> and B<HEX> can be 86used to specify the format of B<value>. 87 88=item B<BITSRING>, B<BITSTR> 89 90Emcodes an ASN1 B<BIT STRING>. B<value> represents the contents 91of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST> 92can be used to specify the format of B<value>. 93 94If the format is anything other than B<BITLIST> the number of unused 95bits is set to zero. 96 97=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>, 98B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>, 99B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>, 100B<T61STRING>, B<TELETEXSTRING>, B<GeneralString> 101 102These encode the corresponding string types. B<value> represents the 103contents of this structure. The format can be B<ASCII> or B<UTF8>. 104 105=item B<SEQUENCE>, B<SEQ>, B<SET> 106 107Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value> 108should be a section name which will contain the contents. The 109field names in the section are ignored and the values are in the 110generated string format. If B<value> is absent then an empty SEQUENCE 111will be encoded. 112 113=back 114 115=head2 MODIFIERS 116 117Modifiers affect the following structure, they can be used to 118add EXPLICIT or IMPLICIT tagging, add wrappers or to change 119the string format of the final type and value. The supported 120formats are documented below. 121 122=over 2 123 124=item B<EXPLICIT>, B<EXP> 125 126Add an explicit tag to the following structure. This string 127should be followed by a colon and the tag value to use as a 128decimal value. 129 130By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL, 131APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used, 132the default is CONTEXT SPECIFIC. 133 134=item B<IMPLICIT>, B<IMP> 135 136This is the same as B<EXPLICIT> except IMPLICIT tagging is used 137instead. 138 139=item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP> 140 141The following structure is surrounded by an OCTET STRING, a SEQUENCE, 142a SET or a BIT STRING respectively. For a BIT STRING the number of unused 143bits is set to zero. 144 145=item B<FORMAT> 146 147This specifies the format of the ultimate value. It should be followed 148by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>. 149 150If no format specifier is included then B<ASCII> is used. If B<UTF8> is specified 151then the value string must be a valid B<UTF8> string. For B<HEX> the output must 152be a set of hex digits. B<BITLIST> (which is only valid for a BIT STRING) is a 153comma separated list of set bits. 154 155=back 156 157=head1 EXAMPLES 158 159A simple IA5String: 160 161 IA5STRING:Hello World 162 163An IA5String explicitly tagged: 164 165 EXPLICIT:0,IA5STRING:Hello World 166 167An IA5String explicitly tagged using APPLICATION tagging: 168 169 EXPLICIT:0A,IA5STRING:Hello World 170 171A more complex example using a config file to produce a 172SEQUENCE consiting of a BOOL an OID and a UTF8String: 173 174asn1 = SEQUENCE:seq_section 175 176[seq_section] 177 178field1 = BOOLEAN:TRUE 179field2 = OID:commonName 180field3 = UTF8:Third field 181 182This example produces an RSAPrivateKey structure, this is the 183key contained in the file client.pem in all OpenSSL distributions 184(note: the field names such as 'coeff' are ignored and are present just 185for clarity): 186 187 asn1=SEQUENCE:private_key 188 [private_key] 189 version=INTEGER:0 190 191 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\ 192 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 193 194 e=INTEGER:0x010001 195 196 d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\ 197 F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D 198 199 p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\ 200 D4BD57 201 202 q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\ 203 46EC4F 204 205 exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\ 206 9C0A39B9 207 208 exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\ 209 E7B2458F 210 211 coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\ 212 628657053A 213 214This example is the corresponding public key in a SubjectPublicKeyInfo 215structure: 216 217 # Start with a SEQUENCE 218 asn1=SEQUENCE:pubkeyinfo 219 220 # pubkeyinfo contains an algorithm identifier and the public key wrapped 221 # in a BIT STRING 222 [pubkeyinfo] 223 algorithm=SEQUENCE:rsa_alg 224 pubkey=BITWRAP,SEQUENCE:rsapubkey 225 226 # algorithm ID for RSA is just an OID and a NULL 227 [rsa_alg] 228 algorithm=OID:rsaEncryption 229 parameter=NULL 230 231 # Actual public key: modulus and exponent 232 [rsapubkey] 233 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\ 234 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 235 236 e=INTEGER:0x010001 237 238=head1 RETURN VALUES 239 240ASN1_generate_nconf() and ASN1_generate_v3() return the encoded 241data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred. 242 243The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. 244 245=head1 SEE ALSO 246 247L<ERR_get_error(3)|ERR_get_error(3)> 248 249=head1 HISTORY 250 251ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8 252 253=cut 254