158 lines
3.5 KiB
Groff
158 lines
3.5 KiB
Groff
.\" $OpenBSD: PKCS7_dataFinal.3,v 1.3 2022/12/26 07:18:52 jmc Exp $
|
|
.\"
|
|
.\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.Dd $Mdocdate: December 26 2022 $
|
|
.Dt PKCS7_DATAFINAL 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm PKCS7_dataFinal
|
|
.Nd move data from a BIO chain to a ContentInfo object
|
|
.Sh SYNOPSIS
|
|
.In openssl/pkcs7.h
|
|
.Ft int
|
|
.Fo PKCS7_dataFinal
|
|
.Fa "PKCS7 *p7"
|
|
.Fa "BIO *chain"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
.Fn PKCS7_dataFinal
|
|
transfers the data from the memory BIO at the end of the given
|
|
.Fa chain
|
|
into the appropriate content field of
|
|
.Fa p7
|
|
itself or of its appropriate substructure.
|
|
It is typically used as the final step of populating
|
|
.Fa p7 ,
|
|
after creating the
|
|
.Fa chain
|
|
with
|
|
.Xr PKCS7_dataInit 3
|
|
and after writing the data into it.
|
|
.Pp
|
|
After calling
|
|
.Fn PKCS7_dataFinal ,
|
|
the program can call
|
|
.Xr BIO_free_all 3
|
|
on the
|
|
.Fa chain
|
|
because such chains are not designed for reuse.
|
|
.Pp
|
|
Depending on the
|
|
.Fa contentType
|
|
of
|
|
.Fa p7 ,
|
|
.Fn PKCS7_dataFinal
|
|
sets the following fields:
|
|
.Bl -tag -width Ds
|
|
.It for Vt SignedData No or Vt DigestedData :
|
|
in substructures of the
|
|
.Fa content
|
|
field of
|
|
.Fa p7 :
|
|
the
|
|
.Fa content
|
|
field in the
|
|
.Vt ContentInfo
|
|
structure (unless
|
|
.Fa p7
|
|
is configured to store a detached signature) and the
|
|
.Fa encryptedDigest
|
|
fields in all the
|
|
.Vt SignerInfo
|
|
structures
|
|
.It for Vt EnvelopedData No or Vt SignedAndEnvelopedData :
|
|
the
|
|
.Fa encryptedContent
|
|
field in the
|
|
.Vt EncryptedContentInfo
|
|
structure contained in the
|
|
.Fa content
|
|
field of
|
|
.Fa p7
|
|
.It for arbitrary data :
|
|
the
|
|
.Fa content
|
|
field of
|
|
.Fa p7
|
|
itself
|
|
.El
|
|
.Sh RETURN VALUES
|
|
.Fn PKCS7_dataFinal
|
|
returns 1 on success or 0 on failure.
|
|
.Pp
|
|
Possible reasons for failure include:
|
|
.Pp
|
|
.Bl -dash -compact -offset 2n -width 1n
|
|
.It
|
|
.Fa p7
|
|
is
|
|
.Dv NULL .
|
|
.It
|
|
The
|
|
.Fa content
|
|
field of
|
|
.Fa p7
|
|
is empty.
|
|
.It
|
|
The
|
|
.Fa contentType
|
|
of
|
|
.Fa p7
|
|
is unsupported.
|
|
.It
|
|
The
|
|
.Fa chain
|
|
does not contain the expected memory BIO.
|
|
.It
|
|
Signing or digesting is requested and
|
|
.Fa p7
|
|
is not configured to store a detached signature,
|
|
but does not contain the required field to store the content either.
|
|
.It
|
|
At least one signer lacks a usable digest algorithm.
|
|
.It
|
|
Signing or digesting fails.
|
|
.It
|
|
Memory allocation fails.
|
|
.El
|
|
.Pp
|
|
Signers lacking private keys do not cause failure
|
|
but are silently skipped.
|
|
.Sh SEE ALSO
|
|
.Xr BIO_new 3 ,
|
|
.Xr PKCS7_dataInit 3 ,
|
|
.Xr PKCS7_final 3 ,
|
|
.Xr PKCS7_new 3 ,
|
|
.Xr PKCS7_sign 3
|
|
.Sh HISTORY
|
|
.Fn PKCS7_dataFinal
|
|
first appeared in SSLeay 0.9.1 and has been available since
|
|
.Ox 2.6 .
|
|
.Sh CAVEATS
|
|
This function does not support
|
|
.Vt EncryptedData .
|
|
.Pp
|
|
Even though this function is typically used after
|
|
.Xr PKCS7_dataInit 3
|
|
and even though
|
|
.Xr PKCS7_dataInit 3
|
|
also supports reading from
|
|
.Vt ContentInfo
|
|
structures that are already fully populated, do not use
|
|
.Fn PKCS7_dataFinal
|
|
on fully populated structures.
|
|
It is only intended for putting data into new structures
|
|
and it is neither needed nor suitable for reading.
|