secure/lib/libcrypto/man/ASN1_generate_nconf.3

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  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 "2007-03-28" "0.9.8e" "OpenSSL"
 133 .SH "NAME"
 134 ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 generation functions
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \& ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
 139 \& ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
 140 .Ve
 141 .SH "DESCRIPTION"
 142 .IX Header "DESCRIPTION"
 143 These functions generate the \s-1ASN1\s0 encoding of a string
 144 in an \fB\s-1ASN1_TYPE\s0\fR structure.
 145 .PP
 146 \&\fBstr\fR contains the string to encode \fBnconf\fR or \fBcnf\fR contains
 147 the optional configuration information where additional strings
 148 will be read from. \fBnconf\fR will typically come from a config
 149 file wherease \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
 150 which will typically be used by X509 v3 certificate extension
 151 functions. \fBcnf\fR or \fBnconf\fR can be set to \fB\s-1NULL\s0\fR if no additional
 152 configuration will be used.
 153 .SH "GENERATION STRING FORMAT"
 154 .IX Header "GENERATION STRING FORMAT"
 155 The actual data encoded is determined by the string \fBstr\fR and
 156 the configuration information. The general format of the string
 157 is:
 158 .PP
 159 .Vb 1
 160 \& B<[modifier,]type[:value]>
 161 .Ve
 162 .PP
 163 That is zero or more comma separated modifiers followed by a type
 164 followed by an optional colon and a value. The formats of \fBtype\fR,
 165 \&\fBvalue\fR and \fBmodifier\fR are explained below.
 166 .Sh "\s-1SUPPORTED\s0 \s-1TYPES\s0"
 167 .IX Subsection "SUPPORTED TYPES"
 168 The supported types are listed below. Unless otherwise specified
 169 only the \fB\s-1ASCII\s0\fR format is permissible.
 170 .IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 2
 171 .IX Item "BOOLEAN, BOOL"
 172 This encodes a boolean type. The \fBvalue\fR string is mandatory and
 173 should be \fB\s-1TRUE\s0\fR or \fB\s-1FALSE\s0\fR. Additionally \fB\s-1TRUE\s0\fR, \fBtrue\fR, \fBY\fR,
 174 \&\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
 175 are acceptable.
 176 .IP "\fB\s-1NULL\s0\fR" 2
 177 .IX Item "NULL"
 178 Encode the \fB\s-1NULL\s0\fR type, the \fBvalue\fR string must not be present.
 179 .IP "\fB\s-1INTEGER\s0\fR, \fB\s-1INT\s0\fR" 2
 180 .IX Item "INTEGER, INT"
 181 Encodes an \s-1ASN1\s0 \fB\s-1INTEGER\s0\fR type. The \fBvalue\fR string represents
 182 the value of the integer, it can be preceeded by a minus sign and
 183 is normally interpreted as a decimal value unless the prefix \fB0x\fR
 184 is included.
 185 .IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 2
 186 .IX Item "ENUMERATED, ENUM"
 187 Encodes the \s-1ASN1\s0 \fB\s-1ENUMERATED\s0\fR type, it is otherwise identical to
 188 \&\fB\s-1INTEGER\s0\fR.
 189 .IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 2
 190 .IX Item "OBJECT, OID"
 191 Encodes an \s-1ASN1\s0 \fB\s-1OBJECT\s0 \s-1IDENTIFIER\s0\fR, the \fBvalue\fR string can be
 192 a short name, a long name or numerical format.
 193 .IP "\fB\s-1UTCTIME\s0\fR, \fB\s-1UTC\s0\fR" 2
 194 .IX Item "UTCTIME, UTC"
 195 Encodes an \s-1ASN1\s0 \fBUTCTime\fR structure, the value should be in
 196 the format \fB\s-1YYMMDDHHMMSSZ\s0\fR.
 197 .IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 2
 198 .IX Item "GENERALIZEDTIME, GENTIME"
 199 Encodes an \s-1ASN1\s0 \fBGeneralizedTime\fR structure, the value should be in
 200 the format \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
 201 .IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 2
 202 .IX Item "OCTETSTRING, OCT"
 203 Emcodes an \s-1ASN1\s0 \fB\s-1OCTET\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
 204 of this structure, the format strings \fB\s-1ASCII\s0\fR and \fB\s-1HEX\s0\fR can be
 205 used to specify the format of \fBvalue\fR.
 206 .IP "\fB\s-1BITSRING\s0\fR, \fB\s-1BITSTR\s0\fR" 2
 207 .IX Item "BITSRING, BITSTR"
 208 Emcodes an \s-1ASN1\s0 \fB\s-1BIT\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
 209 of this structure, the format strings \fB\s-1ASCII\s0\fR, \fB\s-1HEX\s0\fR and \fB\s-1BITLIST\s0\fR
 210 can be used to specify the format of \fBvalue\fR.
 211 .Sp
 212 If the format is anything other than \fB\s-1BITLIST\s0\fR the number of unused
 213 bits is set to zero.
 214 .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" 2
 215 .IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString"
 216 These encode the corresponding string types. \fBvalue\fR represents the
 217 contents of this structure. The format can be \fB\s-1ASCII\s0\fR or \fB\s-1UTF8\s0\fR.
 218 .IP "\fB\s-1SEQUENCE\s0\fR, \fB\s-1SEQ\s0\fR, \fB\s-1SET\s0\fR" 2
 219 .IX Item "SEQUENCE, SEQ, SET"
 220 Formats the result as an \s-1ASN1\s0 \fB\s-1SEQUENCE\s0\fR or \fB\s-1SET\s0\fR type. \fBvalue\fR
 221 should be a section name which will contain the contents. The
 222 field names in the section are ignored and the values are in the
 223 generated string format. If \fBvalue\fR is absent then an empty \s-1SEQUENCE\s0
 224 will be encoded.
 225 .Sh "\s-1MODIFIERS\s0"
 226 .IX Subsection "MODIFIERS"
 227 Modifiers affect the following structure, they can be used to
 228 add \s-1EXPLICIT\s0 or \s-1IMPLICIT\s0 tagging, add wrappers or to change
 229 the string format of the final type and value. The supported
 230 formats are documented below.
 231 .IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 2
 232 .IX Item "EXPLICIT, EXP"
 233 Add an explicit tag to the following structure. This string
 234 should be followed by a colon and the tag value to use as a
 235 decimal value.
 236 .Sp
 237 By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR \s-1UNIVERSAL\s0,
 238 \&\s-1APPLICATION\s0, \s-1PRIVATE\s0 or \s-1CONTEXT\s0 \s-1SPECIFIC\s0 tagging can be used,
 239 the default is \s-1CONTEXT\s0 \s-1SPECIFIC\s0.
 240 .IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 2
 241 .IX Item "IMPLICIT, IMP"
 242 This is the same as \fB\s-1EXPLICIT\s0\fR except \s-1IMPLICIT\s0 tagging is used
 243 instead.
 244 .IP "\fB\s-1OCTWRAP\s0\fR, \fB\s-1SEQWRAP\s0\fR, \fB\s-1SETWRAP\s0\fR, \fB\s-1BITWRAP\s0\fR" 2
 245 .IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP"
 246 The following structure is surrounded by an \s-1OCTET\s0 \s-1STRING\s0, a \s-1SEQUENCE\s0,
 247 a \s-1SET\s0 or a \s-1BIT\s0 \s-1STRING\s0 respectively. For a \s-1BIT\s0 \s-1STRING\s0 the number of unused
 248 bits is set to zero.
 249 .IP "\fB\s-1FORMAT\s0\fR" 2
 250 .IX Item "FORMAT"
 251 This specifies the format of the ultimate value. It should be followed
 252 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.
 253 .Sp
 254 If no format specifier is included then \fB\s-1ASCII\s0\fR is used. If \fB\s-1UTF8\s0\fR is specified
 255 then the value string must be a valid \fB\s-1UTF8\s0\fR string. For \fB\s-1HEX\s0\fR the output must
 256 be a set of hex digits. \fB\s-1BITLIST\s0\fR (which is only valid for a \s-1BIT\s0 \s-1STRING\s0) is a
 257 comma separated list of set bits.
 258 .SH "EXAMPLES"
 259 .IX Header "EXAMPLES"
 260 A simple IA5String:
 261 .PP
 262 .Vb 1
 263 \& IA5STRING:Hello World
 264 .Ve
 265 .PP
 266 An IA5String explicitly tagged:
 267 .PP
 268 .Vb 1
 269 \& EXPLICIT:0,IA5STRING:Hello World
 270 .Ve
 271 .PP
 272 An IA5String explicitly tagged using \s-1APPLICATION\s0 tagging:
 273 .PP
 274 .Vb 1
 275 \& EXPLICIT:0A,IA5STRING:Hello World
 276 .Ve
 277 .PP
 278 A more complex example using a config file to produce a
 279 \&\s-1SEQUENCE\s0 consiting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
 280 .PP
 281 asn1 = SEQUENCE:seq_section
 282 .PP
 283 [seq_section]
 284 .PP
 285 field1 = \s-1BOOLEAN:TRUE\s0
 286 field2 = OID:commonName
 287 field3 = UTF8:Third field
 288 .PP
 289 This example produces an RSAPrivateKey structure, this is the
 290 key contained in the file client.pem in all OpenSSL distributions
 291 (note: the field names such as 'coeff' are ignored and are present just
 292 for clarity):
 293 .PP
 294 .Vb 3
 295 \& asn1=SEQUENCE:private_key
 296 \& [private_key]
 297 \& version=INTEGER:0
 298 .Ve
 299 .PP
 300 .Vb 2
 301 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
 302 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
 303 .Ve
 304 .PP
 305 .Vb 1
 306 \& e=INTEGER:0x010001
 307 .Ve
 308 .PP
 309 .Vb 2
 310 \& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
 311 \& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
 312 .Ve
 313 .PP
 314 .Vb 2
 315 \& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
 316 \& D4BD57
 317 .Ve
 318 .PP
 319 .Vb 2
 320 \& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
 321 \& 46EC4F
 322 .Ve
 323 .PP
 324 .Vb 2
 325 \& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
 326 \& 9C0A39B9
 327 .Ve
 328 .PP
 329 .Vb 2
 330 \& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
 331 \& E7B2458F
 332 .Ve
 333 .PP
 334 .Vb 2
 335 \& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
 336 \& 628657053A
 337 .Ve
 338 .PP
 339 This example is the corresponding public key in a SubjectPublicKeyInfo
 340 structure:
 341 .PP
 342 .Vb 2
 343 \& # Start with a SEQUENCE
 344 \& asn1=SEQUENCE:pubkeyinfo
 345 .Ve
 346 .PP
 347 .Vb 5
 348 \& # pubkeyinfo contains an algorithm identifier and the public key wrapped
 349 \& # in a BIT STRING
 350 \& [pubkeyinfo]
 351 \& algorithm=SEQUENCE:rsa_alg
 352 \& pubkey=BITWRAP,SEQUENCE:rsapubkey
 353 .Ve
 354 .PP
 355 .Vb 4
 356 \& # algorithm ID for RSA is just an OID and a NULL
 357 \& [rsa_alg]
 358 \& algorithm=OID:rsaEncryption
 359 \& parameter=NULL
 360 .Ve
 361 .PP
 362 .Vb 4
 363 \& # Actual public key: modulus and exponent
 364 \& [rsapubkey]
 365 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
 366 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
 367 .Ve
 368 .PP
 369 .Vb 1
 370 \& e=INTEGER:0x010001
 371 .Ve
 372 .SH "RETURN VALUES"
 373 .IX Header "RETURN VALUES"
 374 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR return the encoded
 375 data as an \fB\s-1ASN1_TYPE\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred.
 376 .PP
 377 The error codes that can be obtained by \fIERR_get_error\fR\|(3).
 378 .SH "SEE ALSO"
 379 .IX Header "SEE ALSO"
 380 \&\fIERR_get_error\fR\|(3)
 381 .SH "HISTORY"
 382 .IX Header "HISTORY"
 383 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR were added to OpenSSL 0.9.8