PHP RFC: Add CMS Support

• Version: 0.9
• Date: 2020-05-11
• Author: Eliot Lear, lear@lear.ch
• Status: Draft
• First Published at: http://wiki.php.net/rfc/add-cms-support

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:

As currently stands, the CMS sign and verify functions now can take as an argument the encoding method (DER/CMS/PEM).

The calling interface is as follows:

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 = ENCODING_CMS ): bool {}
 
function openssl_cms_encrypt(string $infile, string $outfile, $recipcerts, ?array $headers, int $flags = 0, int $cipher = OPENSSL_CIPHER_RC2_40): bool {}
function openssl_cms_sign(string $infile, string $outfile, $signcert, $signkey, ?array $headers, int $flags = 0, int $encoding = OPENSSL_ENCODING_CMS, ?string $extracertsfilename = null): bool {}
function openssl_cms_decrypt(string $infilename, string $outfilename, $recipcert, $recipkey = UNKNOWN): bool {}
function openssl_cms_read(string $infilename, &$certs): bool {}

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.

openssl code is extended. No existing functions are changed.

These are entirely file operations.

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) */

No change.

Currently encoding isn't passed to the encrypt, decrypt, and read operations.

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. It may make sense to take strings as input and deliver strings as output. However, existing use cases do not require this, and any such change could be backward compatible with a new flag.

Include these so readers know where you are heading and can discuss the proposed voting options.

This capability is available for inspection as PR5251. Tests are available in that PR. This PR is subject to change of course, based on community feedback.

After the project is implemented, this section should contain

1. the version(s) it was merged into
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature
4. a link to the language specification section (if any)

1. RFC 5652
2. RFC 8520

Keep this updated with features that were discussed on the mail lists.