lib/libcrypto/man/d2i_PKCS7.3

   1 .\"     $OpenBSD: d2i_PKCS7.3,v 1.5 2018/03/21 00:54:31 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2016 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: March 21 2018 $
  18 .Dt D2I_PKCS7 3
  19 .Os
  20 .Sh NAME
  21 .Nm d2i_PKCS7 ,
  22 .Nm i2d_PKCS7 ,
  23 .Nm d2i_PKCS7_bio ,
  24 .Nm i2d_PKCS7_bio ,
  25 .Nm d2i_PKCS7_fp ,
  26 .Nm i2d_PKCS7_fp ,
  27 .Nm i2d_PKCS7_NDEF ,
  28 .Nm d2i_PKCS7_DIGEST ,
  29 .Nm i2d_PKCS7_DIGEST ,
  30 .Nm d2i_PKCS7_ENCRYPT ,
  31 .Nm i2d_PKCS7_ENCRYPT ,
  32 .Nm d2i_PKCS7_ENC_CONTENT ,
  33 .Nm i2d_PKCS7_ENC_CONTENT ,
  34 .Nm d2i_PKCS7_ENVELOPE ,
  35 .Nm i2d_PKCS7_ENVELOPE ,
  36 .Nm d2i_PKCS7_ISSUER_AND_SERIAL ,
  37 .Nm i2d_PKCS7_ISSUER_AND_SERIAL ,
  38 .Nm d2i_PKCS7_RECIP_INFO ,
  39 .Nm i2d_PKCS7_RECIP_INFO ,
  40 .Nm d2i_PKCS7_SIGNED ,
  41 .Nm i2d_PKCS7_SIGNED ,
  42 .Nm d2i_PKCS7_SIGNER_INFO ,
  43 .Nm i2d_PKCS7_SIGNER_INFO ,
  44 .Nm d2i_PKCS7_SIGN_ENVELOPE ,
  45 .Nm i2d_PKCS7_SIGN_ENVELOPE
  46 .Nd decode and encode PKCS#7 data structures
  47 .Sh SYNOPSIS
  48 .In openssl/pkcs7.h
  49 .Ft PKCS7 *
  50 .Fo d2i_PKCS7
  51 .Fa "PKCS7 **val_out"
  52 .Fa "const unsigned char **der_in"
  53 .Fa "long length"
  54 .Fc
  55 .Ft int
  56 .Fo i2d_PKCS7
  57 .Fa "PKCS7 *val_in"
  58 .Fa "unsigned char **der_out"
  59 .Fc
  60 .Ft PKCS7 *
  61 .Fo d2i_PKCS7_bio
  62 .Fa "BIO *in_bio"
  63 .Fa "PKCS7 **val_out"
  64 .Fc
  65 .Ft int
  66 .Fo i2d_PKCS7_bio
  67 .Fa "BIO *out_bio"
  68 .Fa "PKCS7 *val_in"
  69 .Fc
  70 .Ft PKCS7 *
  71 .Fo d2i_PKCS7_fp
  72 .Fa "FILE *in_fp"
  73 .Fa "PKCS7 **val_out"
  74 .Fc
  75 .Ft int
  76 .Fo i2d_PKCS7_fp
  77 .Fa "FILE *out_fp"
  78 .Fa "PKCS7 *val_in"
  79 .Fc
  80 .Ft int
  81 .Fo i2d_PKCS7_NDEF
  82 .Fa "PKCS7 *val_in"
  83 .Fa "unsigned char **ber_out"
  84 .Fc
  85 .Ft PKCS7_DIGEST *
  86 .Fo d2i_PKCS7_DIGEST
  87 .Fa "PKCS7_DIGEST **val_out"
  88 .Fa "const unsigned char **der_in"
  89 .Fa "long length"
  90 .Fc
  91 .Ft int
  92 .Fo i2d_PKCS7_DIGEST
  93 .Fa "PKCS7_DIGEST *val_in"
  94 .Fa "unsigned char **der_out"
  95 .Fc
  96 .Ft PKCS7_ENCRYPT *
  97 .Fo d2i_PKCS7_ENCRYPT
  98 .Fa "PKCS7_ENCRYPT **val_out"
  99 .Fa "const unsigned char **der_in"
 100 .Fa "long length"
 101 .Fc
 102 .Ft int
 103 .Fo i2d_PKCS7_ENCRYPT
 104 .Fa "PKCS7_ENCRYPT *val_in"
 105 .Fa "unsigned char **der_out"
 106 .Fc
 107 .Ft PKCS7_ENC_CONTENT *
 108 .Fo d2i_PKCS7_ENC_CONTENT
 109 .Fa "PKCS7_ENC_CONTENT **val_out"
 110 .Fa "const unsigned char **der_in"
 111 .Fa "long length"
 112 .Fc
 113 .Ft int
 114 .Fo i2d_PKCS7_ENC_CONTENT
 115 .Fa "PKCS7_ENC_CONTENT *val_in"
 116 .Fa "unsigned char **der_out"
 117 .Fc
 118 .Ft PKCS7_ENVELOPE *
 119 .Fo d2i_PKCS7_ENVELOPE
 120 .Fa "PKCS7_ENVELOPE **val_out"
 121 .Fa "const unsigned char **der_in"
 122 .Fa "long length"
 123 .Fc
 124 .Ft int
 125 .Fo i2d_PKCS7_ENVELOPE
 126 .Fa "PKCS7_ENVELOPE *val_in"
 127 .Fa "unsigned char **der_out"
 128 .Fc
 129 .Ft PKCS7_ISSUER_AND_SERIAL *
 130 .Fo d2i_PKCS7_ISSUER_AND_SERIAL
 131 .Fa "PKCS7_ISSUER_AND_SERIAL **val_out"
 132 .Fa "const unsigned char **der_in"
 133 .Fa "long length"
 134 .Fc
 135 .Ft int
 136 .Fo i2d_PKCS7_ISSUER_AND_SERIAL
 137 .Fa "PKCS7_ISSUER_AND_SERIAL *val_in"
 138 .Fa "unsigned char **der_out"
 139 .Fc
 140 .Ft PKCS7_RECIP_INFO *
 141 .Fo d2i_PKCS7_RECIP_INFO
 142 .Fa "PKCS7_RECIP_INFO **val_out"
 143 .Fa "const unsigned char **der_in"
 144 .Fa "long length"
 145 .Fc
 146 .Ft int
 147 .Fo i2d_PKCS7_RECIP_INFO
 148 .Fa "PKCS7_RECIP_INFO *val_in"
 149 .Fa "unsigned char **der_out"
 150 .Fc
 151 .Ft PKCS7_SIGNED *
 152 .Fo d2i_PKCS7_SIGNED
 153 .Fa "PKCS7_SIGNED **val_out"
 154 .Fa "const unsigned char **der_in"
 155 .Fa "long length"
 156 .Fc
 157 .Ft int
 158 .Fo i2d_PKCS7_SIGNED
 159 .Fa "PKCS7_SIGNED *val_in"
 160 .Fa "unsigned char **der_out"
 161 .Fc
 162 .Ft PKCS7_SIGNER_INFO *
 163 .Fo d2i_PKCS7_SIGNER_INFO
 164 .Fa "PKCS7_SIGNER_INFO **val_out"
 165 .Fa "const unsigned char **der_in"
 166 .Fa "long length"
 167 .Fc
 168 .Ft int
 169 .Fo i2d_PKCS7_SIGNER_INFO
 170 .Fa "PKCS7_SIGNER_INFO *val_in"
 171 .Fa "unsigned char **der_out"
 172 .Fc
 173 .Ft PKCS7_SIGN_ENVELOPE *
 174 .Fo d2i_PKCS7_SIGN_ENVELOPE
 175 .Fa "PKCS7_SIGN_ENVELOPE **val_out"
 176 .Fa "const unsigned char **der_in"
 177 .Fa "long length"
 178 .Fc
 179 .Ft int
 180 .Fo i2d_PKCS7_SIGN_ENVELOPE
 181 .Fa "PKCS7_SIGN_ENVELOPE *val_in"
 182 .Fa "unsigned char **der_out"
 183 .Fc
 184 .Sh DESCRIPTION
 185 These functions decode and encode PKCS#7 data structures.
 186 For details about the semantics, examples, caveats, and bugs, see
 187 .Xr ASN1_item_d2i 3 .
 188 .Pp
 189 .Fn d2i_PKCS7
 190 and
 191 .Fn i2d_PKCS7
 192 decode and encode an ASN.1
 193 .Vt ContentInfo
 194 structure defined in RFC 2315 section 7.
 195 .Fn d2i_PKCS7_bio ,
 196 .Fn i2d_PKCS7_bio ,
 197 .Fn d2i_PKCS7_fp ,
 198 and
 199 .Fn i2d_PKCS7_fp
 200 are similar except that they decode or encode using a
 201 .Vt BIO
 202 or
 203 .Vt FILE
 204 pointer.
 205 .Pp
 206 .Fn i2d_PKCS7_NDEF
 207 is similar to
 208 .Fn i2d_PKCS7
 209 except that it encodes using BER rather than DER, using the indefinite
 210 length form where appropriate.
 211 .Pp
 212 .Fn d2i_PKCS7_DIGEST
 213 and
 214 .Fn i2d_PKCS7_DIGEST
 215 decode and encode an ASN.1
 216 .Vt DigestedData
 217 structure defined in RFC 2315 section 12.
 218 .Pp
 219 .Fn d2i_PKCS7_ENCRYPT
 220 and
 221 .Fn i2d_PKCS7_ENCRYPT
 222 decode and encode an ASN.1
 223 .Vt EncryptedData
 224 structure defined in RFC 2315 section 13.
 225 .Pp
 226 .Fn d2i_PKCS7_ENC_CONTENT
 227 and
 228 .Fn i2d_PKCS7_ENC_CONTENT
 229 decode and encode an ASN.1
 230 .Vt EncryptedContentInfo
 231 structure defined in RFC 2315 section 10.1.
 232 .Pp
 233 .Fn d2i_PKCS7_ENVELOPE
 234 and
 235 .Fn i2d_PKCS7_ENVELOPE
 236 decode and encode an ASN.1
 237 .Vt EnvelopedData
 238 structure defined in RFC 2315 section 10.
 239 .Pp
 240 .Fn d2i_PKCS7_ISSUER_AND_SERIAL
 241 and
 242 .Fn i2d_PKCS7_ISSUER_AND_SERIAL
 243 decode and encode an ASN.1
 244 .Vt IssuerAndSerialNumber
 245 structure defined in RFC 2315 section 6.7.
 246 .Pp
 247 .Fn d2i_PKCS7_RECIP_INFO
 248 and
 249 .Fn i2d_PKCS7_RECIP_INFO
 250 decode and encode an ASN.1
 251 .Vt RecipientInfo
 252 structure defined in RFC 2315 section 10.2.
 253 .Pp
 254 .Fn d2i_PKCS7_SIGNED
 255 and
 256 .Fn i2d_PKCS7_SIGNED
 257 decode and encode an ASN.1
 258 .Vt SignedData
 259 structure defined in RFC 2315 section 9.
 260 .Pp
 261 .Fn d2i_PKCS7_SIGNER_INFO
 262 and
 263 .Fn i2d_PKCS7_SIGNER_INFO
 264 decode and encode an ASN.1
 265 .Vt SignerInfo
 266 structure defined in RFC 2315 section 9.2.
 267 .Pp
 268 .Fn d2i_PKCS7_SIGN_ENVELOPE
 269 and
 270 .Fn i2d_PKCS7_SIGN_ENVELOPE
 271 decode and encode an ASN.1
 272 .Vt SignedAndEnvelopedData
 273 structure defined in RFC 2315 section 11.
 274 .Sh RETURN VALUES
 275 .Fn d2i_PKCS7 ,
 276 .Fn d2i_PKCS7_bio ,
 277 and
 278 .Fn d2i_PKCS7_fp
 279 return a
 280 .Vt PKCS7
 281 object or
 282 .Dv NULL
 283 if an error occurs.
 284 .Pp
 285 .Fn d2i_PKCS7_DIGEST ,
 286 .Fn d2i_PKCS7_ENCRYPT ,
 287 .Fn d2i_PKCS7_ENC_CONTENT ,
 288 .Fn d2i_PKCS7_ENVELOPE ,
 289 .Fn d2i_PKCS7_ISSUER_AND_SERIAL ,
 290 .Fn d2i_PKCS7_RECIP_INFO ,
 291 .Fn d2i_PKCS7_SIGNED ,
 292 .Fn d2i_PKCS7_SIGNER_INFO ,
 293 and
 294 .Fn d2i_PKCS7_SIGN_ENVELOPE
 295 return an object of the respective type or
 296 .Dv NULL
 297 if an error occurs.
 298 .Pp
 299 .Fn i2d_PKCS7 ,
 300 .Fn i2d_PKCS7_NDEF ,
 301 .Fn i2d_PKCS7_DIGEST ,
 302 .Fn i2d_PKCS7_ENCRYPT ,
 303 .Fn i2d_PKCS7_ENC_CONTENT ,
 304 .Fn i2d_PKCS7_ENVELOPE ,
 305 .Fn i2d_PKCS7_ISSUER_AND_SERIAL ,
 306 .Fn i2d_PKCS7_RECIP_INFO ,
 307 .Fn i2d_PKCS7_SIGNED ,
 308 .Fn i2d_PKCS7_SIGNER_INFO ,
 309 and
 310 .Fn i2d_PKCS7_SIGN_ENVELOPE
 311 return the number of bytes successfully encoded or a negative value
 312 if an error occurs.
 313 .Pp
 314 .Fn i2d_PKCS7_bio
 315 and
 316 .Fn i2d_PKCS7_fp
 317 return 1 for success or 0 if an error occurs.
 318 .Sh SEE ALSO
 319 .Xr ASN1_item_d2i 3 ,
 320 .Xr i2d_PKCS7_bio_stream 3 ,
 321 .Xr PEM_write_bio_PKCS7_stream 3 ,
 322 .Xr PEM_write_PKCS7 3 ,
 323 .Xr PKCS7_new 3 ,
 324 .Xr SMIME_write_PKCS7 3
 325 .Sh STANDARDS
 326 RFC 2315: PKCS #7: Cryptographic Message Syntax Version 1.5
 327 .Sh HISTORY
 328 .Fn d2i_PKCS7 ,
 329 .Fn i2d_PKCS7 ,
 330 .Fn d2i_PKCS7_bio ,
 331 .Fn i2d_PKCS7_bio ,
 332 .Fn d2i_PKCS7_fp ,
 333 .Fn i2d_PKCS7_fp ,
 334 .Fn d2i_PKCS7_DIGEST ,
 335 .Fn i2d_PKCS7_DIGEST ,
 336 .Fn d2i_PKCS7_ENCRYPT ,
 337 .Fn i2d_PKCS7_ENCRYPT ,
 338 .Fn d2i_PKCS7_ENC_CONTENT ,
 339 .Fn i2d_PKCS7_ENC_CONTENT ,
 340 .Fn d2i_PKCS7_ENVELOPE ,
 341 .Fn i2d_PKCS7_ENVELOPE ,
 342 .Fn d2i_PKCS7_ISSUER_AND_SERIAL ,
 343 .Fn i2d_PKCS7_ISSUER_AND_SERIAL ,
 344 .Fn d2i_PKCS7_RECIP_INFO ,
 345 .Fn i2d_PKCS7_RECIP_INFO ,
 346 .Fn d2i_PKCS7_SIGNED ,
 347 .Fn i2d_PKCS7_SIGNED ,
 348 .Fn d2i_PKCS7_SIGNER_INFO ,
 349 .Fn i2d_PKCS7_SIGNER_INFO ,
 350 .Fn d2i_PKCS7_SIGN_ENVELOPE ,
 351 and
 352 .Fn i2d_PKCS7_SIGN_ENVELOPE
 353 appeared in SSLeay 0.8.1b or earlier and have been available since
 354 .Ox 2.4 .