secure/lib/libcrypto/man/ASN1_generate_nconf.3

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