# PHP 8.2: New `openssl_cipher_key_length`

function

The OpenSSL extension in PHP 8.2 adds a new function named `openssl_cipher_key_length`

, that returns the required length of the key (in bytes) for any supported OpenSSL cipher.

The information is fetched from the underlying OpenSSL library, so they are consistent and can be trusted.

This function follows similar semantics of the existing `openssl_cipher_iv_length()`

function, which returns the initialization vector length required for the cipher.

`openssl_cipher_key_length`

function synopsis

`openssl_cipher_key_length`

function returns the required length of the key for a given cipher algorithm, or returns `false`

if the cipher name is known.

For unknown cipher names, it also emits a warning `openssl_cipher_key_length(): Unknown cipher algorithm`

.

```
/**
* Returns the key length for the given cipher algorithm.
*
* @param string $cipher_algo Cipher algorithm name.
* @return int|false Length of the key, or false if the cipher name is unknown
*/
function openssl_cipher_key_length(string $cipher_algo): int|false {
}
```

## User-land polyfill

Note that the `openssl_cipher_key_length`

function uses the OpenSSL library to retrieve the key lengths, and the OpenSSL PHP extension does not hard-code any of the key length information. However because the key lengths for each cipher are constant, a (meticulous yet static) polyfill function can be created by hard-coding the key lengths of known ciphers.

The following is an example that returns key lengths of each OpenSSL cipher, and follows a similar behavior when it encounters an unknown cipher name. However, when OpenSSL is built with different or uncommon cipher suites, the following hard-coded values must be updated to maintain the compatibility with the built-in `openssl_cipher_key_length`

function.

```
function openssl_cipher_key_length(string $cipher_algo): int|false {
$length = match(strtolower($cipher_algo)) {
'aes-128-cbc' => 16,
'aes-128-cbc-hmac-sha1' => 16,
'aes-128-cbc-hmac-sha256' => 16,
'aes-128-ccm' => 16,
'aes-128-cfb' => 16,
'aes-128-cfb1' => 16,
'aes-128-cfb8' => 16,
'aes-128-ctr' => 16,
'aes-128-ecb' => 16,
'aes-128-gcm' => 16,
'aes-128-ocb' => 16,
'aes-128-ofb' => 16,
'aes-128-wrap' => 16,
'aes-128-wrap-pad' => 16,
'aes-128-xts' => 32,
'aes-192-cbc' => 24,
'aes-192-ccm' => 24,
'aes-192-cfb' => 24,
'aes-192-cfb1' => 24,
'aes-192-cfb8' => 24,
'aes-192-ctr' => 24,
'aes-192-ecb' => 24,
'aes-192-gcm' => 24,
'aes-192-ocb' => 24,
'aes-192-ofb' => 24,
'aes-192-wrap' => 24,
'aes-192-wrap-pad' => 24,
'aes-256-cbc' => 32,
'aes-256-cbc-hmac-sha1' => 32,
'aes-256-cbc-hmac-sha256' => 32,
'aes-256-ccm' => 32,
'aes-256-cfb' => 32,
'aes-256-cfb1' => 32,
'aes-256-cfb8' => 32,
'aes-256-ctr' => 32,
'aes-256-ecb' => 32,
'aes-256-gcm' => 32,
'aes-256-ocb' => 32,
'aes-256-ofb' => 32,
'aes-256-wrap' => 32,
'aes-256-wrap-pad' => 32,
'aes-256-xts' => 64,
'aria-128-cbc' => 16,
'aria-128-ccm' => 16,
'aria-128-cfb' => 16,
'aria-128-cfb1' => 16,
'aria-128-cfb8' => 16,
'aria-128-ctr' => 16,
'aria-128-ecb' => 16,
'aria-128-gcm' => 16,
'aria-128-ofb' => 16,
'aria-192-cbc' => 24,
'aria-192-ccm' => 24,
'aria-192-cfb' => 24,
'aria-192-cfb1' => 24,
'aria-192-cfb8' => 24,
'aria-192-ctr' => 24,
'aria-192-ecb' => 24,
'aria-192-gcm' => 24,
'aria-192-ofb' => 24,
'aria-256-cbc' => 32,
'aria-256-ccm' => 32,
'aria-256-cfb' => 32,
'aria-256-cfb1' => 32,
'aria-256-cfb8' => 32,
'aria-256-ctr' => 32,
'aria-256-ecb' => 32,
'aria-256-gcm' => 32,
'aria-256-ofb' => 32,
'camellia-128-cbc' => 16,
'camellia-128-cfb' => 16,
'camellia-128-cfb1' => 16,
'camellia-128-cfb8' => 16,
'camellia-128-ctr' => 16,
'camellia-128-ecb' => 16,
'camellia-128-ofb' => 16,
'camellia-192-cbc' => 24,
'camellia-192-cfb' => 24,
'camellia-192-cfb1' => 24,
'camellia-192-cfb8' => 24,
'camellia-192-ctr' => 24,
'camellia-192-ecb' => 24,
'camellia-192-ofb' => 24,
'camellia-256-cbc' => 32,
'camellia-256-cfb' => 32,
'camellia-256-cfb1' => 32,
'camellia-256-cfb8' => 32,
'camellia-256-ctr' => 32,
'camellia-256-ecb' => 32,
'camellia-256-ofb' => 32,
'chacha20' => 32,
'chacha20-poly1305' => 32,
'des-ede-cbc' => 16,
'des-ede-cfb' => 16,
'des-ede-ecb' => 16,
'des-ede-ofb' => 16,
'des-ede3-cbc' => 24,
'des-ede3-cfb' => 24,
'des-ede3-cfb1' => 24,
'des-ede3-cfb8' => 24,
'des-ede3-ecb' => 24,
'des-ede3-ofb' => 24,
'des3-wrap' => 24,
'sm4-cbc' => 16,
'sm4-cfb' => 16,
'sm4-ctr' => 16,
'sm4-ecb' => 16,
'sm4-ofb' => 16,
default => false,
};
if ($length === false) {
trigger_error('openssl_cipher_key_length(): Unknown cipher algorithm', E_USER_WARNING);
}
return $length;
}
```

## Backwards Compatibility Impact

`openssl_cipher_key_length`

is a new function added to the OpenSSL extension in PHP 8.2. It can be polyfilled in older PHP versions, albeit imperfectly, by creating a user-land PHP function with a hard-coded list of key lengths for known ciphers.