[RTC-18] Don't raise in protect and unprotect (#14)

Author: daniel-jodlos

c_src/ex_libsrtp/srtp.c

@@ -254,7 +254,7 @@ UNIFEX_TERM protect(UnifexEnv *env, UnifexState *state, char *what,
                                      use_mki, mki_index);
   if (serr) {
     unifex_payload_free_clone(protected);
-    return unifex_raise(env, srtp_util_strerror(serr));
+    return protect_result_error(env, srtp_util_error_to_atom(serr));
   }
 
   err = unifex_payload_realloc(protected, len);
@@ -283,19 +283,7 @@ UNIFEX_TERM unprotect(UnifexEnv *env, UnifexState *state, char *what,
                                     use_mki);
   if (serr) {
     unifex_payload_free_clone(unprotected);
-
-    switch (serr) {
-    case srtp_err_status_auth_fail:
-      return unprotect_result_error_auth_fail(env);
-    case srtp_err_status_replay_fail:
-      return unprotect_result_error_replay_fail(env);
-    case srtp_err_status_bad_mki:
-      return unprotect_result_error_bad_mki(env);
-    case srtp_err_status_replay_old:
-        return unprotect_result_error_replay_too_old(env);
-    default:
-      return unifex_raise(env, srtp_util_strerror(serr));
-    }
+    return unprotect_result_error(env, srtp_util_error_to_atom(serr));
   }
 
   err = unifex_payload_realloc(unprotected, len);

c_src/ex_libsrtp/srtp.spec.exs

@@ -35,10 +35,8 @@ spec update(
 
 spec protect(state, what :: atom, payload, use_mki :: bool, mki_index :: unsigned) ::
        {:ok :: label, payload}
+       | {:error :: label, reason :: atom}
 
 spec unprotect(state, what :: atom, payload, use_mki :: bool) ::
        {:ok :: label, payload}
-       | {:error :: label, :auth_fail :: label}
-       | {:error :: label, :replay_fail :: label}
-       | {:error :: label, :bad_mki :: label}
-       | {:error :: label, :replay_too_old :: label}
+       | {:error :: label, reason :: atom}

c_src/ex_libsrtp/srtp_util.c

@@ -181,3 +181,67 @@ const char *srtp_util_strerror(srtp_err_status_t err) {
     return "srtp: unknown error";
   }
 }
+
+const char *srtp_util_error_to_atom(srtp_err_status_t err) {
+  switch (err) {
+  case srtp_err_status_ok:
+    // hardly an error, but let's leave it here for completeness sake
+    return "ok";
+  case srtp_err_status_fail:
+    return "fail";
+  case srtp_err_status_bad_param:
+    return "bad_param";
+  case srtp_err_status_alloc_fail:
+    return "alloc_fail";
+  case srtp_err_status_dealloc_fail:
+    return "dealloc_fail";
+  case srtp_err_status_init_fail:
+    return "init_fail";
+  case srtp_err_status_terminus:
+    return "terminus";
+  case srtp_err_status_auth_fail:
+    return "auth_fail";
+  case srtp_err_status_cipher_fail:
+    return "cipher_fail";
+  case srtp_err_status_replay_fail:
+    return "replay_fail";
+  case srtp_err_status_replay_old:
+    return "replay_old";
+  case srtp_err_status_algo_fail:
+    return "algo_fail";
+  case srtp_err_status_no_such_op:
+    return "no_such_op";
+  case srtp_err_status_no_ctx:
+    return "no_ctx";
+  case srtp_err_status_cant_check:
+    return "cant_check";
+  case srtp_err_status_key_expired:
+    return "key_expired";
+  case srtp_err_status_socket_err:
+    return "socket_err";
+  case srtp_err_status_signal_err:
+    return "signal_err";
+  case srtp_err_status_nonce_bad:
+    return "nonce_bad";
+  case srtp_err_status_read_fail:
+    return "read_fail";
+  case srtp_err_status_write_fail:
+    return "write_fail";
+  case srtp_err_status_parse_err:
+    return "parse_err";
+  case srtp_err_status_encode_err:
+    return "encode_err";
+  case srtp_err_status_semaphore_err:
+    return "semaphore_err";
+  case srtp_err_status_pfkey_err:
+    return "pfkey_err";
+  case srtp_err_status_bad_mki:
+    return "bad_mki";
+  case srtp_err_status_pkt_idx_old:
+    return "pkt_idx_old";
+  case srtp_err_status_pkt_idx_adv:
+    return "pkt_idx_adv";
+  default:
+    return "unknown";
+  }
+}

c_src/ex_libsrtp/srtp_util.h

@@ -4,7 +4,11 @@
 #include <stdbool.h>
 
 const char *srtp_util_strerror(srtp_err_status_t err);
+
 bool srtp_util_unmarshal_ssrc(int ssrc_type, unsigned int ssrc,
                               srtp_ssrc_t *result);
+
 bool srtp_util_set_crypto_policy_from_crypto_profile_atom(
     char *crypto_profile, srtp_crypto_policy_t *policy);
