STIR/SHAKEN Module

The following modules must be loaded before this module:

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

The maximum number of seconds that the value in the Date header field can be older than the current time.

This parameter is only relevant for the stir_shaken_auth() function.

The default value is 60.

...
modparam("stir_shaken", "auth_date_freshness", 300)
...

The maximum number of seconds that the value in the Date header field can be older than the current time. Also, if the iat value in the PASSporT is different than the Date value, but remains within the permitted interval, it will be used in the verification process (for the reconstructed PASSporT) instead of the Date value.

If the require_date_hdr parameter is set to not required and the Date header is missing, the iat value will be used for this check instead.

This parameter is only relevant for the stir_shaken_verify() function.

The default value is 60.

...
modparam("stir_shaken", "verify_date_freshness", 300)
...

Path to a file containing trusted CA certificates for the verifier. The certificates must be in PEM format, one after another.

...
modparam("stir_shaken", "ca_list", "/stir_certs/ca_list.pem")
...

Path to a directory containing trusted CA certificates for the verifier. The certificates in the directory must be in hashed form, as described in the openssl documentation for the Hashed Directory Method.

...
modparam("stir_shaken", "ca_dir", "/stir_certs/cas")
...

Path to a file containing certificate revocation lists (CRLs) for the verifier.

...
modparam("stir_shaken", "crl_list", "/stir_certs/crl_list.pem")
...

Path to a directory containing certificate revocation lists (CRLs) for the verifier. The CRLs in the directory must be in hashed form, as described in the openssl documentation for the Hashed Directory Method.

...
modparam("stir_shaken", "crl_dir", "/stir_certs/crls")
...

Require a leading "+" to be present in the originating/destination SHAKEN identity, on top of mandating an E.164 telephone number by default. Additionally, require the URI to be either a tel URI or a sip / sips URI with the user=phone parameter.

The default value is 0 (disabled).

...
modparam("stir_shaken", "e164_strict_mode", 1)
...

This parameter allows the 15-digit number length restriction of the E.164 format to be bypassed. Especially useful in scenarios where various telephony number prefixes are in use, causing some numbers to exceed the standard maximum length.

The default value is 15.

...
modparam("stir_shaken", "e164_max_length", 16)
...

Specifies whether the Date header is mandatory when doing verification with the stir_shaken_verify() function.

A value of 1 means required and 0 not required.

If the parameter is set to "not required" but the Date header is present in the message, the header value will be used as normally to check the freshness (as configured in the verify_date_freshness parameter). If the Date header is indeed missing, the value of the iat claim in the PASSporT will be used instead.

The default value is 1 (required).

...
modparam("stir_shaken", "require_date_hdr", 0)
...

This function performs the steps of an authentication service. Before calling this function though, you must ensure:

Meaning of the parameters is as follows:

The function returns the following values:

This function can be used from REQUEST_ROUTE.

...
stir_shaken_auth("A", "4437c7eb-8f7a-4f0e-a863-f53a0e60251a",
	$var(cert), $var(privKey), "https://certs.example.org/cert.pem");
...

This function performs the steps of an verification service.

Meaning of the parameters is as follows:

The function returns the following values:

This function can be used from REQUEST_ROUTE.

...
$var(rc) = stir_shaken_verify($var(cert), $var(err_code), $var(err_reason));
if ($var(rc) < -1) {
	send_reply($var(err_sip_code), $var(err_sip_reason));
	exit;
}
...

This function checks the Identity header in order to validate the STIR/SHAKEN information in terms of format. It detects issues such as: missing or badly formated PASSporT claims, unsupported extensions etc.

The function returns the following values:

This function can be used from REQUEST_ROUTE.

...
if (stir_shaken_check()) {
	xlog("forwarding call to stir/shaken verification service\n");
	...
}
...

This function checks if the current time falls within the given certificate's validity period.

The function returns the following values:

This function can be used from REQUEST_ROUTE.

...
# update expired cached certificates
cache_fetch("local", $identity(x5u), $var(cert));
if (!stir_shaken_check_cert($var(cert))) {
	rest_get($identity(x5u), $var(cert));
	cache_store("local", $identity(x5u), $var(cert));
}
...

This function add P-Identity-Bypass header with token value at the end of SIP headers.

Meaning of the parameters is as follows:

The function returns the following values:

This function can be used from REQUEST_ROUTE.

...
if ( is_method("INVITE") && !has_totag()) {
	# equivalent to sipmsgops module: append_hf("P-Identity-Bypass: OSIP99-1234567890ABCDEF\r\n");
	stir_shaken_disengagement("OSIP99-1234567890ABCDEF");
}
...

This is a read-only pseudo-variable that provides access to the parsed information from the Identity header, through the following subnames:

...
	# acquire the certificate to use for the verification process
	$var(rc) = rest_get($identity(x5u), $var(cert));
	if ($var(rc) < 0) {
		send_reply(436, "Bad Identity Info");
		exit;
	}
	...
	xlog("Verified caller:$identity(orig), attestation level: $identity(attest)\n");
...
	

Reload the file containing trusted CA certificates for the verifier and the directory containing trusted CA certificates for the verifier.

Name: stir_shaken_ca_reload

Parameters: none

MI FIFO Command Format:

...
opensips-cli -x mi stir_shaken_ca_reload
"OK"
...

Reload the file containing certificate revocation lists (CRLs) for the verifier and the directory containing certificate revocation lists for the verifier.

Name: stir_shaken_crl_reload

Parameters: none

MI FIFO Command Format:

...
opensips-cli -x mi stir_shaken_crl_reload
"OK"
...