doc/man3/CMS_get0_type.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/cms.h>
  10
  11  const ASN1_OBJECT *CMS_get0_type(const CMS_ContentInfo *cms);
  12  int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);
  13  const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);
  14  ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms);
  15
  16 =head1 DESCRIPTION
  17
  18 CMS_get0_type() returns the content type of a CMS_ContentInfo structure as
  19 an ASN1_OBJECT pointer. An application can then decide how to process the
  20 CMS_ContentInfo structure based on this value.
  21
  22 CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo
  23 structure. It should be called with CMS functions (such as L<CMS_sign>, L<CMS_encrypt>)
  24 with the B<CMS_PARTIAL>
  25 flag and B<before> the structure is finalised, otherwise the results are
  26 undefined.
  27
  28 ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded
  29 content type.
  30
  31 CMS_get0_content() returns a pointer to the B<ASN1_OCTET_STRING> pointer
  32 containing the embedded content.
  33
  34 =head1 NOTES
  35
  36 As the B<0> implies CMS_get0_type(), CMS_get0_eContentType() and
  37 CMS_get0_content() return internal pointers which should B<not> be freed up.
  38 CMS_set1_eContentType() copies the supplied OID and it B<should> be freed up
  39 after use.
  40
  41 The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value
  42 using OBJ_obj2nid(). For the currently supported content types the following
  43 values are returned:
  44
  45  NID_pkcs7_data
  46  NID_pkcs7_signed
  47  NID_pkcs7_digest
  48  NID_id_smime_ct_compressedData:
  49  NID_pkcs7_encrypted
  50  NID_pkcs7_enveloped
  51
  52 The return value of CMS_get0_content() is a pointer to the B<ASN1_OCTET_STRING>
  53 content pointer. That means that for example:
  54
  55  ASN1_OCTET_STRING **pconf = CMS_get0_content(cms);
  56
  57 B<*pconf> could be NULL if there is no embedded content. Applications can
  58 access, modify or create the embedded content in a B<CMS_ContentInfo> structure
  59 using this function. Applications usually will not need to modify the
  60 embedded content as it is normally set by higher level functions.
  61
  62 =head1 RETURN VALUES
  63
  64 CMS_get0_type() and CMS_get0_eContentType() return an ASN1_OBJECT structure.
  65
  66 CMS_set1_eContentType() returns 1 for success or 0 if an error occurred.  The
  67 error can be obtained from ERR_get_error(3).
  68
  69 =head1 SEE ALSO
  70
  71 L<ERR_get_error(3)>
  72
  73 =head1 COPYRIGHT
  74
  75 Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
  76
  77 Licensed under the Apache License 2.0 (the "License").  You may not use
  78 this file except in compliance with the License.  You can obtain a copy
  79 in the file LICENSE in the source distribution or at
  80 L<https://www.openssl.org/source/license.html>.
  81
  82 =cut