├── README.org ├── cljwt.asd ├── COPYING └── src └── cljwt.lisp /README.org: -------------------------------------------------------------------------------- 1 | * CLJWT 2 | A library for issuing and validating JSON Web Tokens 3 | 4 | ** Implemented so far 5 | - Issue unsecured tokens 6 | - Issue tokens secured with HS256 7 | - Decode and verify tokens 8 | 9 | ** To do 10 | - Additional algorithms 11 | - Encrypted tokens 12 | - Better abstractions 13 | - Tests 14 | - Documentation 15 | - Release 16 | - Add to Quicklisp 17 | 18 | ** License 19 | This program is free software: you can redistribute it and/or modify 20 | it under the terms of the GNU Lesser General Public License as 21 | published by the Free Software Foundation, either version 3 of the 22 | License, or (at your option) any later version. 23 | 24 | This program is distributed in the hope that it will be useful, 25 | but WITHOUT ANY WARRANTY; without even the implied warranty of 26 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 27 | GNU Lesser General Public License for more details. 28 | 29 | You should have received a copy of the GNU Lesser General Public 30 | License along with this program. If not, see 31 | . 32 | -------------------------------------------------------------------------------- /cljwt.asd: -------------------------------------------------------------------------------- 1 | ;; Copyright © 2014 Grim Schjetne 2 | 3 | ;; This file is part of CLJWT. 4 | 5 | ;; CLJWT is free software: you can redistribute it and/or modify 6 | ;; it under the terms of the GNU Lesser General Public License as 7 | ;; published by the Free Software Foundation, either version 3 of the 8 | ;; License, or (at your option) any later version. 9 | 10 | ;; CLJWT is distributed in the hope that it will be useful, but 11 | ;; WITHOUT ANY WARRANTY; without even the implied warranty of 12 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 | ;; Lesser General Public License for more details. 14 | 15 | ;; You should have received a copy of the GNU Lesser General Public 16 | ;; License along with CLJWT. If not, see 17 | ;; . 18 | 19 | (in-package :cl-user) 20 | (defpackage :cljwt-system (:use :cl :asdf)) 21 | (in-package :cljwt-system) 22 | 23 | (defsystem cljwt 24 | :name "CLJWT" 25 | :author "Grim Schjetne 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | 9 | This version of the GNU Lesser General Public License incorporates 10 | the terms and conditions of version 3 of the GNU General Public 11 | License, supplemented by the additional permissions listed below. 12 | 13 | 0. Additional Definitions. 14 | 15 | As used herein, "this License" refers to version 3 of the GNU Lesser 16 | General Public License, and the "GNU GPL" refers to version 3 of the GNU 17 | General Public License. 18 | 19 | "The Library" refers to a covered work governed by this License, 20 | other than an Application or a Combined Work as defined below. 21 | 22 | An "Application" is any work that makes use of an interface provided 23 | by the Library, but which is not otherwise based on the Library. 24 | Defining a subclass of a class defined by the Library is deemed a mode 25 | of using an interface provided by the Library. 26 | 27 | A "Combined Work" is a work produced by combining or linking an 28 | Application with the Library. The particular version of the Library 29 | with which the Combined Work was made is also called the "Linked 30 | Version". 31 | 32 | The "Minimal Corresponding Source" for a Combined Work means the 33 | Corresponding Source for the Combined Work, excluding any source code 34 | for portions of the Combined Work that, considered in isolation, are 35 | based on the Application, and not on the Linked Version. 36 | 37 | The "Corresponding Application Code" for a Combined Work means the 38 | object code and/or source code for the Application, including any data 39 | and utility programs needed for reproducing the Combined Work from the 40 | Application, but excluding the System Libraries of the Combined Work. 41 | 42 | 1. Exception to Section 3 of the GNU GPL. 43 | 44 | You may convey a covered work under sections 3 and 4 of this License 45 | without being bound by section 3 of the GNU GPL. 46 | 47 | 2. Conveying Modified Versions. 48 | 49 | If you modify a copy of the Library, and, in your modifications, a 50 | facility refers to a function or data to be supplied by an Application 51 | that uses the facility (other than as an argument passed when the 52 | facility is invoked), then you may convey a copy of the modified 53 | version: 54 | 55 | a) under this License, provided that you make a good faith effort to 56 | ensure that, in the event an Application does not supply the 57 | function or data, the facility still operates, and performs 58 | whatever part of its purpose remains meaningful, or 59 | 60 | b) under the GNU GPL, with none of the additional permissions of 61 | this License applicable to that copy. 62 | 63 | 3. Object Code Incorporating Material from Library Header Files. 64 | 65 | The object code form of an Application may incorporate material from 66 | a header file that is part of the Library. You may convey such object 67 | code under terms of your choice, provided that, if the incorporated 68 | material is not limited to numerical parameters, data structure 69 | layouts and accessors, or small macros, inline functions and templates 70 | (ten or fewer lines in length), you do both of the following: 71 | 72 | a) Give prominent notice with each copy of the object code that the 73 | Library is used in it and that the Library and its use are 74 | covered by this License. 75 | 76 | b) Accompany the object code with a copy of the GNU GPL and this license 77 | document. 78 | 79 | 4. Combined Works. 80 | 81 | You may convey a Combined Work under terms of your choice that, 82 | taken together, effectively do not restrict modification of the 83 | portions of the Library contained in the Combined Work and reverse 84 | engineering for debugging such modifications, if you also do each of 85 | the following: 86 | 87 | a) Give prominent notice with each copy of the Combined Work that 88 | the Library is used in it and that the Library and its use are 89 | covered by this License. 90 | 91 | b) Accompany the Combined Work with a copy of the GNU GPL and this license 92 | document. 93 | 94 | c) For a Combined Work that displays copyright notices during 95 | execution, include the copyright notice for the Library among 96 | these notices, as well as a reference directing the user to the 97 | copies of the GNU GPL and this license document. 98 | 99 | d) Do one of the following: 100 | 101 | 0) Convey the Minimal Corresponding Source under the terms of this 102 | License, and the Corresponding Application Code in a form 103 | suitable for, and under terms that permit, the user to 104 | recombine or relink the Application with a modified version of 105 | the Linked Version to produce a modified Combined Work, in the 106 | manner specified by section 6 of the GNU GPL for conveying 107 | Corresponding Source. 108 | 109 | 1) Use a suitable shared library mechanism for linking with the 110 | Library. A suitable mechanism is one that (a) uses at run time 111 | a copy of the Library already present on the user's computer 112 | system, and (b) will operate properly with a modified version 113 | of the Library that is interface-compatible with the Linked 114 | Version. 115 | 116 | e) Provide Installation Information, but only if you would otherwise 117 | be required to provide such information under section 6 of the 118 | GNU GPL, and only to the extent that such information is 119 | necessary to install and execute a modified version of the 120 | Combined Work produced by recombining or relinking the 121 | Application with a modified version of the Linked Version. (If 122 | you use option 4d0, the Installation Information must accompany 123 | the Minimal Corresponding Source and Corresponding Application 124 | Code. If you use option 4d1, you must provide the Installation 125 | Information in the manner specified by section 6 of the GNU GPL 126 | for conveying Corresponding Source.) 127 | 128 | 5. Combined Libraries. 129 | 130 | You may place library facilities that are a work based on the 131 | Library side by side in a single library together with other library 132 | facilities that are not Applications and are not covered by this 133 | License, and convey such a combined library under terms of your 134 | choice, if you do both of the following: 135 | 136 | a) Accompany the combined library with a copy of the same work based 137 | on the Library, uncombined with any other library facilities, 138 | conveyed under the terms of this License. 139 | 140 | b) Give prominent notice with the combined library that part of it 141 | is a work based on the Library, and explaining where to find the 142 | accompanying uncombined form of the same work. 143 | 144 | 6. Revised Versions of the GNU Lesser General Public License. 145 | 146 | The Free Software Foundation may publish revised and/or new versions 147 | of the GNU Lesser General Public License from time to time. Such new 148 | versions will be similar in spirit to the present version, but may 149 | differ in detail to address new problems or concerns. 150 | 151 | Each version is given a distinguishing version number. If the 152 | Library as you received it specifies that a certain numbered version 153 | of the GNU Lesser General Public License "or any later version" 154 | applies to it, you have the option of following the terms and 155 | conditions either of that published version or of any later version 156 | published by the Free Software Foundation. If the Library as you 157 | received it does not specify a version number of the GNU Lesser 158 | General Public License, you may choose any version of the GNU Lesser 159 | General Public License ever published by the Free Software Foundation. 160 | 161 | If the Library as you received it specifies that a proxy can decide 162 | whether future versions of the GNU Lesser General Public License shall 163 | apply, that proxy's public statement of acceptance of any version is 164 | permanent authorization for you to choose that version for the 165 | Library. 166 | -------------------------------------------------------------------------------- /src/cljwt.lisp: -------------------------------------------------------------------------------- 1 | ;; Copyright © 2014 Grim Schjetne 2 | 3 | ;; This file is part of CLJWT. 4 | 5 | ;; CLJWT is free software: you can redistribute it and/or modify 6 | ;; it under the terms of the GNU Lesser General Public License as 7 | ;; published by the Free Software Foundation, either version 3 of the 8 | ;; License, or (at your option) any later version. 9 | 10 | ;; CLJWT is distributed in the hope that it will be useful, but 11 | ;; WITHOUT ANY WARRANTY; without even the implied warranty of 12 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 | ;; Lesser General Public License for more details. 14 | 15 | ;; You should have received a copy of the GNU Lesser General Public 16 | ;; License along with CLJWT. If not, see 17 | ;; . 18 | 19 | (in-package #:cl-user) 20 | (defpackage #:cljwt 21 | (:use #:cl 22 | #:cl-base64) 23 | (:import-from #:alexandria 24 | #:plist-hash-table) 25 | (:import-from #:flexi-streams 26 | #:string-to-octets 27 | #:octets-to-string) 28 | (:import-from #:ironclad 29 | #:make-hmac 30 | #:update-hmac 31 | #:hmac-digest) 32 | (:import-from #:split-sequence 33 | #:split-sequence) 34 | (:export #:issue 35 | #:decode 36 | #:to-unix-time 37 | #:from-unix-time 38 | #:unsecured-token 39 | #:invalid-hmac 40 | #:unsupported-algorithm 41 | #:invalid-time 42 | #:expired 43 | #:not-yet-valid)) 44 | 45 | (in-package #:cljwt) 46 | 47 | (defmacro bind-hash-tables (bindings &body body) 48 | `(let ,(loop for binding in bindings collect 49 | (list (car binding) 50 | `(etypecase ,(cadr binding) 51 | (hash-table ,(cadr binding)) 52 | (list (plist-hash-table ,(cadr binding) 53 | :test #'equal))))) 54 | ,@body)) 55 | 56 | (defmacro add-claims (hash &rest claims) 57 | `(progn ,@(loop for (key value) on claims by #'cddr collect 58 | `(when ,value 59 | (setf (gethash ,key ,hash) ,value))))) 60 | 61 | (defun to-unix-time (time) 62 | "Convert universal time to New Jersey time" 63 | (when time (- time (encode-universal-time 0 0 0 1 1 1970 0)))) 64 | 65 | (defun from-unix-time (time) 66 | "Convert New Jersey time to universal time" 67 | (when time (+ time (encode-universal-time 0 0 0 1 1 1970 0)))) 68 | 69 | (defun base64-encode (input) 70 | "Takes a string or octets, returns an unpadded URI-encoded Base64 string." 71 | (etypecase input 72 | (string (base64-encode (string-to-octets input :external-format :utf-8))) 73 | ((simple-array (unsigned-byte 8)) 74 | (with-output-to-string (out) 75 | (with-input-from-string (in (usb8-array-to-base64-string input :uri t)) 76 | (loop for character = (read-char in nil) 77 | while character do 78 | ;; CL-BASE64 always uses padding, which must be removed. 79 | (unless (eq character #\.) 80 | (write-char character out)))))))) 81 | 82 | (defun base64-decode (base-64-string) 83 | "Takes a base64-uri string and return an array of octets" 84 | (base64-string-to-usb8-array 85 | ;; Re-pad the string, or CL-BASE64 will get confused 86 | (concatenate 'string 87 | base-64-string 88 | (make-array (rem (length base-64-string) 4) 89 | :element-type 'character 90 | :initial-element #\.)) 91 | :uri t)) 92 | 93 | (defun issue (claims &key algorithm secret issuer subject audience 94 | expiration not-before issued-at id more-header) 95 | "Encodes and returns a JSON Web Token. Times are in universal-time, 96 | number of seconds from 1900-01-01 00:00:00" 97 | (bind-hash-tables ((claimset claims) 98 | (header more-header)) 99 | ;; Add registered claims to the claims hash table 100 | (add-claims claimset 101 | "iss" issuer 102 | "sub" subject 103 | "aud" audience 104 | "exp" (to-unix-time expiration) 105 | "nbf" (to-unix-time not-before) 106 | "iat" (to-unix-time issued-at) 107 | "jti" id) 108 | ;; Add type and algorithm to the header hash table 109 | (add-claims header 110 | "typ" "JWT" 111 | "alg" (ecase algorithm 112 | (:none "none") 113 | (:hs256 "HS256"))) 114 | ;; Prepare JSON 115 | (let ((header-string (base64-encode 116 | (with-output-to-string (s) 117 | (yason:encode header s)))) 118 | (claims-string (base64-encode 119 | (with-output-to-string (s) 120 | (yason:encode claimset s))))) 121 | ;; Assemble and, if applicable, sign the JWT 122 | (format nil "~A.~A.~@[~A~]" 123 | header-string 124 | claims-string 125 | (when (eq algorithm :hs256) 126 | (HS256-digest header-string 127 | claims-string 128 | secret)))))) 129 | 130 | (defun HS256-digest (header-string claims-string secret) 131 | "Takes header and claims in Base64, secret as a string or octets, 132 | returns the digest, in Base64" 133 | (base64-encode 134 | (hmac-digest 135 | (update-hmac 136 | (make-hmac (etypecase secret 137 | ((simple-array (unsigned-byte 8)) 138 | secret) 139 | (string 140 | (string-to-octets secret 141 | :external-format :utf-8))) 142 | 'ironclad:SHA256) 143 | (concatenate '(vector (unsigned-byte 8)) 144 | (string-to-octets 145 | header-string) 146 | #(46) ; ASCII period (.) 147 | (string-to-octets 148 | claims-string)))))) 149 | 150 | (defun compare-HS256-digest (header-string claims-string 151 | secret reported-digest) 152 | "Takes header and claims in Base64, secret as a string or octets, and a digest in Base64 to compare with. Signals an error if there is a mismatch." 153 | (let ((computed-digest 154 | (HS256-digest header-string 155 | claims-string 156 | secret))) 157 | (unless (equalp computed-digest 158 | reported-digest) 159 | (cerror "Continue anyway" 'invalid-hmac 160 | :reported-digest reported-digest 161 | :computed-digest computed-digest)))) 162 | 163 | (defun decode (jwt-string &key secret fail-if-unsecured) 164 | "Decodes and verifies a JSON Web Token. Returns two hash tables, 165 | token claims and token header" 166 | (destructuring-bind (header-string claims-string digest-string) 167 | (split-sequence #\. jwt-string) 168 | (let* ((header-hash (yason:parse 169 | (octets-to-string 170 | (base64-decode 171 | header-string) 172 | :external-format :utf-8))) 173 | (claims-hash (yason:parse 174 | (octets-to-string 175 | (base64-decode 176 | claims-string) 177 | :external-format :utf-8))) 178 | (algorithm (gethash "alg" header-hash))) 179 | ;; Verify HMAC 180 | (cond ((equal algorithm "HS256") 181 | (compare-HS256-digest header-string 182 | claims-string 183 | secret 184 | digest-string)) 185 | ((and (or (null algorithm) (equal algorithm "none")) fail-if-unsecured) 186 | (cerror "Continue anyway" 'unsecured-token)) 187 | (t (cerror "Continue anyway" 'unsupported-algorithm 188 | :algorithm algorithm))) 189 | ;; Verify timestamps 190 | (let ((expires (from-unix-time (gethash "exp" claims-hash))) 191 | (not-before (from-unix-time (gethash "nbf" claims-hash))) 192 | (current-time (get-universal-time))) 193 | (when (and expires (> current-time expires)) 194 | (cerror "Continue anyway" 'expired :delta (- current-time expires))) 195 | (when (and not-before (< current-time not-before)) 196 | (cerror "Continue anyway" 'not-yet-valid :delta (- current-time not-before)))) 197 | ;; Return hashes 198 | (values claims-hash header-hash)))) 199 | 200 | ;;; Conditions 201 | 202 | (define-condition unsecured-token (error) ()) 203 | 204 | (define-condition invalid-hmac (error) ()) 205 | 206 | (define-condition unsupported-algorithm (error) 207 | ((algorithm :initarg :algorithm :reader algorithm)) 208 | (:report (lambda (condition stream) 209 | (format stream "Algorithm \"~A\" not supported" 210 | (algorithm condition))))) 211 | 212 | (define-condition invalid-time (error) 213 | ((delta :initarg :delta :reader time-delta)) 214 | (:report (lambda (condition stream) 215 | (format stream "Token ~A. ~D seconds off." 216 | (typecase condition 217 | (expired "has expired") 218 | (not-yet-valid "is not yet valid")) 219 | (time-delta condition))))) 220 | 221 | (define-condition expired (invalid-time) ()) 222 | 223 | (define-condition not-yet-valid (invalid-time) ()) 224 | --------------------------------------------------------------------------------