1.\" $OpenBSD: PKCS7_dataInit.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_DATAINIT 3 19.Os 20.Sh NAME 21.Nm PKCS7_dataInit 22.Nd construct a BIO chain for adding or retrieving content 23.Sh SYNOPSIS 24.In openssl/pkcs7.h 25.Ft BIO * 26.Fo PKCS7_dataInit 27.Fa "PKCS7 *p7" 28.Fa "BIO *indata" 29.Fc 30.Sh DESCRIPTION 31.Fn PKCS7_dataInit 32constructs a BIO chain in preparation for putting data into 33or retrieving data out of 34.Fa p7 . 35Depending on the 36.Fa contentType 37of 38.Fa p7 , 39the created chain starts with: 40.Bl -tag -width Ds 41.It for Vt SignedData : 42one or more 43.Xr BIO_f_md 3 44message digest filters 45.It for Vt EnvelopedData : 46one 47.Xr BIO_f_cipher 3 48encryption filter 49.It for Vt SignedAndEnvelopedData : 50one or more 51.Xr BIO_f_md 3 52message digest filters followed by one 53.Xr BIO_f_cipher 3 54encryption filter 55.It for Vt DigestedData : 56one 57.Xr BIO_f_md 3 58message digest filter 59.It for arbitrary data : 60no filter BIO 61.El 62.Pp 63One additional BIO is appended to the end of the chain, 64depending on the first condition that holds in the following list: 65.Bl -tag -width Ds 66.It Fa indata 67if the 68.Fa indata 69argument is not 70.Dv NULL . 71This only makes sense while verifying a detached signature, in which case 72.Fa indata 73is expected to supply the content associated with the detached signature. 74.It Xr BIO_s_null 3 75if the 76.Fa contentType 77of 78.Fa p7 79is 80.Vt SignedData 81and it is configured to contain a detached signature. 82This only makes sense while creating the detached signature. 83.It Xr BIO_new_mem_buf 3 84when reading from a 85.Vt SignedData 86or 87.Vt DigestedData 88object. 89.Fn PKCS7_dataInit 90attaches the end of the chain to the nested content of 91.Fa p7 . 92.It Xr BIO_s_mem 3 93otherwise. 94This is the most common case while writing data to 95.Fa p7 . 96.Xr PKCS7_dataFinal 3 97can later be used to transfer the data from the memory BIO into 98.Fa p7 . 99.El 100.Ss Adding content 101Before calling 102.Fn PKCS7_dataInit 103in order to add content, 104.Xr PKCS7_new 3 , 105.Xr PKCS7_set_type 3 , 106and 107.Xr PKCS7_content_new 3 108are typically required to create 109.Fa p7 , 110to choose its desired type, and to allocate the nested 111.Vt ContentInfo 112structure. 113Alternatively, for 114.Vt SignedData , 115.Xr PKCS7_sign 3 116can be used with the 117.Dv PKCS7_PARTIAL 118or 119.Dv PKCS7_STREAM 120.Fa flags 121or for 122.Vt EnvelopedData , 123.Xr PKCS7_encrypt 3 124with the 125.Dv PKCS7_STREAM 126flag. 127.Pp 128After calling 129.Fn PKCS7_dataInit , 130the desired data can be written into the returned 131.Vt BIO , 132.Xr BIO_flush 3 133can be called on it, 134.Xr PKCS7_dataFinal 3 135can be used to transfer the processed data 136from the returned memory BIO to the 137.Fa p7 138structure, and the chain can finally be destroyed with 139.Xr BIO_free_all 3 . 140.Pp 141While 142.Fn PKCS7_dataInit 143does support the 144.Vt EnvelopedData 145and 146.Vt SignedAndEnvelopedData 147types, using it for these types is awkward and error prone 148except when using 149.Xr PKCS7_encrypt 3 150for the setup because 151.Xr PKCS7_content_new 3 152does not support these two types. 153So in addition to creating 154.Fa p7 155itself and setting its type, the nested 156.Fa ContentInfo 157structure also needs to be constructed with 158.Xr PKCS7_new 3 159and 160.Xr PKCS7_set_type 3 161and manually inserted into the correct field 162of the respective sub-structure of 163.Fa p7 . 164.Ss Retrieving content 165.Fn PKCS7_dataInit 166can also be called on a fully populated object of type 167.Vt SignedData 168or 169.Vt DigestedData . 170After that, 171.Xr BIO_read 3 172can be used to retrieve data from it. 173In this use case, do not call 174.Xr PKCS7_dataFinal 3 ; 175simply proceed directly to 176.Xr BIO_free_all 3 177after reading the data. 178.Sh RETURN VALUES 179.Fn PKCS7_dataInit 180returns a BIO chain on success or 181.Dv NULL 182on failure. 183It fails if 184.Fa p7 185is 186.Dv NULL , 187if the 188.Fa content 189field of 190.Fa p7 191is empty, if the 192.Fa contentType 193of 194.Fa p7 195is unsupported, if a cipher is required but none is configured, or 196if any required operation fails, for example due to lack of memory 197or for various other reasons. 198.Sh SEE ALSO 199.Xr BIO_new 3 , 200.Xr BIO_read 3 , 201.Xr PKCS7_content_new 3 , 202.Xr PKCS7_dataFinal 3 , 203.Xr PKCS7_encrypt 3 , 204.Xr PKCS7_final 3 , 205.Xr PKCS7_new 3 , 206.Xr PKCS7_set_type 3 , 207.Xr PKCS7_sign 3 208.Sh HISTORY 209.Fn PKCS7_dataInit 210first appeared in SSLeay 0.8.1 and has been available since 211.Ox 2.4 . 212.Sh CAVEATS 213This function does not support 214.Vt EncryptedData . 215.Sh BUGS 216If 217.Fa p7 218is a fully populated structure containing 219.Vt EnvelopedData , 220.Vt SignedAndEnvelopedData , 221or arbitrary data, 222.Fn PKCS7_dataInit 223returns a BIO chain that ultimately reads from an empty memory BIO, 224so reading from it will instantly return an end-of-file indication 225rather than reading the actual data contained in 226.Fa p7 . 227