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