Ignore:
Timestamp:
Jan 18, 2006 11:34:15 PM (18 years ago)
Author:
bennylp
Message:

Complete tsx layer selftest, implemented authentication framework

File:
1 edited

Legend:

Unmodified
Added
Removed

  • pjproject/trunk/pjsip/include/pjsip/sip_auth.h

    r65 r123  
    3030PJ_BEGIN_DECL 
    3131 
     32 
    3233/** 
    3334 * @defgroup PJSIP_AUTH_API Authorization API's 
    … …  
    3637 */ 
    3738 
    38  /** Type of data in the credential information. */ 
     39/* Length of digest string. */ 
     40#define PJSIP_MD5STRLEN 32 
     41 
     42 
     43/** Type of data in the credential information. */ 
    3944typedef enum pjsip_cred_data_type 
    4045{ 
    … …  
    7883    PJ_DECL_LIST_MEMBER(struct pjsip_cached_auth_hdr); 
    7984 
    80     pjsip_method             method; 
    81     pjsip_authorization_hdr *hdr; 
     85    pjsip_method             method;    /**< To quickly see the method. */ 
     86    pjsip_authorization_hdr *hdr;       /**< The cached header.         */ 
    8287 
    8388} pjsip_cached_auth_hdr; 
    … …  
    9499 * that have been sent in the cache list. 
    95100 */ 
    96 typedef struct pjsip_auth_session 
    97 { 
    98     PJ_DECL_LIST_MEMBER(struct pjsip_auth_session); 
    99  
    100     pj_str_t                     realm; 
    101     pj_bool_t                    is_proxy; 
    102     pjsip_auth_qop_type          qop_value; 
     101typedef struct pjsip_cached_auth 
     102{ 
     103    PJ_DECL_LIST_MEMBER(struct pjsip_cached_auth); 
     104 
     105    pj_str_t                     realm;     /**< Realm.                     */ 
     106    pj_bool_t                    is_proxy;  /**< Server type (401/407)      */ 
     107    pjsip_auth_qop_type          qop_value; /**< qop required by server.    */ 
    103108#if PJSIP_AUTH_QOP_SUPPORT 
    104     pj_uint32_t                  nc; 
    105     pj_str_t                     cnonce; 
     109    pj_uint32_t                  nc;        /**< Nonce count.               */ 
     110    pj_str_t                     cnonce;    /**< Cnonce value.              */ 
    106111#endif 
    107112#if PJSIP_AUTH_AUTO_SEND_NEXT 
    108     pjsip_www_authenticate_hdr  *last_chal; 
     113    pjsip_www_authenticate_hdr  *last_chal; /**< Last challenge seen.       */ 
    109114#endif 
    110115#if PJSIP_AUTH_HEADER_CACHING 
    111     pjsip_cached_auth_hdr        cached_hdr; 
     116    pjsip_cached_auth_hdr        cached_hdr;/**< List of cached header for 
     117                                                 each method.               */ 
    112118#endif 
    113119 
    114 } pjsip_auth_session; 
    115  
    116  
    117 /** 
    118  * Create authorization header for the specified credential. 
    119  * Application calls this function to create Authorization or Proxy-Authorization 
    120  * header after receiving WWW-Authenticate or Proxy-Authenticate challenge 
    121  * (normally in 401/407 response). 
    122  * If authorization session argument is specified, this function will update 
    123  * the session with the updated information if required (e.g. to update 
    124  * nonce-count when qop is "auth" or "auth-int"). This function will also 
    125  * save the authorization header in the session's cached header list. 
    126  * 
    127  * @param req_pool      Pool to allocate new header for the request. 
    128  * @param hdr           The WWW-Authenticate or Proxy-Authenticate found in  
    129  *                      the response. 
    130  * @param uri           The URI for which authorization is targeted to. 
    131  * @param cred_info     The credential to be used for authentication. 
    132  * @param method        The method. 
    133  * @param sess_pool     Session pool to update session or to allocate message 
    134  *                      in the cache. May be NULL if auth_sess is NULL. 
    135  * @param auth_sess     If not NULL, this specifies the specific authentication 
    136  *                      session to be used or updated. 
    137  * 
    138  * @return              The Authorization header, which can be typecasted to  
    139  *                      Proxy-Authorization. 
    140  */ 
    141 PJ_DECL(pjsip_authorization_hdr*) pjsip_auth_respond(  
    142                                          pj_pool_t *req_pool, 
    143                                          const pjsip_www_authenticate_hdr *hdr, 
    144                                          const pjsip_uri *uri, 
    145                                          const pjsip_cred_info *cred_info, 
    146                                          const pjsip_method *method, 
    147                                          pj_pool_t *sess_pool, 
    148                                          pjsip_auth_session *auth_sess); 
    149  
    150 /** 
    151  * Verify digest in the authorization request. 
    152  * 
    153  * @param hdr           The incoming Authorization/Proxy-Authorization header. 
    154  * @param method        The method. 
    155  * @param password      The plaintext password to verify. 
    156  * 
    157  * @return              Non-zero if authorization succeed. 
    158  */ 
    159 PJ_DECL(pj_bool_t) pjsip_auth_verify(   const pjsip_authorization_hdr *hdr, 
    160                                         const pj_str_t *method, 
    161                                         const pjsip_cred_info *cred_info ); 
    162  
    163  
    164 /** 
    165  * This function can be used to find credential information which matches 
    166  * the specified realm. 
    167  * 
    168  * @param count         Number of credentials in the parameter. 
    169  * @param cred          The array of credentials. 
    170  * @param realm         Realm to search. 
    171  * @param scheme        Authentication scheme. 
    172  * 
    173  * @return              The credential which matches the specified realm. 
    174  */ 
    175 PJ_DECL(const pjsip_cred_info*) pjsip_auth_find_cred( unsigned count, 
    176                                                       const pjsip_cred_info cred[], 
    177                                                       const pj_str_t *realm, 
    178                                                       const pj_str_t *scheme ); 
     120} pjsip_cached_auth; 
     121 
     122 
     123/** 
     124 * This structure describes client authentication sessions. It keeps 
     125 * all the information needed to authorize the client against all downstream  
     126 * servers. 
     127 */ 
     128typedef struct pjsip_auth_clt_sess 
     129{ 
     130    pj_pool_t           *pool;          /**< Pool to use.                   */ 
     131    pjsip_endpoint      *endpt;         /**< Endpoint where this belongs.   */ 
     132    unsigned             cred_cnt;      /**< Number of credentials.         */ 
     133    pjsip_cred_info     *cred_info;     /**< Array of credential information*/ 
     134    pjsip_cached_auth    cached_auth;   /**< Cached authorization info.     */ 
     135 
     136} pjsip_auth_clt_sess; 
     137 
     138 
     139/** 
     140 * Type of function to lookup credential for the specified name. 
     141 * 
     142 * @param pool          Pool to initialize the credential info. 
     143 * @param realm         Realm to find the account. 
     144 * @param acc_name      Account name to look for. 
     145 * @param cred_info     The structure to put the credential when it's found. 
     146 * 
     147 * @return              The function MUST return PJ_SUCCESS when it found 
     148 *                      a correct credential for the specified account and 
     149 *                      realm. Otherwise it may return PJSIP_EAUTHACCNOTFOUND 
     150 *                      or PJSIP_EAUTHACCDISABLED. 
     151 */ 
     152typedef pj_status_t pjsip_auth_lookup_cred( pj_pool_t *pool, 
     153                                            const pj_str_t *realm, 
     154                                            const pj_str_t *acc_name, 
     155                                            pjsip_cred_info *cred_info ); 
     156 
     157/** Flag to specify that server is a proxy. */ 
     158#define PJSIP_AUTH_SRV_IS_PROXY     1 
     159 
     160/** 
     161 * This structure describes server authentication information. 
     162 */ 
     163typedef struct pjsip_auth_srv 
     164{ 
     165    pj_str_t                 realm;     /**< Realm to serve.                */ 
     166    pj_bool_t                is_proxy;  /**< Will issue 407 instead of 401  */ 
     167    pjsip_auth_lookup_cred  *lookup;    /**< Lookup function.               */ 
     168 
     169} pjsip_auth_srv; 
     170 
     171 
     172/** 
     173 * Initialize client authentication session data structure, and set the  
     174 * session to use pool for its subsequent memory allocation. The argument  
     175 * options should be set to zero for this PJSIP version. 
     176 * 
     177 * @param sess          The client authentication session. 
     178 * @param endpt         Endpoint where this session belongs. 
     179 * @param pool          Pool to use. 
     180 * @param options       Must be zero. 
     181 * 
     182 * @return              PJ_SUCCESS on success. 
     183 */ 
     184PJ_DECL(pj_status_t) pjsip_auth_clt_init( pjsip_auth_clt_sess *sess, 
     185                                          pjsip_endpoint *endpt, 
     186                                          pj_pool_t *pool,  
     187                                          unsigned options); 
     188 
     189 
     190 
     191/** 
     192 * Set the credentials to be used during the session. This will duplicate  
     193 * the specified credentials using client authentication's pool. 
     194 * 
     195 * @param sess          The client authentication session. 
     196 * @param cred_cnt      Number of credentials. 
     197 * @param c             Array of credentials. 
     198 * 
     199 * @return              PJ_SUCCESS on success. 
     200 */ 
     201PJ_DECL(pj_status_t) pjsip_auth_clt_set_credentials( pjsip_auth_clt_sess *sess, 
     202                                                     int cred_cnt, 
     203                                                     const pjsip_cred_info *c); 
    179204 
    180205 
    … …  
    195220 * Authorization/Proxy-Authorization to respond 401/407 response. 
    196221 * 
    197  * @param sess_pool     Session level pool, where memory will be allocated from 
    198  *                      for data that persists across requests (e.g. caching). 
     222 * @param sess          The client authentication session. 
    199223 * @param tdata         The request message to be initialized. 
    200  * @param sess_list     List of authorization sessions that have been recorded. 
    201  * @param cred_count    Number of credentials. 
    202  * @param cred_info     Array of credentials. 
    203  * 
    204  * @return              Zero if successfull. 
    205  */ 
    206 PJ_DECL(pj_status_t) pjsip_auth_init_req( pj_pool_t *sess_pool, 
    207                                           pjsip_tx_data *tdata, 
    208                                           pjsip_auth_session *sess_list, 
    209                                           int cred_count,  
    210                                           const pjsip_cred_info cred_info[]); 
     224 * 
     225 * @return              PJ_SUCCESS if successfull. 
     226 */ 
     227PJ_DECL(pj_status_t) pjsip_auth_clt_init_req( pjsip_auth_clt_sess *sess, 
     228                                              pjsip_tx_data *tdata ); 
     229 
    211230 
    212231/** 
    … …  
    216235 * new authorization header in the authorization cache. 
    217236 * 
    218  * Note that upon return the reference counter of the transmit data 
    219  * will be incremented. 
    220  * 
    221  * @param endpt         Endpoint. 
    222  * @param pool          The pool to allocate memory for new cred_info. 
    223  * @param cached_list   Cached authorization headers. 
    224  * @param cred_count    Number of credentials. 
    225  * @param cred_info     Array of credentials to use. 
    226  * @param tdata         The original request message, which normally can be 
    227  *                      retrieved from tsx->last_tx. 
     237 * Note that upon return the reference counter of the new transmit data 
     238 * will be set to 1. 
     239 * 
     240 * @param sess          The client authentication session. 
    228241 * @param rdata         The response message containing 401/407 status. 
    229  * 
    230  * @return              New transmit data buffer, or NULL if the dialog 
    231  *                      can not respond to the authorization challenge. 
    232  */ 
    233 PJ_DECL(pjsip_tx_data*)  
    234 pjsip_auth_reinit_req( pjsip_endpoint *endpt, 
    235                        pj_pool_t *ses_pool, 
    236                        pjsip_auth_session *sess_list, 
    237                        int cred_count, const pjsip_cred_info cred_info[], 
    238                        pjsip_tx_data *tdata, const pjsip_rx_data *rdata); 
     242 * @param old_request   The original request message, which will be re- 
     243 *                      created with authorization info. 
     244 * @param new_request   Pointer to receive new request message which 
     245 *                      will contain all required authorization headers. 
     246 * 
     247 * @return              PJ_SUCCESS if new request can be successfully 
     248 *                      created to respond all the authentication 
     249 *                      challenges. 
     250 */ 
     251PJ_DECL(pj_status_t) pjsip_auth_clt_reinit_req( pjsip_auth_clt_sess *sess, 
     252                                                const pjsip_rx_data *rdata, 
     253                                                pjsip_tx_data *old_request, 
     254                                                pjsip_tx_data **new_request ); 
     255 
     256/** 
     257 * Initialize server authorization session data structure to serve the  
     258 * specified realm and to use lookup_func function to look for the credential  
     259 * info.  
     260 * 
     261 * @param pool          Pool used to initialize the authentication server. 
     262 * @param auth_srv      The authentication server structure. 
     263 * @param realm         Realm to be served by the server. 
     264 * @param lookup        Account lookup function. 
     265 * @param options       Options, bitmask of: 
     266 *                      - PJSIP_AUTH_SRV_IS_PROXY: to specify that the server 
     267 *                        will authorize clients as a proxy server (instead of 
     268 *                        as UAS), which means that Proxy-Authenticate will  
     269 *                        be used instead of WWW-Authenticate. 
     270 * 
     271 * @return              PJ_SUCCESS on success. 
     272 */ 
     273PJ_DECL(pj_status_t) pjsip_auth_srv_init( pj_pool_t *pool, 
     274                                          pjsip_auth_srv *auth_srv, 
     275                                          const pj_str_t *realm, 
     276                                          pjsip_auth_lookup_cred *lookup, 
     277                                          unsigned options ); 
     278 
     279 
     280/** 
     281 * Request the authorization server framework to verify the authorization  
     282 * information in the specified request in rdata. 
     283 * 
     284 * @param auth_srv      The server authentication structure. 
     285 * @param rdata         Incoming request to be authenticated. 
     286 * @param status_code   When not null, it will be filled with suitable  
     287 *                      status code to be sent to the client. 
     288 * 
     289 * @return              PJ_SUCCESS if request is successfully authenticated. 
     290 *                      Otherwise the function may return one of the 
     291 *                      following error codes: 
     292 *                      - PJSIP_EAUTHNOAUTH 
     293 *                      - PJSIP_EINVALIDAUTHSCHEME 
     294 *                      - PJSIP_EAUTHACCNOTFOUND 
     295 *                      - PJSIP_EAUTHACCDISABLED 
     296 *                      - PJSIP_EAUTHINVALIDREALM 
     297 *                      - PJSIP_EAUTHINVALIDDIGEST 
     298 */ 
     299PJ_DECL(pj_status_t) pjsip_auth_srv_verify( pjsip_auth_srv *auth_srv, 
     300                                            pjsip_rx_data *rdata, 
     301                                            int *status_code ); 
     302 
     303 
     304/** 
     305 * Add authentication challenge headers to the outgoing response in tdata.  
     306 * Application may specify its customized nonce and opaque for the challenge,  
     307 * or can leave the value to NULL to make the function fills them in with  
     308 * random characters. 
     309 * 
     310 * @param auth_srv      The server authentication structure. 
     311 * @param qop           Optional qop value. 
     312 * @param nonce         Optional nonce value. 
     313 * @param opaque        Optional opaque value. 
     314 * @param stale         Stale indication. 
     315 * @param tdata         The outgoing response message. The response must have 
     316 *                      401 or 407 response code. 
     317 * 
     318 * @return              PJ_SUCCESS on success. 
     319 */ 
     320PJ_DECL(pj_status_t) pjsip_auth_srv_challenge( pjsip_auth_srv *auth_srv, 
     321                                               const pj_str_t *qop, 
     322                                               const pj_str_t *nonce, 
     323                                               const pj_str_t *opaque, 
     324                                               pj_bool_t stale, 
     325                                               pjsip_tx_data *tdata); 
     326 
    239327 
    240328/** 
    … …  
    242330 */ 
    243331 
     332 
    244333PJ_END_DECL 
    245334 
     335 
    246336#endif  /* __PJSIP_AUTH_SIP_AUTH_H__ */ 
    247337 
Note: See TracChangeset for help on using the changeset viewer.