Debian Codegraph @

upstream/debian-unstable/man3/CMS_get1_ReceiptRequest.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "CMS_GET1_RECEIPTREQUEST 3SSL"
58 .TH CMS_GET1_RECEIPTREQUEST 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 CMS_ReceiptRequest_create0_ex, CMS_ReceiptRequest_create0,
65 CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values
66 \&\- CMS signed receipt request functions
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/cms.h>
71 \&
72 \& CMS_ReceiptRequest *CMS_ReceiptRequest_create0_ex(
73 \& unsigned char *id, int idlen, int allorfirst,
74 \& STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo,
75 \& OSSL_LIB_CTX *libctx);
76 \& CMS_ReceiptRequest *CMS_ReceiptRequest_create0(
77 \& unsigned char *id, int idlen, int allorfirst,
78 \& STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo);
79 \& int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr);
80 \& int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr);
81 \& void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid,
82 \& int *pallorfirst,
83 \& STACK_OF(GENERAL_NAMES) **plist,
84 \& STACK_OF(GENERAL_NAMES) **prto);
85 .Ve
86 .SH DESCRIPTION
87 .IX Header "DESCRIPTION"
88 \&\fBCMS_ReceiptRequest_create0_ex()\fR creates a signed receipt request
89 structure. The \fBsignedContentIdentifier\fR field is set using \fIid\fR and \fIidlen\fR,
90 or it is set to 32 bytes of pseudo random data if \fIid\fR is NULL.
91 If \fIreceiptList\fR is NULL the allOrFirstTier option in \fIreceiptsFrom\fR is used
92 and set to the value of the \fIallorfirst\fR parameter. If \fIreceiptList\fR is not
93 NULL the \fIreceiptList\fR option in \fIreceiptsFrom\fR is used. The \fIreceiptsTo\fR
94 parameter specifies the \fIreceiptsTo\fR field value. The library context \fIlibctx\fR
95 is used to find the public random generator.
96 .PP
97 \&\fBCMS_ReceiptRequest_create0()\fR is similar to
98 \&\fBCMS_ReceiptRequest_create0_ex()\fR but uses default values of NULL for the
99 library context \fIlibctx\fR.
100 .PP
101 The \fBCMS_add1_ReceiptRequest()\fR function adds a signed receipt request \fBrr\fR
102 to SignerInfo structure \fBsi\fR.
103 .PP
104 int \fBCMS_get1_ReceiptRequest()\fR looks for a signed receipt request in \fBsi\fR, if
105 any is found it is decoded and written to \fBprr\fR.
106 .PP
107 \&\fBCMS_ReceiptRequest_get0_values()\fR retrieves the values of a receipt request.
108 The signedContentIdentifier is copied to \fBpcid\fR. If the \fBallOrFirstTier\fR
109 option of \fBreceiptsFrom\fR is used its value is copied to \fBpallorfirst\fR
110 otherwise the \fBreceiptList\fR field is copied to \fBplist\fR. The \fBreceiptsTo\fR
111 parameter is copied to \fBprto\fR.
112 .SH NOTES
113 .IX Header "NOTES"
114 For more details of the meaning of the fields see RFC2634.
115 .PP
116 The contents of a signed receipt should only be considered meaningful if the
117 corresponding CMS_ContentInfo structure can be successfully verified using
118 \&\fBCMS_verify()\fR.
119 .SH "RETURN VALUES"
120 .IX Header "RETURN VALUES"
121 \&\fBCMS_ReceiptRequest_create0_ex()\fR and \fBCMS_ReceiptRequest_create0()\fR return
122 a signed receipt request structure or NULL if an error occurred.
123 .PP
124 \&\fBCMS_add1_ReceiptRequest()\fR returns 1 for success or 0 if an error occurred.
125 .PP
126 \&\fBCMS_get1_ReceiptRequest()\fR returns 1 is a signed receipt request is found and
127 decoded. It returns 0 if a signed receipt request is not present and \-1 if
128 it is present but malformed.
129 .SH "SEE ALSO"
130 .IX Header "SEE ALSO"
131 \&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3),
132 \&\fBCMS_sign_receipt\fR\|(3), \fBCMS_verify\fR\|(3)
133 \&\fBCMS_verify_receipt\fR\|(3)
134 .SH HISTORY
135 .IX Header "HISTORY"
136 The function \fBCMS_ReceiptRequest_create0_ex()\fR was added in OpenSSL 3.0.
137 .SH COPYRIGHT
138 .IX Header "COPYRIGHT"
139 Copyright 2008\-2021 The OpenSSL Project Authors. All Rights Reserved.
140 .PP
141 Licensed under the Apache License 2.0 (the "License"). You may not use
142 this file except in compliance with the License. You can obtain a copy
143 in the file LICENSE in the source distribution or at
144 <https://www.openssl.org/source/license.html>.