lib/libcrypto/man/ASN1_generate_nconf.3

   1 .\"     $OpenBSD: ASN1_generate_nconf.3,v 1.10 2018/03/23 00:09:11 schwarze Exp $
   2 .\"     OpenSSL 05ea606a Fri May 20 20:52:46 2016 -0400
   3 .\"
   4 .\" This file was written by Dr. Stephen Henson.
   5 .\" Copyright (c) 2002, 2003, 2006-2009, 2013-2015 The OpenSSL Project.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\"
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in
  17 .\"    the documentation and/or other materials provided with the
  18 .\"    distribution.
  19 .\"
  20 .\" 3. All advertising materials mentioning features or use of this
  21 .\"    software must display the following acknowledgment:
  22 .\"    "This product includes software developed by the OpenSSL Project
  23 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  24 .\"
  25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26 .\"    endorse or promote products derived from this software without
  27 .\"    prior written permission. For written permission, please contact
  28 .\"    openssl-core@openssl.org.
  29 .\"
  30 .\" 5. Products derived from this software may not be called "OpenSSL"
  31 .\"    nor may "OpenSSL" appear in their names without prior written
  32 .\"    permission of the OpenSSL Project.
  33 .\"
  34 .\" 6. Redistributions of any form whatsoever must retain the following
  35 .\"    acknowledgment:
  36 .\"    "This product includes software developed by the OpenSSL Project
  37 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  38 .\"
  39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  51 .\"
  52 .Dd $Mdocdate: March 23 2018 $
  53 .Dt ASN1_GENERATE_NCONF 3
  54 .Os
  55 .Sh NAME
  56 .Nm ASN1_generate_nconf ,
  57 .Nm ASN1_generate_v3
  58 .Nd ASN.1 generation functions
  59 .Sh SYNOPSIS
  60 .In openssl/asn1.h
  61 .Ft ASN1_TYPE *
  62 .Fo ASN1_generate_nconf
  63 .Fa "char *str"
  64 .Fa "CONF *nconf"
  65 .Fc
  66 .Ft ASN1_TYPE *
  67 .Fo ASN1_generate_v3
  68 .Fa "char *str"
  69 .Fa "X509V3_CTX *cnf"
  70 .Fc
  71 .Sh DESCRIPTION
  72 These functions generate the ASN.1 encoding of a string in an
  73 .Vt ASN1_TYPE
  74 structure.
  75 .Pp
  76 .Fa str
  77 contains the string to encode
  78 .Fa nconf
  79 or
  80 .Fa cnf
  81 contains the optional configuration information
  82 where additional strings will be read from.
  83 .Fa nconf
  84 will typically come from a config file whereas
  85 .Fa cnf
  86 is obtained from an
  87 .Vt X509V3_CTX
  88 structure which will typically be used
  89 by X509 v3 certificate extension functions.
  90 .Fa cnf
  91 or
  92 .Fa nconf
  93 can be set to
  94 .Dv NULL
  95 if no additional configuration will be used.
  96 .Sh GENERATION STRING FORMAT
  97 The actual data encoded is determined by the string
  98 .Fa str
  99 and the configuration information.
 100 The general format of the string is:
 101 .Pp
 102 .D1 Oo Ar modifier , Oc Ns Ar type Ns Op : Ns Ar value
 103 .Pp
 104 That is zero or more comma separated modifiers followed by a type
 105 followed by an optional colon and a value.
 106 The formats of
 107 .Ar type ,
 108 .Ar value
 109 and
 110 .Ar modifier
 111 are explained below.
 112 .Ss Supported types
 113 The supported types are listed below.
 114 Unless otherwise specified, only the
 115 .Cm ASCII
 116 format is permissible.
 117 .Bl -tag -width Ds
 118 .It Cm BOOLEAN , BOOL
 119 This encodes a boolean type.
 120 The
 121 .Ar value
 122 string is mandatory and should be
 123 .Cm TRUE
 124 or
 125 .Cm FALSE .
 126 Additionally
 127 .Cm true ,
 128 .Cm Y ,
 129 .Cm y ,
 130 .Cm YES ,
 131 .Cm yes ,
 132 .Cm false ,
 133 .Cm N ,
 134 .Cm n ,
 135 .Cm NO
 136 and
 137 .Cm no
 138 are acceptable.
 139 .It Cm NULL
 140 Encode the NULL type.
 141 The
 142 .Ar value
 143 string must not be present.
 144 .It Cm INTEGER , INT
 145 Encodes an ASN.1 INTEGER type.
 146 The
 147 .Ar value
 148 string represents the value of the integer.
 149 It can be prefaced by a minus sign
 150 and is normally interpreted as a decimal value unless the prefix
 151 .Cm 0x
 152 is included.
 153 .It Cm ENUMERATED , ENUM
 154 Encodes the ASN.1 ENUMERATED type.
 155 It is otherwise identical to
 156 .Cm INTEGER .
 157 .It Cm OBJECT , OID
 158 Encodes an ASN.1 OBJECT IDENTIFIER.
 159 The
 160 .Ar value
 161 string can be a short name, a long name, or numerical format.
 162 .It Cm UTCTIME , UTC
 163 Encodes an ASN.1 UTCTime structure.
 164 The value should be in the format
 165 .Ar YYMMDDHHMMSSZ .
 166 .It Cm GENERALIZEDTIME , GENTIME
 167 Encodes an ASN.1 GeneralizedTime structure.
 168 The value should be in the format
 169 .Ar YYYYMMDDHHMMSSZ .
 170 .It Cm OCTETSTRING , OCT
 171 Encodes an ASN.1 OCTET STRING.
 172 .Ar value
 173 represents the contents of this structure.
 174 The format strings
 175 .Cm ASCII
 176 and
 177 .Cm HEX
 178 can be used to specify the format of
 179 .Ar value .
 180 .It Cm BITSTRING , BITSTR
 181 Encodes an ASN.1 BIT STRING.
 182 .Ar value
 183 represents the contents of this structure.
 184 The format strings
 185 .Cm ASCII ,
 186 .Cm HEX ,
 187 and
 188 .Cm BITLIST
 189 can be used to specify the format of
 190 .Ar value .
 191 .Pp
 192 If the format is anything other than
 193 .Cm BITLIST ,
 194 the number of unused bits is set to zero.
 195 .It Xo
 196 .Cm BMPSTRING , BMP ,
 197 .Cm GeneralString ,
 198 .Cm IA5STRING , IA5 ,
 199 .Cm NUMERICSTRING , NUMERIC ,
 200 .Cm PRINTABLESTRING , PRINTABLE ,
 201 .Cm T61STRING , T61 ,
 202 .Cm TELETEXSTRING ,
 203 .Cm UNIVERSALSTRING , UNIV ,
 204 .Cm UTF8String , UTF8 ,
 205 .Cm VISIBLESTRING , VISIBLE
 206 .Xc
 207 These encode the corresponding string types.
 208 .Ar value
 209 represents the contents of this structure.
 210 The format can be
 211 .Cm ASCII
 212 or
 213 .Cm UTF8 .
 214 .It Cm SEQUENCE , SEQ , SET
 215 Formats the result as an ASN.1 SEQUENCE or SET type.
 216 .Ar value
 217 should be a section name which will contain the contents.
 218 The field names in the section are ignored
 219 and the values are in the generated string format.
 220 If
 221 .Ar value
 222 is absent, then an empty SEQUENCE will be encoded.
 223 .El
 224 .Ss Modifiers
 225 Modifiers affect the following structure.
 226 They can be used to add EXPLICIT or IMPLICIT tagging, add wrappers,
 227 or to change the string format of the final type and value.
 228 The supported formats are:
 229 .Bl -tag -width Ds
 230 .It Cm EXPLICIT , EXP
 231 Add an explicit tag to the following structure.
 232 This string should be followed by a colon
 233 and the tag value to use as a decimal value.
 234 .Pp
 235 By following the number with
 236 .Cm U ,
 237 .Cm A ,
 238 .Cm P
 239 or
 240 .Cm C ,
 241 UNIVERSAL, APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used.
 242 The default is CONTEXT SPECIFIC.
 243 .It Cm IMPLICIT , IMP
 244 This is the same as
 245 .Cm EXPLICIT
 246 except IMPLICIT tagging is used instead.
 247 .It Cm OCTWRAP , SEQWRAP , SETWRAP , BITWRAP
 248 The following structure is surrounded by
 249 an OCTET STRING, a SEQUENCE, a SET, or a BIT STRING, respectively.
 250 For a BIT STRING the number of unused bits is set to zero.
 251 .It Cm FORMAT
 252 This specifies the format of the ultimate value.
 253 It should be followed by a colon and one of the strings
 254 .Cm ASCII ,
 255 .Cm UTF8 ,
 256 .Cm HEX ,
 257 or
 258 .Cm BITLIST .
 259 .Pp
 260 If no format specifier is included, then
 261 .Cm ASCII
 262 is used.
 263 If
 264 .Cm UTF8
 265 is specified, then the
 266 .Ar value
 267 string must be a valid UTF-8 string.
 268 For
 269 .Cm HEX ,
 270 the output must be a set of hex digits.
 271 .Cm BITLIST
 272 (which is only valid for a BIT STRING) is a comma separated list
 273 of the indices of the set bits, all other bits are zero.
 274 .El
 275 .Sh RETURN VALUES
 276 .Fn ASN1_generate_nconf
 277 and
 278 .Fn ASN1_generate_v3
 279 return the encoded data as an
 280 .Vt ASN1_TYPE
 281 structure or
 282 .Dv NULL
 283 if an error occurred.
 284 .Pp
 285 The error codes can be obtained by
 286 .Xr ERR_get_error 3 .
 287 .Sh EXAMPLES
 288 A simple
 289 .Vt IA5String :
 290 .Pp
 291 .Dl IA5STRING:Hello World
 292 .Pp
 293 An
 294 .Vt IA5String
 295 explicitly tagged:
 296 .Pp
 297 .Dl EXPLICIT:0,IA5STRING:Hello World
 298 .Pp
 299 An
 300 .Vt IA5String
 301 explicitly tagged using APPLICATION tagging:
 302 .Pp
 303 .Dl EXPLICIT:0A,IA5STRING:Hello World
 304 .Pp
 305 A BITSTRING with bits 1 and 5 set and all others zero:
 306 .Pp
 307 .Dl FORMAT:BITLIST,BITSTRING:1,5
 308 .Pp
 309 A more complex example using a config file to produce a
 310 SEQUENCE consisting of a BOOL an OID and a
 311 .Vt UTF8String :
 312 .Bd -literal -offset indent
 313 asn1 = SEQUENCE:seq_section
 314
 315 [seq_section]
 316
 317 field1 = BOOLEAN:TRUE
 318 field2 = OID:commonName
 319 field3 = UTF8:Third field
 320 .Ed
 321 .Pp
 322 This example produces an
 323 .Vt RSAPrivateKey
 324 structure.
 325 This is the key contained in the file
 326 .Pa client.pem
 327 in all OpenSSL distributions.
 328 Note that the field names such as
 329 .Qq coeff
 330 are ignored and are present just for clarity.
 331 .Bd -literal -offset 2n
 332 asn1=SEQUENCE:private_key
 333 [private_key]
 334 version=INTEGER:0
 335
 336 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
 337 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
 338
 339 e=INTEGER:0x010001
 340
 341 d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
 342 F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
 343
 344 p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
 345 D4BD57
 346
 347 q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
 348 46EC4F
 349
 350 exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
 351 9C0A39B9
 352
 353 exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
 354 E7B2458F
 355
 356 coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
 357 628657053A
 358 .Ed
 359 .Pp
 360 This example is the corresponding public key in an ASN.1
 361 .Vt SubjectPublicKeyInfo
 362 structure:
 363 .Bd -literal -offset 2n
 364 # Start with a SEQUENCE
 365 asn1=SEQUENCE:pubkeyinfo
 366
 367 # pubkeyinfo contains an algorithm identifier and the public key
 368 # wrapped in a BIT STRING
 369 [pubkeyinfo]
 370 algorithm=SEQUENCE:rsa_alg
 371 pubkey=BITWRAP,SEQUENCE:rsapubkey
 372
 373 # algorithm ID for RSA is just an OID and a NULL
 374 [rsa_alg]
 375 algorithm=OID:rsaEncryption
 376 parameter=NULL
 377
 378 # Actual public key: modulus and exponent
 379 [rsapubkey]
 380 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
 381 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
 382
 383 e=INTEGER:0x010001
 384 .Ed
 385 .Sh SEE ALSO
 386 .Xr ERR_get_error 3 ,
 387 .Xr x509v3.cnf 5
 388 .Sh HISTORY
 389 .Fn ASN1_generate_nconf
 390 and
 391 .Fn ASN1_generate_v3
 392 first appeared in OpenSSL 0.9.8 and have been available since
 393 .Ox 4.5 .