\

src/site/php/openssl fix.php

Classes

OpenSSLAsymmetricKey A key, holding PEM text rather than a native handle.
OpenSSLCertificate A certificate, holding its PEM text.

Constants

OPENSSL_VERSION_TEXT

OPENSSL_VERSION_TEXT = 'BoringSSL (node:crypto)'

Functions

cfw_openssl_installed()

cfw_openssl_installed() : bool

Returns

bool —

cfw_sign_call()

cfw_sign_call(array  $payload) : array<string,mixed>

Runs one op over the bridge.

Parameters

array $payload

The request, including its op.

Returns

array —

The decoded reply, always with an 'ok' key.

cfw_openssl_degraded()

cfw_openssl_degraded(string  $capability, string  $why) : void

Declares a failure to the operator, the way curl-fix.ts does.

A per-call trigger_error reaches the log and never the status report, and a failed verify had neither -- so a caller misreading -1 as "forged" was invisible from outside.

Parameters

string $capability

The capability that degraded.
string $why

Why it did.

Returns

void —

cfw_openssl_pem()

cfw_openssl_pem(\OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string  $key, string  $want) : string

The PEM text for whatever ext-openssl would accept as a key or certificate.

Parameters

\OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string $key

A key object, a certificate object, a two-key array, a PEM or a file:// path.
string $want

'private' for the private half, 'public' for the public half or a certificate.

Returns

string —

openssl_error_string()

openssl_error_string() : string|false

Returns

string|false —

openssl_random_pseudo_bytes()

openssl_random_pseudo_bytes(int  $length, bool|null  $strong_result = null) : string

Parameters

int $length

The number of bytes.
bool|null $strong_result

Set to TRUE, since the bytes come from random_bytes().

Returns

string —

openssl_get_cipher_methods()

openssl_get_cipher_methods(bool  $aliases = false) : list<string>

Parameters

bool $aliases

Ignored; there are no aliases here.

Returns

list —

cfw_openssl_cipher()

cfw_openssl_cipher(string  $cipher) : array{0: int, 1: int, 2: string}|null

Key and IV length for a supported cipher, or NULL.

Parameters

string $cipher

A cipher name.

Returns

array{0: int, 1: int, 2: string}|null —

[key bytes, iv bytes, mode].

openssl_cipher_iv_length()

openssl_cipher_iv_length(string  $cipher_algo) : int|false

Parameters

string $cipher_algo

A cipher name.

Returns

int|false —

openssl_cipher_key_length()

openssl_cipher_key_length(string  $cipher_algo) : int|false

Parameters

string $cipher_algo

A cipher name.

Returns

int|false —

cfw_openssl_crypt()

cfw_openssl_crypt(string  $dir, string  $data, string  $cipher_algo, string  $passphrase, int  $options, string  $iv, string|false|null  $tag, string  $aad, int  $tag_length) : array<string,mixed>|false

The shared half of encrypt and decrypt: key and IV sized the way ext-openssl sizes them.

A short key is padded with NUL and a long one truncated, silently, as ext-openssl does. A short IV is padded with a warning; a GCM IV keeps whatever length the caller gave.

Parameters

string $dir

'enc' or 'dec'.
string $data

The plaintext, or the ciphertext.
string $cipher_algo

A cipher name.
string $passphrase

The key material.
int $options

OPENSSL_RAW_DATA and OPENSSL_ZERO_PADDING flags.
string $iv

The initialisation vector.
string|false|null $tag

The GCM tag, on decrypt.
string $aad

Additional authenticated data, for GCM.
int $tag_length

The GCM tag length in bytes.

Returns

array|false —

The bridge reply, or FALSE for an unknown cipher or a malformed ciphertext.

openssl_encrypt()

openssl_encrypt(string  $data, string  $cipher_algo, string  $passphrase, int  $options = 0, string  $iv = '', string|false|null  $tag = null, string  $aad = '', int  $tag_length = 16) : string|false

Parameters

string $data

The plaintext.
string $cipher_algo

A cipher name.
string $passphrase

The key material.
int $options

OPENSSL_RAW_DATA and OPENSSL_ZERO_PADDING flags.
string $iv

The initialisation vector.
string|false|null $tag

Set to the GCM tag.
string $aad

Additional authenticated data, for GCM.
int $tag_length

The GCM tag length in bytes.

Returns

string|false —

openssl_decrypt()

openssl_decrypt(string  $data, string  $cipher_algo, string  $passphrase, int  $options = 0, string  $iv = '', string|false|null  $tag = null, string  $aad = '') : string|false

Parameters

string $data

The ciphertext.
string $cipher_algo

A cipher name.
string $passphrase

The key material.
int $options

OPENSSL_RAW_DATA and OPENSSL_ZERO_PADDING flags.
string $iv

