openssl_x509_fingerprint calculates a fingerprint digest of an X.509 certificate, usually displayed as hexadecimal text.
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_fingerprint calculates a fingerprint digest of an X.509 certificate, usually displayed as hexadecimal text.
The OpenSSL extension must be enabled.
Syntax and Return Value
openssl_x509_fingerprint(OpenSSLCertificate|string $certificate, string $digest_algo = ..., bool $binary = ...): string|false| Parameter | Purpose |
|---|---|
| $certificate (OpenSSLCertificate|string) | The recipient or signing certificate, issued or trusted for the intended use. |
| $digest_algo (string) | Use the PHP signature above to determine the exact expected input type; validate untrusted inputs before calling. |
| $binary (bool) | 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'); }
echo openssl_x509_fingerprint($cert, "sha256");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'); }
echo openssl_x509_fingerprint($cert, "sha256");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'); }
echo openssl_x509_fingerprint($cert, "sha256");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_fingerprint | openssl_x509_fingerprint calculates a fingerprint digest of an X.509 certificate, usually displayed as hexadecimal text. |
| 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_fingerprint calculates a fingerprint digest of an X.509 certificate, usually displayed as hexadecimal text.
- 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.