1.\" $OpenBSD: PKCS7_dataFinal.3,v 1.2 2020/06/03 13:41:27 schwarze 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: June 3 2020 $ 18.Dt PKCS7_DATAFINAL 3 19.Os 20.Sh NAME 21.Nm PKCS7_dataFinal 22.Nd move data from a BIO chain to a ContentInfo object 23.Sh SYNOPSIS 24.In openssl/pkcs7.h 25.Ft int 26.Fo PKCS7_dataFinal 27.Fa "PKCS7 *p7" 28.Fa "BIO *chain" 29.Fc 30.Sh DESCRIPTION 31.Fn PKCS7_dataFinal 32transfers the data from the memory BIO at the end of the given 33.Fa chain 34into the appropriate content field of 35.Fa p7 36itself or of its appropriate substructure. 37It is typically used as the final step of populating 38.Fa p7 , 39after creating the 40.Fa chain 41with 42.Xr PKCS7_dataInit 3 43and after writing the data into it. 44.Pp 45After calling 46.Fn PKCS7_dataFinal , 47the program can call 48.Xr BIO_free_all 3 49on the 50.Fa chain 51because such chains are not designed for reuse. 52.Pp 53Depending on the 54.Fa contentType 55of 56.Fa p7 , 57.Fn PKCS7_dataFinal 58sets the following fields: 59.Bl -tag -width Ds 60.It for Vt SignedData No or Vt DigestedData : 61in substructures of the 62.Fa content 63field of 64.Fa p7 : 65the 66.Fa content 67field in the 68.Vt ContentInfo 69structure (unless 70.Fa p7 71is configured to store a detached signature) and the 72.Fa encryptedDigest 73fields in all the 74.Vt SignerInfo 75structures 76.It for Vt EnvelopedData No or Vt SignedAndEnvelopedData : 77the 78.Fa encryptedContent 79field in the 80.Vt EncryptedContentInfo 81structure contained in the 82.Fa content 83field of 84.Fa p7 85.It for arbitrary data : 86the 87.Fa content 88field of 89.Fa p7 90itself 91.El 92.Sh RETURN VALUES 93.Fn PKCS7_dataFinal 94returns 1 on success or 0 on failure. 95.Pp 96Possible reasons for failure include: 97.Pp 98.Bl -dash -compact -offset 2n -width 1n 99.It 100.Fa p7 101is 102.Dv NULL . 103.It 104The 105.Fa content 106field of 107.Fa p7 108is empty. 109.It 110The 111.Fa contentType 112of 113.Fa p7 114is unsupported. 115.It 116The 117.Fa chain 118does not contain the expected memory BIO. 119.It 120Signing or digesting is requested and 121.Fa p7 122is not configured to store a detached signature, 123but does not contain the required field to store the content either. 124.It 125At least one signer lacks a useable digest algorithm. 126.It 127Signing or digesting fails. 128.It 129Memory allocation fails. 130.El 131.Pp 132Signers lacking private keys do not cause failure 133but are silently skipped. 134.Sh SEE ALSO 135.Xr BIO_new 3 , 136.Xr PKCS7_dataInit 3 , 137.Xr PKCS7_final 3 , 138.Xr PKCS7_new 3 , 139.Xr PKCS7_sign 3 140.Sh HISTORY 141.Fn PKCS7_dataFinal 142first appeared in SSLeay 0.9.1 and has been available since 143.Ox 2.6 . 144.Sh CAVEATS 145This function does not support 146.Vt EncryptedData . 147.Pp 148Even though this function is typically used after 149.Xr PKCS7_dataInit 3 150and even though 151.Xr PKCS7_dataInit 3 152also supports reading from 153.Vt ContentInfo 154structures that are already fully populated, do not use 155.Fn PKCS7_dataFinal 156on fully populated structures. 157It is only intended for putting data into new structures 158and it is neither needed nor suitable for reading. 159