1.\" $OpenBSD: CMS_get1_ReceiptRequest.3,v 1.7 2019/11/02 15:39:46 schwarze Exp $
2.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100
3.\"
4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5.\" Copyright (c) 2008 The OpenSSL Project.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in
16.\"    the documentation and/or other materials provided with the
17.\"    distribution.
18.\"
19.\" 3. All advertising materials mentioning features or use of this
20.\"    software must display the following acknowledgment:
21.\"    "This product includes software developed by the OpenSSL Project
22.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23.\"
24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25.\"    endorse or promote products derived from this software without
26.\"    prior written permission. For written permission, please contact
27.\"    openssl-core@openssl.org.
28.\"
29.\" 5. Products derived from this software may not be called "OpenSSL"
30.\"    nor may "OpenSSL" appear in their names without prior written
31.\"    permission of the OpenSSL Project.
32.\"
33.\" 6. Redistributions of any form whatsoever must retain the following
34.\"    acknowledgment:
35.\"    "This product includes software developed by the OpenSSL Project
36.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37.\"
38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\"
51.Dd $Mdocdate: November 2 2019 $
52.Dt CMS_GET1_RECEIPTREQUEST 3
53.Os
54.Sh NAME
55.Nm CMS_ReceiptRequest_create0 ,
56.Nm CMS_add1_ReceiptRequest ,
57.Nm CMS_get1_ReceiptRequest ,
58.Nm CMS_ReceiptRequest_get0_values
59.Nd CMS signed receipt request functions
60.Sh SYNOPSIS
61.In openssl/cms.h
62.Ft CMS_ReceiptRequest *
63.Fo CMS_ReceiptRequest_create0
64.Fa "unsigned char *id"
65.Fa "int idlen"
66.Fa "int allorfirst"
67.Fa "STACK_OF(GENERAL_NAMES) *receiptList"
68.Fa "STACK_OF(GENERAL_NAMES) *receiptsTo"
69.Fc
70.Ft int
71.Fo CMS_add1_ReceiptRequest
72.Fa "CMS_SignerInfo *si"
73.Fa "CMS_ReceiptRequest *rr"
74.Fc
75.Ft int
76.Fo CMS_get1_ReceiptRequest
77.Fa "CMS_SignerInfo *si"
78.Fa "CMS_ReceiptRequest **prr"
79.Fc
80.Ft void
81.Fo CMS_ReceiptRequest_get0_values
82.Fa "CMS_ReceiptRequest *rr"
83.Fa "ASN1_STRING **pcid"
84.Fa "int *pallorfirst"
85.Fa "STACK_OF(GENERAL_NAMES) **plist"
86.Fa "STACK_OF(GENERAL_NAMES) **prto"
87.Fc
88.Sh DESCRIPTION
89.Fn CMS_ReceiptRequest_create0
90creates a new
91.Vt ReceiptRequest
92structure.
93The
94.Fa signedContentIdentifier
95field is set using
96.Fa id
97and
98.Fa idlen ,
99or it is set to 32 bytes of pseudo random data if
100.Fa id
101is
102.Dv NULL .
103If
104.Fa receiptList
105is
106.Dv NULL ,
107the
108.Fa allOrFirstTier
109option in the
110.Fa receiptsFrom
111field is set to the value of the
112.Fa allorfirst
113argument.
114If
115.Fa receiptList
116is not
117.Dv NULL ,
118the
119.Fa receiptList
120option in the
121.Fa receiptsFrom
122field is used.
123The
124.Fa receiptsTo
125argument specifies the value of the
126.Fa receiptsTo
127field.
128.Pp
129.Fn CMS_add1_ReceiptRequest
130adds a BER-encoded copy of
131.Fa rr
132to
133.Fa si .
134.Pp
135.Fn CMS_get1_ReceiptRequest
136looks for a signed receipt request in
137.Fa si .
138If any is found, it is decoded and written to
139.Fa prr .
140.Pp
141.Fn CMS_ReceiptRequest_get0_values
142retrieves the values of a receipt request.
143The
144.Fa signedContentIdentifier
145is copied to
146.Fa pcid .
147If the
148.Fa allOrFirstTier
149option is used in the
150.Fa receiptsFrom
151field, its value is copied to
152.Fa pallorfirst ;
153otherwise the
154.Fa receiptList
155field is copied to
156.Fa plist .
157The
158.Fa receiptsTo
159field is copied to
160.Fa prto .
161.Pp
162The contents of a signed receipt should only be considered meaningful if
163the corresponding
164.Vt CMS_ContentInfo
165structure can be successfully verified using
166.Xr CMS_verify 3 .
167.Sh RETURN VALUES
168.Fn CMS_ReceiptRequest_create0
169returns the new signed receipt request structure or
170.Dv NULL
171if an error occurred.
172.Pp
173.Fn CMS_add1_ReceiptRequest
174returns 1 for success or 0 if an error occurred.
175.Pp
176.Fn CMS_get1_ReceiptRequest
177returns 1 is a signed receipt request is found and decoded.
178It returns 0 if a signed receipt request is not present or -1 if it is
179present but malformed.
180.Sh SEE ALSO
181.Xr CMS_ContentInfo_new 3 ,
182.Xr CMS_sign 3 ,
183.Xr CMS_sign_receipt 3 ,
184.Xr CMS_verify 3 ,
185.Xr CMS_verify_receipt 3 ,
186.Xr ERR_get_error 3
187.Sh STANDARDS
188RFC 2634: Enhanced Security Services for S/MIME,
189section 2.7: Receipt Request Syntax
190.Sh HISTORY
191.Fn CMS_ReceiptRequest_create0 ,
192.Fn CMS_add1_ReceiptRequest ,
193.Fn CMS_get1_ReceiptRequest ,
194and
195.Fn CMS_ReceiptRequest_get0_values
196first appeared in OpenSSL 0.9.8h
197and have been available since
198.Ox 6.7 .
199