res_stir_shaken.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	STIR_SHAKEN_ENCRYPTION_ALGORITHM   "ES256"
#define	STIR_SHAKEN_PPT   "shaken"
#define	STIR_SHAKEN_TYPE   "passport"

Enumerations
enum	ast_stir_shaken_verification_result { AST_STIR_SHAKEN_VERIFY_NOT_PRESENT, AST_STIR_SHAKEN_VERIFY_SIGNATURE_FAILED, AST_STIR_SHAKEN_VERIFY_MISMATCH, AST_STIR_SHAKEN_VERIFY_PASSED }

Functions
int	ast_stir_shaken_add_verification (struct ast_channel *chan, const char *identity, const char *attestation, enum ast_stir_shaken_verification_result result)
	Add a STIR/SHAKEN verification result to a channel. More...
unsigned int	ast_stir_shaken_get_signature_timeout (void)
	Retrieve the value for 'signature_timeout' from 'general' config object. More...
void	ast_stir_shaken_payload_free (struct ast_stir_shaken_payload *payload)
	Free a STIR/SHAKEN payload. More...
char *	ast_stir_shaken_payload_get_public_cert_url (const struct ast_stir_shaken_payload *payload)
	Retrieve the value for 'public_cert_url' from an ast_stir_shaken_payload. More...
unsigned char *	ast_stir_shaken_payload_get_signature (const struct ast_stir_shaken_payload *payload)
	Retrieve the value for 'signature' from an ast_stir_shaken_payload. More...
struct ast_stir_shaken_payload *	ast_stir_shaken_sign (struct ast_json *json)
	Sign a JSON STIR/SHAKEN payload. More...
struct ast_sorcery *	ast_stir_shaken_sorcery (void)
	Retrieve the stir/shaken sorcery context. More...
struct ast_stir_shaken_payload *	ast_stir_shaken_verify (const char *header, const char *payload, const char *signature, const char *algorithm, const char *public_cert_url)
	Verify a JSON STIR/SHAKEN payload. More...

Macro Definition Documentation

STIR_SHAKEN_ENCRYPTION_ALGORITHM

#define STIR_SHAKEN_ENCRYPTION_ALGORITHM   "ES256"

Definition at line 21 of file res_stir_shaken.h.

Referenced by add_identity_header(), AST_TEST_DEFINE(), and stir_shaken_verify_json().

STIR_SHAKEN_PPT

#define STIR_SHAKEN_PPT   "shaken"

Definition at line 22 of file res_stir_shaken.h.

Referenced by add_identity_header(), AST_TEST_DEFINE(), and stir_shaken_verify_json().

STIR_SHAKEN_TYPE

#define STIR_SHAKEN_TYPE   "passport"

Definition at line 23 of file res_stir_shaken.h.

Referenced by AST_TEST_DEFINE(), and stir_shaken_verify_json().

Enumeration Type Documentation

ast_stir_shaken_verification_result

enum ast_stir_shaken_verification_result

Enumerator
AST_STIR_SHAKEN_VERIFY_NOT_PRESENT
AST_STIR_SHAKEN_VERIFY_SIGNATURE_FAILED	No STIR/SHAKEN information was available
AST_STIR_SHAKEN_VERIFY_MISMATCH	Signature verification failed
AST_STIR_SHAKEN_VERIFY_PASSED	Contents of the signaling and the STIR/SHAKEN payload did not match

Definition at line 25 of file res_stir_shaken.h.

 {
 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 */
};

Function Documentation

ast_stir_shaken_add_verification()

int ast_stir_shaken_add_verification	(	struct ast_channel *	chan,
		const char *	identity,
		const char *	attestation,
		enum ast_stir_shaken_verification_result	result
	)

Add a STIR/SHAKEN verification result to a channel.

Parameters

chan	The channel
identity	The identity
attestation	The attestation
result	The verification result

Return values

-1	on failure
0	on success

Definition at line 277 of file res_stir_shaken.c.

References ast_calloc, ast_channel_datastore_add(), ast_channel_lock, ast_channel_name(), ast_channel_unlock, ast_datastore_alloc, ast_log, ast_strdup, stir_shaken_datastore::attestation, ast_datastore::data, stir_shaken_datastore::identity, LOG_ERROR, NULL, result, stir_shaken_datastore_free(), and stir_shaken_datastore::verify_result.

