Module cms

cms module for lua-openssl binding

The Cryptographic Message Syntax (CMS) is the IETF’s standard for cryptographically protected messages.

It can be used to digitally sign, digest, authenticate or encrypt any form of digital data. CMS is based on the syntax of PKCS#7, which in turn is based on the Privacy-Enhanced Mail standard. The newest version of CMS is specified in RFC 5652.

The architecture of CMS is built around certificate-based key management, such as the profile defined by the PKIX working group. CMS is used as the key cryptographic component of many other cryptographic standards, such as S/MIME, PKCS #12 and the RFC 3161 Digital timestamping protocol.

OpenSSL is open source software that can encrypt, decrypt, sign and verify, compress and uncompress CMS documents.

CMS are based on apps/cms.c from the OpenSSL dist, so for more information, you better see the documentation for OpenSSL. cms api need flags, not support “detached”, “nodetached”, “text”, “nointern”, “noverify”, “nochain”, “nocerts”, “noattr”, “binary”, “nosigs”

OpenSSL not give full document about CMS api, so some function will be dangers.

Usage:

    cms = require('openssl').cms
    

Functions

read (input[, format='auto'[, content=nil]]) read cms object from input bio or string
export (cms[, data[, flags=0[, format='smime']]]) write cms object to bio object
new () create empty cms object
data_create (input[, flags=0]) create cms object from string or bio object
compress (input, alg[, flags=0]) create compress cms object
uncompress (cms[, dcent=nil[, flags=0]]) uncompress cms object
sign (signer, pkey, input_data[, certs[, flags=0]]) make signed cms object
verify (signed, signers[, store[, message[, flags=0]]]) verfiy signed cms object
EncryptedData_encrypt (input, key[, cipher_alg='des-ede3-cbc'[, flags=0]]) create enryptdata cms
EncryptedData_decrypt (encrypted, key[, dcont[, flags=0]]) decrypt encryptdata cms
digest_create (input[, digest_alg='sha256'[, flags=0]]) create digest cms
digest_verify (digested[, dcont[, flags=0]]) verify digest cms
encrypt (recipt, input[, cipher_alg='des-ede3-cbc'[, flags=0[, options=nil]]]) encrypt with recipt certs
decrypt (message, pkey, recipt[, dcount[, flags=0[, options=nil]]]) decrypt cms message

Class cms

cms:type () get type of cms object
cms:detached (cmsbio) get detached state
cms:detached (detach) set detached state
cms:content () get content of cms object
cms:add_signers (cms, signer, pkey) add signers to CMS structure
cms:get_signers (cms) get signers from CMS structure
cms:data ([flags=0]) extract the data content from CMS object
cms:final (input[, flags=CMS_STREAM]) finalize CMS object processing with provided input
cms:add_receipt ([receipt_to[, receipt_from[, all_or_first]]]) add receipt request to CMS structure
cms:sign_receipt (signcert, pkey[, other[, flags]]) sign receipt for CMS message
cms:verify_receipt (rcms, cms[, other], store[, flags]) verify receipt for CMS message


Functions

read (input[, format='auto'[, content=nil]])
read cms object from input bio or string

Parameters:

  • input bio or string
  • format string , support ‘auto’,‘smime’,‘der’,‘pem’ auto will only try ‘der’ or ‘pem’ (default 'auto')
  • content bio , only used when format is ‘smime’ (default nil)

Returns:

    cms
export (cms[, data[, flags=0[, format='smime']]])
write cms object to bio object

Parameters:

  • cms cms
  • data bio (optional)
  • flags number (default 0)
  • format string (default 'smime')

Returns:

  1. string
  2. nil, and followed by error message
new ()
create empty cms object

Returns:

    cms
data_create (input[, flags=0])
create cms object from string or bio object

Parameters:

  • input bio
  • flags number (default 0)

Returns:

    cms
compress (input, alg[, flags=0])
create compress cms object

Parameters:

  • input bio
  • alg string , zlib or rle
  • flags number (default 0)

Returns:

    cms
uncompress (cms[, dcent=nil[, flags=0]])
uncompress cms object

Parameters:

  • cms cms
  • dcent bio default nil for normal, in the rare case where the compressed content is detached. (default nil)
  • flags number (default 0)

Returns:

    string
sign (signer, pkey, input_data[, certs[, flags=0]])
make signed cms object

Parameters:

  • signer x509 cert
  • pkey evp_pkey
  • input_data bio
  • certs stack_of_x509 include in the CMS (optional)
  • flags number (default 0)

Returns:

    cms object
