diff options
Diffstat (limited to 'pjsip/src/pjsip/sip_auth.h')
| -rw-r--r-- | pjsip/src/pjsip/sip_auth.h | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/pjsip/src/pjsip/sip_auth.h b/pjsip/src/pjsip/sip_auth.h new file mode 100644 index 00000000..1aad8cbb --- /dev/null +++ b/pjsip/src/pjsip/sip_auth.h @@ -0,0 +1,230 @@ +/* $Header: /pjproject/pjsip/src/pjsip/sip_auth.h 11 8/31/05 9:05p Bennylp $ */
+#ifndef __PJSIP_AUTH_SIP_AUTH_H__
+#define __PJSIP_AUTH_SIP_AUTH_H__
+
+/**
+ * @file pjsip_auth.h
+ * @brief SIP Authorization Module.
+ */
+
+#include <pjsip/sip_config.h>
+#include <pjsip/sip_auth_msg.h>
+
+PJ_BEGIN_DECL
+
+/**
+ * @defgroup PJSIP_AUTH_API Authorization API's
+ * @ingroup PJSIP_AUTH
+ * @{
+ */
+
+ /** Type of data in the credential information. */
+typedef enum pjsip_cred_data_type
+{
+ PJSIP_CRED_DATA_PLAIN_PASSWD, /**< Plain text password. */
+ PJSIP_CRED_DATA_DIGEST, /**< Hashed digest. */
+} pjsip_cred_data_type;
+
+/** Authentication's quality of protection (qop) type. */
+typedef enum pjsip_auth_qop_type
+{
+ PJSIP_AUTH_QOP_NONE, /**< No quality of protection. */
+ PJSIP_AUTH_QOP_AUTH, /**< Authentication. */
+ PJSIP_AUTH_QOP_AUTH_INT, /**< Authentication with integrity protection. */
+ PJSIP_AUTH_QOP_UNKNOWN, /**< Unknown protection. */
+} pjsip_auth_qop_type;
+
+
+/**
+ * This structure describes credential information.
+ * A credential information is a static, persistent information that identifies
+ * username and password required to authorize to a specific realm.
+ */
+struct pjsip_cred_info
+{
+ pj_str_t realm; /**< Realm. */
+ pj_str_t scheme; /**< Scheme. */
+ pj_str_t username; /**< User name. */
+ int data_type; /**< Type of data. */
+ pj_str_t data; /**< The data, which can be a plaintext
+ password or a hashed digest. */
+};
+
+/**
+ * This structure describes cached value of previously sent Authorization
+ * or Proxy-Authorization header. The authentication framework keeps a list
+ * of this structure and will resend the same header to the same server
+ * as long as the method, uri, and nonce stays the same.
+ */
+typedef struct pjsip_cached_auth_hdr
+{
+ PJ_DECL_LIST_MEMBER(struct pjsip_cached_auth_hdr)
+
+ pjsip_method method;
+ pjsip_authorization_hdr *hdr;
+
+} pjsip_cached_auth_hdr;
+
+
+/**
+ * This structure describes authentication information for the specified
+ * realm. Each instance of this structure describes authentication "session"
+ * between this endpoint and remote server. This "session" information is
+ * usefull to keep information that persists for more than one challenge,
+ * such as nonce-count and cnonce value.
+ *
+ * Other than that, this structure also keeps the last authorization headers
+ * that have been sent in the cache list.
+ */
+typedef struct pjsip_auth_session
+{
+ PJ_DECL_LIST_MEMBER(struct pjsip_auth_session)
+
+ pj_str_t realm;
+ pj_bool_t is_proxy;
+ pjsip_auth_qop_type qop_value;
+#if PJSIP_AUTH_QOP_SUPPORT
+ pj_uint32_t nc;
+ pj_str_t cnonce;
+#endif
+#if PJSIP_AUTH_AUTO_SEND_NEXT
+ pjsip_www_authenticate_hdr *last_chal;
+#endif
+#if PJSIP_AUTH_HEADER_CACHING
+ pjsip_cached_auth_hdr cached_hdr;
+#endif
+
+} pjsip_auth_session;
+
+
+/**
+ * Create authorization header for the specified credential.
+ * Application calls this function to create Authorization or Proxy-Authorization
+ * header after receiving WWW-Authenticate or Proxy-Authenticate challenge
+ * (normally in 401/407 response).
+ * If authorization session argument is specified, this function will update
+ * the session with the updated information if required (e.g. to update
+ * nonce-count when qop is "auth" or "auth-int"). This function will also
+ * save the authorization header in the session's cached header list.
+ *
+ * @param req_pool Pool to allocate new header for the request.
+ * @param hdr The WWW-Authenticate or Proxy-Authenticate found in
+ * the response.
+ * @param uri The URI for which authorization is targeted to.
+ * @param cred_info The credential to be used for authentication.
+ * @param method The method.
+ * @param sess_pool Session pool to update session or to allocate message
+ * in the cache. May be NULL if auth_sess is NULL.
+ * @param auth_sess If not NULL, this specifies the specific authentication
+ * session to be used or updated.
+ *
+ * @return The Authorization header, which can be typecasted to
+ * Proxy-Authorization.
+ */
+PJ_DECL(pjsip_authorization_hdr*) pjsip_auth_respond(
+ pj_pool_t *req_pool,
+ const pjsip_www_authenticate_hdr *hdr,
+ const pjsip_uri *uri,
+ const pjsip_cred_info *cred_info,
+ const pjsip_method *method,
+ pj_pool_t *sess_pool,
+ pjsip_auth_session *auth_sess);
+
+/**
+ * Verify digest in the authorization request.
+ *
+ * @param hdr The incoming Authorization/Proxy-Authorization header.
+ * @param method The method.
+ * @param password The plaintext password to verify.
+ *
+ * @return Non-zero if authorization succeed.
+ */
+PJ_DECL(pj_bool_t) pjsip_auth_verify( const pjsip_authorization_hdr *hdr,
+ const pj_str_t *method,
+ const pjsip_cred_info *cred_info );
+
+
+/**
+ * This function can be used to find credential information which matches
+ * the specified realm.
+ *
+ * @param count Number of credentials in the parameter.
+ * @param cred The array of credentials.
+ * @param realm Realm to search.
+ * @param scheme Authentication scheme.
+ *
+ * @return The credential which matches the specified realm.
+ */
+PJ_DECL(const pjsip_cred_info*) pjsip_auth_find_cred( unsigned count,
+ const pjsip_cred_info cred[],
+ const pj_str_t *realm,
+ const pj_str_t *scheme );
+
+
+/**
+ * Initialize new request message with authorization headers.
+ * This function will put Authorization/Proxy-Authorization headers to the
+ * outgoing request message. If caching is enabled (PJSIP_AUTH_HEADER_CACHING)
+ * and the session has previously sent Authorization/Proxy-Authorization header
+ * with the same method, then the same Authorization/Proxy-Authorization header
+ * will be resent from the cache only if qop is not present. If the stack is
+ * configured to automatically generate next Authorization/Proxy-Authorization
+ * headers (PJSIP_AUTH_AUTO_SEND_NEXT flag), then new Authorization/Proxy-
+ * Authorization headers are calculated and generated when they are not present
+ * in the case or if authorization session has qop.
+ *
+ * If both PJSIP_AUTH_HEADER_CACHING flag and PJSIP_AUTH_AUTO_SEND_NEXT flag
+ * are not set, this function will do nothing. The stack then will only send
+ * Authorization/Proxy-Authorization to respond 401/407 response.
+ *
+ * @param sess_pool Session level pool, where memory will be allocated from
+ * for data that persists across requests (e.g. caching).
+ * @param tdata The request message to be initialized.
+ * @param sess_list List of authorization sessions that have been recorded.
+ * @param cred_count Number of credentials.
+ * @param cred_info Array of credentials.
+ *
+ * @return Zero if successfull.
+ */
+PJ_DECL(pj_status_t) pjsip_auth_init_req( pj_pool_t *sess_pool,
+ pjsip_tx_data *tdata,
+ pjsip_auth_session *sess_list,
+ int cred_count,
+ const pjsip_cred_info cred_info[]);
+
+/**
+ * Call this function when a transaction failed with 401 or 407 response.
+ * This function will reinitialize the original request message with the
+ * authentication challenge found in the response message, and add the
+ * new authorization header in the authorization cache.
+ *
+ * Note that upon return the reference counter of the transmit data
+ * will be incremented.
+ *
+ * @param endpt Endpoint.
+ * @param pool The pool to allocate memory for new cred_info.
+ * @param cached_list Cached authorization headers.
+ * @param cred_count Number of credentials.
+ * @param cred_info Array of credentials to use.
+ * @param tdata The original request message, which normally can be
+ * retrieved from tsx->last_tx.
+ * @param rdata The response message containing 401/407 status.
+ *
+ * @return New transmit data buffer, or NULL if the dialog
+ * can not respond to the authorization challenge.
+ */
+PJ_DECL(pjsip_tx_data*)
+pjsip_auth_reinit_req( pjsip_endpoint *endpt,
+ pj_pool_t *ses_pool,
+ pjsip_auth_session *sess_list,
+ int cred_count, const pjsip_cred_info cred_info[],
+ pjsip_tx_data *tdata, const pjsip_rx_data *rdata);
+
+/**
+ * @}
+ */
+
+PJ_END_DECL
+
+#endif /* __PJSIP_AUTH_SIP_AUTH_H__ */
+
|