Referenced by stir_shaken_incoming_request().

{
 struct stir_shaken_datastore *ss_datastore;
 struct ast_datastore *datastore;
 const char *chan_name;

 if (!chan) {
 ast_log(LOG_ERROR, "Channel is required to add STIR/SHAKEN verification\n");
 return -1;
 }

 chan_name = ast_channel_name(chan);

 if (!identity) {
 ast_log(LOG_ERROR, "No identity to add STIR/SHAKEN verification to channel "
 "%s\n", chan_name);
 return -1;
 }

 if (!attestation) {
 ast_log(LOG_ERROR, "Attestation cannot be NULL to add STIR/SHAKEN verification to "
 "channel %s\n", chan_name);
 return -1;
 }

 ss_datastore = ast_calloc(1, sizeof(*ss_datastore));
 if (!ss_datastore) {
 ast_log(LOG_ERROR, "Failed to allocate space for STIR/SHAKEN datastore for "
 "channel %s\n", chan_name);
 return -1;
 }

 ss_datastore->identity = ast_strdup(identity);
 if (!ss_datastore->identity) {
 ast_log(LOG_ERROR, "Failed to allocate space for STIR/SHAKEN datastore "
 "identity for channel %s\n", chan_name);
 stir_shaken_datastore_free(ss_datastore);
 return -1;
 }

 ss_datastore->attestation = ast_strdup(attestation);
 if (!ss_datastore->attestation) {
 ast_log(LOG_ERROR, "Failed to allocate space for STIR/SHAKEN datastore "
 "attestation for channel %s\n", chan_name);
 stir_shaken_datastore_free(ss_datastore);
 return -1;
 }

 ss_datastore->verify_result = result;

 datastore = ast_datastore_alloc(&stir_shaken_datastore_info, NULL);
 if (!datastore) {
 ast_log(LOG_ERROR, "Failed to allocate space for datastore for channel "
 "%s\n", chan_name);
 stir_shaken_datastore_free(ss_datastore);
 return -1;
 }

 datastore->data = ss_datastore;

 ast_channel_lock(chan);
 ast_channel_datastore_add(chan, datastore);
 ast_channel_unlock(chan);

 return 0;
}

ast_stir_shaken_get_signature_timeout()

unsigned int ast_stir_shaken_get_signature_timeout

(

void

)

Retrieve the value for 'signature_timeout' from 'general' config object.

Return values

The	signature timeout

Definition at line 203 of file res_stir_shaken.c.

References ast_stir_shaken_signature_timeout(), and stir_shaken_general_get().

Referenced by compare_timestamp().

{
 return ast_stir_shaken_signature_timeout(stir_shaken_general_get());
}

ast_stir_shaken_payload_free()

void ast_stir_shaken_payload_free

(

struct ast_stir_shaken_payload *

payload

)

Free a STIR/SHAKEN payload.

Definition at line 178 of file res_stir_shaken.c.

References ast_stir_shaken_payload::algorithm, ast_free, ast_json_unref(), ast_stir_shaken_payload::header, ast_stir_shaken_payload::payload, ast_stir_shaken_payload::public_cert_url, and ast_stir_shaken_payload::signature.

Referenced by add_identity_header(), ast_stir_shaken_sign(), ast_stir_shaken_verify(), AST_TEST_DEFINE(), stir_shaken_incoming_request(), and stir_shaken_verify_json().

{
 if (!payload) {
 return;
 }

 ast_json_unref(payload->header);
 ast_json_unref(payload->payload);
 ast_free(payload->algorithm);
 ast_free(payload->public_cert_url);
 ast_free(payload->signature);

 ast_free(payload);
}

ast_stir_shaken_payload_get_public_cert_url()

char* ast_stir_shaken_payload_get_public_cert_url

(

const struct ast_stir_shaken_payload *

payload

)

Retrieve the value for 'public_cert_url' from an ast_stir_shaken_payload.

Parameters

payload

The payload

Return values

The	public key URL

Definition at line 198 of file res_stir_shaken.c.

References NULL, and ast_stir_shaken_payload::public_cert_url.

Referenced by add_identity_header().

