> For the complete documentation index, see [llms.txt](https://atomframework.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atomframework.gitbook.io/docs/misc/security/encryption.md).

# Encryption

Atom's encrypter uses OpenSSL to provide AES-256 and AES-128 encryption. You are strongly encouraged to use Atom's built-in encryption facilities and not attempt to roll your own "home grown" encryption algorithms. All of Atom's encrypted values are signed using a message authentication code (MAC) so that their underlying value can not be modified once encrypted.

## **Configuration**

Before using Atom's encrypter, you must set a `app_key` option in your `config/env.json` configuration file. You should use the `php atom secure` command to generate this key since this Atom command will use PHP's secure random bytes generator to build your key. If this value is not properly set, all values encrypted by Atom will be insecure.

## **Using The Encrypter**

You should use the `crypter` global helper to access all encryption methods.

### **Encrypting Value**

You may encrypt a value using the `encrypt` helper. All encrypted values are encrypted using OpenSSL and the `AES-256-CBC`cipher. Furthermore, all encrypted values are signed with a message authentication code (MAC) to detect any modifications to the encrypted string:

```php
$message = "My secret message";

$secret = encrypt($message);
```

### **Encrypt Without Serialization**

Encrypted values are passed through `serialize` during encryption, which allows for encryption of objects and arrays. Thus, non-PHP clients receiving encrypted values will need to `unserialize` the data. If you would like to encrypt and decrypt values without serialization, you may use the `encryptString` and `decryptString` methods on the `crypter` helper:

```php
$encrypted = crypter()->encryptString('Hello world.');

$decrypted = crypter()->decryptString($encrypted);
```

### **Decrypting A Value**

You may decrypt values using the `decrypt` helper. If the value can not be properly decrypted, such as when the MAC is invalid, an `Exception` will be thrown:

```php
try {
    $decrypted = decrypt($encryptedValue);
} catch (Exception $e) {
    //
}
```