diff --git a/encryption.md b/encryption.md index 5eea5ca..85d8270 100644 --- a/encryption.md +++ b/encryption.md @@ -2,4 +2,53 @@ ## Overview -Encryption is not yet available in Supercharge v2. +Supercharge comes with a convenient encryption service for encrypting and decrypting values. Encryption uses OpenSSL with the AES-256 cipher. All encrypted values are signed using a message authentication code (MAC) keeping your values secure from modification once they are encrypted. + + +## Configuration +Supercharge’s encrypter requires a secret key for encryption. The encrypter uses the app `key` configured in your `config/app.ts` file. The app `key` configuration is driven by the `APP_KEY` environment variable. You should configure a random app key with at least 32 characters to keep your values secure. + + +## Using Encryption +You may encrypt and decrypt values using the `Crypt` facade. The `Crypt` facade is part of the `@supercharge/facades` package. + + +### Encrypt a Value +Use the `Crypt.encrypt` method to encrypt a given value: + +```ts +import { Crypt } from '@supercharge/facades' +import { Controller } from '@supercharge/http' +import { HttpContext } from '@supercharge/contracts' + +export class StoreGithubAuthTokenController extends Controller { + /** + * Handle the given request. + */ + async handle ({ request, response }: HttpContext): Promise { + const encrypted = Crypt.encrypt(request.input('github-auth-token')) + // da29f2134efa… + + // … proceed handling the request + } +} +``` + +**Notice:** the encrypter JSON-serializes the value before encrypting it. + + +### Decrypt a Value +Use the `Crypt.decrypt` method to decrypt an encrypted string: + +```ts +import { Crypt } from '@supercharge/facades' + +try { + const decrypted = Crypt.decrypt(encryptedValue) + // { name: 'Supercharge' } +} catch (error) { + // +} +``` + +**Notice:** the encrypter JSON-serializes values when encrypting them. It also parses the decrypted value. The parsed value may not be the same as the encrypted value. For example, this happens when encrypting a class instance which will be parsed as an object and not brought back to a class instance. diff --git a/navigation.js b/navigation.js index be181bc..3220016 100644 --- a/navigation.js +++ b/navigation.js @@ -65,6 +65,14 @@ module.exports = { // } // }, + Security: { + slug: 'security', + sections: { + Encryption: 'encryption', + // Hashing: 'hashing', + } + }, + Packages: { slug: 'packages', sections: {