lib/libcrypto/man/d2i_ASN1_OCTET_STRING.3

   1 .\"     $OpenBSD: d2i_ASN1_OCTET_STRING.3,v 1.5 2017/08/01 14:57:03 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: August 1 2017 $
  18 .Dt D2I_ASN1_OCTET_STRING 3
  19 .Os
  20 .Sh NAME
  21 .Nm d2i_ASN1_OCTET_STRING ,
  22 .Nm i2d_ASN1_OCTET_STRING ,
  23 .Nm d2i_ASN1_BIT_STRING ,
  24 .Nm i2d_ASN1_BIT_STRING ,
  25 .Nm d2i_ASN1_INTEGER ,
  26 .Nm i2d_ASN1_INTEGER ,
  27 .Nm d2i_ASN1_UINTEGER ,
  28 .Nm d2i_ASN1_ENUMERATED ,
  29 .Nm i2d_ASN1_ENUMERATED ,
  30 .Nm d2i_ASN1_UTF8STRING ,
  31 .Nm i2d_ASN1_UTF8STRING ,
  32 .Nm d2i_ASN1_IA5STRING ,
  33 .Nm i2d_ASN1_IA5STRING ,
  34 .Nm d2i_ASN1_UNIVERSALSTRING ,
  35 .Nm i2d_ASN1_UNIVERSALSTRING ,
  36 .Nm d2i_ASN1_BMPSTRING ,
  37 .Nm i2d_ASN1_BMPSTRING ,
  38 .Nm d2i_ASN1_GENERALSTRING ,
  39 .Nm i2d_ASN1_GENERALSTRING ,
  40 .Nm d2i_ASN1_T61STRING ,
  41 .Nm i2d_ASN1_T61STRING ,
  42 .Nm d2i_ASN1_VISIBLESTRING ,
  43 .Nm i2d_ASN1_VISIBLESTRING ,
  44 .Nm d2i_ASN1_PRINTABLESTRING ,
  45 .Nm i2d_ASN1_PRINTABLESTRING ,
  46 .Nm d2i_ASN1_PRINTABLE ,
  47 .Nm i2d_ASN1_PRINTABLE ,
  48 .Nm d2i_DIRECTORYSTRING ,
  49 .Nm i2d_DIRECTORYSTRING ,
  50 .Nm d2i_DISPLAYTEXT ,
  51 .Nm i2d_DISPLAYTEXT ,
  52 .Nm d2i_ASN1_GENERALIZEDTIME ,
  53 .Nm i2d_ASN1_GENERALIZEDTIME ,
  54 .Nm d2i_ASN1_UTCTIME ,
  55 .Nm i2d_ASN1_UTCTIME ,
  56 .Nm d2i_ASN1_TIME ,
  57 .Nm i2d_ASN1_TIME
  58 .Nd decode and encode ASN1_STRING objects
  59 .Sh SYNOPSIS
  60 .In openssl/asn1.h
  61 .Ft ASN1_OCTET_STRING *
  62 .Fo d2i_ASN1_OCTET_STRING
  63 .Fa "ASN1_OCTET_STRING **val_out"
  64 .Fa "const unsigned char **der_in"
  65 .Fa "long length"
  66 .Fc
  67 .Ft int
  68 .Fo i2d_ASN1_OCTET_STRING
  69 .Fa "ASN1_OCTET_STRING *val_in"
  70 .Fa "unsigned char **der_out"
  71 .Fc
  72 .Ft ASN1_BIT_STRING *
  73 .Fo d2i_ASN1_BIT_STRING
  74 .Fa "ASN1_BIT_STRING **val_out"
  75 .Fa "const unsigned char **der_in"
  76 .Fa "long length"
  77 .Fc
  78 .Ft int
  79 .Fo i2d_ASN1_BIT_STRING
  80 .Fa "ASN1_BIT_STRING *val_in"
  81 .Fa "unsigned char **der_out"
  82 .Fc
  83 .Ft ASN1_INTEGER *
  84 .Fo d2i_ASN1_INTEGER
  85 .Fa "ASN1_INTEGER **val_out"
  86 .Fa "const unsigned char **der_in"
  87 .Fa "long length"
  88 .Fc
  89 .Ft int
  90 .Fo i2d_ASN1_INTEGER
  91 .Fa "ASN1_INTEGER *val_in"
  92 .Fa "unsigned char **der_out"
  93 .Fc
  94 .Ft ASN1_INTEGER *
  95 .Fo d2i_ASN1_UINTEGER
  96 .Fa "ASN1_INTEGER **val_out"
  97 .Fa "const unsigned char **der_in"
  98 .Fa "long length"
  99 .Fc
 100 .Ft ASN1_ENUMERATED *
 101 .Fo d2i_ASN1_ENUMERATED
 102 .Fa "ASN1_ENUMERATED **val_out"
 103 .Fa "const unsigned char **der_in"
 104 .Fa "long length"
 105 .Fc
 106 .Ft int
 107 .Fo i2d_ASN1_ENUMERATED
 108 .Fa "ASN1_ENUMERATED *val_in"
 109 .Fa "unsigned char **der_out"
 110 .Fc
 111 .Ft ASN1_UTF8STRING *
 112 .Fo d2i_ASN1_UTF8STRING
 113 .Fa "ASN1_UTF8STRING **val_out"
 114 .Fa "const unsigned char **der_in"
 115 .Fa "long length"
 116 .Fc
 117 .Ft int
 118 .Fo i2d_ASN1_UTF8STRING
 119 .Fa "ASN1_UTF8STRING *val_in"
 120 .Fa "unsigned char **der_out"
 121 .Fc
 122 .Ft ASN1_IA5STRING *
 123 .Fo d2i_ASN1_IA5STRING
 124 .Fa "ASN1_IA5STRING **val_out"
 125 .Fa "const unsigned char **der_in"
 126 .Fa "long length"
 127 .Fc
 128 .Ft int
 129 .Fo i2d_ASN1_IA5STRING
 130 .Fa "ASN1_IA5STRING *val_in"
 131 .Fa "unsigned char **der_out"
 132 .Fc
 133 .Ft ASN1_UNIVERSALSTRING *
 134 .Fo d2i_ASN1_UNIVERSALSTRING
 135 .Fa "ASN1_UNIVERSALSTRING **val_out"
 136 .Fa "const unsigned char **der_in"
 137 .Fa "long length"
 138 .Fc
 139 .Ft int
 140 .Fo i2d_ASN1_UNIVERSALSTRING
 141 .Fa "ASN1_UNIVERSALSTRING *val_in"
 142 .Fa "unsigned char **der_out"
 143 .Fc
 144 .Ft ASN1_BMPSTRING *
 145 .Fo d2i_ASN1_BMPSTRING
 146 .Fa "ASN1_BMPSTRING **val_out"
 147 .Fa "const unsigned char **der_in"
 148 .Fa "long length"
 149 .Fc
 150 .Ft int
 151 .Fo i2d_ASN1_BMPSTRING
 152 .Fa "ASN1_BMPSTRING *val_in"
 153 .Fa "unsigned char **der_out"
 154 .Fc
 155 .Ft ASN1_GENERALSTRING *
 156 .Fo d2i_ASN1_GENERALSTRING
 157 .Fa "ASN1_GENERALSTRING **val_out"
 158 .Fa "const unsigned char **der_in"
 159 .Fa "long length"
 160 .Fc
 161 .Ft int
 162 .Fo i2d_ASN1_GENERALSTRING
 163 .Fa "ASN1_GENERALSTRING *val_in"
 164 .Fa "unsigned char **der_out"
 165 .Fc
 166 .Ft ASN1_T61STRING *
 167 .Fo d2i_ASN1_T61STRING
 168 .Fa "ASN1_T61STRING **val_out"
 169 .Fa "const unsigned char **der_in"
 170 .Fa "long length"
 171 .Fc
 172 .Ft int
 173 .Fo i2d_ASN1_T61STRING
 174 .Fa "ASN1_T61STRING *val_in"
 175 .Fa "unsigned char **der_out"
 176 .Fc
 177 .Ft ASN1_VISIBLESTRING *
 178 .Fo d2i_ASN1_VISIBLESTRING
 179 .Fa "ASN1_VISIBLESTRING **val_out"
 180 .Fa "const unsigned char **der_in"
 181 .Fa "long length"
 182 .Fc
 183 .Ft int
 184 .Fo i2d_ASN1_VISIBLESTRING
 185 .Fa "ASN1_VISIBLESTRING *val_in"
 186 .Fa "unsigned char **der_out"
 187 .Fc
 188 .Ft ASN1_PRINTABLESTRING *
 189 .Fo d2i_ASN1_PRINTABLESTRING
 190 .Fa "ASN1_PRINTABLESTRING **val_out"
 191 .Fa "const unsigned char **der_in"
 192 .Fa "long length"
 193 .Fc
 194 .Ft int
 195 .Fo i2d_ASN1_PRINTABLESTRING
 196 .Fa "ASN1_PRINTABLESTRING *val_in"
 197 .Fa "unsigned char **der_out"
 198 .Fc
 199 .Ft ASN1_STRING *
 200 .Fo d2i_ASN1_PRINTABLE
 201 .Fa "ASN1_STRING **val_out"
 202 .Fa "const unsigned char **der_in"
 203 .Fa "long length"
 204 .Fc
 205 .Ft int
 206 .Fo i2d_ASN1_PRINTABLE
 207 .Fa "ASN1_STRING *val_in"
 208 .Fa "unsigned char **der_out"
 209 .Fc
 210 .Ft ASN1_STRING *
 211 .Fo d2i_DIRECTORYSTRING
 212 .Fa "ASN1_STRING **val_out"
 213 .Fa "const unsigned char **der_in"
 214 .Fa "long length"
 215 .Fc
 216 .Ft int
 217 .Fo i2d_DIRECTORYSTRING
 218 .Fa "ASN1_STRING *val_in"
 219 .Fa "unsigned char **der_out"
 220 .Fc
 221 .Ft ASN1_STRING *
 222 .Fo d2i_DISPLAYTEXT
 223 .Fa "ASN1_STRING **val_out"
 224 .Fa "const unsigned char **der_in"
 225 .Fa "long length"
 226 .Fc
 227 .Ft int
 228 .Fo i2d_DISPLAYTEXT
 229 .Fa "ASN1_STRING *val_in"
 230 .Fa "unsigned char **der_out"
 231 .Fc
 232 .Ft ASN1_GENERALIZEDTIME *
 233 .Fo d2i_ASN1_GENERALIZEDTIME
 234 .Fa "ASN1_GENERALIZEDTIME **val_out"
 235 .Fa "const unsigned char **der_in"
 236 .Fa "long length"
 237 .Fc
 238 .Ft int
 239 .Fo i2d_ASN1_GENERALIZEDTIME
 240 .Fa "ASN1_GENERALIZEDTIME *val_in"
 241 .Fa "unsigned char **der_out"
 242 .Fc
 243 .Ft ASN1_UTCTIME *
 244 .Fo d2i_ASN1_UTCTIME
 245 .Fa "ASN1_UTCTIME **val_out"
 246 .Fa "const unsigned char **der_in"
 247 .Fa "long length"
 248 .Fc
 249 .Ft int
 250 .Fo i2d_ASN1_UTCTIME
 251 .Fa "ASN1_UTCTIME *val_in"
 252 .Fa "unsigned char **der_out"
 253 .Fc
 254 .Ft ASN1_TIME *
 255 .Fo d2i_ASN1_TIME
 256 .Fa "ASN1_TIME **val_out"
 257 .Fa "const unsigned char **der_in"
 258 .Fa "long length"
 259 .Fc
 260 .Ft int
 261 .Fo i2d_ASN1_TIME
 262 .Fa "ASN1_TIME *val_in"
 263 .Fa "unsigned char **der_out"
 264 .Fc
 265 .Sh DESCRIPTION
 266 These functions decode and encode various ASN.1 built-in types
 267 that can be represented by
 268 .Vt ASN1_STRING
 269 objects.
 270 For details about the semantics, examples, caveats, and bugs, see
 271 .Xr ASN1_item_d2i 3 .
 272 .Pp
 273 The format consists of one identifier octet,
 274 one or more length octets,
 275 and one or more content octets.
 276 The identifier octets and corresponding ASN.1 types are as follows:
 277 .Bl -column ASN1_GENERALIZEDTIME identifier
 278 .It Em OpenSSL type Ta Em identifier Ta Em ASN.1 type
 279 .It Ta
 280 .It Vt ASN1_OCTET_STRING    Ta 0x04 Ta OCTET STRING
 281 .It Vt ASN1_BIT_STRING      Ta 0x03 Ta BIT STRING
 282 .It Vt ASN1_INTEGER         Ta 0x02 Ta INTEGER
 283 .It Vt ASN1_ENUMERATED      Ta 0x0a Ta ENUMERATED
 284 .It Vt ASN1_UTF8STRING      Ta 0x0c Ta UTF8String
 285 .It Vt ASN1_IA5STRING       Ta 0x16 Ta IA5String
 286 .It Vt ASN1_UNIVERSALSTRING Ta 0x1c Ta UniversalString
 287 .It Vt ASN1_BMPSTRING       Ta 0x1e Ta BMPString
 288 .It Vt ASN1_GENERALSTRING   Ta 0x1b Ta GeneralString
 289 .It Vt ASN1_T61STRING       Ta 0x14 Ta T61String
 290 .It Vt ASN1_VISIBLESTRING   Ta 0x1a Ta VisibleString
 291 .It Vt ASN1_PRINTABLESTRING Ta 0x13 Ta PrintableString
 292 .It Vt ASN1_GENERALIZEDTIME Ta 0x18 Ta GeneralizedTime
 293 .It Vt ASN1_UTCTIME         Ta 0x17 Ta UTCTime
 294 .El
 295 .Pp
 296 .Fn d2i_DIRECTORYSTRING
 297 and
 298 .Fn i2d_DIRECTORYSTRING
 299 decode and encode an ASN.1
 300 .Vt DirectoryString
 301 structure defined in RFC 5280 section 4.1.2.4
 302 and used for ASN.1
 303 .Vt EDIPartyName
 304 structures; see
 305 .Xr EDIPARTYNAME_new 3 .
 306 When decoding, it accepts any of the types UTF8String, UniversalString,
 307 BMPString, T61String, or PrintableString.
 308 When encoding,
 309 it writes out the character string type that is actually passed in.
 310 .Pp
 311 .Fn d2i_ASN1_PRINTABLE
 312 and
 313 .Fn i2d_ASN1_PRINTABLE
 314 are non-standard variants of
 315 .Fn d2i_DIRECTORYSTRING
 316 and
 317 .Fn i2d_DIRECTORYSTRING
 318 that also accept IA5String, NumericString, BIT STRING, and SEQUENCE
 319 ASN.1 values as well as ASN.1 values with unknown identifier
 320 octets (0x07, 0x08, 0x09, 0x0b, 0x0d, 0x0e, 0x0f, 0x1d, and 0x1f).
 321 Even though the standard requires the use of
 322 .Vt DirectoryString
 323 in the relative distinguished names described in
 324 .Xr X509_NAME_ENTRY_new 3 ,
 325 the library accepts this wider range of choices.
 326 .Pp
 327 .Fn d2i_DISPLAYTEXT
 328 and
 329 .Fn i2d_DISPLAYTEXT
 330 decode and encode an ASN.1
 331 .Vt DisplayText
 332 structure defined in RFC 5280 section 4.2.1.4
 333 and used for ASN.1
 334 .Vt UserNotice
 335 structures in certificate policies; see
 336 .Xr USERNOTICE_new 3 .
 337 When decoding, it accepts any of the types UTF8String, IA5String,
 338 BMPString, or VisibleString.
 339 When encoding,
 340 it writes out the character string type that is actually passed in.
 341 .Pp
 342 .Fn d2i_ASN1_TIME
 343 and
 344 .Fn i2d_ASN1_TIME
 345 decode and encode an ASN.1
 346 .Vt Time
 347 structure defined in RFC 5280 section 4.1
 348 and used for ASN.1
 349 .Vt Validity
 350 structures in certificates; see
 351 .Xr X509_VAL_new 3 .
 352 They are also used for certificate revocation lists; see
 353 .Xr X509_CRL_INFO_new 3 .
 354 When decoding, it accepts either GeneralizedTime or UTCTime.
 355 When encoding, it writes out the time type that is actually passed in.
 356 .Pp
 357 .Fn d2i_ASN1_UINTEGER
 358 is similar to
 359 .Fn d2i_ASN1_INTEGER
 360 except that it ignores the sign bit in the BER encoding and treats
 361 all integers as positive.
 362 It helps to process BER input produced by broken software
 363 that neglects adding a leading NUL content byte where required.
 364 .Sh RETURN VALUES
 365 The
 366 .Fn d2i_*
 367 decoding functions return an
 368 .Vt ASN1_STRING
 369 object or
 370 .Dv NULL
 371 if an error occurs.
 372 .Pp
 373 The
 374 .Fn i2d_*
 375 encoding functions return the number of bytes successfully encoded
 376 or a negative value if an error occurs.
 377 .Sh SEE ALSO
 378 .Xr ASN1_item_d2i 3 ,
 379 .Xr ASN1_STRING_new 3
 380 .Sh STANDARDS
 381 ITU-T Recommendation X.680, also known as ISO/IEC 8824-1:
 382 Information technology - Abstract Syntax Notation One (ASN.1):
 383 Specification of basic notation
 384 .Pp
 385 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
 386 Certificate Revocation List (CRL) Profile