The following modules must be installed (but not loaded) to use this module:

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

The interval in seconds after which the Identity header JWT is considered to be expired.

Default value is 300.

...
modparam("secsipid", "expire", 600)
...

The interval in seconds after which the HTTP GET operation to download the public key times out.

Default value is 5.

...
modparam("secsipid", "timeout", 2)
...

The path to the directory where to save cached public keys. If set, it activates the public key file caching in the libsecsipid library.

Default value is "".

...
modparam("secsipid", "cache_dir", "/tmp/kamailio/secsipid")
...

The interval in seconds after which a cached public key is considered expired. This value is passed to the libsecsipid library.

Default value is 3600.

...
modparam("secsipid", "cache_expire", 7200)
...

The name of or the path to the required per-process API module.

Default value is "secsipid_proc.so".

...
modparam("secsipid", "modproc", "secsipid_proc2.so")
...

Set a libsecsipid option. The value has to be name=value. The parameter can be set many times.

Default value is "" (not set).

...
modparam("secsipid", "libopt", "CacheExpires=0")
...

Check the validity of the Identity header using the keys stored in the file specified by "keyPath". If the parameter is empty, the function is downloading the key using the URL from "info" parameter of the Identity header, using the value of "timeout" parameter to limit the download time. The validity of the JWT body in the Identity header is also checked against the "expire" parameter.

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

...
request_route {
    ...
	if(secsipid_check_identity("/secsipid/$si/cert.pem")) { ... }
    ...
	if(secsipid_check_identity("")) { ... }
    ...
}
...

Further checks can be done with config operations, decoding the JWT header and payload using {s.select} and {s.decode.base64t} transformations together with jansson module.

Similar to secsipid_check_identity() with the public key value provided in the parameter.

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

...
request_route {
  ...
  http_client_query("https://provider.com/stir-shaken/cert.pem", "$var(pubkey)");
  ...
  if(secsipid_check_identity_pubkey("$var(pubkey)")) { ... }
  ...
}
...

Check the validity of the "sIdentity" parameter using the keys stored in the file specified by "keyPath". If the keyPath parameter is empty, the function is downloading the key using the URL from "info" parameter of the sIdentity, using the value of "timeout" parameter to limit the download time. The validity of the JWT in the sIdentity value is also checked against the "expire" parameter.

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

...
request_route {
    ...
	if(secsipid_check("...", "/secsipid/$si/cert.pem")) { ... }
    ...
	if(secsipid_check("...", "")) { ... }
    ...
}
...

Further checks can be done with config operations, decoding the JWT header and payload using {s.select} and {s.decode.base64t} transformations together with jansson module.

Check the validity of the "sIdentity" parameter using the key value given in the parameter "keyVal". The validity of the JWT in the sIdentity value is also checked against the "expire" parameter.

The "opts" parameter provides the verify options:

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

...
request_route {
    ...
    secsipid_get_url("https://provider.com/stir-shaken/cert.pem", "$var(pubkey)");
    if(secsipid_verify("$hdr(Identity)", "$var(pubkey)", "A")) { ... }
    ...
}
...

Further checks can be done with config operations, decoding the JWT header and payload using {s.select} and {s.decode.base64t} transformations together with jansson module.

Get the content of a URL and store the result in a variable. The result is cached by libsecsipid, if caching is enabled.

The url parameters can contain pseudo-variables and ovar has to be the name of a writable pseudo-variable.

This function can be used from ANY_ROUTE.

...
request_route {
  ...
  if(secsipid_get_url("https://$fd/stirshaken/cert.pem", "$var(pubkey)")) { ... }
  ...
}
...

Add Identity header using the key specified by "keyPath" to sign the JWT body. If origID is empty, a UUID string is generated to fill the field. The origTN represents the origination telephone number; destTN represents the destination telephone number; x5u is the HTTP URL referencing to the public key that should be used to verify the signature; attest represents the attestation level (should be "A", "B" or "C").

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

...
request_route {
    ...
    secsipid_add_identity("$fU", "$rU", "A", "",
        "https://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem");
    ...
}
...

Build Identity value using the key specified by "keyPath" to sign the JWT body. If origID is empty, a UUID string is generated to fill the field. The origTN represents the origination telephone number; destTN represents the destination telephone number; x5u is the HTTP URL referencing to the public key that should be used to verify the signature; attest represents the attestation level (should be "A", "B" or "C"). On success, the Indentity value is stored in variable $secsipid(val). It also sets $secsipid(ret) to the return value of the libsecsipid functions.

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

...
request_route {
    ...
    if(secsipid_build_identity("$fU", "$rU", "A", "",
            "https://kamailio.org/stir/$rd/cert.pem", "/secsipid/$rd/key.pem")) {
        xinfo("Identity value: $secsipid(val)\n");
    }
    ...
}
...

Similar to secsipid_build_identity(), but the private key data is provided as parameter instead to the file path.

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

...
request_route {
    ...
    if(secsipid_build_identity_prvkey("$fU", "$rU", "A", "",
            "https://kamailio.org/stir/$rd/cert.pem", "$var(prvkey)")) {
        xinfo("Identity value: $secsipid(val)\n");
    }
    ...
}
...

Build Identity value using the key specified by "keyPath" to sign the JWT body. The sheaders and spayload have to be string representation of JSON headers and payload to be signed. On success, the Indentity value is stored in variable $secsipid(val). It also sets $secsipid(ret) to the return value of the libsecsipid functions.

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

...
request_route {
    ...
    if(secsipid_sign("_JSON_HEADERS_", "_JSON_PAYLOAD_",
            "/secsipid/$rd/key.pem")) {
        xinfo("Identity value: $secsipid(val)\n");
    }
    ...
}
...

Build Identity value using the private key given by "keyData" to sign the JWT body. The sheaders and spayload have to be string representation of JSON headers and payload to be signed. On success, the Indentity value is stored in variable $secsipid(val). It also sets $secsipid(ret) to the return value of the libsecsipid functions.

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

...
request_route {
    ...
    if(secsipid_sign_prvkey("_JSON_HEADERS_", "_JSON_PAYLOAD_",
            "_PRIVATE_KEY_")) {
        xinfo("Identity value: $secsipid(val)\n");
    }
    ...
}
...