{
 return payload ? payload->public_cert_url : NULL;
}

ast_stir_shaken_payload_get_signature()

unsigned char* ast_stir_shaken_payload_get_signature

(

const struct ast_stir_shaken_payload *

payload

)

Retrieve the value for 'signature' from an ast_stir_shaken_payload.

Parameters

payload

The payload

Return values

The

signature

Definition at line 193 of file res_stir_shaken.c.

References NULL, and ast_stir_shaken_payload::signature.

Referenced by add_identity_header().

{
 return payload ? payload->signature : NULL;
}

ast_stir_shaken_sign()

struct ast_stir_shaken_payload* ast_stir_shaken_sign

(

struct ast_json *

json

)

Sign a JSON STIR/SHAKEN payload.

Note

This function will automatically add the "attest", "iat", and "origid" fields.

Parameters

json	The JWT to sign

Return values

ast_stir_shaken_payload	on success
NULL	on failure

Definition at line 1046 of file res_stir_shaken.c.

References ao2_cleanup, ast_calloc, ast_free, ast_json_dump_string, ast_json_object_get(), ast_json_string_get(), ast_log, ast_stir_shaken_payload_free(), ast_strdup, cleanup(), ast_stir_shaken_payload::header, LOG_ERROR, NULL, ast_stir_shaken_payload::payload, ast_stir_shaken_payload::public_cert_url, ast_stir_shaken_payload::signature, stir_shaken_add_attest(), stir_shaken_add_iat(), stir_shaken_add_origid(), stir_shaken_add_x5u(), stir_shaken_certificate_get_attestation(), stir_shaken_certificate_get_by_caller_id_number(), stir_shaken_certificate_get_private_key(), stir_shaken_certificate_get_public_cert_url(), stir_shaken_sign(), and stir_shaken_verify_json().

Referenced by add_identity_header(), and AST_TEST_DEFINE().

{
 struct ast_stir_shaken_payload *ss_payload;
 unsigned char *signature;
 const char *public_cert_url;
 const char *caller_id_num;
 const char *header;
 const char *payload;
 struct ast_json *tmp_json;
 char *msg = NULL;
 size_t msg_len;
 struct stir_shaken_certificate *cert = NULL;

 ss_payload = stir_shaken_verify_json(json);
 if (!ss_payload) {
 return NULL;
 }

 /* From the payload section of the JSON, get the orig section, and then get
 * the value of tn. This will be the caller ID number */
 caller_id_num = ast_json_string_get(ast_json_object_get(ast_json_object_get(
 ast_json_object_get(json, "payload"), "orig"), "tn"));
 if (!caller_id_num) {
 ast_log(LOG_ERROR, "Failed to get caller ID number from JWT\n");
 goto cleanup;
 }

 cert = stir_shaken_certificate_get_by_caller_id_number(caller_id_num);
 if (!cert) {
 ast_log(LOG_ERROR, "Failed to retrieve certificate for caller ID "
 "'%s'\n", caller_id_num);
 goto cleanup;
 }

 public_cert_url = stir_shaken_certificate_get_public_cert_url(cert);
 if (stir_shaken_add_x5u(json, public_cert_url)) {
 ast_log(LOG_ERROR, "Failed to add 'x5u' (public cert URL) to payload\n");
 goto cleanup;
 }
 ss_payload->public_cert_url = ast_strdup(public_cert_url);

 if (stir_shaken_add_attest(json, stir_shaken_certificate_get_attestation(cert))) {
 ast_log(LOG_ERROR, "Failed to add 'attest' to payload\n");
 goto cleanup;
 }

 if (stir_shaken_add_origid(json)) {
 ast_log(LOG_ERROR, "Failed to add 'origid' to payload\n");
 goto cleanup;
 }

 if (stir_shaken_add_iat(json)) {
 ast_log(LOG_ERROR, "Failed to add 'iat' to payload\n");
 goto cleanup;
 }

 /* Get the header and the payload. Combine them to get the message to sign */
 tmp_json = ast_json_object_get(json, "header");
 header = ast_json_dump_string(tmp_json);
 tmp_json = ast_json_object_get(json, "payload");
 payload = ast_json_dump_string(tmp_json);
 msg_len = strlen(header) + strlen(payload) + 2;
 msg = ast_calloc(1, msg_len);
 if (!msg) {
 ast_log(LOG_ERROR, "Failed to allocate space for message to sign\n");
 goto cleanup;
 }
 snprintf(msg, msg_len, "%s.%s", header, payload);

 signature = stir_shaken_sign(msg, stir_shaken_certificate_get_private_key(cert));
 if (!signature) {
 goto cleanup;
 }

 ss_payload->signature = signature;
 ao2_cleanup(cert);
 ast_free(msg);

 return ss_payload;

cleanup:
 ao2_cleanup(cert);
 ast_stir_shaken_payload_free(ss_payload);
 ast_free(msg);
 return NULL;
}

