openssl_x509_checkpurpose checks a certificate for a requested X.509 purpose using supplied CA-trust information where applicable.
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_x509_checkpurpose checks a certificate for a requested X.509 purpose using supplied CA-trust information where applicable.
The OpenSSL extension must be enabled.
Syntax and Return Value
openssl_x509_checkpurpose(OpenSSLCertificate|string $certificate, int $purpose, array $ca_info = ..., ?string $untrusted_certificates_file = ...): int|bool| Parameter | Purpose |
|---|---|
| $certificate (OpenSSLCertificate|string) | The recipient or signing certificate, issued or trusted for the intended use. |
| $purpose (int) | Use the PHP signature above to determine the exact expected input type; validate untrusted inputs before calling. |
| $ca_info (array) | Use the PHP signature above to determine the exact expected input type; validate untrusted inputs before calling. |
| $untrusted_certificates_file (?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: A valid signature, key match or fingerprint alone does not prove hostname identity, certificate chain trust or revocation status.
Example 1: Basic Operation
These checks are not equivalent to verifying a certificate chain and hostname for TLS.
<?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'); }
$trusted = tempnam(sys_get_temp_dir(), 'ca_');
openssl_x509_export($cert, $pem);
file_put_contents($trusted, $pem);
var_dump(openssl_x509_checkpurpose($cert, X509_PURPOSE_SSL_SERVER, [$trusted]) === true);
unlink($trusted);Example 2: A Different Use Case
Use a separately generated certificate to inspect the same operation on another identity.
<?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' => 'alternate.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'); }
$trusted = tempnam(sys_get_temp_dir(), 'ca_');
openssl_x509_export($cert, $pem);
file_put_contents($trusted, $pem);
var_dump(openssl_x509_checkpurpose($cert, X509_PURPOSE_SSL_SERVER, [$trusted]) === true);
unlink($trusted);Practical Example: Checking the Result
Use a separately generated certificate to inspect the same operation on another identity.
<?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' => 'production.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'); }
$trusted = tempnam(sys_get_temp_dir(), 'ca_');
openssl_x509_export($cert, $pem);
file_put_contents($trusted, $pem);
var_dump(openssl_x509_checkpurpose($cert, X509_PURPOSE_SSL_SERVER, [$trusted]) === true);
unlink($trusted);Important Behavior and Edge Cases
A valid signature, key match or fingerprint alone does not prove hostname identity, certificate chain trust or revocation status.
Key-matching, certificate parsing and signature verification are separate from chain-of-trust, hostname and revocation validation.
Comparison with Related Functions
| Approach | Key distinction |
|---|---|
| openssl_x509_checkpurpose | openssl_x509_checkpurpose checks a certificate for a requested X.509 purpose using supplied CA-trust information where applicable. |
| Related technique | Use full TLS peer verification for HTTPS instead of assembling trust checks from these helpers alone. |
Common Beginner Mistakes
| Mistake | Correct approach |
|---|---|
| Confusing this operation with a neighboring cryptographic or security mechanism | Use full TLS peer verification for HTTPS instead of assembling trust checks from these helpers alone. |
| Ignoring a security prerequisite or failure case | A valid signature, key match or fingerprint alone does not prove hostname identity, certificate chain trust or revocation status. |
Key Takeaways
- openssl_x509_checkpurpose checks a certificate for a requested X.509 purpose using supplied CA-trust information where applicable.
- A valid signature, key match or fingerprint alone does not prove hostname identity, certificate chain trust or revocation status.
- Use full TLS peer verification for HTTPS instead of assembling trust checks from these helpers alone.
Apply this behavior to a real application only after confirming the required extension, configuration and failure handling on the deployment runtime.