kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-11-08 19:08:14 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
db012e8cc6616d17ff048ea817eb3945b0c13cd4
asterisk/include/asterisk/res_stir_shaken.h

96 lines
2.8 KiB
C
Raw Normal View History

res_stir_shaken: Initial commit and reading private key. This commit sets up some of the initial framework for the module and adds a way to read the private key from the specified file, which will then be appended to the certificate object. This works fine for now, but eventually some other structure will likely need to be used to store all this information. Similarly, the caller_id_number is specified on the certificate config object, but in the end we will want that information to be tied to the certificate itself and read it from there. A method has been added that will retrieve the private key associated with the caller_id_number passed in. Tab completion for certificates and stores has also been added. Change-Id: Ic4bc1416fab5d6afe15a8e2d32f7ddd4e023295f
2020-03-23 15:00:09 -05:00
/*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 2020, Sangoma Technologies Corporation
*
* Kevin Harwell <kharwell@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 _RES_STIR_SHAKEN_H
#define _RES_STIR_SHAKEN_H
#include <openssl/evp.h>
#include <openssl/pem.h>
res_stir_shaken: Added dialplan function and API call. Adds the "STIR_SHAKEN" dialplan function and an API call to add a STIR_SHAKEN verification result to a channel. This information will be held in a datastore on the channel that can later be queried through the "STIR_SHAKEN" dialplan funtion to get information on STIR_SHAKEN results including identity, attestation, and verify_result. Here are some examples: STIR_SHAKEN(count) STIR_SHAKEN(0, identity) STIR_SHAKEN(1, attestation) STIR_SHAKEN(2, verify_result) Getting the count can be used to iterate through the results and pull information by specifying the index and the field you want to retrieve. Change-Id: Ice6d52a3a7d6e4607c9c35b28a1f7c25f5284a82
2020-05-04 16:11:00 -05:00
enum ast_stir_shaken_verification_result {
AST_STIR_SHAKEN_VERIFY_NOT_PRESENT, /*! No STIR/SHAKEN information was available */
AST_STIR_SHAKEN_VERIFY_SIGNATURE_FAILED, /*! Signature verification failed */
AST_STIR_SHAKEN_VERIFY_MISMATCH, /*! Contents of the signaling and the STIR/SHAKEN payload did not match */
AST_STIR_SHAKEN_VERIFY_PASSED, /*! Signature verified and contents match signaling */
};
res_stir_shaken: Implemented signing of JSON payload. This change provides functions that take in a JSON payload, verify that the contents contain all the mandatory fields and required values (if any), and signs the payload with the private key. Four fields are added to the payload: x5u, attest, iat, and origid. As of now, these are just placeholder values that will be set to actual values once the logic is implemented for what to do when an actual payload is received, but the functions to add these values have all been implemented and are ready to use. Upon successful signing and the addition of those four values, a ast_stir_shaken_payload is returned, containing other useful information such as the algorithm and signature. Change-Id: I74fa41c0640ab2a64a1a80110155bd7062f13393
2020-03-26 13:34:47 -05:00
struct ast_stir_shaken_payload;
struct ast_json;
res_stir_shaken: Add inbound INVITE support. Integrated STIR/SHAKEN support with incoming INVITES. Upon receiving an INVITE, the Identity header is retrieved, parsing the message to verify the signature. If any of the parsing fails, AST_STIR_SHAKEN_VERIFY_NOT_PRESENT will be added to the channel for this caller ID. If verification itself fails, AST_STIR_SHAKEN_VERIFY_SIGNATURE_FAILED will be added. If anything in the payload does not line up with the SIP signaling, AST_STIR_SHAKEN_VERIFY_MISMATCH will be added. If all of the above steps pass, then AST_STIR_SHAKEN_VERIFY_PASSED will be added, completing the verification process. A new config option has been added to the general section for stir_shaken.conf. "signature_timeout" is the amount of time a signature will be considered valid. If an INVITE is received and the amount of time between when it was received and when it was signed is greater than signature_timeout, verification will fail. Some changes were also made to signing and verification. There was an error where the whole JSON string was being signed rather than the header combined with the payload. This has been changed to sign the correct thing. Verification has been changed to do this as well, and the unit tests have been updated to reflect these changes. A couple of utility functions have also been added. One decodes a BASE64 string and returns the decoded string, doing all the length calculations for you. The other retrieves a string value from a header in a rdata object. Change-Id: I855f857be3d1c63b64812ac35d9ce0534085b913
2020-05-19 14:46:45 -05:00
/*!
* \brief Retrieve the value for 'signature_timeout' from 'general' config object
*
* \retval The signature timeout
*/
unsigned int ast_stir_shaken_get_signature_timeout(void);
res_stir_shaken: Added dialplan function and API call. Adds the "STIR_SHAKEN" dialplan function and an API call to add a STIR_SHAKEN verification result to a channel. This information will be held in a datastore on the channel that can later be queried through the "STIR_SHAKEN" dialplan funtion to get information on STIR_SHAKEN results including identity, attestation, and verify_result. Here are some examples: STIR_SHAKEN(count) STIR_SHAKEN(0, identity) STIR_SHAKEN(1, attestation) STIR_SHAKEN(2, verify_result) Getting the count can be used to iterate through the results and pull information by specifying the index and the field you want to retrieve. Change-Id: Ice6d52a3a7d6e4607c9c35b28a1f7c25f5284a82
2020-05-04 16:11:00 -05:00
/*!
* \brief Add a STIR/SHAKEN verification result to a channel
*
* \param chan The channel
* \param identity The identity
* \param attestation The attestation
* \param result The verification result
*
* \retval -1 on failure
* \retval 0 on success
*/
int ast_stir_shaken_add_verification(struct ast_channel *chan, const char *identity, const char *attestation,
enum ast_stir_shaken_verification_result result);
res_stir_shaken: Implemented signature verification. There are a lot of moving parts in this patch, but the focus of it is on the verification of the signature using a public key located at the public key URL provided in the JSON payload. First, we check the database to see if we have already downloaded the key. If so, check to see if it has expired. If it has, redownload from the URL. If we don't have an entry in the database, just go ahead and download the public key. The expiration is tested each time we download the file. After that, read the public key from the file and use it to verify the signature. All sanity checking is done when the payload is first received, so the verification is complete once this point is reached. The XML has also been added since a new config option was added to general (curl_timeout). The maximum amount of time to wait for a download can be configured through this option, with a low value by default. Change-Id: I3ba4c63880493bf8c7d17a9cfca1af0e934d1a1c
2020-04-15 13:15:21 -05:00
/*!
* \brief Verify a JSON STIR/SHAKEN payload
*
* \param header The payload header
* \param payload The payload section
* \param signature The payload signature
* \param algorithm The signature algorithm
* \param public_key_url The public key URL
*
* \retval ast_stir_shaken_payload on success
* \retval NULL on failure
*/
struct ast_stir_shaken_payload *ast_stir_shaken_verify(const char *header, const char *payload, const char *signature,
const char *algorithm, const char *public_key_url);
res_stir_shaken: Initial commit and reading private key. This commit sets up some of the initial framework for the module and adds a way to read the private key from the specified file, which will then be appended to the certificate object. This works fine for now, but eventually some other structure will likely need to be used to store all this information. Similarly, the caller_id_number is specified on the certificate config object, but in the end we will want that information to be tied to the certificate itself and read it from there. A method has been added that will retrieve the private key associated with the caller_id_number passed in. Tab completion for certificates and stores has also been added. Change-Id: Ic4bc1416fab5d6afe15a8e2d32f7ddd4e023295f
2020-03-23 15:00:09 -05:00
/*!
* \brief Retrieve the stir/shaken sorcery context
*
* \retval The stir/shaken sorcery context
*/
struct ast_sorcery *ast_stir_shaken_sorcery(void);
/*!
res_stir_shaken: Implemented signing of JSON payload. This change provides functions that take in a JSON payload, verify that the contents contain all the mandatory fields and required values (if any), and signs the payload with the private key. Four fields are added to the payload: x5u, attest, iat, and origid. As of now, these are just placeholder values that will be set to actual values once the logic is implemented for what to do when an actual payload is received, but the functions to add these values have all been implemented and are ready to use. Upon successful signing and the addition of those four values, a ast_stir_shaken_payload is returned, containing other useful information such as the algorithm and signature. Change-Id: I74fa41c0640ab2a64a1a80110155bd7062f13393
2020-03-26 13:34:47 -05:00
* \brief Free a STIR/SHAKEN payload
*/
void ast_stir_shaken_payload_free(struct ast_stir_shaken_payload *payload);
/*!
* \brief Sign a JSON STIR/SHAKEN payload
res_stir_shaken: Initial commit and reading private key. This commit sets up some of the initial framework for the module and adds a way to read the private key from the specified file, which will then be appended to the certificate object. This works fine for now, but eventually some other structure will likely need to be used to store all this information. Similarly, the caller_id_number is specified on the certificate config object, but in the end we will want that information to be tied to the certificate itself and read it from there. A method has been added that will retrieve the private key associated with the caller_id_number passed in. Tab completion for certificates and stores has also been added. Change-Id: Ic4bc1416fab5d6afe15a8e2d32f7ddd4e023295f
2020-03-23 15:00:09 -05:00
*
res_stir_shaken: Implemented signing of JSON payload. This change provides functions that take in a JSON payload, verify that the contents contain all the mandatory fields and required values (if any), and signs the payload with the private key. Four fields are added to the payload: x5u, attest, iat, and origid. As of now, these are just placeholder values that will be set to actual values once the logic is implemented for what to do when an actual payload is received, but the functions to add these values have all been implemented and are ready to use. Upon successful signing and the addition of those four values, a ast_stir_shaken_payload is returned, containing other useful information such as the algorithm and signature. Change-Id: I74fa41c0640ab2a64a1a80110155bd7062f13393
2020-03-26 13:34:47 -05:00
* \note This function will automatically add the "attest", "iat", and "origid" fields.
res_stir_shaken: Implemented signature verification. There are a lot of moving parts in this patch, but the focus of it is on the verification of the signature using a public key located at the public key URL provided in the JSON payload. First, we check the database to see if we have already downloaded the key. If so, check to see if it has expired. If it has, redownload from the URL. If we don't have an entry in the database, just go ahead and download the public key. The expiration is tested each time we download the file. After that, read the public key from the file and use it to verify the signature. All sanity checking is done when the payload is first received, so the verification is complete once this point is reached. The XML has also been added since a new config option was added to general (curl_timeout). The maximum amount of time to wait for a download can be configured through this option, with a low value by default. Change-Id: I3ba4c63880493bf8c7d17a9cfca1af0e934d1a1c
2020-04-15 13:15:21 -05:00
*
* \param json The JWT to sign
*
* \retval ast_stir_shaken_payload on success
* \retval NULL on failure
res_stir_shaken: Initial commit and reading private key. This commit sets up some of the initial framework for the module and adds a way to read the private key from the specified file, which will then be appended to the certificate object. This works fine for now, but eventually some other structure will likely need to be used to store all this information. Similarly, the caller_id_number is specified on the certificate config object, but in the end we will want that information to be tied to the certificate itself and read it from there. A method has been added that will retrieve the private key associated with the caller_id_number passed in. Tab completion for certificates and stores has also been added. Change-Id: Ic4bc1416fab5d6afe15a8e2d32f7ddd4e023295f
2020-03-23 15:00:09 -05:00
*/
res_stir_shaken: Implemented signing of JSON payload. This change provides functions that take in a JSON payload, verify that the contents contain all the mandatory fields and required values (if any), and signs the payload with the private key. Four fields are added to the payload: x5u, attest, iat, and origid. As of now, these are just placeholder values that will be set to actual values once the logic is implemented for what to do when an actual payload is received, but the functions to add these values have all been implemented and are ready to use. Upon successful signing and the addition of those four values, a ast_stir_shaken_payload is returned, containing other useful information such as the algorithm and signature. Change-Id: I74fa41c0640ab2a64a1a80110155bd7062f13393
2020-03-26 13:34:47 -05:00
struct ast_stir_shaken_payload *ast_stir_shaken_sign(struct ast_json *json);
res_stir_shaken: Initial commit and reading private key. This commit sets up some of the initial framework for the module and adds a way to read the private key from the specified file, which will then be appended to the certificate object. This works fine for now, but eventually some other structure will likely need to be used to store all this information. Similarly, the caller_id_number is specified on the certificate config object, but in the end we will want that information to be tied to the certificate itself and read it from there. A method has been added that will retrieve the private key associated with the caller_id_number passed in. Tab completion for certificates and stores has also been added. Change-Id: Ic4bc1416fab5d6afe15a8e2d32f7ddd4e023295f
2020-03-23 15:00:09 -05:00
#endif /* _RES_STIR_SHAKEN_H */
Reference in New Issue Copy Permalink