.Dd $Mdocdate: November 11 2015 $
.Dt CMS_GET1_RECEIPTREQUEST 3
.Os
.Sh NAME
.Nm CMS_ReceiptRequest_create0 ,
.Nm CMS_add1_ReceiptRequest ,
.Nm CMS_get1_ReceiptRequest ,
.Nm CMS_ReceiptRequest_get0_values
.Nd CMS signed receipt request functions
.Sh SYNOPSIS
.In openssl/cms.h
.Ft CMS_ReceiptRequest *
.Fo CMS_ReceiptRequest_create0
.Fa "unsigned char *id"
.Fa "int idlen"
.Fa "int allorfirst"
.Fa "STACK_OF(GENERAL_NAMES) *receiptList"
.Fa "STACK_OF(GENERAL_NAMES) *receiptsTo"
.Fc
.Ft int
.Fo CMS_add1_ReceiptRequest
.Fa "CMS_SignerInfo *si"
.Fa "CMS_ReceiptRequest *rr"
.Fc
.Ft int
.Fo CMS_get1_ReceiptRequest
.Fa "CMS_SignerInfo *si"
.Fa "CMS_ReceiptRequest **prr"
.Fc
.Ft void
.Fo CMS_ReceiptRequest_get0_values
.Fa "CMS_ReceiptRequest *rr"
.Fa "ASN1_STRING **pcid"
.Fa "int *pallorfirst"
.Fa "STACK_OF(GENERAL_NAMES) **plist"
.Fa "STACK_OF(GENERAL_NAMES) **prto"
.Fc
.Sh DESCRIPTION
.Fn CMS_ReceiptRequest_create0
creates a signed receipt request structure.
The
.Sy signedContentIdentifier
field is set using
.Fa id
and
.Fa idlen ,
or it is set to 32 bytes of pseudo random data if
.Fa id
is
.Dv NULL .
If
.Fa receiptList
is
.Dv NULL ,
the
.Sy allOrFirstTier
option in
.Sy receiptsFrom
is used and set to the value of the
.Fa allorfirst
parameter.
If
.Fa receiptList
is not
.Dv NULL ,
the
.Sy receiptList
option in
.Sy receiptsFrom
is used.
The
.Fa receiptsTo
parameter specifies the
.Sy receiptsTo
field value.
.Pp
The
.Fn CMS_add1_ReceiptRequest
function adds a signed receipt request
.Fa rr
to the
.Vt CMS_SignerInfo
structure
.Fa si .
.Pp
.Fn CMS_get1_ReceiptRequest
looks for a signed receipt request in
.Fa si .
If any is found, it is decoded and written to
.Fa prr .
.Pp
.Fn CMS_ReceiptRequest_get0_values
retrieves the values of a receipt request.
The signedContentIdentifier is copied to
.Fa pcid .
If the
.Sy allOrFirstTier
option of
.Sy receiptsFrom
is used, its value is copied to
.Fa pallorfirst ;
otherwise the
.Sy receiptList
field is copied to
.Fa plist .
The
.Sy receiptsTo
parameter is copied to
.Fa prto .
.Sh NOTES
For more details of the meaning of the fields see RFC2634.
.Pp
The contents of a signed receipt should only be considered meaningful if
the corresponding
.Vt CMS_ContentInfo
structure can be successfully verified using
.Xr CMS_verify 3 .
.Sh RETURN VALUES
.Fn CMS_ReceiptRequest_create0
returns a signed receipt request structure or
.Dv NULL
if an error occurred.
.Pp
.Fn CMS_add1_ReceiptRequest
returns 1 for success or 0 is an error occurred.
.Pp
.Fn CMS_get1_ReceiptRequest
returns 1 is a signed receipt request is found and decoded.
It returns 0 if a signed receipt request is not present and -1 if it is
present but malformed.
.Sh SEE ALSO
.Xr CMS_sign 3 ,
.Xr CMS_sign_receipt 3 ,
.Xr CMS_verify 3 ,
.Xr CMS_verify_receipt 3 ,
.Xr ERR_get_error 3
.Sh HISTORY
.Fn CMS_ReceiptRequest_create0 ,
.Fn CMS_add1_ReceiptRequest ,
.Fn CMS_get1_ReceiptRequest ,
and
.Fn CMS_ReceiptRequest_get0_values
were added to OpenSSL 0.9.8.