PHP has for some time incorporated support for PKCS#7 sign, verify, encrypt, decrypt, and read operations. Cryptographic Message Syntax (CMS) is a newer version of PKCS#7. Having been around some time, CMS is used in both email messaging as well as signature verification operations relating to IoT devices.
It is proposed that analogous functions be created for CMS. These would be as follows:
| PKCS#7 function | new CMS function |
|---|---|
| openssl_pkcs7_encrypt() | openssl_cms_encrypt() |
| openssl_pkcs7_decrypt() | openssl_cms_decrypt() |
| openssl_pkcs7_sign() | openssl_cms_sign() |
| openssl_pkcs7_verify () | openssl_cms_verify() |
| openssl_pkcs7_read () | openssl_cms_read() |
As currently stands, the CMS sign and verify functions now can take as an argument the encoding method (DER/CMS/PEM).
function openssl_cms_sign(string $infile, string $outfile, $signcert, $signkey, ?array $headers, int $flags = 0, int $encoding = OPENSSL_ENCODING_SMIME, ?string $extracertsfilename = null): bool {}
This function signs a file with an X.509 certificate and key.
Arguments:
function openssl_cms_verify(string $filename, int $flags = 0, string $signerscerts = UNKNOWN, array $cainfo = UNKNOWN, string $extracerts = UNKNOWN, string $content = UNKNOWN, string $pk7 = UNKNOWN, string $sigfile = UNKNOWN, $encoding = OPENSSL_ENCODING_SMIME ): bool {}
This function verifies a CMS signature, either attached or detached, with the specified encoding.
Arguments:
Returns TRUE on success and FALSE on failure.
function openssl_cms_encrypt(string $infile, string $outfile, $recipcerts, ?array $headers, int $flags = 0, int $encoding = OPENSSL_ENCODING_SMIME, int $cipher = OPENSSL_CIPHER_RC2_40): bool {}
This function encrypts content to one or more recipients, based on the certificates that are passed to it.
Arguments:
Return values: TRUE on success or FALSE on failure.
function openssl_cms_decrypt(string $infilename, string $outfilename, $recipcert, $recipkey = UNKNOWN, int $encoding = OPENSSL_ENCODING_SMIME): bool {}
Decrypts a CMS message.
Arguments:
Returns TRUE on success and FALSE on failure.
function openssl_cms_read(string $infilename, &$certs): bool {}
Performs the exact analog to openssl_pkcs7_read().
This is nearly identical to the PKCS#7 calling interface, the only exception being $encoding.
None.
PHP 8.0
The only change is an additional API. No modifications to existing APIs.
New functions are added to ext/openssl. No existing functions are changed.
No known impact.
Several new constants are defined to indicate encoding, as follows:
OPENSSL_ENCODING_CMS /* encoding is a CMS-encoded message */ OPENSSL_ENCODING_DER /* encoding is DER (Distinguished Encoding Rules) */ OPENSSL_ENCODING_PEM /* encoding is PEM (Privacy-Enhanced Mail) */
The following analogs to PKCS#7 are also added:
OPENSSL_CMS_DETACHED OPENSSL_CMS_TEXT OPENSSL_CMS_NOINTERN OPENSSL_CMS_NOVERIFY OPENSSL_CMS_NOCERTS OPENSSL_CMS_NOATTR OPENSSL_CMS_BINARY OPENSSL_CMS_NOSIGS
No change.
No known issues.
As these are new functions, no side effects to other functions should be expected.
Currently, as with the PKCS#7 calls, these calls take files as arguments. Future work should focus on in-memory signing/encrypting/verifying/decrypting operations.
Include these so readers know where you are heading and can discuss the proposed voting options.
This capability is available for inspection as PR #5251. Tests are available in that PR. This PR is subject to change of course, based on community feedback.
Yes/No.
After the project is implemented, this section should contain
Keep this updated with features that were discussed on the mail lists.