From e4d7e84335e2b01bf3dfd03d13483bafa4700a3c Mon Sep 17 00:00:00 2001 From: Jason McNeil Date: Thu, 7 Dec 2023 03:39:41 -0400 Subject: [PATCH] chore(encryptcookie)!: update default config (#2753) * chore(encryptcookie)!: update default config docs(encryptcookie): enhance documentation and examples BREAKING CHANGE: removed the hardcoded "csrf_" from the Except. * docs(encryptcookie): reads or modifies cookies * chore(encryptcookie): csrf config example * docs(encryptcookie): md table spacing --- docs/api/middleware/encryptcookie.md | 58 ++++++++++++++++------------ middleware/encryptcookie/config.go | 2 +- 2 files changed, 35 insertions(+), 25 deletions(-) diff --git a/docs/api/middleware/encryptcookie.md b/docs/api/middleware/encryptcookie.md index 743578bd87..c6e689e0e8 100644 --- a/docs/api/middleware/encryptcookie.md +++ b/docs/api/middleware/encryptcookie.md @@ -4,7 +4,11 @@ id: encryptcookie # Encrypt Cookie -Encrypt middleware for [Fiber](https://github.com/gofiber/fiber) which encrypts cookie values. Note: this middleware does not encrypt cookie names. +Encrypt Cookie is a middleware for [Fiber](https://github.com/gofiber/fiber) that secures your cookie values through encryption. + +:::note +This middleware encrypts cookie values and not the cookie names. +::: ## Signatures @@ -18,7 +22,7 @@ func GenerateKey() string ## Examples -Import the middleware package that is part of the Fiber web framework +To use the Encrypt Cookie middleware, first, import the middleware package as part of the Fiber web framework: ```go import ( @@ -27,23 +31,20 @@ import ( ) ``` -After you initiate your Fiber app, you can use the following possibilities: +Once you've imported the middleware package, you can use it inside your Fiber app: ```go -// Provide a minimal config -// `Key` must be a 32 character string. It's used to encrypt the values, so make sure it is random and keep it secret. -// You can run `openssl rand -base64 32` or call `encryptcookie.GenerateKey()` to create a random key for you. -// Make sure not to set `Key` to `encryptcookie.GenerateKey()` because that will create a new key every run. +// Provide a minimal configuration app.Use(encryptcookie.New(encryptcookie.Config{ Key: "secret-thirty-2-character-string", })) -// Get / reading out the encrypted cookie +// Retrieve the encrypted cookie value app.Get("/", func(c *fiber.Ctx) error { return c.SendString("value=" + c.Cookies("test")) }) -// Post / create the encrypted cookie +// Create an encrypted cookie app.Post("/", func(c *fiber.Ctx) error { c.Cookie(&fiber.Cookie{ Name: "test", @@ -53,39 +54,48 @@ app.Post("/", func(c *fiber.Ctx) error { }) ``` +:::note +`Key` must be a 32 character string. It's used to encrypt the values, so make sure it is random and keep it secret. +You can run `openssl rand -base64 32` or call `encryptcookie.GenerateKey()` to create a random key for you. +Make sure not to set `Key` to `encryptcookie.GenerateKey()` because that will create a new key every run. +::: + ## Config -| Property | Type | Description | Default | -|:----------|:----------------------------------------------------|:----------------------------------------------------------------------------------------------------|:-----------------------------| -| Next | `func(*fiber.Ctx) bool` | Next defines a function to skip this middleware when returned true. | `nil` | -| Except | `[]string` | Array of cookie keys that should not be encrypted. | `[]` | -| Key | `string` | Base64 encoded unique key to encode & decode cookies. Required. Key length should be 32 characters. | (No default, required field) | -| Encryptor | `func(decryptedString, key string) (string, error)` | Custom function to encrypt cookies. | `EncryptCookie` | -| Decryptor | `func(encryptedString, key string) (string, error)` | Custom function to decrypt cookies. | `DecryptCookie` | +| Property | Type | Description | Default | +|:----------|:----------------------------------------------------|:------------------------------------------------------------------------------------------------------|:-----------------------------| +| Next | `func(*fiber.Ctx) bool` | A function to skip this middleware when returned true. | `nil` | +| Except | `[]string` | Array of cookie keys that should not be encrypted. | `[]` | +| Key | `string` | A base64-encoded unique key to encode & decode cookies. Required. Key length should be 32 characters. | (No default, required field) | +| Encryptor | `func(decryptedString, key string) (string, error)` | A custom function to encrypt cookies. | `EncryptCookie` | +| Decryptor | `func(encryptedString, key string) (string, error)` | A custom function to decrypt cookies. | `DecryptCookie` | ## Default Config ```go var ConfigDefault = Config{ Next: nil, - Except: []string{"csrf_"}, + Except: []string{}, Key: "", Encryptor: EncryptCookie, Decryptor: DecryptCookie, } ``` -## Usage of CSRF and Encryptcookie Middlewares with Custom Cookie Names -Normally, encryptcookie middleware skips `csrf_` cookies. However, it won't work when you use custom cookie names for CSRF. You should update `Except` config to avoid this problem. For example: +## Usage With Other Middlewares That Reads Or Modify Cookies +Place the encryptcookie middleware before any other middleware that reads or modifies cookies. For example, if you are using the CSRF middleware, ensure that the encryptcookie middleware is placed before it. Failure to do so may prevent the CSRF middleware from reading the encrypted cookie. + +You may also choose to exclude certain cookies from encryption. For instance, if you are using the CSRF middleware with a frontend framework like Angular, and the framework reads the token from a cookie, you should exclude that cookie from encryption. This can be achieved by adding the cookie name to the Except array in the configuration: ```go app.Use(encryptcookie.New(encryptcookie.Config{ - Key: "secret-thirty-2-character-string", - Except: []string{"csrf_1"}, // exclude CSRF cookie + Key: "secret-thirty-2-character-string", + Except: []string{csrf.ConfigDefault.CookieName}, // exclude CSRF cookie })) app.Use(csrf.New(csrf.Config{ - KeyLookup: "form:test", - CookieName: "csrf_1", - CookieHTTPOnly: true, + KeyLookup: "header:" + csrf.HeaderName, + CookieSameSite: "Lax", + CookieSecure: true, + CookieHTTPOnly: false, })) ``` diff --git a/middleware/encryptcookie/config.go b/middleware/encryptcookie/config.go index c49fc16ebb..731ac07d79 100644 --- a/middleware/encryptcookie/config.go +++ b/middleware/encryptcookie/config.go @@ -36,7 +36,7 @@ type Config struct { // ConfigDefault is the default config var ConfigDefault = Config{ Next: nil, - Except: []string{"csrf_"}, + Except: []string{}, Key: "", Encryptor: EncryptCookie, Decryptor: DecryptCookie,