sodium_crypto_secretbox_open

Authenticated shared-key decryption

&reftitle.description; ``string``false```sodium_crypto_secretbox_open` `string` `ciphertext` `string` `nonce` #[\SensitiveParameter]`string` `key`

Decrypt an encrypted message with a symmetric (shared) key.

&reftitle.parameters;

`ciphertext`

- Must be in the format provided by `sodium_crypto_secretbox` (ciphertext and tag, concatenated).

`nonce`

- A number that must be only used once, per message. 24 bytes long. This is a large enough bound to generate randomly (i.e. `random_bytes`).

`key`

- Encryption key (256-bit).

&reftitle.returnvalues;

The decrypted string on success&return.falseforfailure;.

&reftitle.errors;

- If `nonce` has a length of bytes different than `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24 bytes), a `SodiumException` will be thrown.

- If `key` has a length of bytes different than `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32 bytes), a `SodiumException` will be thrown.

&reftitle.examples;

### `sodium_crypto_secretbox_open` example

    <?php
    // The $key must be kept confidential
    $key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);
    // Do not reuse $nonce with the same key
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $ciphertext = sodium_crypto_secretbox('message to be encrypted', $nonce, $key);

    // The same nonce and key are required to decrypt the $ciphertext
    $plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
    if ($plaintext !== false) {
        echo $plaintext . PHP_EOL;
    }
    ?>

&example.outputs;

    message to be encrypted

&reftitle.seealso;

- `sodium_crypto_secretbox`
- `sodium_crypto_secretbox_keygen`
- `random_bytes`