openssl_cms_sign signs a file into a CMS message container using a certificate and matching private key.
The examples explain the data format, expected results and the difference between this API and nearby cryptographic operations.
What It Does
The operation is intended for: openssl_cms_sign signs a file into a CMS message container using a certificate and matching private key.
The OpenSSL extension must be enabled.
Syntax and Return Value
openssl_cms_sign(string $input_filename, string $output_filename, OpenSSLCertificate|string $certificate, $private_key, ?array $headers, int $flags = ..., int $encoding = ..., ?string $untrusted_certificates_filename = ...): bool| Parameter | Purpose |
|---|---|
| $input_filename (string) | Path to the file read by the CMS or PKCS#7 operation. |
| $output_filename (string) | Path to the resulting file; ensure permissions and cleanup are appropriate. |
| $certificate (OpenSSLCertificate|string) | The recipient or signing certificate, issued or trusted for the intended use. |
| $private_key (mixed) | The corresponding private key; never expose or log its PEM data. |
| $headers (?array) | Use the PHP signature above to determine the exact expected input type; validate untrusted inputs before calling. |
| $flags (int) | Behavior-control flags defined by the specific PHP extension. |
| $encoding (int) | Use the PHP signature above to determine the exact expected input type; validate untrusted inputs before calling. |
| $untrusted_certificates_filename (?string) | Use the PHP signature above to determine the exact expected input type; validate untrusted inputs before calling. |
The declared return type is shown above. Errors can include false results or exceptions depending on this API: Encrypted CMS data requires matching recipient certificate and private key; signing and verification additionally require certificate trust validation.
Example 1: Basic Operation
The local certificate is self-signed for demonstration; signature acceptance here does not verify a trusted CA chain.
<?php
$private = openssl_pkey_new(['private_key_type' => OPENSSL_KEYTYPE_RSA, 'private_key_bits' => 2048]);
if ($private === false) { throw new RuntimeException('Key generation failed'); }
$details = openssl_pkey_get_details($private);
$public = $details['key'];
$csr = openssl_csr_new(['commonName' => 'test.example'], $private, ['digest_alg' => 'sha256']);
if ($csr === false) { throw new RuntimeException('CSR creation failed'); }
$cert = openssl_csr_sign($csr, null, $private, 1, ['digest_alg' => 'sha256']);
if ($cert === false) { throw new RuntimeException('Certificate creation failed'); }
$input = tempnam(sys_get_temp_dir(), 'cms_input_');
$output = tempnam(sys_get_temp_dir(), 'cms_output_');
$decoded = tempnam(sys_get_temp_dir(), 'cms_plain_');
$certPath = tempnam(sys_get_temp_dir(), 'cms_cert_');
$keyPath = tempnam(sys_get_temp_dir(), 'cms_key_');
file_put_contents($input, 'Private message for recipient');
openssl_x509_export($cert, $certPem);
openssl_pkey_export($private, $keyPem);
file_put_contents($certPath, $certPem);
file_put_contents($keyPath, $keyPem);
var_dump(openssl_cms_sign($input, $output, $cert, $private, []));
foreach ([$input,$output,$decoded,$certPath,$keyPath] as $file) { @unlink($file); }Example 2: A Different Use Case
Exercise the container operation with a different document, including binary document bytes.
<?php
// Check the alternative case.
$private = openssl_pkey_new(['private_key_type' => OPENSSL_KEYTYPE_RSA, 'private_key_bits' => 2048]);
if ($private === false) { throw new RuntimeException('Key generation failed'); }
$details = openssl_pkey_get_details($private);
$public = $details['key'];
$csr = openssl_csr_new(['commonName' => 'test.example'], $private, ['digest_alg' => 'sha256']);
if ($csr === false) { throw new RuntimeException('CSR creation failed'); }
$cert = openssl_csr_sign($csr, null, $private, 1, ['digest_alg' => 'sha256']);
if ($cert === false) { throw new RuntimeException('Certificate creation failed'); }
$input = tempnam(sys_get_temp_dir(), 'cms_input_');
$output = tempnam(sys_get_temp_dir(), 'cms_output_');
$decoded = tempnam(sys_get_temp_dir(), 'cms_plain_');
$certPath = tempnam(sys_get_temp_dir(), 'cms_cert_');
$keyPath = tempnam(sys_get_temp_dir(), 'cms_key_');
file_put_contents($input, 'A second authenticated document');
openssl_x509_export($cert, $certPem);
openssl_pkey_export($private, $keyPem);
file_put_contents($certPath, $certPem);
file_put_contents($keyPath, $keyPem);
var_dump(openssl_cms_sign($input, $output, $cert, $private, []));
foreach ([$input,$output,$decoded,$certPath,$keyPath] as $file) { @unlink($file); }Practical Example: Checking the Result
Exercise the container operation with a different document, including binary document bytes.
<?php
// Verify the expected behavior before using results.
$private = openssl_pkey_new(['private_key_type' => OPENSSL_KEYTYPE_RSA, 'private_key_bits' => 2048]);
if ($private === false) { throw new RuntimeException('Key generation failed'); }
$details = openssl_pkey_get_details($private);
$public = $details['key'];
$csr = openssl_csr_new(['commonName' => 'test.example'], $private, ['digest_alg' => 'sha256']);
if ($csr === false) { throw new RuntimeException('CSR creation failed'); }
$cert = openssl_csr_sign($csr, null, $private, 1, ['digest_alg' => 'sha256']);
if ($cert === false) { throw new RuntimeException('Certificate creation failed'); }
$input = tempnam(sys_get_temp_dir(), 'cms_input_');
$output = tempnam(sys_get_temp_dir(), 'cms_output_');
$decoded = tempnam(sys_get_temp_dir(), 'cms_plain_');
$certPath = tempnam(sys_get_temp_dir(), 'cms_cert_');
$keyPath = tempnam(sys_get_temp_dir(), 'cms_key_');
file_put_contents($input, random_bytes(48));
openssl_x509_export($cert, $certPem);
openssl_pkey_export($private, $keyPem);
file_put_contents($certPath, $certPem);
file_put_contents($keyPath, $keyPem);
var_dump(openssl_cms_sign($input, $output, $cert, $private, []));
foreach ([$input,$output,$decoded,$certPath,$keyPath] as $file) { @unlink($file); }Important Behavior and Edge Cases
Encrypted CMS data requires matching recipient certificate and private key; signing and verification additionally require certificate trust validation.
These file-based APIs write encoded containers. The self-signed test certificate used in examples is not production trust material.
Comparison with Related Functions
| Approach | Key distinction |
|---|---|
| openssl_cms_sign | openssl_cms_sign signs a file into a CMS message container using a certificate and matching private key. |
| Related technique | CMS operations use files and encoding flags; raw openssl_encrypt handles byte strings instead. |
Common Beginner Mistakes
| Mistake | Correct approach |
|---|---|
| Confusing this operation with a neighboring cryptographic or security mechanism | CMS operations use files and encoding flags; raw openssl_encrypt handles byte strings instead. |
| Ignoring a security prerequisite or failure case | Encrypted CMS data requires matching recipient certificate and private key; signing and verification additionally require certificate trust validation. |
Key Takeaways
- openssl_cms_sign signs a file into a CMS message container using a certificate and matching private key.
- Encrypted CMS data requires matching recipient certificate and private key; signing and verification additionally require certificate trust validation.
- CMS operations use files and encoding flags; raw openssl_encrypt handles byte strings instead.
Apply this behavior to a real application only after confirming the required extension, configuration and failure handling on the deployment runtime.