Debian Codegraph @

src/modules/jwt/README

raw
1 JWT Module
2
3 Daniel-Constantin Mierla
4
5 <[email protected]>
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11 <[email protected]>
12
13 Copyright © 2021 asipto.com
14 __________________________________________________________________
15
16 Table of Contents
17
18 1. Admin Guide
19
20 1. Overview
21 2. Dependencies
22
23 2.1. Kamailio Modules
24 2.2. External Libraries or Applications
25
26 3. Parameters
27
28 3.1. key_mode (int)
29
30 4. Functions
31
32 4.1. jwt_generate(prvkey, alg, claims[, headers])
33 4.2. jwt_verify(pubkeypath, alg, claims, jwtval)
34 4.3. jwt_verify_key(pubkeyval, alg, claims, jwtval)
35
36 5. Variables
37
38 5.1. $jwt(key)
39
40 List of Examples
41
42 1.1. Set key_mode parameter
43 1.2. jwt_generate usage
44 1.3. jwt_verify usage
45 1.4. jwt_verify_key usage
46 1.5. $jwt(name) usage
47
48 Chapter 1. Admin Guide
49
50 Table of Contents
51
52 1. Overview
53 2. Dependencies
54
55 2.1. Kamailio Modules
56 2.2. External Libraries or Applications
57
58 3. Parameters
59
60 3.1. key_mode (int)
61
62 4. Functions
63
64 4.1. jwt_generate(prvkey, alg, claims[, headers])
65 4.2. jwt_verify(pubkeypath, alg, claims, jwtval)
66 4.3. jwt_verify_key(pubkeyval, alg, claims, jwtval)
67
68 5. Variables
69
70 5.1. $jwt(key)
71
72 1. Overview
73
74 This module provides JWT (JSON Web Token) functions to be used in
75 Kamailio configuration file.
76
77 It relies on libjwt (at least v1.12.0) library
78 (https://github.com/benmcollins/libjwt), but it is not working with the
79 new libjwt3.
80
81 2. Dependencies
82
83 2.1. Kamailio Modules
84 2.2. External Libraries or Applications
85
86 2.1. Kamailio Modules
87
88 The following modules must be loaded before this module:
89 * none.
90
91 2.2. External Libraries or Applications
92
93 The following libraries or applications must be installed before
94 running Kamailio with this module loaded:
95 * libjwt - minimum version 1.12.0, but less than libjwt 3.0.
96
97 3. Parameters
98
99 3.1. key_mode (int)
100
101 3.1. key_mode (int)
102
103 Mode to use the private and public keys. If set to 0, they are read
104 always from the disk. If set to 1, they are cached in memory with the
105 first use (no reload support yet).
106
107 Default value is 0.
108
109 Example 1.1. Set key_mode parameter
110 ...
111 modparam("jwt", "key_mode", 1)
112 ...
113
114 4. Functions
115
116 4.1. jwt_generate(prvkey, alg, claims[, headers])
117 4.2. jwt_verify(pubkeypath, alg, claims, jwtval)
118 4.3. jwt_verify_key(pubkeyval, alg, claims, jwtval)
119
120 4.1. jwt_generate(prvkey, alg, claims[, headers])
121
122 Generate the JWT, its value can be retrieved in the variable $jwt(val).
123
124 The parameters are:
125 * prvkey - path to private key
126 * alg - the algorithm to build the signature, as supported by the
127 libjwt (e.g., RS256, HS256, ES256, ...)
128 * claims - the list of claims to be added to JWT, in the format
129 "name1=value1;name2=value2;..." (same as the SIP parameters
130 format). The string values can be enclosed in single or double
131 quotes. If a value is not eclosed in between quotes, it is added as
132 numeric value if it is successfully converted to a long value,
133 otherwise is added as string value.
134 * headers - the list of headers to be added to JWT, in the format
135 "name1=value1;name2=value2;..." (same as the SIP parameters
136 format). The string values can be enclosed in single or double
137 quotes. If a value is not eclosed in between quotes, it is added as
138 numeric value if it is successfully converted to a long value,
139 otherwise is added as string value.
140
141 This function can be used from ANY_ROUTE.
142
143 Example 1.2. jwt_generate usage
144 ...
145 jwt_generate("/path/to/prvkey.pem", "RS256",
146 "caller='$fU';callee='$tU';callid='$ci';index=100");
147 ...
148
149 4.2. jwt_verify(pubkeypath, alg, claims, jwtval)
150
151 Verify the JWT.
152
153 The parameters are:
154 * pubkeypath - path to public key file
155 * alg - the algorithm to build the signature, as supported by the
156 libjwt (e.g., RS256, HS256, ES256, ...)
157 * claims - the list of claims to be checked they are in the JWT, in
158 the format "name1=value1;name2=value2;..." (same as the SIP
159 parameters format, see also the description of claims parameter for
160 jwt_generate()).
161 * jwtval - the value of the JWT to verify
162
163 This function can be used from ANY_ROUTE.
164
165 Example 1.3. jwt_verify usage
166 ...
167 if(!jwt_verify("/path/to/pubkey.pem", "RS256",
168 "caller='$fU';callee='$tU';callid='$ci';index=100",
169 "$var(jwt)") {
170 xwarn("failed to verify jwt\n");
171 }
172 ...
173
174 4.3. jwt_verify_key(pubkeyval, alg, claims, jwtval)
175
176 Verify the JWT.
177
178 The parameters are:
179 * pubkeyval - public key value
180 * alg - the algorithm to build the signature, as supported by the
181 libjwt (e.g., RS256, HS256, ES256, ...)
182 * claims - the list of claims to be checked they are in the JWT, in
183 the format "name1=value1;name2=value2;..." (same as the SIP
184 parameters format, see also the description of claims parameter for
185 jwt_generate()).
186 * jwtval - the value of the JWT to verify
187
188 This function can be used from ANY_ROUTE.
189
190 Example 1.4. jwt_verify_key usage
191 ...
192 if(!jwt_verify_key("...", "RS256",
193 "caller='$fU';callee='$tU';callid='$ci';index=100",
194 "$var(jwt)") {
195 xwarn("failed to verify jwt\n");
196 }
197 ...
198
199 5. Variables
200
201 5.1. $jwt(key)
202
203 5.1. $jwt(key)
204
205 Get the values and attributes after using JWT functions.
206
207 The key can be:
208 * val - the value of JWT after a successful jwt_generate().
209 * status - the status of verification after a failed jwt_verify().
210
211 Example 1.5. $jwt(name) usage
212 ...
213 jwt_generate("/path/to/prvkey.pem", "RS256",
214 "caller='$fU';callee='$tU';callid='$ci';index=100");
215 xinfo("jwt is: $jwt(val)");
216 ...