ast_stir_shaken_sorcery()

struct ast_sorcery* ast_stir_shaken_sorcery

(

void

)

Retrieve the stir/shaken sorcery context.

Return values

The	stir/shaken sorcery context

Definition at line 173 of file res_stir_shaken.c.

References stir_shaken_sorcery.

Referenced by load_module(), stir_shaken_certificate_get(), stir_shaken_certificate_get_all(), stir_shaken_certificate_get_by_caller_id_number(), stir_shaken_certificate_load(), stir_shaken_cli_show(), stir_shaken_general_get(), stir_shaken_general_load(), stir_shaken_general_unload(), stir_shaken_store_get(), stir_shaken_store_get_all(), stir_shaken_store_load(), test_stir_shaken_cleanup_cert(), and test_stir_shaken_create_cert().

{
 return stir_shaken_sorcery;
}

ast_stir_shaken_verify()

struct ast_stir_shaken_payload* ast_stir_shaken_verify	(	const char *	header,
		const char *	payload,
		const char *	signature,
		const char *	algorithm,
		const char *	public_cert_url
	)

Verify a JSON STIR/SHAKEN payload.

Parameters

header	The payload header
payload	The payload section
signature	The payload signature
algorithm	The signature algorithm
public_cert_url	The public key URL

Return values

ast_stir_shaken_payload	on success
NULL	on failure

Definition at line 620 of file res_stir_shaken.c.

References add_public_key_to_astdb(), ast_stir_shaken_payload::algorithm, ast_asprintf, ast_calloc, ast_config_AST_DATA_DIR, ast_debug, ast_free, ast_json_load_string(), ast_log, ast_stir_shaken_payload_free(), ast_strdup, ast_strlen_zero, curl_and_check_expiration(), get_path_to_public_key(), ast_stir_shaken_payload::header, LOG_ERROR, NULL, ast_stir_shaken_payload::payload, ast_stir_shaken_payload::public_cert_url, public_key_is_expired(), RAII_VAR, remove_public_key_from_astdb(), run_curl(), ast_stir_shaken_payload::signature, STIR_SHAKEN_DIR_NAME, stir_shaken_read_key(), and stir_shaken_verify_signature().

Referenced by AST_TEST_DEFINE(), and stir_shaken_incoming_request().