The initialisation vector.
string|false|null $tag

The GCM tag.
string $aad

Additional authenticated data, for GCM.

Returns

string|false —

openssl_sign()

openssl_sign(string  $data, string|false|null  $signature, \OpenSSLAsymmetricKey|array|string  $private_key, int|string  $algorithm = 1) : bool

Parameters

string $data

The bytes to sign.
string|false|null $signature

Set to the raw signature.
\OpenSSLAsymmetricKey|array|string $private_key

The signing key.
int|string $algorithm

An OPENSSL_ALGO_* value or a digest name.

Returns

bool —

openssl_verify()

openssl_verify(string  $data, string  $signature, \OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string  $public_key, int|string  $algorithm = 1) : int

Answers 1, 0 or -1, matching ext-openssl.

-1 means the call itself failed -- an unreadable key, an unsupported digest -- and is NOT the same as 0, which means the signature was read and did not match. A caller treating -1 as "invalid" would report a broken key as a forged token.

Parameters

string $data

The signed bytes.
string $signature

The raw signature.
\OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string $public_key

The verification key.
int|string $algorithm

An OPENSSL_ALGO_* value or a digest name.

Returns

int —

openssl_pkey_get_public()

openssl_pkey_get_public(\OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string  $public_key) : \OpenSSLAsymmetricKey|false

Turns a PEM, a certificate or a JWKS entry into a public key openssl_verify() accepts.

THE MISSING STEP IN EVERY OIDC LIBRARY. A provider publishes a key SET, the library reads the entry it needs and hands it here.

Parameters

\OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string $public_key

A PEM, a certificate, a file:// path or a JWK array.

Returns

\OpenSSLAsymmetricKey|false —

The public key, or FALSE.

openssl_get_publickey()

openssl_get_publickey(\OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string  $public_key) : \OpenSSLAsymmetricKey|false

Parameters

\OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string $public_key

A PEM, a certificate, a file:// path or a JWK array.

Returns

\OpenSSLAsymmetricKey|false —

openssl_pkey_get_private()

openssl_pkey_get_private(\OpenSSLAsymmetricKey|array|string  $private_key, string|null  $passphrase = null) : \OpenSSLAsymmetricKey|false

Reads a private key, decrypting it with the passphrase when one was used to write it.

Parameters

\OpenSSLAsymmetricKey|array|string $private_key

A PEM, a key object or a file:// path.
string|null $passphrase

The passphrase the PEM was written with.

Returns

\OpenSSLAsymmetricKey|false —

The key, or FALSE.

openssl_get_privatekey()

openssl_get_privatekey(\OpenSSLAsymmetricKey|array|string  $private_key, string|null  $passphrase = null) : \OpenSSLAsymmetricKey|false

Parameters

\OpenSSLAsymmetricKey|array|string $private_key

A PEM, a key object or a file:// path.
string|null $passphrase

The passphrase the PEM was written with.

Returns

\OpenSSLAsymmetricKey|false —

openssl_pkey_get_details()

openssl_pkey_get_details(\OpenSSLAsymmetricKey|array|string  $key) : array<string,mixed>|false

What ext-openssl reports about a key: bits, the public PEM, the type and its parameters.

Parameters

\OpenSSLAsymmetricKey|array|string $key

The key to describe.

Returns

array|false —

The details, or FALSE.

openssl_pkey_new()

openssl_pkey_new(array|null  $options = null) : \OpenSSLAsymmetricKey|false

A new RSA or EC key pair.

Parameters

array|null $options

private_key_bits, private_key_type or curve_name.

Returns

\OpenSSLAsymmetricKey|false —

The key, or FALSE.

openssl_pkey_export()

openssl_pkey_export(\OpenSSLAsymmetricKey|array|string  $key, string|null  $out, string|null  $passphrase = null) : bool

Writes a private key out as PEM.

PASSPHRASES ARE REFUSED rather than ignored. ext-openssl encrypts the output when one is given, and answering with an UNENCRYPTED key to a caller who asked for an encrypted one would hand them a secret they believe is protected.

Parameters

\OpenSSLAsymmetricKey|array|string $key

The key to export.
string|null $out

Set to the PEM.
string|null $passphrase

Refused when not empty.

Returns

bool —

TRUE on success.

openssl_pkey_derive()

openssl_pkey_derive(\OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string  $public_key, \OpenSSLAsymmetricKey|array|string  $private_key, int  $key_length = 0) : string|false

ECDH: the shared secret between a private key and a peer public key.

Parameters

\OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string $public_key

The peer's public key.
\OpenSSLAsymmetricKey|array|string $private_key

This side's private key.
int $key_length

Truncate the secret to this many bytes, or 0 for all of it.

Returns

string|false —

