1.\" $OpenBSD: PKCS7_final.3,v 1.3 2022/12/26 07:18:52 jmc Exp $ 2.\" 3.\" Copyright (c) 2020 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: December 26 2022 $ 18.Dt PKCS7_FINAL 3 19.Os 20.Sh NAME 21.Nm PKCS7_final 22.Nd read data from a BIO into a ContentInfo object 23.Sh SYNOPSIS 24.In openssl/pkcs7.h 25.Ft int 26.Fo PKCS7_final 27.Fa "PKCS7 *p7" 28.Fa "BIO *data" 29.Fa "int flags" 30.Fc 31.Sh DESCRIPTION 32.Fn PKCS7_final 33reads 34.Fa data 35and puts it into the appropriate content field of 36.Fa p7 37itself or of its appropriate substructure, which can be of type 38.Vt SignedData , 39.Vt EnvelopedData , 40.Vt SignedAndEnvelopedData , 41.Vt DigestedData , 42or arbitrary data. 43The 44.Xr PKCS7_dataFinal 3 45manual explains which field exactly the data is put into. 46.Pp 47The following 48.Fa flags 49are recognized: 50.Bl -tag -width PKCS7_BINARY 51.It Dv PKCS7_BINARY 52Copy the data verbatim without changing any bytes. 53By default, line endings are replaced with two-byte 54.Qq \er\en 55sequences (ASCII CR+LF). 56If this flag is set, 57.Dv PKCS7_TEXT 58is ignored. 59.It Dv PKCS7_TEXT 60Prepend 61.Qq Content-Type: text/plain 62followed by a blank line to the data. 63This flag is ignored if 64.Dv PKCS7_BINARY 65is also set. 66.El 67.Pp 68If any other bits are set in 69.Fa flags , 70for example 71.Dv PKCS7_STREAM 72or 73.Dv PKCS7_PARTIAL , 74they are ignored, allowing to pass the same 75.Fa flags 76argument that was already passed to 77.Xr PKCS7_sign 3 78or 79.Xr PKCS7_encrypt 3 . 80.Pp 81.Fn PKCS7_final 82is most commonly used to finalize a 83.Fa p7 84object returned from a call to 85.Xr PKCS7_sign 3 86that used 87.Fa flags 88including 89.Dv PKCS7_PARTIAL 90or 91.Dv PKCS7_STREAM . 92With these flags, 93.Xr PKCS7_sign 3 94ignores its 95.Fa data 96argument. 97The partial 98.Fa p7 99object returned can then be customized, for example setting up 100multiple signers or non-default digest algorithms with 101.Xr PKCS7_sign_add_signer 3 , 102before calling 103.Fn PKCS7_final . 104.Pp 105Similarly, 106.Fn PKCS7_final 107can be used to finalize a 108.Fa p7 109object returned from a call to 110.Xr PKCS7_encrypt 3 111that used 112.Fa flags 113including 114.Dv PKCS7_STREAM . 115.Pp 116Since 117.Fn PKCS7_final 118starts by calling 119.Xr PKCS7_dataInit 3 120internally, using it to finalize a 121.Fa p7 122object containing 123.Vt SignedAndEnvelopedData , 124.Vt DigestedData , 125or arbitrary data requires the setup described in the 126.Xr PKCS7_dataInit 3 127manual. 128For 129.Vt SignedData 130and 131.Vt EnvelopedData , 132such manual setup is also feasible, but it is more easily performed with 133.Xr PKCS7_sign 3 134or 135.Xr PKCS7_encrypt 3 , 136respectively. 137.Pp 138.Fn PKCS7_final 139is only one among several functions that can be used to finalize 140.Fa p7 ; 141alternatives include 142.Xr SMIME_write_PKCS7 3 , 143.Xr PEM_write_bio_PKCS7_stream 3 , 144and 145.Xr i2d_PKCS7_bio_stream 3 . 146.Sh RETURN VALUES 147.Fn PKCS7_final 148returns 1 on success or 0 on failure. 149.Pp 150Possible reasons for failure include: 151.Pp 152.Bl -dash -compact -offset 2n -width 1n 153.It 154.Fa p7 155is 156.Dv NULL . 157.It 158The 159.Fa content 160field of 161.Fa p7 162is empty. 163.It 164The 165.Fa contentType 166of 167.Fa p7 168is unsupported. 169.It 170Signing or digesting is requested and 171.Fa p7 172is not configured to store a detached signature, but does not contain 173the required field to store the content either. 174.It 175At least one signer lacks a usable digest algorithm. 176.It 177A cipher is required but none is configured. 178.It 179Any required operation fails, for example signing or digesting. 180.It 181Memory allocation fails. 182.El 183.Pp 184Signers lacking private keys do not cause failure but are silently skipped. 185.Sh SEE ALSO 186.Xr BIO_new 3 , 187.Xr i2d_PKCS7_bio_stream 3 , 188.Xr PEM_write_bio_PKCS7_stream 3 , 189.Xr PKCS7_add_attribute 3 , 190.Xr PKCS7_dataFinal 3 , 191.Xr PKCS7_dataInit 3 , 192.Xr PKCS7_encrypt 3 , 193.Xr PKCS7_new 3 , 194.Xr PKCS7_sign 3 , 195.Xr SMIME_write_PKCS7 3 196.Sh HISTORY 197.Fn PKCS7_final 198first appeared in OpenSSL 1.0.0 and has been available since 199.Ox 4.9 . 200.Sh CAVEATS 201This function does not support 202.Vt EncryptedData . 203