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;
}