The secret, or FALSE.

openssl_pkey_free()

openssl_pkey_free(\OpenSSLAsymmetricKey  $key) : void

Parameters

\OpenSSLAsymmetricKey $key

Returns

void —

openssl_free_key()

openssl_free_key(\OpenSSLAsymmetricKey  $key) : void

Parameters

\OpenSSLAsymmetricKey $key

Returns

void —

openssl_x509_free()

openssl_x509_free(\OpenSSLCertificate  $certificate) : void

Parameters

\OpenSSLCertificate $certificate

Returns

void —

openssl_private_encrypt()

openssl_private_encrypt(string  $data, string|false|null  $encrypted_data, \OpenSSLAsymmetricKey|array|string  $private_key, int  $padding = 1) : bool

RSA sign-with-private, which is what a legacy licence check or an older SSO handshake uses.

Parameters

string $data

The bytes to encrypt.
string|false|null $encrypted_data

Set to the result.
\OpenSSLAsymmetricKey|array|string $private_key

The key.
int $padding

An OPENSSL_*_PADDING value; ignored here.

Returns

bool —

TRUE on success.

openssl_public_decrypt()

openssl_public_decrypt(string  $data, string|false|null  $decrypted_data, \OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string  $public_key, int  $padding = 1) : bool

The other half of the pair above.

Parameters

string $data

The bytes to decrypt.
string|false|null $decrypted_data

Set to the result.
\OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string $public_key

The key.
int $padding

An OPENSSL_*_PADDING value; ignored here.

Returns

bool —

TRUE on success.

openssl_public_encrypt()

openssl_public_encrypt(string  $data, string|false|null  $encrypted_data, \OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string  $public_key, int  $padding = 1) : bool

Encrypt to a public key, PKCS#1 v1.5 or OAEP, which is how XML encryption wraps its key.

Parameters

string $data

The bytes to encrypt.
string|false|null $encrypted_data

Set to the result.
\OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string $public_key

The key.
int $padding

OPENSSL_PKCS1_PADDING or OPENSSL_PKCS1_OAEP_PADDING.

Returns

bool —

TRUE on success.

openssl_private_decrypt()

openssl_private_decrypt(string  $data, string|false|null  $decrypted_data, \OpenSSLAsymmetricKey|array|string  $private_key, int  $padding = 1) : bool

Parameters

string $data

The bytes to decrypt.
string|false|null $decrypted_data

Set to the result.
\OpenSSLAsymmetricKey|array|string $private_key

The key.
int $padding

OPENSSL_PKCS1_PADDING or OPENSSL_PKCS1_OAEP_PADDING.

Returns

bool —

openssl_x509_read()

openssl_x509_read(\OpenSSLCertificate|string  $certificate) : \OpenSSLCertificate|false

Reads a certificate from PEM, a file:// path or another certificate.

Parameters

\OpenSSLCertificate|string $certificate

A PEM, a file:// path or a certificate object.

Returns

\OpenSSLCertificate|false —

The certificate, or FALSE.

openssl_x509_export()

openssl_x509_export(\OpenSSLCertificate|string  $certificate, string|null  $output, bool  $no_text = true) : bool

Parameters

\OpenSSLCertificate|string $certificate

A PEM, a file:// path or a certificate object.
string|null $output

Set to the PEM.
bool $no_text

Ignored.

Returns

bool —

openssl_x509_fingerprint()

openssl_x509_fingerprint(\OpenSSLCertificate|string  $certificate, string  $digest_algo = 'sha1', bool  $binary = false) : string|false

Parameters

\OpenSSLCertificate|string $certificate

A PEM, a file:// path or a certificate object.
string $digest_algo

A digest name.
bool $binary

Return raw bytes instead of hex.

Returns

string|false —

openssl_x509_parse()

openssl_x509_parse(\OpenSSLCertificate|string  $certificate, bool  $short_names = true) : array<string,mixed>|false

The fields of a certificate that node:crypto exposes, under ext-openssl's key names.

Parameters

\OpenSSLCertificate|string $certificate

A PEM, a file:// path or a certificate object.
bool $short_names

Ignored.

Returns

array|false —

The parsed certificate, or FALSE.

openssl_x509_checkpurpose()

openssl_x509_checkpurpose(\OpenSSLCertificate|string  $certificate, int  $purpose, array  $ca_info = [], string|null  $untrusted_certificates_file = null) : int

Purpose checking needs a trust store and purpose table this runtime does not carry.

Parameters

\OpenSSLCertificate|string $certificate

The certificate to check.
int $purpose

An X509_PURPOSE_* value.
array $ca_info

Trusted CA locations.
string|null $untrusted_certificates_file

Intermediate certificates.

Returns

int —

-1, which ext-openssl uses for "could not be determined".