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
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:
- export (cms[, data[, flags=0[, format='smime']]])
-
write cms object to bio object
Parameters:
Returns:
- string
- nil, and followed by error message
- new ()
-
create empty cms object
Returns:
- data_create (input[, flags=0])
-
create cms object from string or bio object
Parameters:
- input bio
- flags number (default 0)
Returns:
- compress (input, alg[, flags=0])
-
create compress cms object
Parameters:
- input bio
- alg string , zlib or rle
- flags number (default 0)
Returns:
- 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:
- 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:
- string content
- 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:
- cms object
- nil, followed by error message
- EncryptedData_decrypt (encrypted, key[, dcont[, flags=0]])
-
decrypt encryptdata cms
Parameters:
Returns:
-
boolean
result
- digest_create (input[, digest_alg='sha256'[, flags=0]])
-
create digest cms
Parameters:
Returns:
- cms object
- nil, followed by error message
- digest_verify (digested[, dcont[, flags=0]])
-
verify digest cms
Parameters:
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:
- 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:
- string decrypted message
- 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:
- boolean true for detached
- 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