.\" $OpenBSD: CMS_get0_type.3,v 1.9 2023/07/27 05:31:28 tb Exp $ .\" full merge up to: OpenSSL 72a7a702 Feb 26 14:05:09 2019 +0000 .\" .\" This file is a derived work. .\" The changes are covered by the following Copyright and license: .\" .\" Copyright (c) 2019 Ingo Schwarze .\" .\" 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. .\" .\" The original file was written by Dr. Stephen Henson . .\" Copyright (c) 2008, 2015 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" 3. All advertising materials mentioning features or use of this .\" software must display the following acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" .\" .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to .\" endorse or promote products derived from this software without .\" prior written permission. For written permission, please contact .\" openssl-core@openssl.org. .\" .\" 5. Products derived from this software may not be called "OpenSSL" .\" nor may "OpenSSL" appear in their names without prior written .\" permission of the OpenSSL Project. .\" .\" 6. Redistributions of any form whatsoever must retain the following .\" acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" .\" .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: July 27 2023 $ .Dt CMS_GET0_TYPE 3 .Os .Sh NAME .Nm CMS_get0_type , .Nm CMS_get_version , .Nm CMS_set1_eContentType , .Nm CMS_get0_eContentType , .Nm CMS_get0_content .Nd get and set CMS content types and content .Sh SYNOPSIS .In openssl/cms.h .Ft const ASN1_OBJECT * .Fo CMS_get0_type .Fa "const CMS_ContentInfo *cms" .Fc .Ft int .Fo CMS_get_version .Fa "const CMS_ContentInfo *cms" .Fa "long *version" .Fc .Ft int .Fo CMS_set1_eContentType .Fa "CMS_ContentInfo *cms" .Fa "const ASN1_OBJECT *oid" .Fc .Ft const ASN1_OBJECT * .Fo CMS_get0_eContentType .Fa "CMS_ContentInfo *cms" .Fc .Ft ASN1_OCTET_STRING ** .Fo CMS_get0_content .Fa "CMS_ContentInfo *cms" .Fc .Sh DESCRIPTION .Fn CMS_get0_type returns the content type of the .Vt ContentInfo structure .Fa cms . The .Vt ASN1_OBJECT value returned can be converted to an integer NID value using .Xr OBJ_obj2nid 3 . The following content types are identified by the following NIDs: .Pp .Bl -column AuthenticatedData NID_id_smime_ct_compressedData -compact .It Vt SignedData Ta Dv NID_pkcs7_signed .It Vt EnvelopedData Ta Dv NID_pkcs7_enveloped .It Vt DigestedData Ta Dv NID_pkcs7_digest .It Vt EncryptedData Ta Dv NID_pkcs7_encrypted .It Vt AuthenticatedData Ta Dv NID_id_smime_ct_authData .It Vt CompressedData Ta Dv NID_id_smime_ct_compressedData .It arbitrary data Ta Dv NID_pkcs7_data .El .Pp The .Vt SignedData , .Vt DigestedData , .Vt AuthenticatedData , and .Vt CompressedData types contain a field .Fa encapContentInfo to allow embedding content, and .Vt EnvelopedData and .Vt EncryptedData contain a field .Fa encryptedContentInfo for that purpose. The type of the embedded content to be stored in that field can be set with the function .Fn CMS_set1_eContentType , to be called on .Fa cms structures returned from functions such as .Xr CMS_sign 3 or .Xr CMS_encrypt 3 with the .Dv CMS_PARTIAL flag set and .Em before the structure is finalised; otherwise the results are undefined. .Fn CMS_set1_eContentType copies the supplied .Fa oid , so it should be freed up after use. .Pp .Fn CMS_get_version sets .Pf * Fa version to the syntax version number of the .Vt ContentInfo structure .Fa cms . The version is a number between 0 and 5 and is defined for all the above content types except for arbitrary data. For arbitrary data and unsupported content types .Fn CMS_get_version fails and the content of .Pf * Fa version is unspecified. .Pp .Fn CMS_get0_eContentType returns the type of the embedded content. .Pp .Fn CMS_get0_content returns a pointer to the storage location where the pointer to the embedded content is stored. That means that for example after .Pp .Dl ASN1_OCTET_STRING **pconf = CMS_get0_content(cms); .Pp .Pf * Va pconf could be .Dv NULL if there is no embedded content. Applications can access, modify or create the embedded content in a .Vt CMS_ContentInfo structure using this function. Applications usually will not need to modify the embedded content as it is normally set by higher level functions. .Sh RETURN VALUES .Fn CMS_get0_type and .Fn CMS_get0_eContentType return internal pointers to .Vt OBJECT IDENTIFIER structures. .Pp .Fn CMS_get_version returns 1 on success and 0 on failure. .Pp .Fn CMS_get0_content returns an internal pointer to the storage location where the pointer to the embedded content is stored. .Pp .Fn CMS_set1_eContentType returns 1 for success or 0 if an error occurred. The error can be obtained from .Xr ERR_get_error 3 . .Sh SEE ALSO .Xr CMS_ContentInfo_new 3 , .Xr d2i_CMS_ContentInfo 3 , .Xr SMIME_read_CMS 3 .Sh STANDARDS RFC 5652: Cryptographic Message Syntax .Pp RFC 3274: Compressed Data Content Type for Cryptographic Message Syntax (CMS) .Sh HISTORY These functions first appeared in OpenSSL 0.9.8h and have been available since .Ox 6.7 . .Pp .Fn CMS_get_version first appeared in .Ox 7.4 .