From 000f85caf4f141a4b736bc714c196e517a30f6fb Mon Sep 17 00:00:00 2001 From: Jason McNeil Date: Wed, 6 Dec 2023 11:47:14 -0400 Subject: [PATCH 1/4] chore(encryptcookie)!: update default config docs(encryptcookie): enhance documentation and examples BREAKING CHANGE: removed the hardcoded "csrf_" from the Except. --- docs/api/middleware/encryptcookie.md | 53 ++++++++++++++++------------ middleware/encryptcookie/config.go | 2 +- 2 files changed, 32 insertions(+), 23 deletions(-) diff --git a/docs/api/middleware/encryptcookie.md b/docs/api/middleware/encryptcookie.md index 743578bd87..8ea117e7ef 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,47 @@ 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` | +|:----------|:----------------------------------------------------|:------------------------------------------------------------------------------------------------------|:-----------------------------| +| 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 Modify Cookies +Place the encryptcookie middleware before any other middleware that 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, + CookieHTTPOnly: false, + CookieSecure: true, })) ``` 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, From a8b3b4d56e4c66c969854212458681d2c4b7d591 Mon Sep 17 00:00:00 2001 From: Jason McNeil Date: Wed, 6 Dec 2023 12:10:33 -0400 Subject: [PATCH 2/4] docs(encryptcookie): reads or modifies cookies --- docs/api/middleware/encryptcookie.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/middleware/encryptcookie.md b/docs/api/middleware/encryptcookie.md index 8ea117e7ef..c7442c827b 100644 --- a/docs/api/middleware/encryptcookie.md +++ b/docs/api/middleware/encryptcookie.md @@ -82,8 +82,8 @@ var ConfigDefault = Config{ } ``` -## Usage With Other Middlewares That Modify Cookies -Place the encryptcookie middleware before any other middleware that 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. +## 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: From f17602bc215d86d74ba6b0a5d8f0cfb1b687962a Mon Sep 17 00:00:00 2001 From: Jason McNeil Date: Wed, 6 Dec 2023 12:17:18 -0400 Subject: [PATCH 3/4] chore(encryptcookie): csrf config example --- docs/api/middleware/encryptcookie.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/api/middleware/encryptcookie.md b/docs/api/middleware/encryptcookie.md index c7442c827b..715abe3ba6 100644 --- a/docs/api/middleware/encryptcookie.md +++ b/docs/api/middleware/encryptcookie.md @@ -93,8 +93,9 @@ app.Use(encryptcookie.New(encryptcookie.Config{ Except: []string{csrf.ConfigDefault.CookieName}, // exclude CSRF cookie })) app.Use(csrf.New(csrf.Config{ - KeyLookup: "form:test", - CookieHTTPOnly: false, + KeyLookup: "header:" + csrf.HeaderName, + CookieSameSite: "Lax", CookieSecure: true, + CookieHTTPOnly: false, })) ``` From e8dca566d486b4371ef75ba5bb2f0960ee8802ad Mon Sep 17 00:00:00 2001 From: Jason McNeil Date: Wed, 6 Dec 2023 12:17:56 -0400 Subject: [PATCH 4/4] docs(encryptcookie): md table spacing --- docs/api/middleware/encryptcookie.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/middleware/encryptcookie.md b/docs/api/middleware/encryptcookie.md index 715abe3ba6..c6e689e0e8 100644 --- a/docs/api/middleware/encryptcookie.md +++ b/docs/api/middleware/encryptcookie.md @@ -62,7 +62,7 @@ Make sure not to set `Key` to `encryptcookie.GenerateKey()` because that will cr ## Config -| Property | Type | Description | Default | +| 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. | `[]` |