secure/lib/libcrypto/man/ASN1_generate_nconf.3

   1 .\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "ASN1_generate_nconf 3"
 132 .TH ASN1_generate_nconf 3 "2017-11-02" "1.0.2m" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 generation functions
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/asn1.h>
 143 \&
 144 \& ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
 145 \& ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
 146 .Ve
 147 .SH "DESCRIPTION"
 148 .IX Header "DESCRIPTION"
 149 These functions generate the \s-1ASN1\s0 encoding of a string
 150 in an \fB\s-1ASN1_TYPE\s0\fR structure.
 151 .PP
 152 \&\fBstr\fR contains the string to encode \fBnconf\fR or \fBcnf\fR contains
 153 the optional configuration information where additional strings
 154 will be read from. \fBnconf\fR will typically come from a config
 155 file wherease \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
 156 which will typically be used by X509 v3 certificate extension
 157 functions. \fBcnf\fR or \fBnconf\fR can be set to \fB\s-1NULL\s0\fR if no additional
 158 configuration will be used.
 159 .SH "GENERATION STRING FORMAT"
 160 .IX Header "GENERATION STRING FORMAT"
 161 The actual data encoded is determined by the string \fBstr\fR and
 162 the configuration information. The general format of the string
 163 is:
 164 .IP "\fB[modifier,]type[:value]\fR" 2
 165 .IX Item "[modifier,]type[:value]"
 166 .PP
 167 That is zero or more comma separated modifiers followed by a type
 168 followed by an optional colon and a value. The formats of \fBtype\fR,
 169 \&\fBvalue\fR and \fBmodifier\fR are explained below.
 170 .SS "\s-1SUPPORTED TYPES\s0"
 171 .IX Subsection "SUPPORTED TYPES"
 172 The supported types are listed below. Unless otherwise specified
 173 only the \fB\s-1ASCII\s0\fR format is permissible.
 174 .IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 2
 175 .IX Item "BOOLEAN, BOOL"
 176 This encodes a boolean type. The \fBvalue\fR string is mandatory and
 177 should be \fB\s-1TRUE\s0\fR or \fB\s-1FALSE\s0\fR. Additionally \fB\s-1TRUE\s0\fR, \fBtrue\fR, \fBY\fR,
 178 \&\fBy\fR, \fB\s-1YES\s0\fR, \fByes\fR, \fB\s-1FALSE\s0\fR, \fBfalse\fR, \fBN\fR, \fBn\fR, \fB\s-1NO\s0\fR and \fBno\fR
 179 are acceptable.
 180 .IP "\fB\s-1NULL\s0\fR" 2
 181 .IX Item "NULL"
 182 Encode the \fB\s-1NULL\s0\fR type, the \fBvalue\fR string must not be present.
 183 .IP "\fB\s-1INTEGER\s0\fR, \fB\s-1INT\s0\fR" 2
 184 .IX Item "INTEGER, INT"
 185 Encodes an \s-1ASN1 \s0\fB\s-1INTEGER\s0\fR type. The \fBvalue\fR string represents
 186 the value of the integer, it can be prefaced by a minus sign and
 187 is normally interpreted as a decimal value unless the prefix \fB0x\fR
 188 is included.
 189 .IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 2
 190 .IX Item "ENUMERATED, ENUM"
 191 Encodes the \s-1ASN1 \s0\fB\s-1ENUMERATED\s0\fR type, it is otherwise identical to
 192 \&\fB\s-1INTEGER\s0\fR.
 193 .IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 2
 194 .IX Item "OBJECT, OID"
 195 Encodes an \s-1ASN1 \s0\fB\s-1OBJECT IDENTIFIER\s0\fR, the \fBvalue\fR string can be
 196 a short name, a long name or numerical format.
 197 .IP "\fB\s-1UTCTIME\s0\fR, \fB\s-1UTC\s0\fR" 2
 198 .IX Item "UTCTIME, UTC"
 199 Encodes an \s-1ASN1 \s0\fBUTCTime\fR structure, the value should be in
 200 the format \fB\s-1YYMMDDHHMMSSZ\s0\fR.
 201 .IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 2
 202 .IX Item "GENERALIZEDTIME, GENTIME"
 203 Encodes an \s-1ASN1 \s0\fBGeneralizedTime\fR structure, the value should be in
 204 the format \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
 205 .IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 2
 206 .IX Item "OCTETSTRING, OCT"
 207 Encodes an \s-1ASN1 \s0\fB\s-1OCTET STRING\s0\fR. \fBvalue\fR represents the contents
 208 of this structure, the format strings \fB\s-1ASCII\s0\fR and \fB\s-1HEX\s0\fR can be
 209 used to specify the format of \fBvalue\fR.
 210 .IP "\fB\s-1BITSTRING\s0\fR, \fB\s-1BITSTR\s0\fR" 2
 211 .IX Item "BITSTRING, BITSTR"
 212 Encodes an \s-1ASN1 \s0\fB\s-1BIT STRING\s0\fR. \fBvalue\fR represents the contents
 213 of this structure, the format strings \fB\s-1ASCII\s0\fR, \fB\s-1HEX\s0\fR and \fB\s-1BITLIST\s0\fR
 214 can be used to specify the format of \fBvalue\fR.
 215 .Sp
 216 If the format is anything other than \fB\s-1BITLIST\s0\fR the number of unused
 217 bits is set to zero.
 218 .IP "\fB\s-1UNIVERSALSTRING\s0\fR, \fB\s-1UNIV\s0\fR, \fB\s-1IA5\s0\fR, \fB\s-1IA5STRING\s0\fR, \fB\s-1UTF8\s0\fR, \fBUTF8String\fR, \fB\s-1BMP\s0\fR, \fB\s-1BMPSTRING\s0\fR, \fB\s-1VISIBLESTRING\s0\fR, \fB\s-1VISIBLE\s0\fR, \fB\s-1PRINTABLESTRING\s0\fR, \fB\s-1PRINTABLE\s0\fR, \fBT61\fR, \fBT61STRING\fR, \fB\s-1TELETEXSTRING\s0\fR, \fBGeneralString\fR, \fB\s-1NUMERICSTRING\s0\fR, \fB\s-1NUMERIC\s0\fR" 2
 219 .IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString, NUMERICSTRING, NUMERIC"
 220 These encode the corresponding string types. \fBvalue\fR represents the
 221 contents of this structure. The format can be \fB\s-1ASCII\s0\fR or \fB\s-1UTF8\s0\fR.
 222 .IP "\fB\s-1SEQUENCE\s0\fR, \fB\s-1SEQ\s0\fR, \fB\s-1SET\s0\fR" 2
 223 .IX Item "SEQUENCE, SEQ, SET"
 224 Formats the result as an \s-1ASN1 \s0\fB\s-1SEQUENCE\s0\fR or \fB\s-1SET\s0\fR type. \fBvalue\fR
 225 should be a section name which will contain the contents. The
 226 field names in the section are ignored and the values are in the
 227 generated string format. If \fBvalue\fR is absent then an empty \s-1SEQUENCE\s0
 228 will be encoded.
 229 .SS "\s-1MODIFIERS\s0"
 230 .IX Subsection "MODIFIERS"
 231 Modifiers affect the following structure, they can be used to
 232 add \s-1EXPLICIT\s0 or \s-1IMPLICIT\s0 tagging, add wrappers or to change
 233 the string format of the final type and value. The supported
 234 formats are documented below.
 235 .IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 2
 236 .IX Item "EXPLICIT, EXP"
 237 Add an explicit tag to the following structure. This string
 238 should be followed by a colon and the tag value to use as a
 239 decimal value.
 240 .Sp
 241 By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR \s-1UNIVERSAL,
 242 APPLICATION, PRIVATE\s0 or \s-1CONTEXT SPECIFIC\s0 tagging can be used,
 243 the default is \s-1CONTEXT SPECIFIC.\s0
 244 .IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 2
 245 .IX Item "IMPLICIT, IMP"
 246 This is the same as \fB\s-1EXPLICIT\s0\fR except \s-1IMPLICIT\s0 tagging is used
 247 instead.
 248 .IP "\fB\s-1OCTWRAP\s0\fR, \fB\s-1SEQWRAP\s0\fR, \fB\s-1SETWRAP\s0\fR, \fB\s-1BITWRAP\s0\fR" 2
 249 .IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP"
 250 The following structure is surrounded by an \s-1OCTET STRING,\s0 a \s-1SEQUENCE,\s0
 251 a \s-1SET\s0 or a \s-1BIT STRING\s0 respectively. For a \s-1BIT STRING\s0 the number of unused
 252 bits is set to zero.
 253 .IP "\fB\s-1FORMAT\s0\fR" 2
 254 .IX Item "FORMAT"
 255 This specifies the format of the ultimate value. It should be followed
 256 by a colon and one of the strings \fB\s-1ASCII\s0\fR, \fB\s-1UTF8\s0\fR, \fB\s-1HEX\s0\fR or \fB\s-1BITLIST\s0\fR.
 257 .Sp
 258 If no format specifier is included then \fB\s-1ASCII\s0\fR is used. If \fB\s-1UTF8\s0\fR is
 259 specified then the value string must be a valid \fB\s-1UTF8\s0\fR string. For \fB\s-1HEX\s0\fR the
 260 output must be a set of hex digits. \fB\s-1BITLIST\s0\fR (which is only valid for a \s-1BIT
 261 STRING\s0) is a comma separated list of the indices of the set bits, all other
 262 bits are zero.
 263 .SH "EXAMPLES"
 264 .IX Header "EXAMPLES"
 265 A simple IA5String:
 266 .PP
 267 .Vb 1
 268 \& IA5STRING:Hello World
 269 .Ve
 270 .PP
 271 An IA5String explicitly tagged:
 272 .PP
 273 .Vb 1
 274 \& EXPLICIT:0,IA5STRING:Hello World
 275 .Ve
 276 .PP
 277 An IA5String explicitly tagged using \s-1APPLICATION\s0 tagging:
 278 .PP
 279 .Vb 1
 280 \& EXPLICIT:0A,IA5STRING:Hello World
 281 .Ve
 282 .PP
 283 A \s-1BITSTRING\s0 with bits 1 and 5 set and all others zero:
 284 .PP
 285 .Vb 1
 286 \& FORMAT:BITLIST,BITSTRING:1,5
 287 .Ve
 288 .PP
 289 A more complex example using a config file to produce a
 290 \&\s-1SEQUENCE\s0 consiting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
 291 .PP
 292 .Vb 1
 293 \& asn1 = SEQUENCE:seq_section
 294 \&
 295 \& [seq_section]
 296 \&
 297 \& field1 = BOOLEAN:TRUE
 298 \& field2 = OID:commonName
 299 \& field3 = UTF8:Third field
 300 .Ve
 301 .PP
 302 This example produces an RSAPrivateKey structure, this is the
 303 key contained in the file client.pem in all OpenSSL distributions
 304 (note: the field names such as 'coeff' are ignored and are present just
 305 for clarity):
 306 .PP
 307 .Vb 3
 308 \& asn1=SEQUENCE:private_key
 309 \& [private_key]
 310 \& version=INTEGER:0
 311 \&
 312 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
 313 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
 314 \&
 315 \& e=INTEGER:0x010001
 316 \&
 317 \& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
 318 \& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
 319 \&
 320 \& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
 321 \& D4BD57
 322 \&
 323 \& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
 324 \& 46EC4F
 325 \&
 326 \& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
 327 \& 9C0A39B9
 328 \&
 329 \& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
 330 \& E7B2458F
 331 \&
 332 \& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
 333 \& 628657053A
 334 .Ve
 335 .PP
 336 This example is the corresponding public key in a SubjectPublicKeyInfo
 337 structure:
 338 .PP
 339 .Vb 2
 340 \& # Start with a SEQUENCE
 341 \& asn1=SEQUENCE:pubkeyinfo
 342 \&
 343 \& # pubkeyinfo contains an algorithm identifier and the public key wrapped
 344 \& # in a BIT STRING
 345 \& [pubkeyinfo]
 346 \& algorithm=SEQUENCE:rsa_alg
 347 \& pubkey=BITWRAP,SEQUENCE:rsapubkey
 348 \&
 349 \& # algorithm ID for RSA is just an OID and a NULL
 350 \& [rsa_alg]
 351 \& algorithm=OID:rsaEncryption
 352 \& parameter=NULL
 353 \&
 354 \& # Actual public key: modulus and exponent
 355 \& [rsapubkey]
 356 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
 357 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
 358 \&
 359 \& e=INTEGER:0x010001
 360 .Ve
 361 .SH "RETURN VALUES"
 362 .IX Header "RETURN VALUES"
 363 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR return the encoded
 364 data as an \fB\s-1ASN1_TYPE\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred.
 365 .PP
 366 The error codes that can be obtained by \fIERR_get_error\fR\|(3).
 367 .SH "SEE ALSO"
 368 .IX Header "SEE ALSO"
 369 \&\fIERR_get_error\fR\|(3)
 370 .SH "HISTORY"
 371 .IX Header "HISTORY"
 372 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR were added to OpenSSL 0.9.8