Ignore:
Timestamp:
Jan 18, 2008 12:30:18 PM (16 years ago)
Author:
bennylp
Message:

Ticket #452: changed SRTP API with new specification from test doc

File:
1 edited

Legend:

Unmodified
Added
Removed

  • pjproject/branches/users/nanang/pjmedia/include/pjmedia/transport_srtp.h

    r1698 r1702  
    3030PJ_BEGIN_DECL 
    3131 
    32 /** 
    33  * Options that can be specified when creating SRTP transport. 
    34  */ 
    35 enum pjmedia_transport_srtp_options 
    36 { 
    37     /** 
    38      * This option will make the underlying transport to be closed whenever 
    39      * the SRTP transport is closed. 
    40      */ 
    41     PJMEDIA_SRTP_AUTO_CLOSE_UNDERLYING_TRANSPORT = 1 
    42 }; 
    43  
    44 /** 
    45  * SRTP session parameters. 
    46  */ 
    47 typedef struct pjmedia_srtp_stream_policy 
    48 { 
    49     pj_str_t key;            /**< Key string.               */ 
    50     pj_str_t crypto_suite;   /**< SRTP parameter for RTP.   */ 
    51 } pjmedia_srtp_stream_policy; 
     32 
     33/** 
     34 * Crypto option. 
     35 */ 
     36typedef enum pjmedia_srtp_crypto_option 
     37{ 
     38    /** When this flag is specified, encryption will be disabled. */ 
     39    PJMEDIA_SRTP_NO_ENCRYPTION  = 1, 
     40 
     41    /** When this flag is specified, authentication will be disabled. */ 
     42    PJMEDIA_SRTP_NO_AUTHENTICATION  = 2 
     43 
     44} pjmedia_srtp_crypto_option; 
     45 
     46 
     47/** 
     48 * This structure describes an individual crypto setting. 
     49 */ 
     50typedef struct pjmedia_srtp_crypto 
     51{ 
     52    /** Optional key. If empty, a random key will be autogenerated. */ 
     53    pj_str_t    key; 
     54 
     55    /** Crypto name.   */ 
     56    pj_str_t    crypto; 
     57 
     58    /* Flags, bitmask from #pjmedia_srtp_crypto_option */ 
     59    unsigned    flags; 
     60 
     61} pjmedia_srtp_crypto; 
     62 
     63 
     64/** 
     65 * This enumeration specifies the behavior of the SRTP transport regarding 
     66 * media security offer and answer. 
     67 */ 
     68typedef enum pjmedia_srtp_use 
     69{ 
     70    /** 
     71     * When this flag is specified, SRTP will be disabled, and the transport 
     72     * will reject RTP/SAVP offer. 
     73     */ 
     74    PJMEDIA_SRTP_DISABLED, 
     75 
     76    /** 
     77     * When this flag is specified, SRTP will be advertised as optional and 
     78     * incoming SRTP offer will be accepted. 
     79     */ 
     80    PJMEDIA_SRTP_OPTIONAL, 
     81 
     82    /** 
     83     * When this flag is specified, the transport will require that RTP/SAVP 
     84     * media shall be used. 
     85     */ 
     86    PJMEDIA_SRTP_MANDATORY 
     87 
     88} pjmedia_srtp_use; 
     89 
     90 
     91/** 
     92 * Settings to be given when creating SRTP transport. Application should call 
     93 * #pjmedia_srtp_setting_default() to initialize this structure with its  
     94 * default values. 
     95 */ 
     96typedef struct pjmedia_srtp_setting 
     97{ 
     98    /** 
     99     * Specify the usage policy. Default is PJMEDIA_SRTP_OPTIONAL. 
     100     */ 
     101    pjmedia_srtp_use use; 
     102 
     103    /** 
     104     * Specify whether the SRTP transport should close the member transport  
     105     * when it is destroyed. Default: PJ_TRUE. 
     106     */ 
     107    pj_bool_t                   close_member_tp; 
     108 
     109    /** 
     110     * Specify the number of crypto suite settings. 
     111     */ 
     112    unsigned                    crypto_count; 
     113 
     114    /** 
     115     * Specify individual crypto suite setting. 
     116     */ 
     117    pjmedia_srtp_crypto         crypto[8]; 
     118 
     119} pjmedia_srtp_setting; 
     120 
     121 
     122/** 
     123 * Initialize SRTP setting with its default values. 
     124 * 
     125 * @param opt   SRTP setting to be initialized. 
     126 */ 
     127PJ_DECL(void) pjmedia_srtp_setting_default(pjmedia_srtp_setting *opt); 
    52128 
    53129 
    … …  
    55131 * Create an SRTP media transport. 
    56132 * 
    57  * @param endpt             The media endpoint instance. 
    58  * @param tp                The actual media transport  
    59  *                          to send and receive RTP/RTCP packets. 
    60  * @param p_tp_srtp         Pointer to receive the transport SRTP instance. 
    61  * 
    62  * @return                  PJ_SUCCESS on success. 
    63  */ 
    64 PJ_DECL(pj_status_t) pjmedia_transport_srtp_create(pjmedia_endpt *endpt, 
    65                                          pjmedia_transport *tp, 
    66                                          unsigned options, 
    67                                          pjmedia_transport **p_tp_srtp); 
    68  
    69 /** 
    70  * Initialize and start SRTP session with the given parameters. 
    71  * Please note: 
    72  * 1. pjmedia_transport_srtp_init_session() and  
    73  *    pjmedia_transport_srtp_deinit_session() is automatic called by  
    74  *    SRTP pjmedia_transport_media_start() and pjmedia_transport_media_stop(), 
    75  *    application needs to call these functions directly only if the application 
    76  *    is not intended to call SRTP pjmedia_transport_media_start. 
    77  * 2. Even if an RTP stream is only one direction, you might need to provide  
    78  *    both policies, because it is needed by RTCP, which is usually two  
    79  *    directions. 
    80  * 3. Key for transmit and receive direction MUST be different, this is 
    81  *    specified by libsrtp. 
     133 * @param endpt     The media endpoint instance. 
     134 * @param tp        The actual media transport to send and receive  
     135 *                  RTP/RTCP packets. This media transport will be 
     136 *                  kept as member transport of this SRTP instance. 
     137 * @param opt       Optional settings. If NULL is given, default 
     138 *                  settings will be used. 
     139 * @param p_tp      Pointer to receive the transport SRTP instance. 
     140 * 
     141 * @return          PJ_SUCCESS on success. 
     142 */ 
     143PJ_DECL(pj_status_t) pjmedia_transport_srtp_create( 
     144                                       pjmedia_endpt *endpt, 
     145                                       pjmedia_transport *tp, 
     146                                       const pjmedia_srtp_setting *opt, 
     147                                       pjmedia_transport **p_tp); 
     148 
     149 
     150/** 
     151 * Manually start SRTP session with the given parameters. Application only 
     152 * needs to call this function when the SRTP transport is used without SDP 
     153 * offer/answer. When SDP offer/answer framework is used, the SRTP transport 
     154 * will be started/stopped by #pjmedia_transport_media_start() and  
     155 * #pjmedia_transport_media_stop() respectively. 
     156 * 
     157 * Please note that even if an RTP stream is only one direction, application 
     158 * will still need to provide both crypto suites, because it is needed by  
     159 * RTCP. 
     160 
     161 * If application specifies the crypto keys, the keys for transmit and receive 
     162 * direction MUST be different. 
    82163 * 
    83164 * @param srtp      The SRTP transport. 
    84  * @param prm       Session parameters. 
     165 * @param tx        Crypto suite setting for transmit direction. 
     166 * @param rx        Crypto suite setting for receive direction. 
    85167 * 
    86168 * @return          PJ_SUCCESS on success. 
    87169 */ 
    88 PJ_DECL(pj_status_t) pjmedia_transport_srtp_init_session( 
    89                        pjmedia_transport *srtp, 
    90                        const pjmedia_srtp_stream_policy *policy_tx, 
    91                        const pjmedia_srtp_stream_policy *policy_rx); 
    92  
    93 /** 
    94  * Stop SRTP seession. 
     170PJ_DECL(pj_status_t) pjmedia_transport_srtp_start( 
     171                                            pjmedia_transport *srtp, 
     172                                            const pjmedia_srtp_crypto *tx, 
     173                                            const pjmedia_srtp_crypto *rx); 
     174 
     175/** 
     176 * Stop SRTP session. 
    95177 * 
    96178 * @param srtp      The SRTP media transport. 
    … …  
    98180 * @return          PJ_SUCCESS on success. 
    99181 * 
    100  * @see pjmedia_transport_srtp_init_session()  
    101  */ 
    102 PJ_DECL(pj_status_t) pjmedia_transport_srtp_deinit_session( 
    103                        pjmedia_transport *srtp); 
    104  
    105  
    106 /** 
    107  * Query real transport of SRTP. 
     182 * @see #pjmedia_transport_srtp_start()  
     183 */ 
     184PJ_DECL(pj_status_t) pjmedia_transport_srtp_stop(pjmedia_transport *srtp); 
     185 
     186 
     187/** 
     188 * Query member transport of SRTP. 
    108189 * 
    109190 * @param srtp              The SRTP media transport. 
    110191 * 
    111  * @return                  real media transport. 
    112  */ 
    113 PJ_DECL(pjmedia_transport*) pjmedia_transport_srtp_get_real_transport( 
    114                                 pjmedia_transport *srtp); 
     192 * @return                  member media transport. 
     193 */ 
     194PJ_DECL(pjmedia_transport*) pjmedia_transport_srtp_get_member( 
     195                                                    pjmedia_transport *srtp); 
    115196 
    116197 
Note: See TracChangeset for help on using the changeset viewer.