diff --git a/resources/views/docs/1/digging-deeper/security.md b/resources/views/docs/1/digging-deeper/security.md index f4d38e43..1e02f2bc 100644 --- a/resources/views/docs/1/digging-deeper/security.md +++ b/resources/views/docs/1/digging-deeper/security.md @@ -30,7 +30,8 @@ level of entropy, as this makes them hard to guess and hard to abuse. If your application allows users to connect _their own_ API keys for a service, you should treat these keys with great care. If you choose to store them anywhere (either in a [File](/docs/digging-deeper/files) or -[Database](/docs/digging-deeper/databases)), make sure you store them encrypted and decrypt them only when in use. +[Database](/docs/digging-deeper/databases)), make sure you store them +[encrypted](/docs/the-basics/system#encryption-decryption) and decrypt them only when needed. See [Environment Files](/docs/getting-started/env-files#removing-sensitive-data-from-your-environment-files) for details on how to redact your `.env` files at build-time. diff --git a/resources/views/docs/1/the-basics/system.md b/resources/views/docs/1/the-basics/system.md index 968de2fb..86b16b87 100644 --- a/resources/views/docs/1/the-basics/system.md +++ b/resources/views/docs/1/the-basics/system.md @@ -18,6 +18,51 @@ the platform on which your app is running. While some features are platform-specific, NativePHP gracefully handles this for you so that you don't have to think about whether something is Linux-, Mac-, or Windows-only. +## Encryption / Decryption + +Almost every non-trivial application will require some concept of secure data storage and retrieval. For example, if +you want to generate and store an API key to access a third-party service on behalf of your user. + +You shouldn't ship these sorts of secrets _with_ your app, but rather generate them or ask your user for them at +runtime. + +But when your app is running on a user's device, you have +[far less control and fewer guarantees](/docs/digging-deeper/security) over the safety of any secrets stored. + +On a traditional server-rendered application, this is a relatively simple problem to solve using server-side encryption +with keys which are hidden from end users. + +For this to work on the user's device, you need to be able to generate and store an encryption key securely. + +NativePHP takes care of the key generation and storage for you, all that's left for you to do is encrypt, store and +decrypt the secrets that you need to store on behalf of your user. + +NativePHP allows you to encrypt and decrypt data in your application easily: + +```php +use Native\Laravel\Facades\System; + +if (System::canEncrypt()) { + $encrypted = System::encrypt('secret_key_a79hiunfw86...'); + + // $encrypted => 'djEwJo+Huv+aeBgUoav5nIJWRQ==' +} +``` + +You can then safely store the encrypted string in a database or the filesystem. + +When you need to get the original value, you can decrypt it: + +```php +use Native\Laravel\Facades\System; + +if (System::canEncrypt()) { + $decrypted = System::decrypt('djEwJo+Huv+aeBgUoav5nIJWRQ=='); + + // $decrypted = 'secret_key_a79hiunfw86...' +} +``` + ## TouchID For Mac systems that support TouchID, you can use TouchID to protect and unlock various parts of your application.