├── .gitignore
├── .travis.yml
├── LICENSE
├── Makefile
├── README.md
├── doc.go
├── example
├── auth.go
├── login.html
└── secured
│ └── index.html
├── seshcookie.go
└── seshcookie_test.go
/.gitignore:
--------------------------------------------------------------------------------
1 | *~
2 | /example/authenticated
3 | /example/example
4 | /cover.out
5 |
--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
1 | language: go
2 |
3 | go:
4 | - 1.7.x
5 | - 1.8.x
6 | - 1.9.x
7 | - master
8 |
9 | script:
10 | - go test
11 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Copyright 2011 Bobby Powers
2 |
3 | Permission is hereby granted, free of charge, to any person obtaining
4 | a copy of this software and associated documentation files (the
5 | "Software"), to deal in the Software without restriction, including
6 | without limitation the rights to use, copy, modify, merge, publish,
7 | distribute, sublicense, and/or sell copies of the Software, and to
8 | permit persons to whom the Software is furnished to do so, subject to
9 | the following conditions:
10 |
11 | The above copyright notice and this permission notice shall be
12 | included in all copies or substantial portions of the Software.
13 |
14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 |
2 | COV_FILE = cover.out
3 |
4 | # quiet output, but allow us to look at what commands are being
5 | # executed by passing 'V=1' to make, without requiring temporarily
6 | # editing the Makefile.
7 | ifneq ($V, 1)
8 | MAKEFLAGS += -s
9 | endif
10 |
11 | # GNU make, you are the worst.
12 | .SUFFIXES:
13 | %: %,v
14 | %: RCS/%,v
15 | %: RCS/%
16 | %: s.%
17 | %: SCCS/s.%
18 |
19 |
20 | all:
21 | go test
22 | go install
23 |
24 | cover coverage:
25 | go test -covermode atomic -coverprofile $(COV_FILE)
26 | go tool cover -html=$(COV_FILE)
27 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | seshcookie - cookie-based sessions for Go
2 | =========================================
3 |
4 | [](https://travis-ci.org/bpowers/seshcookie)
5 | [](https://godoc.org/github.com/bpowers/seshcookie)
6 | [](https://cover.run/go?tag=golang-1.10&repo=github.com%2Fbpowers%2Fseshcookie)
7 | [](https://goreportcard.com/report/github.com/bpowers/seshcookie)
8 |
9 | seshcookie enables you to associate session-state with HTTP requests
10 | while keeping your server stateless. Because session-state is
11 | transferred as part of the HTTP request (in a cookie), state can be
12 | seamlessly maintained between server restarts or load balancing. It's
13 | inspired by [Beaker](http://pypi.python.org/pypi/Beaker), which
14 | provides a similar service for Python webapps. The cookies are
15 | authenticated and encrypted (using AES-GCM) with a key derived from a
16 | string provided to the `NewHandler` function. This makes seshcookie
17 | reliable and secure: session contents are opaque to users and not able
18 | to be manipulated or forged by third parties.
19 |
20 | examples
21 | --------
22 |
23 | The simple example below returns different content based on whether
24 | the user has visited the site before or not:
25 |
26 |
27 | ```Go
28 | package main
29 |
30 | import (
31 | "fmt"
32 | "log"
33 | "net/http"
34 |
35 | "github.com/bpowers/seshcookie"
36 | )
37 |
38 | type VisitedHandler struct{}
39 |
40 | func (h *VisitedHandler) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
41 | if req.URL.Path != "/" {
42 | return
43 | }
44 |
45 | session := seshcookie.GetSession(req.Context())
46 |
47 | count, _ := session["count"].(int)
48 | count++
49 | session["count"] = count
50 |
51 | rw.Header().Set("Content-Type", "text/plain")
52 | rw.WriteHeader(200)
53 | if count == 1 {
54 | rw.Write([]byte("this is your first visit, welcome!"))
55 | } else {
56 | rw.Write([]byte(fmt.Sprintf("page view #%d", count)))
57 | }
58 | }
59 |
60 | func main() {
61 | key := "session key, preferably a sequence of data from /dev/urandom"
62 | http.Handle("/", seshcookie.NewHandler(
63 | &VisitedHandler{},
64 | key,
65 | &seshcookie.Config{HTTPOnly: true, Secure: false}))
66 |
67 | if err := http.ListenAndServe(":8080", nil); err != nil {
68 | log.Fatalf("ListenAndServe: %s", err)
69 | }
70 | }
71 | ```
72 |
73 | There is a more detailed example in example/ which uses seshcookie to
74 | enforce authentication for a particular resource. In particular, it
75 | shows how you can embed (or stack) multiple http.Handlers to get the
76 | behavior you want.
77 |
78 | license
79 | -------
80 |
81 | seshcookie is offered under the MIT license, see LICENSE for details.
82 |
--------------------------------------------------------------------------------
/doc.go:
--------------------------------------------------------------------------------
1 | // Copyright 2017 Bobby Powers. All rights reserved.
2 | // Use of this source code is governed by the MIT
3 | // license that can be found in the LICENSE file.
4 |
5 | /*
6 | Package seshcookie enables you to associate session-state with HTTP
7 | requests while keeping your server stateless. Because session-state
8 | is transferred as part of the HTTP request (in a cookie), state can be
9 | seamlessly maintained between server restarts or load balancing. It's
10 | inspired by Beaker (http://pypi.python.org/pypi/Beaker), which
11 | provides a similar service for Python webapps. The cookies are
12 | authenticated and encrypted (using AES-GCM) with a key derived from a
13 | string provided to the NewHandler function. This makes seshcookie
14 | reliable and secure: session contents are opaque to users and not able
15 | to be manipulated or forged by third parties.
16 |
17 | Storing session-state in a cookie makes building some apps trivial,
18 | like this example that tells a user how many times they have visited
19 | the site:
20 |
21 | package main
22 |
23 | import (
24 | "net/http"
25 | "log"
26 | "fmt"
27 |
28 | "github.com/bpowers/seshcookie"
29 | )
30 |
31 | type VisitedHandler struct{}
32 |
33 | func (h *VisitedHandler) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
34 | if req.URL.Path != "/" {
35 | return
36 | }
37 |
38 | session := seshcookie.GetSession(req.Context())
39 |
40 | count, _ := session["count"].(int)
41 | count++
42 | session["count"] = count
43 |
44 | rw.Header().Set("Content-Type", "text/plain")
45 | rw.WriteHeader(200)
46 | if count == 1 {
47 | rw.Write([]byte("this is your first visit, welcome!"))
48 | } else {
49 | rw.Write([]byte(fmt.Sprintf("page view #%d", count)))
50 | }
51 | }
52 |
53 | func main() {
54 | key := "session key, preferably a sequence of data from /dev/urandom"
55 | http.Handle("/", seshcookie.NewHandler(
56 | &VisitedHandler{},
57 | key,
58 | &seshcookie.Config{HTTPOnly: true, Secure: false}))
59 |
60 | if err := http.ListenAndServe(":8080", nil); err != nil {
61 | log.Fatalf("ListenAndServe: %s", err)
62 | }
63 | }
64 | */
65 | package seshcookie
66 |
--------------------------------------------------------------------------------
/example/auth.go:
--------------------------------------------------------------------------------
1 | // Copyright 2017 Bobby Powers. All rights reserved.
2 | // Use of this source code is governed by the MIT
3 | // license that can be found in the LICENSE file.
4 | package main
5 |
6 | import (
7 | "log"
8 | "net/http"
9 |
10 | "github.com/bpowers/seshcookie"
11 | )
12 |
13 | var contentDir http.Dir = "./secured"
14 |
15 | // a simple map of users to their passwords, for demo purposes
16 | var userDb = map[string]string{
17 | "user1": "love",
18 | "user2": "sex",
19 | "user3": "secret",
20 | "user4": "god",
21 | }
22 |
23 | // AuthHandler is an http.Handler which is meant to be sandwiched
24 | // between the seshcookie session handler and the handler for
25 | // resources you wish to require authentication to access.
26 | type AuthHandler struct {
27 | http.Handler
28 | Users map[string]string
29 | }
30 |
31 | // Restricts resource access to only those who have been logged in.
32 | // In order to provide a mechanism for logging in (and logging back
33 | // out) 2 paths are reserved for use by AuthHandler: "/login", and
34 | // "/logout".
35 | //
36 | // A GET request on "/login" serves a login form, which, upon
37 | // submission POSTs to "/login". If the login was successful, the
38 | // user is redirected to "/".
39 | //
40 | // Logging out is simply a matter of clearing the 'user' key from the
41 | // session map and redirecting to "/login"
42 | func (h *AuthHandler) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
43 |
44 | session := seshcookie.GetSession(req.Context())
45 | log.Printf("using session: %#v\n", session)
46 |
47 | switch req.URL.Path {
48 | case "/login":
49 | if req.Method != "POST" {
50 | http.ServeFile(rw, req, "./login.html")
51 | return
52 | }
53 | err := req.ParseForm()
54 | if err != nil {
55 | log.Printf("error '%s' parsing form for %#v\n", err, req)
56 | }
57 | user := req.Form.Get("user")
58 | expectedPass, exists := h.Users[user]
59 | if !exists || req.Form.Get("pass") != expectedPass {
60 | log.Printf("authentication failed for %s (pass:%s)\n",
61 | user, req.Form.Get("pass"))
62 | http.Redirect(rw, req, "/login", http.StatusFound)
63 | return
64 | }
65 |
66 | log.Printf("authorized %s\n", user)
67 | session["user"] = user
68 | http.Redirect(rw, req, "/", http.StatusFound)
69 | return
70 | case "/logout":
71 | delete(session, "user")
72 | http.Redirect(rw, req, "/login", http.StatusFound)
73 | return
74 | }
75 |
76 | if _, ok := session["user"]; !ok {
77 | http.Redirect(rw, req, "/login", http.StatusFound)
78 | return
79 | }
80 |
81 | h.Handler.ServeHTTP(rw, req)
82 | }
83 |
84 | func main() {
85 | // Here we have 3 levels of handlers:
86 | // 1 - session handler
87 | // 2 - auth handler
88 | // 3 - file server
89 | //
90 | // When a request comes in, first it goes through the session
91 | // handler, which deals with decrypting and unpacking session
92 | // data coming in as cookies on incoming requests, and making
93 | // sure the session is serialized when the response header is
94 | // written. After deserializing the incoming session, the
95 | // request is passed to AuthHandler (defined above).
96 | // AuthHandler directly serves requests for /login, /logout,
97 | // and /session. Requests for any other resource require the
98 | // session map to have a user key, which is obtained by
99 | // logging in. If the user key is present, the request is
100 | // passed to the FileServer, otherwise the browser is
101 | // redirected to the login page.
102 | handler := seshcookie.NewHandler(
103 | &AuthHandler{http.FileServer(contentDir), userDb},
104 | "session key, preferably a sequence of data from /dev/urandom",
105 | &seshcookie.Config{HTTPOnly: true, Secure: false})
106 |
107 | if err := http.ListenAndServe(":8080", handler); err != nil {
108 | log.Fatalf("ListenAndServe: %s", err)
109 | }
110 | }
111 |
--------------------------------------------------------------------------------
/example/login.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 | login
8 |
9 |
10 |
11 |
12 |
13 |