{
 struct ast_stir_shaken_payload *ret_payload;
 EVP_PKEY *public_key;
 int curl = 0;
 RAII_VAR(char *, file_path, NULL, ast_free);
 RAII_VAR(char *, dir_path, NULL, ast_free);
 RAII_VAR(char *, combined_str, NULL, ast_free);
 size_t combined_size;

 if (ast_strlen_zero(header)) {
 ast_log(LOG_ERROR, "'header' is required for STIR/SHAKEN verification\n");
 return NULL;
 }

 if (ast_strlen_zero(payload)) {
 ast_log(LOG_ERROR, "'payload' is required for STIR/SHAKEN verification\n");
 return NULL;
 }

 if (ast_strlen_zero(signature)) {
 ast_log(LOG_ERROR, "'signature' is required for STIR/SHAKEN verification\n");
 return NULL;
 }

 if (ast_strlen_zero(algorithm)) {
 ast_log(LOG_ERROR, "'algorithm' is required for STIR/SHAKEN verification\n");
 return NULL;
 }

 if (ast_strlen_zero(public_cert_url)) {
 ast_log(LOG_ERROR, "'public_cert_url' is required for STIR/SHAKEN verification\n");
 return NULL;
 }

 /* Check to see if we have already downloaded this public cert. The reason we
 * store the file path is because:
 *
 * 1. If, for some reason, the default directory changes, we still know where
 * to look for the files we already have.
 *
 * 2. In the future, if we want to add a way to store the certs in multiple
 * {configurable) directories, we already have the storage mechanism in place.
 * The only thing that would be left to do is pull from the configuration.
 */
 file_path = get_path_to_public_key(public_cert_url);
 if (ast_asprintf(&dir_path, "%s/keys/%s", ast_config_AST_DATA_DIR, STIR_SHAKEN_DIR_NAME) < 0) {
 return NULL;
 }

 /* If we don't have an entry in AstDB, CURL from the provided URL */
 if (ast_strlen_zero(file_path)) {
 /* Remove this entry from the database, since we will be
 * downloading a new file anyways.
 */
 remove_public_key_from_astdb(public_cert_url);

 /* Go ahead and free file_path, in case anything was allocated above */
 ast_free(file_path);

 /* Download to the default path */
 file_path = run_curl(public_cert_url, dir_path);
 if (!file_path) {
 return NULL;
 }

 /* Signal that we have already downloaded a new file, no reason to do it again */
 curl = 1;

 /* We should have a successful download at this point, so
 * add an entry to the database.
 */
 add_public_key_to_astdb(public_cert_url, file_path);
 }

 /* Check to see if the cert we downloaded (or already had) is expired */
 if (public_key_is_expired(public_cert_url)) {

 ast_debug(3, "Public cert '%s' is expired\n", public_cert_url);

 remove_public_key_from_astdb(public_cert_url);

 /* If this fails, then there's nothing we can do */
 ast_free(file_path);
 file_path = curl_and_check_expiration(public_cert_url, dir_path, &curl);
 if (!file_path) {
 return NULL;
 }
 }

 /* First attempt to read the key. If it fails, try downloading the file,
 * unless we already did. Check for expiration again */
 public_key = stir_shaken_read_key(file_path, 0);
 if (!public_key) {

 ast_debug(3, "Failed first read of public key file '%s'\n", file_path);

 remove_public_key_from_astdb(public_cert_url);

 ast_free(file_path);
 file_path = curl_and_check_expiration(public_cert_url, dir_path, &curl);
 if (!file_path) {
 return NULL;
 }

 public_key = stir_shaken_read_key(file_path, 0);
 if (!public_key) {
 ast_log(LOG_ERROR, "Failed to read public key from '%s'\n", file_path);
 remove_public_key_from_astdb(public_cert_url);
 return NULL;
 }
 }

 /* Combine the header and payload to get the original signed message: header.payload */
 combined_size = strlen(header) + strlen(payload) + 2;
 combined_str = ast_calloc(1, combined_size);
 if (!combined_str) {
 ast_log(LOG_ERROR, "Failed to allocate space for message to verify\n");
 EVP_PKEY_free(public_key);
 return NULL;
 }
 snprintf(combined_str, combined_size, "%s.%s", header, payload);
 if (stir_shaken_verify_signature(combined_str, signature, public_key)) {
 ast_log(LOG_ERROR, "Failed to verify signature\n");
 EVP_PKEY_free(public_key);
 return NULL;
 }

 /* We don't need the public key anymore */
 EVP_PKEY_free(public_key);

 ret_payload = ast_calloc(1, sizeof(*ret_payload));
 if (!ret_payload) {
 ast_log(LOG_ERROR, "Failed to allocate STIR/SHAKEN payload\n");
 return NULL;
 }

 ret_payload->header = ast_json_load_string(header, NULL);
 if (!ret_payload->header) {
 ast_log(LOG_ERROR, "Failed to create JSON from header\n");
 ast_stir_shaken_payload_free(ret_payload);
 return NULL;
 }

 ret_payload->payload = ast_json_load_string(payload, NULL);
 if (!ret_payload->payload) {
 ast_log(LOG_ERROR, "Failed to create JSON from payload\n");
 ast_stir_shaken_payload_free(ret_payload);
 return NULL;
 }

 ret_payload->signature = (unsigned char *)ast_strdup(signature);
 ret_payload->algorithm = ast_strdup(algorithm);
 ret_payload->public_cert_url = ast_strdup(public_cert_url);

 return ret_payload;
}