1.\" $OpenBSD: d2i_PKCS7.3,v 1.6 2018/03/27 17:35:50 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 27 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 185These functions decode and encode PKCS#7 data structures. 186For details about the semantics, examples, caveats, and bugs, see 187.Xr ASN1_item_d2i 3 . 188.Pp 189.Fn d2i_PKCS7 190and 191.Fn i2d_PKCS7 192decode and encode an ASN.1 193.Vt ContentInfo 194structure defined in RFC 2315 section 7. 195.Fn d2i_PKCS7_bio , 196.Fn i2d_PKCS7_bio , 197.Fn d2i_PKCS7_fp , 198and 199.Fn i2d_PKCS7_fp 200are similar except that they decode or encode using a 201.Vt BIO 202or 203.Vt FILE 204pointer. 205.Pp 206.Fn i2d_PKCS7_NDEF 207is similar to 208.Fn i2d_PKCS7 209except that it encodes using BER rather than DER, using the indefinite 210length form where appropriate. 211.Pp 212.Fn d2i_PKCS7_DIGEST 213and 214.Fn i2d_PKCS7_DIGEST 215decode and encode an ASN.1 216.Vt DigestedData 217structure defined in RFC 2315 section 12. 218.Pp 219.Fn d2i_PKCS7_ENCRYPT 220and 221.Fn i2d_PKCS7_ENCRYPT 222decode and encode an ASN.1 223.Vt EncryptedData 224structure defined in RFC 2315 section 13. 225.Pp 226.Fn d2i_PKCS7_ENC_CONTENT 227and 228.Fn i2d_PKCS7_ENC_CONTENT 229decode and encode an ASN.1 230.Vt EncryptedContentInfo 231structure defined in RFC 2315 section 10.1. 232.Pp 233.Fn d2i_PKCS7_ENVELOPE 234and 235.Fn i2d_PKCS7_ENVELOPE 236decode and encode an ASN.1 237.Vt EnvelopedData 238structure defined in RFC 2315 section 10. 239.Pp 240.Fn d2i_PKCS7_ISSUER_AND_SERIAL 241and 242.Fn i2d_PKCS7_ISSUER_AND_SERIAL 243decode and encode an ASN.1 244.Vt IssuerAndSerialNumber 245structure defined in RFC 2315 section 6.7. 246.Pp 247.Fn d2i_PKCS7_RECIP_INFO 248and 249.Fn i2d_PKCS7_RECIP_INFO 250decode and encode an ASN.1 251.Vt RecipientInfo 252structure defined in RFC 2315 section 10.2. 253.Pp 254.Fn d2i_PKCS7_SIGNED 255and 256.Fn i2d_PKCS7_SIGNED 257decode and encode an ASN.1 258.Vt SignedData 259structure defined in RFC 2315 section 9. 260.Pp 261.Fn d2i_PKCS7_SIGNER_INFO 262and 263.Fn i2d_PKCS7_SIGNER_INFO 264decode and encode an ASN.1 265.Vt SignerInfo 266structure defined in RFC 2315 section 9.2. 267.Pp 268.Fn d2i_PKCS7_SIGN_ENVELOPE 269and 270.Fn i2d_PKCS7_SIGN_ENVELOPE 271decode and encode an ASN.1 272.Vt SignedAndEnvelopedData 273structure defined in RFC 2315 section 11. 274.Sh RETURN VALUES 275.Fn d2i_PKCS7 , 276.Fn d2i_PKCS7_bio , 277and 278.Fn d2i_PKCS7_fp 279return a 280.Vt PKCS7 281object or 282.Dv NULL 283if 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 , 293and 294.Fn d2i_PKCS7_SIGN_ENVELOPE 295return an object of the respective type or 296.Dv NULL 297if 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 , 309and 310.Fn i2d_PKCS7_SIGN_ENVELOPE 311return the number of bytes successfully encoded or a negative value 312if an error occurs. 313.Pp 314.Fn i2d_PKCS7_bio 315and 316.Fn i2d_PKCS7_fp 317return 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 326RFC 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 , 351and 352.Fn i2d_PKCS7_SIGN_ENVELOPE 353first appeared in SSLeay 0.5.1 and have been available since 354.Ox 2.4 . 355