secure/lib/libcrypto/man/ASN1_generate_nconf.3

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