asterisk/res/res_stir_shaken/verification.h

76 lines
1.8 KiB
C
Raw Normal View History

Stir/Shaken Refactor Why do we need a refactor? The original stir/shaken implementation was started over 3 years ago when little was understood about practical implementation. The result was an implementation that wouldn't actually interoperate with any other stir-shaken implementations. There were also a number of stir-shaken features and RFC requirements that were never implemented such as TNAuthList certificate validation, sending Reason headers in SIP responses when verification failed but we wished to continue the call, and the ability to send Media Key(mky) grants in the Identity header when the call involved DTLS. Finally, there were some performance concerns around outgoing calls and selection of the correct certificate and private key. The configuration was keyed by an arbitrary name which meant that for every outgoing call, we had to scan the entire list of configured TNs to find the correct cert to use. With only a few TNs configured, this wasn't an issue but if you have a thousand, it could be. What's changed? * Configuration objects have been refactored to be clearer about their uses and to fix issues. * The "general" object was renamed to "verification" since it contains parameters specific to the incoming verification process. It also never handled ca_path and crl_path correctly. * A new "attestation" object was added that controls the outgoing attestation process. It sets default certificates, keys, etc. * The "certificate" object was renamed to "tn" and had it's key change to telephone number since outgoing call attestation needs to look up certificates by telephone number. * The "profile" object had more parameters added to it that can override default parameters specified in the "attestation" and "verification" objects. * The "store" object was removed altogther as it was never implemented. * We now use libjwt to create outgoing Identity headers and to parse and validate signatures on incoming Identiy headers. Our previous custom implementation was much of the source of the interoperability issues. * General code cleanup and refactor. * Moved things to better places. * Separated some of the complex functions to smaller ones. * Using context objects rather than passing tons of parameters in function calls. * Removed some complexity and unneeded encapsuation from the config objects. Resolves: #351 Resolves: #46 UserNote: Asterisk's stir-shaken feature has been refactored to correct interoperability, RFC compliance, and performance issues. See https://docs.asterisk.org/Deployment/STIR-SHAKEN for more information. UpgradeNote: The stir-shaken refactor is a breaking change but since it's not working now we don't think it matters. The stir_shaken.conf file has changed significantly which means that existing ones WILL need to be changed. The stir_shaken.conf.sample file in configs/samples/ has quite a bit more information. This is also an ABI breaking change since some of the existing objects needed to be changed or removed, and new ones added. Additionally, if res_stir_shaken is enabled in menuselect, you'll need to either have the development package for libjwt v1.15.3 installed or use the --with-libjwt-bundled option with ./configure.
2023-10-26 16:27:35 +00:00
/*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 2023, Sangoma Technologies Corporation
*
* George Joseph <gjoseph@sangoma.com>
*
* See http://www.asterisk.org for more information about
* the Asterisk project. Please do not directly contact
* any of the maintainers of this project for assistance;
* the project provides a web site, mailing lists and IRC
* channels for your use.
*
* This program is free software, distributed under the terms of
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree.
*/
#ifndef VERIFICATION_H_
#define VERIFICATION_H_
#include "common_config.h"
struct ast_stir_shaken_vs_ctx {
AST_DECLARE_STRING_FIELDS(
AST_STRING_FIELD(tag);
AST_STRING_FIELD(caller_id);
AST_STRING_FIELD(orig_tn);
AST_STRING_FIELD(identity_hdr);
AST_STRING_FIELD(date_hdr);
AST_STRING_FIELD(filename);
AST_STRING_FIELD(public_url);
AST_STRING_FIELD(hash);
AST_STRING_FIELD(hash_family);
AST_STRING_FIELD(url_family);
AST_STRING_FIELD(attestation);
AST_STRING_FIELD(cert_spc);
AST_STRING_FIELD(cert_cn);
);
struct profile_cfg *eprofile;
struct ast_channel *chan;
time_t date_hdr_time;
time_t validity_check_time;
long raw_key_len;
unsigned char *raw_key;
char expiration[32];
X509 *xcert;
enum ast_stir_shaken_vs_response_code failure_reason;
};
/*!
* \brief Load the stir/shaken verification service
*
* \retval 0 on success
* \retval -1 on error
*/
int vs_load(void);
/*!
* \brief Reload the stir/shaken verification service
*
* \retval 0 on success
* \retval -1 on error
*/
int vs_reload(void);
/*!
* \brief Unload the stir/shaken verification service
*
* \retval 0 on success
* \retval -1 on error
*/
int vs_unload(void);
#endif /* VERIFICATION_H_ */