doc/man3/ASN1_generate_nconf.pod

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