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