modules: Add stirshaken module

[piotr-gregor]

Pre-Submission Checklist

• Commit message has the format required by CONTRIBUTING guide
• Commits are split per component (core, individual modules, libs, utils, ...)
• Each component has a single commit (if not, squash them into one commit)
• No commits to README files for modules (changes must be done to docbook files
  in doc/ subfolder, the README file is autogenerated)

Type Of Change

• Small bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds new functionality)
• Breaking change (fix or feature that would change existing functionality)

Checklist:

• PR should be backported to stable branches
• Tested changes locally
• Related to issue #XXXX (replace XXXX with an open issue number)

Description

This module uses libstirshaken to implement STIR-Shaken authentication and verification functions (STI-AS/VS).
It allows for easy verification of a SIP call containing PASSporT wrapped into SIP Identity Header using a specific certificate,
or a specific key, or by performing complete check on PASSporT including downloading certificate referenced in it's x5u header,
and optionally checking it against trusted root certificates (X509 cert path check). Certificates may be cached and loaded from disk.

Example usage:

loadmodule "stirshaken"
modparam("stirshaken", "as_default_key", "/path/to/key")

modparam("stirshaken", "vs_verify_x509_cert_path", 1)
modparam("stirshaken", "vs_ca_dir", "/path/to/ca")
modparam("stirshaken", "vs_cache_certificates", 1)
modparam("stirshaken", "vs_cache_dir", "/tmp/cert_cache")
modparam("stirshaken", "vs_cache_expire_s", 90)

request_route {
(...)
stirshaken_add_identity("https://sp.com/sp.pem", "B", "+44100", "+44200", "ref");
(...)

request_route {
(...)
stirshaken_check_identity();
(...)

[miconda]

Thanks for this contribution!

First thing that I noticed is the missing of the doc/ folder with the docbook documentation files for the module. You can look at secsipid module, probably you can copy over, rename the files to match the module name as well as the content to reflect what the module provides.

[miconda]

Thanks!

[miconda]

@piotr-gregor: the module was merged, a group for it was created in src/Makefile.groups, so the module is not going to be compiled by default, having dependency on libstirshaken -- it can be compiled and installed with:

make include_modules="stirshaken" cfg
make all
make install

During development, another way to compile it in the source code tree to check for errors, etc., is:

make modules modules=src/modules/stirshaken

Soon you will get an invitation for write access to Kamailio github repository, so you can push commits to stirshaken module directly. Of course, you can also use pull requests if you want other developers to review your changes.

Anyhow, for changes that you want to push to other components (core, internal libraries, other modules) it is strongly recommended to do pull requests. As a last remark here, do not forget about contributing guidelines and formatting the commit message, because we use commit history for building changelogs for releases:

• https://github.com/kamailio/kamailio/blob/master/.github/CONTRIBUTING.md#contributing-code-or-content

[piotr-gregor]

This is great! Thank you very much Daniel!