hx509_cms(3)

💖 NAME 💖

hx509_cms — the hx509 CMS/pkcs7 functions, bestie. That's the whole vibe. It's a page from the Heimdal x509 library manual, and we're gonna go through every single one of these functions together, no skips, no cap. 🎀

---

✨ SYNOPSIS ✨

Okay so here's the full cast, like the group chat roster. Every single one of these signatures, exactly as they are:

int hx509_cms_wrap_ContentInfo (const heim_oid *oid, const
    heim_octet_string *buf, heim_octet_string *res)
int hx509_cms_unwrap_ContentInfo (const heim_octet_string *in, heim_oid
    *oid, heim_octet_string *out, int *have_data)
int hx509_cms_unenvelope (hx509_context context, hx509_certs certs, int
    flags, const void *data, size_t length, const heim_octet_string
    *encryptedContent, time_t time_now, heim_oid *contentType,
    heim_octet_string *content)
int hx509_cms_envelope_1 (hx509_context context, int flags, hx509_cert
    cert, const void *data, size_t length, const heim_oid
    *encryption_type, const heim_oid *contentType, heim_octet_string
    *content)
int hx509_cms_verify_signed (hx509_context context, hx509_verify_ctx
    ctx, unsigned int flags, const void *data, size_t length, const
    heim_octet_string *signedContent, hx509_certs pool, heim_oid
    *contentType, heim_octet_string *content, hx509_certs *signer_certs)
int hx509_cms_create_signed_1 (hx509_context context, int flags, const
    heim_oid *eContentType, const void *data, size_t length, const
    AlgorithmIdentifier *digest_alg, hx509_cert cert, hx509_peer_info
    peer, hx509_certs anchors, hx509_certs pool, heim_octet_string
    *signed_data)

These are the functions. Yes bestie, they're C, they're long, they're giving main character energy. 🫶

---

🌈 DETAILED DESCRIPTION 🌈

So like, for the actual description and examples? Go check out the CMS/PKCS7 message functions. That's where the tea is. This page is just the function-by-function receipts. 💅

---

🌸 FUNCTION DOCUMENTATION 🌸

---

🦋 int hx509_cms_create_signed_1

int hx509_cms_create_signed_1 (hx509_context context, int flags, const
    heim_oid * eContentType, const void * data, size_t length, const
    AlgorithmIdentifier * digest_alg, hx509_cert cert, hx509_peer_info peer,
    hx509_certs anchors, hx509_certs pool, heim_octet_string * signed_data)

