secure/lib/libcrypto/man/ASN1_generate_nconf.3

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