verify (signed, signers[, store[, message[, flags=0]]])
verfiy signed cms object

Parameters:

  • signed cms
  • signers stack_of_x509
  • store x509_store trust certificates store (optional)
  • message bio (optional)
  • flags number (default 0)

Returns:

  1. string content
  2. nil, and followed by error message
EncryptedData_encrypt (input, key[, cipher_alg='des-ede3-cbc'[, flags=0]])
create enryptdata cms

Parameters:

  • input bio or string
  • key strig
  • cipher_alg string or evp_cipher (default 'des-ede3-cbc')
  • flags number (default 0)

Returns:

  1. cms object
  2. nil, followed by error message
EncryptedData_decrypt (encrypted, key[, dcont[, flags=0]])
decrypt encryptdata cms

Parameters:

  • encrypted cms
  • key string
  • dcont bio (optional)
  • flags number (default 0)

Returns:

    boolean result
digest_create (input[, digest_alg='sha256'[, flags=0]])
create digest cms

Parameters:

  • input bio or string
  • digest_alg string or evp_md (default 'sha256')
  • flags number (default 0)

Returns:

  1. cms object
  2. nil, followed by error message
digest_verify (digested[, dcont[, flags=0]])
verify digest cms

Parameters:

  • digested cms
  • dcont string or bio (optional)
  • flags number (default 0)

Returns:

    boolean result
encrypt (recipt, input[, cipher_alg='des-ede3-cbc'[, flags=0[, options=nil]]])
encrypt with recipt certs

Parameters:

  • recipt stack_of_x509 certs
  • input bio or string
  • cipher_alg string or evp_cipher (default 'des-ede3-cbc')
  • flags number (default 0)
  • options table , support key, keyid, password fields, and values must be string type (default nil)

Returns:

    cms
decrypt (message, pkey, recipt[, dcount[, flags=0[, options=nil]]])
decrypt cms message

Parameters:

  • message cms
  • pkey evp_pkey
  • recipt x509
  • dcount bio output object (optional)
  • flags number (default 0)
  • options table may have key, keyid, password field, and values must be string type (default nil)

Returns:

  1. string decrypted message
  2. nil, and followed by error message

Class cms

openssl.cms object
cms:type ()
get type of cms object

Returns:

    asn1_object type of cms
cms:detached (cmsbio)
get detached state

Parameters:

  • cmsbio bio bio returned by datainit

Returns:

  1. boolean true for detached
  2. boolean true for success, others value will followed by error message
cms:detached (detach)
set detached state

Parameters:

  • detach boolean

Returns:

    boolean for success, others value will followed by error message
cms:content ()
get content of cms object

Returns:

    string content, if have no content will return nil
cms:add_signers (cms, signer, pkey)
add signers to CMS structure

Parameters:

  • cms cms object to add signers to
  • signer x509 certificate for signing
  • pkey evp_pkey private key for signing

Returns:

    boolean result
cms:get_signers (cms)
get signers from CMS structure

Parameters:

  • cms cms object to get signers from

Returns:

    table array of x509 certificates
cms:data ([flags=0])
extract the data content from CMS object

Parameters:

  • flags number optional flags for data extraction (default 0)

Returns:

    string extracted data content
cms:final (input[, flags=CMS_STREAM])
finalize CMS object processing with provided input

Parameters:

  • input string or bio data to finalize the CMS with
  • flags number optional flags for finalization (default CMS_STREAM)

Returns:

    boolean true on success, false on failure
cms:add_receipt ([receipt_to[, receipt_from[, all_or_first]]])
add receipt request to CMS structure

Parameters:

  • receipt_to table array of recipient emails (optional)
  • receipt_from table array of sender emails (optional)
  • all_or_first boolean request receipt from all or first recipient (optional)

Returns:

    boolean result true for success
cms:sign_receipt (signcert, pkey[, other[, flags]])
sign receipt for CMS message

Parameters:

  • signcert x509 certificate to use for signing receipt
  • pkey evp_pkey private key for signing
  • other table additional certificates (optional)
  • flags number signing flags (optional)

Returns:

    cms signed receipt CMS object or nil if failed
cms:verify_receipt (rcms, cms[, other], store[, flags])
verify receipt for CMS message

Parameters:

  • rcms cms receipt CMS object to verify
  • cms cms original CMS object
  • other table additional certificates (optional)
  • store x509_store certificate store for verification
  • flags number verification flags (optional)

Returns:

    boolean result true if receipt is valid
generated by LDoc 1.5.0 Last updated 2025-09-22 19:55:54