Changeset 5755 for pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h

Timestamp:

Mar 15, 2018 3:00:59 AM (6 years ago)

Author:

nanang

Message:

Close #2100:

• Added new APIs:
  • PJMEDIA: pjmedia_srtp_enum_crypto(), pjmedia_srtp_enum_keying()
  • PJSUA: pjsua_config.srtp_opt, pjsua_acc_config.srtp_opt, pjsua_srtp_opt_default()
  • PJSUA2: AccountMediaConfig::srtpOpt, Endpoint::srtpCryptoEnum()
• Deprecated PJSUA callback on_create_media_transport_srtp() (not removed yet, just warnings).
• Slightly refactored SRTP code:
  • Fixed potential issue with on_create_media_transport_srtp(), some PJSUA internal values in pjmedia_srtp_setting may be overridden by app.
  • Fixed few issues in SRTP and keying mechanism, e.g: premature local SDP modification (it should be done after verification).
  • Potential minor backward compatibility issue: default value of pjmedia_srtp_setting.crypto_count is now zero, previously it was initialized with all crypto via pjmedia_srtp_setting_default(), actually zero and all cryptos in this setting semantically are the same.

File:

• pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h (modified) (6 diffs)

pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h

@@ -636 +636 @@
 
 } pjsua_create_media_transport_flag;
+
+
+/**
+ * Specify SRTP media transport settings.
+ */
+typedef struct pjsua_srtp_opt
+{
+    /**
+     * Specify the number of crypto suite settings. If set to zero, all
+     * available cryptos will be enabled. Note that available crypto names
+     * can be enumerated using pjmedia_srtp_enum_crypto().
+     *
+     * Default is zero.
+     */
+    unsigned                     crypto_count;
+
+    /**
+     * Specify individual crypto suite setting and its priority order.
+     *
+     * Notes for DTLS-SRTP keying:
+     *  - Currently only supports these cryptos: AES_CM_128_HMAC_SHA1_80,
+     *    AES_CM_128_HMAC_SHA1_32, AEAD_AES_256_GCM, and AEAD_AES_128_GCM.
+     *  - SRTP key is not configurable.
+     */
+    pjmedia_srtp_crypto          crypto[PJMEDIA_SRTP_MAX_CRYPTOS];
+
+    /**
+     * Specify the number of enabled keying methods. If set to zero, all
+     * keyings will be enabled. Maximum value is PJMEDIA_SRTP_MAX_KEYINGS.
+     * Note that available keying methods can be enumerated using
+     * pjmedia_srtp_enum_keying().
+     *
+     * Default is zero (all keyings are enabled with priority order:
+     * SDES, DTLS-SRTP).
+     */
+    unsigned                     keying_count;
+
+    /**
+     * Specify enabled keying methods and its priority order. Keying method
+     * with higher priority will be given earlier chance to process the SDP,
+     * for example as currently only one keying is supported in the SDP offer,
+     * keying with first priority will be likely used in the SDP offer.
+     */
+    pjmedia_srtp_keying_method   keying[PJMEDIA_SRTP_KEYINGS_COUNT];
+
+} pjsua_srtp_opt;
 
 
@@ -1520 +1566 @@
 
     /**
-     * This callback is called when SRTP media transport is created.
+     * Warning: deprecated and may be removed in future release. Application
+     * can set SRTP crypto settings (including keys) and keying methods
+     * via pjsua_srtp_opt in pjsua_config and pjsua_acc_config.
+     * See also ticket #2100.
+     *
+     * This callback is called before SRTP media transport is created.
      * Application can modify the SRTP setting \a srtp_opt to specify
-     * the cryptos and keys which are going to be used. Note that
-     * application should not modify the field
-     * \a pjmedia_srtp_setting.close_member_tp and can only modify
-     * the field \a pjmedia_srtp_setting.use for initial INVITE.
+     * the cryptos & keys and keying methods which are going to be used.
+     * Note that only some fields of pjmedia_srtp_setting can be overriden
+     * from this callback, i.e: "crypto_count", "crypto", "keying_count",
+     * "keying", and "use" (only for initial INVITE), any modification in
+     * other fields will be ignored.
      *
      * @param call_id       Call ID
@@ -1901 +1953 @@
      */
     pj_bool_t        srtp_optional_dup_offer;
+
+    /**
+     * Specify SRTP transport setting. Application can initialize it with
+     * default values using pjsua_srtp_opt_default().
+     */
+    pjsua_srtp_opt   srtp_opt;
 
     /**
@@ -3224 +3282 @@
 } pjsua_nat64_opt;
 
+
 /**
  * This structure describes account configuration to be specified when
@@ -3741 +3800 @@
      */
     pj_bool_t        srtp_optional_dup_offer;
+
+    /**
+     * Specify SRTP transport setting. Application can initialize it with
+     * default values using pjsua_srtp_opt_default().
+     */
+    pjsua_srtp_opt   srtp_opt;
 
     /**
@@ -3891 +3956 @@
                                     pjsua_turn_config *dst,
                                     const pjsua_turn_config *src);
+
+
+/**
+ * Call this function to initialize SRTP config with default values.
+ *
+ * @param cfg       The SRTP config to be initialized.
+ */
+PJ_DECL(void) pjsua_srtp_opt_default(pjsua_srtp_opt *cfg);
+
 
 /**