res_stir_shaken: STIR/SHAKEN module for Asterisk¶
This configuration documentation is for functionality provided by res_stir_shaken.
Configuration File: stir_shaken.conf¶
[attestation]: STIR/SHAKEN attestation options¶
Configuration Option Reference¶
| Option Name | Type | Default Value | Regular Expression | Description |
|---|---|---|---|---|
| attest_level | Custom | not_set | false | Attestation level |
| check_tn_cert_public_url | Custom | no | false | On load, Retrieve all TN's certificates and validate their dates |
| global_disable | Boolean | no | false | Globally disable verification |
| private_key_file | String | false | File path to a certificate | |
| public_cert_url | String | false | URL to the public certificate | |
| send_mky | Custom | no | false | Send a media key (mky) grant in the attestation for DTLS calls. (not common) |
| unknown_tn_attest_level | Custom | not_set | false | Attestation level to use for unknown TNs |
Configuration Option Descriptions¶
public_cert_url¶
Must be a valid http, or https, URL.
unknown_tn_attest_level¶
Normally if a callerid TN isn't configured in stir_shaken.conf no Identity header will be created. If this option is set, however, an Identity header will be sent using this attestation level. Since there's no TN object, you must ensure that a private_key_file and public_cert_url are configured in the attestation or profile objects for this to work.
[tn]: STIR/SHAKEN TN options¶
Configuration Option Reference¶
| Option Name | Type | Default Value | Regular Expression | Description |
|---|---|---|---|---|
| attest_level | Custom | not_set | false | Attestation level |
| check_tn_cert_public_url | Custom | not_set | false | On load, Retrieve all TN's certificates and validate their dates |
| private_key_file | String | false | File path to a certificate | |
| public_cert_url | String | false | URL to the public certificate | |
| send_mky | Custom | not_set | false | Send a media key (mky) grant in the attestation for DTLS calls. (not common) |
| type | None | false | Must be of type 'tn'. |
Configuration Option Descriptions¶
public_cert_url¶
Must be a valid http, or https, URL.
[verification]: STIR/SHAKEN verification options¶
Configuration Option Reference¶
| Option Name | Type | Default Value | Regular Expression | Description |
|---|---|---|---|---|
| ca_file | String | false | Path to a file containing one or more CA certs in PEM format | |
| ca_path | String | false | Path to a directory containing one or more hashed CA certs | |
| cert_cache_dir | String | /var/lib/asterisk/keys/stir_shaken/cache | false | Directory to cache retrieved verification certs |
| crl_file | String | false | Path to a file containing one or more CRLs in PEM format | |
| crl_path | String | false | Path to a directory containing one or more hashed CRLs | |
| curl_timeout | Unsigned Integer | 2 | false | Maximum time to wait to CURL certificates |
| failure_action | Custom | continue | false | The default failure action when not set on a profile |
| global_disable | Boolean | no | false | Globally disable verification |
| load_system_certs | Custom | no | false | A boolean indicating whether trusted CA certificates should be loaded from the system |
| max_cache_entry_age | Unsigned Integer | 3600 | false | Number of seconds a cache entry may be behind current time |
| max_cache_size | Unsigned Integer | 1000 | false | Maximum size to use for caching public keys |
| max_date_header_age | Unsigned Integer | 15 | false | Number of seconds a SIP Date header may be behind current time |
| max_iat_age | Unsigned Integer | 15 | false | Number of seconds an iat grant may be behind current time |
| relax_x5u_path_restrictions | Custom | no | false | Relaxes check for query parameters, user/password, etc. in incoming Identity header x5u URLs. |
| relax_x5u_port_scheme_restrictions | Custom | no | false | Relaxes check for "https" and port 443 or 8443 in incoming Identity header x5u URLs. |
| untrusted_cert_file | String | false | Path to a file containing one or more untrusted cert in PEM format used to verify CRLs | |
| untrusted_cert_path | String | false | Path to a directory containing one or more hashed untrusted certs used to verify CRLs | |
| use_rfc9410_responses | Custom | no | false | RFC9410 uses the STIR protocol on Reason headers instead of the SIP protocol |
| x5u_acl | Custom | false | An existing ACL from acl.conf to use when checking hostnames in incoming Identity header x5u URLs. | |
| x5u_deny | Custom | false | An IP or subnet to deny checking hostnames in incoming Identity header x5u URLs. | |
| x5u_permit | Custom | false | An IP or subnet to permit when checking hostnames in incoming Identity header x5u URLs. |
Configuration Option Descriptions¶
ca_file¶
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.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
ca_path¶
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.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
For this option, the individual certificates must be placed in the directory specified and hashed using the 'openssl rehash' command.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
crl_file¶
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.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
crl_path¶
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.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
For this option, the individual CRLs must be placed in the directory specified and hashed using the 'openssl rehash' command.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
failure_action¶
-
continue- If set to 'continue', continue and let the dialplan decide what action to take. -
reject_request- If set to 'reject_request', reject the incoming request with response codes defined in RFC8224. -
continue_return_reason- If set to 'return_reason', continue to the dialplan but add a 'Reason' header to the sender in the next provisional response.
untrusted_cert_file¶
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. Unfortunately, sometimes the CRLs are signed by a different CA than the certificate being verified. In this case, you may need to provide the untrusted certificate to verify the CRL.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
untrusted_cert_path¶
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. Unfortunately, sometimes the CRLs are signed by a different CA than the certificate being verified. In this case, you may need to provide the untrusted certificate to verify the CRL.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
For this option, the individual certificates must be placed in the directory specified and hashed using the 'openssl rehash' command.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
[profile]: STIR/SHAKEN profile configuration options¶
Configuration Option Reference¶
| Option Name | Type | Default Value | Regular Expression | Description |
|---|---|---|---|---|
| attest_level | Custom | not_set | false | Attestation level |
| ca_file | String | false | Path to a file containing one or more CA certs in PEM format | |
| ca_path | String | false | Path to a directory containing one or more hashed CA certs | |
| cert_cache_dir | String | false | Directory to cache retrieved verification certs | |
| check_tn_cert_public_url | Custom | not_set | false | On load, Retrieve all TN's certificates and validate their dates |
| crl_file | String | false | Path to a file containing one or more CRLs in PEM format | |
| crl_path | String | false | Path to a directory containing one or more hashed CRLs | |
| curl_timeout | Unsigned Integer | 0 | false | Maximum time to wait to CURL certificates |
| endpoint_behavior | Custom | off | false | Actions performed when an endpoint references this profile |
| failure_action | Custom | continue | false | The default failure action when not set on a profile |
| load_system_certs | Custom | not_set | false | A boolean indicating whether trusted CA certificates should be loaded from the system |
| max_cache_entry_age | Unsigned Integer | 0 | false | Number of seconds a cache entry may be behind current time |
| max_cache_size | Unsigned Integer | 0 | false | Maximum size to use for caching public keys |
| max_date_header_age | Unsigned Integer | 0 | false | Number of seconds a SIP Date header may be behind current time |
| max_iat_age | Unsigned Integer | 0 | false | Number of seconds an iat grant may be behind current time |
| private_key_file | String | false | File path to a certificate | |
| public_cert_url | String | false | URL to the public certificate | |
| relax_x5u_path_restrictions | Custom | not_set | false | Relaxes check for query parameters, user/password, etc. in incoming Identity header x5u URLs. |
| relax_x5u_port_scheme_restrictions | Custom | not_set | false | Relaxes check for "https" and port 443 or 8443 in incoming Identity header x5u URLs. |
| send_mky | Custom | not_set | false | Send a media key (mky) grant in the attestation for DTLS calls. (not common) |
| type | None | false | Must be of type 'profile'. | |
| unknown_tn_attest_level | Custom | not_set | false | Attestation level to use for unknown TNs |
| untrusted_cert_file | String | false | Path to a file containing one or more untrusted cert in PEM format used to verify CRLs | |
| untrusted_cert_path | String | false | Path to a directory containing one or more hashed untrusted certs used to verify CRLs | |
| use_rfc9410_responses | Custom | not_set | false | RFC9410 uses the STIR protocol on Reason headers instead of the SIP protocol |
| x5u_acl | Custom | false | An existing ACL from acl.conf to use when checking hostnames in incoming Identity header x5u URLs. | |
| x5u_deny | Custom | false | An IP or subnet to deny checking hostnames in incoming Identity header x5u URLs. | |
| x5u_permit | Custom | false | An IP or subnet to permit when checking hostnames in incoming Identity header x5u URLs. |
Configuration Option Descriptions¶
ca_file¶
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.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
ca_path¶
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.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
For this option, the individual certificates must be placed in the directory specified and hashed using the 'openssl rehash' command.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
crl_file¶
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.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
crl_path¶
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.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
For this option, the individual CRLs must be placed in the directory specified and hashed using the 'openssl rehash' command.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
endpoint_behavior¶
-
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.
failure_action¶
-
continue- If set to 'continue', continue and let the dialplan decide what action to take. -
reject_request- If set to 'reject_request', reject the incoming request with response codes defined in RFC8224. -
continue_return_reason- If set to 'return_reason', continue to the dialplan but add a 'Reason' header to the sender in the next provisional response.
public_cert_url¶
Must be a valid http, or https, URL.
unknown_tn_attest_level¶
Normally if a callerid TN isn't configured in stir_shaken.conf no Identity header will be created. If this option is set, however, an Identity header will be sent using this attestation level. Since there's no TN object, you must ensure that a private_key_file and public_cert_url are configured in the attestation or profile objects for this to work.
untrusted_cert_file¶
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. Unfortunately, sometimes the CRLs are signed by a different CA than the certificate being verified. In this case, you may need to provide the untrusted certificate to verify the CRL.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
untrusted_cert_path¶
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. Unfortunately, sometimes the CRLs are signed by a different CA than the certificate being verified. In this case, you may need to provide the untrusted certificate to verify the CRL.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
For this option, the individual certificates must be placed in the directory specified and hashed using the 'openssl rehash' command.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
Generated Version¶
This documentation was generated from Asterisk branch 20 using version GIT