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