1.\" $OpenBSD: CMS_get0_type.3,v 1.9 2023/07/27 05:31:28 tb Exp $ 2.\" full merge up to: OpenSSL 72a7a702 Feb 26 14:05:09 2019 +0000 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 22.\" Copyright (c) 2008, 2015 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: July 27 2023 $ 69.Dt CMS_GET0_TYPE 3 70.Os 71.Sh NAME 72.Nm CMS_get0_type , 73.Nm CMS_get_version , 74.Nm CMS_set1_eContentType , 75.Nm CMS_get0_eContentType , 76.Nm CMS_get0_content 77.Nd get and set CMS content types and content 78.Sh SYNOPSIS 79.In openssl/cms.h 80.Ft const ASN1_OBJECT * 81.Fo CMS_get0_type 82.Fa "const CMS_ContentInfo *cms" 83.Fc 84.Ft int 85.Fo CMS_get_version 86.Fa "const CMS_ContentInfo *cms" 87.Fa "long *version" 88.Fc 89.Ft int 90.Fo CMS_set1_eContentType 91.Fa "CMS_ContentInfo *cms" 92.Fa "const ASN1_OBJECT *oid" 93.Fc 94.Ft const ASN1_OBJECT * 95.Fo CMS_get0_eContentType 96.Fa "CMS_ContentInfo *cms" 97.Fc 98.Ft ASN1_OCTET_STRING ** 99.Fo CMS_get0_content 100.Fa "CMS_ContentInfo *cms" 101.Fc 102.Sh DESCRIPTION 103.Fn CMS_get0_type 104returns the content type of the 105.Vt ContentInfo 106structure 107.Fa cms . 108The 109.Vt ASN1_OBJECT 110value returned can be converted to an integer NID value using 111.Xr OBJ_obj2nid 3 . 112The following content types are identified by the following NIDs: 113.Pp 114.Bl -column AuthenticatedData NID_id_smime_ct_compressedData -compact 115.It Vt SignedData Ta Dv NID_pkcs7_signed 116.It Vt EnvelopedData Ta Dv NID_pkcs7_enveloped 117.It Vt DigestedData Ta Dv NID_pkcs7_digest 118.It Vt EncryptedData Ta Dv NID_pkcs7_encrypted 119.It Vt AuthenticatedData Ta Dv NID_id_smime_ct_authData 120.It Vt CompressedData Ta Dv NID_id_smime_ct_compressedData 121.It arbitrary data Ta Dv NID_pkcs7_data 122.El 123.Pp 124The 125.Vt SignedData , 126.Vt DigestedData , 127.Vt AuthenticatedData , 128and 129.Vt CompressedData 130types contain a field 131.Fa encapContentInfo 132to allow embedding content, and 133.Vt EnvelopedData 134and 135.Vt EncryptedData 136contain a field 137.Fa encryptedContentInfo 138for that purpose. 139The type of the embedded content to be stored in that field can be 140set with the function 141.Fn CMS_set1_eContentType , 142to be called on 143.Fa cms 144structures returned from functions such as 145.Xr CMS_sign 3 146or 147.Xr CMS_encrypt 3 148with the 149.Dv CMS_PARTIAL 150flag set and 151.Em before 152the structure is finalised; otherwise the results are undefined. 153.Fn CMS_set1_eContentType 154copies the supplied 155.Fa oid , 156so it should be freed up after use. 157.Pp 158.Fn CMS_get_version 159sets 160.Pf * Fa version 161to the syntax version number of the 162.Vt ContentInfo 163structure 164.Fa cms . 165The version is a number between 0 and 5 and is defined for all the 166above content types except for arbitrary data. 167For arbitrary data and unsupported content types 168.Fn CMS_get_version 169fails and the content of 170.Pf * Fa version 171is unspecified. 172.Pp 173.Fn CMS_get0_eContentType 174returns the type of the embedded content. 175.Pp 176.Fn CMS_get0_content 177returns a pointer to the storage location where the pointer to the 178embedded content is stored. 179That means that for example after 180.Pp 181.Dl ASN1_OCTET_STRING **pconf = CMS_get0_content(cms); 182.Pp 183.Pf * Va pconf 184could be 185.Dv NULL 186if there is no embedded content. 187Applications can access, modify or create the embedded content in a 188.Vt CMS_ContentInfo 189structure using this function. 190Applications usually will not need to modify the embedded content as it 191is normally set by higher level functions. 192.Sh RETURN VALUES 193.Fn CMS_get0_type 194and 195.Fn CMS_get0_eContentType 196return internal pointers to 197.Vt OBJECT IDENTIFIER 198structures. 199.Pp 200.Fn CMS_get_version 201returns 1 on success and 0 on failure. 202.Pp 203.Fn CMS_get0_content 204returns an internal pointer to the storage location where the pointer 205to the embedded content is stored. 206.Pp 207.Fn CMS_set1_eContentType 208returns 1 for success or 0 if an error occurred. 209The error can be obtained from 210.Xr ERR_get_error 3 . 211.Sh SEE ALSO 212.Xr CMS_ContentInfo_new 3 , 213.Xr d2i_CMS_ContentInfo 3 , 214.Xr SMIME_read_CMS 3 215.Sh STANDARDS 216RFC 5652: Cryptographic Message Syntax 217.Pp 218RFC 3274: Compressed Data Content Type for Cryptographic Message Syntax (CMS) 219.Sh HISTORY 220These functions first appeared in OpenSSL 0.9.8h 221and have been available since 222.Ox 6.7 . 223.Pp 224.Fn CMS_get_version 225first appeared in 226.Ox 7.4 . 227