-
Notifications
You must be signed in to change notification settings - Fork 972
/
stir_shaken.conf.sample
494 lines (384 loc) · 18.5 KB
/
stir_shaken.conf.sample
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
;--
There are 4 object types used by the STIR/SHAKEN process...
The "attestation" object sets the parameters for creating an Identity
header which attests to the ownership of the caller id on outgoing
INVITE requests.
One or more "tn" objects that are used to create the outgoing Identity
header. Each object's "id" is a specific caller-id telephone number
and the object contains the URL to the certificate that was used to
attest to the ownership of the caller-id, the level (A,B,C) of the
attestation you're making, and the private key the asterisk
attestation service will use to sign the Identity header. When
an outgoing INVITE request is placed, the attestation service will
look up the caller-id in the tn object list and if it's found, use
the information in the object to create the Identity header.
The "verification" object sets the parameters for verification
of the Identity header and caller id on incoming INVITE requests.
One or more "profile" objects that can be associated to channel
driver endpoints (currently only chan_pjsip). Profiles can set
whether verification, attestation, both or neither should be
performed on requests coming in to this endpoint or requests
going out from this endpoint. Additionally they can override
most of the attestation and verification options to make them
specific to an endpoint. When Asterisk loads the configs, it
creates "effective profiles" or "eprofiles" on the fly that are
the amalgamation of the attestation, verification and profile.
You can see them in the CLI with "stir_shaken show eprofiles".
NOTE: The "tn" object can be configured to source its data from a
realtime database by configuring sorcery.conf and extconfig.conf.
Both of those files have examples for "stir_tn". There is also an
Alembic script in the "config" section of contrib/ast-db-manage that
will create the table. Since there can be only one "verification"
or "attestation" object, and will probably be only a few "profile"
objects, those objects aren't realtime enabled.
--;
;--
=======================================================================
Attestation Object Description
=======================================================================
The "attestation" object sets the parameters for creating an Identity
header which attests to the ownership of the caller id on outgoing
INVITE requests.
All parameters except 'global_disable" may be overridden in a "profile"
or "tn" object.
Only one "attestation" object may exist.
Parameters:
-- global_disable -----------------------------------------------------
If set, globally disables the attestation service. No Identity headers
will be added to any outgoing INVITE requests.
Default: no
-- private_key_file ---------------------------------------------------
The path to a file containing the private key you received from the
issuing authority. The file must NOT be group or world readable or
writable so make sure the user the asterisk process is running as is
the owner.
Default: none
-- public_cert_url ----------------------------------------------------
The URL to the certificate you received from the issueing authority.
They may give you a URL to use or you may have to host the certificate
yourself and provide your own URL here.
Default: none
WARNING: Make absolutely sure the file that's made public doesn't
accidentally include the privite key as well as the certificate.
If you set "check_tn_cert_public_url" in the "attestation" section
above, the tn will not be loaded and a "DANGER" message will be output
on the asterisk console if the file does contain a private key.
-- check_tn_cert_public_url -------------------------------------------
Identity headers in outgoing requests must contain a URL that points
to the certificate used to sign the header. Setting this parameter
tells Asterisk to actually try to retrieve the certificates indicated
by "public_cert_url" parameters and fail loading that tn if the cert
can't be retrieved or if its 'Not Valid Before" -> 'Not Valid After"
date range doesn't include today. This is a network intensive process
so use with caution.
Default: no
-- attest_level -------------------------------------------------------
The level of the attestation you're making.
One of "A", "B", "C"
Default: none
-- send_mky -----------------------------------------------------------
If set and an outgoing call uses DTLS, an "mky" Media Key grant will
be added to the Identity header. Although RFC8224/8225 require this,
not many implementations support it so a remote verification service
may fail to verify the signature.
Default: no
-----------------------------------------------------------------------
Example "attestation" object:
--;
;[attestation]
;global_disable = no
;private_key_file = /var/lib/asterisk/keys/stir_shaken/tns/multi-tns-key.pem
;public_cert_url = https://example.com/tncerts/multi-tns-cert.pem
;attest_level = C
;--
=======================================================================
TN Object Description
=======================================================================
Each "tn" object contains the parameters needed to create the Identity
header used to attest to the ownership of the caller-id on outgoing
requests. When an outgoing INVITE request is placed, the attestation
service will look up the caller-id in this list and if it's found, use
the information in the object to create the Identity header.
The private key and certificate needed to sign the Identity header are
usually provided to you by the telephone number issuing authority along
with their certificate authority certificate. You should give the CA
certificate to any recipients who expect to receive calls from you
although this has probably already been done by the issuing authority.
The "id" of this object MUST be a canonicalized telephone number which
starts with a country code. The only valid characters are the numbers
0-9, '#' and '*'.
Parameters:
-- type (required) ----------------------------------------------------
Must be set to "tn"
Default: none
-- private_key_file ---------------------------------------------------
The path to a file containing the private key you received from the
issuing authority. The file must NOT be group or world readable or
writable so make sure the user the asterisk process is running as is
the owner.
Default: private_key_file from the profile or attestation objects.
-- public_cert_url ----------------------------------------------------
The URL to the certificate you received from the issueing authority.
They may give you a URL to use or you may have to host the certificate
yourself and provide your own URL here.
Default: public_cert_url from the profile or attestation objects.
WARNING: Make absolutely sure the file that's made public doesn't
accidentally include the privite key as well as the certificate.
If you set "check_tn_cert_public_url" in the "attestation" section
above, the tn will not be loaded and a "DANGER" message will be output
on the asterisk console if the file does contain a private key.
-- attest_level -------------------------------------------------------
The level of the attestation you're making.
One of "A", "B", "C"
Default: attest_level from the profile or attestation objects.
-----------------------------------------------------------------------
Example "tn" object:
--;
;[18005551515]
;type = tn
;private_key_file = /var/lib/asterisk/keys/stir_shaken/tns/18005551515-key.pem
;public_cert_url = https://example.com/tncerts/18005551515-cert.pem
;attest_level = C
;--
=======================================================================
Verification Object Description
=======================================================================
The "verification" object sets the parameters for verification
of the Identity header on incoming INVITE requests.
All parameters except 'global_disable" may be overridden in a "profile"
object.
Only one "verification" object may exist.
Parameters:
-- global_disable -----------------------------------------------------
If set, globally disables the verification service.
Default: no
-- load_system_certs---------------------------------------------------
If set, loads the system Certificate Authority certificates
(usually located in /etc/pki/CA) into the trust store used to
validate the certificates in incoming requests. This is not
normally required as service providers will usually provide their
CA certififcate to you separately.
Default: no
-- ca_file -----------------------------------------------------------
Path to a file containing one or more CA certs in PEM format.
These certs are used to verify the chain of trust for the
certificate retrieved from the X5U Identity header parameter. This
file must have the root CA certificate, the certificate of the
issuer of the X5U certificate, and any intermediate certificates
between them.
Default: none
-- ca_path -----------------------------------------------------------
Path to a directory containing one or more hashed CA certs.
See ca_file above.
For this option, each certificate must be placed in its own
PEM file in the directory specified and hashed with the
following command:
`openssl rehash <ca_path>`
Default: none
NOTE: Both ca_file and ca_path can be specified but at least one
MUST be.
-- crl_file -----------------------------------------------------------
Path to a file containing one or more CRLs in PEM format.
If you with to check if the certificate in the X5U Identity header
parameter has been revoked, you'll need the certificate revocation
list generated by the issuer.
Default: none
-- crl_path -----------------------------------------------------------
Path to a directory containing one or more hashed CRLs.
See crl_file above.
For this option, each CRL must be placed in its own
PEM file in the directory specified and hashed with the
following command:
`openssl rehash <crl_path>`
Default: none
NOTE: Neither crl_file nor crl_path are required.
-- untrusted_cert_file ------------------------------------------------
Path to a file containing one or more untrusted certs in PEM format.
Unfortunately, sometimes the CRLs are signed by a different CA
than the certificate being verified. In this case, you'll need to
provide the certificate belonging to the issuer of the CRL. That
certificate is considered "untrusted" by OpenSSL and can't be placed
in the ca_file or ca_path. It has to be specified here.
Default: none
-- untrusted_cert_path ------------------------------------------------
Path to a directory containing one or more hashed untrusted certs used
to verify CRLs.
See untrusted_cert_file above.
For this option, each certificates must be placed in its own
PEM file in the directory specified and hashed with the
following command:
`openssl rehash <ca_path>`
Default: none
NOTE: Neither untrusted_cert_file nor untrusted_cert_path are required
unless you're verifying CRLs that aren't signed by the same CA as the
X5U certificate.
-- cert_cache_dir -----------------------------------------------------
Incoming Identity headers will have a URL pointing to the certificate
used to sign the header. To prevent us from having to retrieve the
certificate for every request, we maintain a cache of them in the
'cert_cache_dir' specified. The directory will be checked for
existence and writability at startup.
Default: <astvarlibdir>/keys/stir_shaken/cache
-- curl_timeout -------------------------------------------------------
The number of seconds we'll wait for a response when trying to retrieve
the certificate specified in the incoming Identity header's "x5u"
parameter.
Default: 2
-- max_cache_entry_age ------------------------------------------------
Maximum age in seconds a certificate in the cache can reach before
re-retrieving it.
Default: 86400 (24 hours per ATIS-1000074)
NOTE: If, when retrieving the URL specified by the "x5u" parameter,
we receive a recognized caching directive in the HTTP response AND that
directive indicates caching for MORE than the value set here, we'll use
that time for the max_cache_entry_age.
-- max_cache_size -----------------------------------------------------
Maximum number of entries the cache can hold.
Not presently implemented.
-- max_iat_age --------------------------------------------------------
The "iat" parameter in the Identity header indicates the time the
sender actually created their attestation. If that is older than the
current time by the number of seconds set here, the request will be
considered "failed".
Default: 15
-- max_date_header_age ------------------------------------------------
The sender MUST also send a SIP Date header in their request. If we
receive one that is older than the current time by the number of seconds
set here, the request will be considered "failed".
Default: 15
-- failure_action -----------------------------------------------------
Indicates what will happen to requests that have failed verification.
Must be one of:
- continue -
Continue processing the request. You can use the STIR_SHAKEN
dialplan function to determine whether the request passed or failed
verification and take the action you deem appropriate.
- reject_request -
Reject the request immediately using the SIP response codes
defined by RFC8224.
- continue_return_reason -
Continue processing the request but, per RFC8224, send a SIP Reason
header back to the originator in the next provisional response
indicating the issue according to RFC8224. You can use the
STIR_SHAKEN dialplan function to determine whether the request
passed or failed verification and take the action you deem
appropriate.
Default: continue
NOTE: If you select "continue" or "continue_return_reason", and,
based on the results from the STIR_SHAKEN function, you determine you
want to terminate the call, you can use the PJSIPHangup() dialplan
application to reject the call using a STIR/SHAKEN-specific SIP
response code.
-- use_rfc9410_responses ----------------------------------------------
If set, when sending Reason headers back to originators, the protocol
header parameter will be set to "STIR" rather than "SIP". This is a
new protocol defined in RFC9410 and may not be supported by all
participants.
Default: no
-- relax_x5u_port_scheme_restrictions ---------------------------------
If set, the port and scheme restrictions imposed by ATIS-1000074
section 5.3.1 that require the scheme to be "https" and the port to
be 443 or 8443 are relaxed. This will allow schemes like "http"
and ports other than the two mentioned to appear in x5u URLs received
in Identity headers.
Default: no
CAUTION: Setting this parameter could have serious security
implications and should only be use for testing.
-- relax_x5u_path_restrictions ----------------------------------------
If set, the path restrictions imposed by ATIS-1000074 section 5.3.1
that require the x5u URL to be rejected if it contains a query string,
path parameters, fragment identifier or user/password are relaxed.
Default: no
CAUTION: Setting this parameter could have serious security
implications and should only be use for testing.
-- x5u_permit/x5u_deny ------------------------------------------------
When set, the IP address of the host in a received Identity header x5u
URL is checked against the acl created by this list of permit/deny
parameters. If the check fails, the x5u URL will be considered invalid
and verification will fail. This can prevent an attacker from sending
you a request pretending to be a known originator with a mailcious
certificate URL. (Server-side request forgery (SSRF)).
See acl.conf.sample to see examples of how to specify the permit/deny
parameters.
Default: Deny all "Special-Purpose" IP addresses described in RFC 6890.
This includes the loopback addresses 127.0.0.0/8, private use networks such
as 10.0.0/8, 172.16.0.0/12 and 192.168.0.0/16, and the link local network
169.254.0.0/16 among others.
CAUTION: Setting this parameter could have serious security
implications and should only be use for testing.
-- x5u_acl ------------------------------------------------------------
Rather than providing individual permit/deny parameters, you can set
the acllist parameter to an acl list predefined in acl.conf.
Default: none
CAUTION: Setting this parameter could have serious security
implications and should only be use for testing.
-----------------------------------------------------------------------
Example "verification" object:
--;
;[verification]
;global_disable = yes
;load_system_certs = no
;ca_path = /var/lib/asterisk/keys/stir_shaken/verification_ca
;cert_cache_dir = /var/lib/asterisk/keys/stir_shaken/verification_cache
;failure_action = reject_request
;curl_timeout=5
;max_iat_age=60
;max_date_header_age=60
;max_cache_entry_age = 300
; For internal testing
;x5u_deny=0.0.0.0/0.0.0.0
;x5u_permit=127.0.0.0/8
;x5u_permit=192.168.100.0/24
;relax_x5u_port_scheme_restrictions = yes
;relax_x5u_path_restrictions = yes
;--
=======================================================================
Profile Object Description
=======================================================================
A "profile" object can be associated to channel driver endpoint
(currently only chan_pjsip) and can set verification and attestation
parameters specific to endpoints using this profile. If you have
multiple upstream providers, this is the place to set parameters
specific to them.
The "id" of this object is arbitrary and you'd specify it in the
"stir_shaken_profile" parameter of the endpoint.
Parameters:
-- type (required) ----------------------------------------------------
Must be set to "profile"
Default: none
-- endpoint_behavior--------------------------------------------------
Actions to be performed for endpoints referencing this profile.
Must be one of:
- off -
Don't do any STIR/SHAKEN processing.
- attest -
Attest on outgoing calls.
- verify
Verify incoming calls.
- on -
Attest outgoing calls and verify incoming calls.
Default: off
All of the "verification" parameters defined above can be set on a profile
with the exception of 'global_disable'.
All of the "attestation" parameters defined above can be set on a profile
with the exception of 'global_disable'.
When Asterisk loads the configs, it creates "effective profiles" or
"eprofiles" on the fly that are the amalgamation of the attestation,
verification and profile. You can see them in the CLI with
"stir_shaken show eprofiles".
-----------------------------------------------------------------------
Example "profile" object:
--;
;[myprofile]
;type = profile
;endpoint_behavior = verify
;failure_action = continue_return_reason
;x5u_acl = myacllist
;In pjsip.conf...
;[myendpoint]
;type = endpoint
;stir_shaken_profile = myprofile
;In acl.conf...
;[myacllist]
;permit=0.0.0.0/0.0.0.0
;deny=10.24.20.171