Decode SignedData and verify that the signature is correct. (Yes, that's literally what the original says for this one — we're not editing, we're reporting. 😌)

Parameters — okay, going down the list, every single one:

• context — A hx509 context.
• flags — (no description given, it's just there, living its truth.)
• eContentType — the type of the data.
• data — data to sign.
• length — length of the data that data point to.
• digest_alg — digest algorithm to use, use NULL to get the default or the peer determined algorithm.
• cert — certificate to use for sign the data.
• peer — info about the peer the message to send the message to, like what digest algorithm to use.
• anchors — trust anchors that the client will use, used to polulate the certificates included in the message.
• pool — certificates to use in try to build the path to the trust anchors.
• signed_data — the output of the function, free with der_free_octet_string().

Returns — Returns an hx509 error code. ✨

---

🦋 int hx509_cms_envelope_1

int hx509_cms_envelope_1 (hx509_context context, int flags, hx509_cert cert,
    const void * data, size_t length, const heim_oid * encryption_type,
    const heim_oid * contentType, heim_octet_string * content)

Encrypt end encode EnvelopedData.

Encrypt and encode EnvelopedData. The data is encrypted with a random key and the the random key is encrypted with the certificates private key. This limits what private key type can be used to RSA. 🎀

Parameters:

• context — A hx509 context.
• flags — flags to control the behavior.
  • HX509_CMS_EV_NO_KU_CHECK — Don't check KU on certificate
  • HX509_CMS_EV_ALLOW_WEAK — Allow weak crytpo
  • HX509_CMS_EV_ID_NAME — prefer issuer name and serial number
• cert — Certificate to encrypt the EnvelopedData encryption key with.
• data — pointer the data to encrypt.
• length — length of the data that data point to.
• encryption_type — Encryption cipher to use for the bulk data, use NULL to get default.
• contentType — type of the data that is encrypted.
• content — the output of the function, free with der_free_octet_string().

Returns — an hx509 error code. 💜

---

🦋 int hx509_cms_unenvelope

int hx509_cms_unenvelope (hx509_context context, hx509_certs certs, int
    flags, const void * data, size_t length, const heim_octet_string *
    encryptedContent, time_t time_now, heim_oid * contentType,
    heim_octet_string * content)

Decode and unencrypt EnvelopedData.

Extract data and parameteres from from the EnvelopedData. Also supports using detached EnvelopedData. Obsessed with the flexibility honestly. 🌈

Parameters:

• context — A hx509 context.
• certs — Certificate that can decrypt the EnvelopedData encryption key.
• flags — HX509_CMS_UE flags to control the behavior.
• data — pointer the structure the contains the DER/BER encoded EnvelopedData stucture.
• length — length of the data that data point to.
• encryptedContent — in case of detached signature, this contains the actual encrypted data, othersize its should be NULL.
• time_now — set the current time, if zero the library uses now as the date.
• contentType — output type oid, should be freed with der_free_oid().
• content — the data, free with der_free_octet_string().

Returns — an hx509 error code. ✨

---

🦋 int hx509_cms_unwrap_ContentInfo

int hx509_cms_unwrap_ContentInfo (const heim_octet_string * in, heim_oid *
    oid, heim_octet_string * out, int * have_data)

Decode an ContentInfo and unwrap data and oid it.

Parameters:

• in — the encoded buffer.
• oid — type of the content.
• out — data to be wrapped.
• have_data — since the data is optional, this flags show dthe diffrence between no data and the zero length data. (Very important distinction bestie, like "no thoughts" vs "one (1) thought, empty" 💀)

Returns — Returns an hx509 error code. 🫶

---

🦋 int hx509_cms_verify_signed

int hx509_cms_verify_signed (hx509_context context, hx509_verify_ctx ctx,
    unsigned int flags, const void * data, size_t length, const
    heim_octet_string * signedContent, hx509_certs pool, heim_oid *
    contentType, heim_octet_string * content, hx509_certs * signer_certs)

Decode SignedData and verify that the signature is correct.

Parameters:

• context — A hx509 context.
• ctx — a hx509 verify context.
• flags — to control the behaivor of the function.
  • HX509_CMS_VS_NO_KU_CHECK — Don't check KeyUsage
  • HX509_CMS_VS_ALLOW_DATA_OID_MISMATCH — allow oid mismatch
  • HX509_CMS_VS_ALLOW_ZERO_SIGNER — no signer, see below.
• data — pointer to CMS SignedData encoded data.
• length — length of the data that data point to.
• signedContent — external data used for signature.
• pool — certificate pool to build certificates paths.
• contentType — free with der_free_oid().
• content — the output of the function, free with der_free_octet_string().
• signer_certs — list of the cerficates used to sign this request, free with hx509_certs_free().

Returns — an hx509 error code.

---

Okay now the ✨special flag lore✨, and these are IMPORTANT, so listen up:

If HX509_CMS_VS_NO_KU_CHECK is set, allow more liberal search for matching certificates by not considering KeyUsage bits on the certificates.

If HX509_CMS_VS_ALLOW_DATA_OID_MISMATCH, allow encapContentInfo mismatch with the oid in signedAttributes (or if no signedAttributes where use, pkcs7-data oid). This is only needed to work with broken CMS implementations that doesn't follow CMS signedAttributes rules. Like bestie... do better. 😭

If HX509_CMS_VS_NO_VALIDATE flags is set, do not verify the signing certificates and leave that up to the caller. (You're on your own, good luck, you got this 👑)

If HX509_CMS_VS_ALLOW_ZERO_SIGNER is set, allow empty SignerInfo (no signatures). If SignedData have no signatures, the function will return 0 with signer_certs set to NULL. Zero signers is allowed by the standard, but since its only useful in corner cases, it make into a flag that the caller have to turn on. 💅

---

🦋 int hx509_cms_wrap_ContentInfo

int hx509_cms_wrap_ContentInfo (const heim_oid * oid, const
    heim_octet_string * buf, heim_octet_string * res)

Wrap data and oid in a ContentInfo and encode it.

Parameters:

• oid — type of the content.
• buf — data to be wrapped. If a NULL pointer is passed in, the optional content field in the ContentInfo is not going be filled in.
• res — the encoded buffer, the result should be freed with der_free_octet_string().

Returns — Returns an hx509 error code. 🌸

---

👑 AUTHOR 👑

Generated automatically by Doxygen for Heimdal x509 library from the source code. Not me, bestie — the robots wrote this one. 🤖✨

---

And that's the whole page, fr fr. 🎀 This was Version 7.8.0, dated Tue Nov 15 2022, and the manual is hx509_cms(3) — that's the Heimdal x509 library's very own page. Now go build something iconic with it. 💖🦋