+
+const char *srtp_util_error_to_atom(srtp_err_status_t err);

lib/ex_libsrtp.ex

@@ -12,6 +12,42 @@ defmodule ExLibSRTP do
 
   alias ExLibSRTP.{Native, Policy}
 
+  @typedoc """
+  Type describing possible errors that might be returned by ExLibSRTP functions.
+
+  Meaning of these might vary depending on the function. For explanation, please refer to
+  appropriate documentation.
+
+  This type is based on [`srtp_err_status_t` enum](https://github.com/cisco/libsrtp/blob/004b7bb85caf4f52a7cc8a7aad94d9d1706e8b6d/include/srtp.h#L164).
+  """
+  @type libsrtp_error_t() ::
+          :fail
+          | :bad_param
+          | :alloc_fail
+          | :dealloc_fail
+          | :init_fail
+          | :terminus
+          | :auth_fail
+          | :cipher_fail
+          | :replay_fail
+          | :replay_old
+          | :algo_fail
+          | :no_such_op
+          | :no_ctx
+          | :cant_check
+          | :key_expired
+          | :socket_err
+          | :signal_err
+          | :nonce_bad
+          | :read_fail
+          | :write_fail
+          | :parse_err
+          | :encode_err
+          | :semaphore_err
+          | :pfkey_err
+          | :bad_mki
+          | :pkt_idx_old
+
   @opaque t :: {__MODULE__, native :: reference}
 
   @type ssrc_t :: 0..4_294_967_295
@@ -72,8 +108,18 @@ defmodule ExLibSRTP do
     )
   end
 
+  @doc """
+  Protect RTP packet.
+
+  Most common errors:
+  - `:replay_fail` - packet has either a duplicate sequence number or its sequence number has an old rollover counter (roc)
+  - `:replay_old` - packet has a sequence number with current roc, but it is older than the beginning of the encryption window.
+  - `:bad_mki` - provided MKI is not a known MKI id
+
+  Other errors indicate a failure in cryptographic mechanisms, please refer to [libsrtp documentation](https://github.com/cisco/libsrtp)
+  """
   @spec protect(t(), unprotected :: binary(), mki_index :: pos_integer() | nil) ::
-          {:ok, protected :: binary()}
+          {:ok, protected :: binary()} | {:error, libsrtp_error_t()}
   def protect(srtp, unprotected, mki_index \\ nil)
 
   def protect(ref(native), unprotected, nil) do
@@ -84,8 +130,13 @@ defmodule ExLibSRTP do
     Native.protect(native, :rtp, unprotected, true, mki_index)
   end
 
+  @doc """
+  Protect RTCP packet.
+
+  All errors indicate an error in the cryptographic mechanisms.
+  """
   @spec protect_rtcp(t(), unprotected :: binary(), mki_index :: pos_integer() | nil) ::
-          {:ok, protected :: binary()}
+          {:ok, protected :: binary()} | {:error, libsrtp_error_t()}
   def protect_rtcp(srtp, unprotected, mki_index \\ nil)
 
   def protect_rtcp(ref(native), unprotected, nil) do
@@ -96,14 +147,34 @@ defmodule ExLibSRTP do
     Native.protect(native, :rtcp, unprotected, true, mki_index)
   end
 
+  @doc """
+  Unprotect RTP packet.
+
+  Most common errors:
+  - `:replay_fail` - packet has either a duplicate sequence number or its sequence number has an old rollover counter (roc)
+  - `:replay_old` - packet has a sequence number with current roc, but it is older than the beginning of the decryption window.
+  - `:auth_fail` - packet has failed the message authentication check
+
+  Other errors indicate a failure in cryptographic mechanisms, please refer to [libsrtp documentation](https://github.com/cisco/libsrtp)
+  """
   @spec unprotect(t(), protected :: binary(), use_mki :: boolean()) ::
-          {:ok, unprotected :: binary()} | {:error, :auth_fail | :reply_fail | :bad_mki}
+          {:ok, unprotected :: binary()} | {:error, libsrtp_error_t()}
   def unprotect(ref(native) = _srtp, protected, use_mki \\ false) do
     Native.unprotect(native, :rtp, protected, use_mki)
   end
 
+  @doc """
+  Unprotect RTCP packet.
+
+  Expected errors:
+  - `:auth_fail` - SRTCP message has failed the message authentication check.
+  - `:replay_fail` - SRTCP message is a duplicate
+  - `:bad_mki` - provided MKI is not a known MKI id
+
+  Other errors indicate issues in the cryptographic mechanisms.
+  """
   @spec unprotect_rtcp(t(), protected :: binary(), use_mki :: boolean()) ::
-          {:ok, unprotected :: binary()} | {:error, :auth_fail | :reply_fail | :bad_mki}
+          {:ok, unprotected :: binary()} | {:error, libsrtp_error_t()}
   def unprotect_rtcp(ref(native) = _srtp, protected, use_mki \\ false) do
     Native.unprotect(native, :rtcp, protected, use_mki)
   end