[asterisk-commits] mmichelson: branch mmichelson/res_sip r378682 - /team/mmichelson/res_sip/incl...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Tue Jan 8 16:20:18 CST 2013
Author: mmichelson
Date: Tue Jan 8 16:20:14 2013
New Revision: 378682
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=378682
Log:
Add res_sip.h as it has been defined on the wiki.
Obviously, no compilation checking has been done yet.
Added:
team/mmichelson/res_sip/include/asterisk/res_sip.h (with props)
Added: team/mmichelson/res_sip/include/asterisk/res_sip.h
URL: http://svnview.digium.com/svn/asterisk/team/mmichelson/res_sip/include/asterisk/res_sip.h?view=auto&rev=378682
==============================================================================
--- team/mmichelson/res_sip/include/asterisk/res_sip.h (added)
+++ team/mmichelson/res_sip/include/asterisk/res_sip.h Tue Jan 8 16:20:14 2013
@@ -1,0 +1,404 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2013, Digium, Inc.
+ *
+ * Mark Michelson <mmichelson at digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+#ifndef _RES_SIP_H
+#define _RES_SIP_H
+
+/*!
+ * \brief Opaque structure representing related SIP tasks
+ */
+struct ast_sip_work;
+
+/*!
+ * \brief Data used for creating authentication challenges.
+ *
+ * This data gets populated by an authenticator's get_authentication_credentials() callback.
+ */
+struct ast_sip_digest_challenge_data {
+ /*!
+ * The realm to which the user is authenticating. An authenticator MUST fill this in.
+ */
+ const char *realm;
+ /*!
+ * Indicates whether the username and password are in plaintext or encoded as MD5.
+ * If this is non-zero, then the data is an MD5 sum. Otherwise, the username and password are plaintext.
+ * Authenticators MUST set this.
+ */
+ int is_md5;
+ /*!
+ * This is the actual username and secret. The is_md5 field is used to determine which member
+ * of the union is to be used when creating the authentication challenge. In other words, if
+ * is_md5 is non-zero, then we will use the md5 field of the auth union. Otherwise, we will
+ * use the plain struct in the auth union.
+ * Authenticators MUST fill in the appropriate field of the union.
+ */
+ union {
+ /*!
+ * Structure containing the username and password to encode in a digest authentication challenge.
+ */
+ struct {
+ const char *username;
+ const char *password;
+ } plain;
+ /*!
+ * An MD5-encoded string that incorporates the username and password.
+ */
+ const char *md5;
+ } auth;
+ /*!
+ * Domain for which the authentication challenge is being sent. This corresponds to the "domain=" portion of
+ * a digest authentication.
+ *
+ * Authenticators do not have to fill in this field since it is an optional part of a digest.
+ */
+ const char *domain;
+ /*!
+ * Opaque string for digest challenge. This corresponds to the "opaque=" portion of a digest authentication.
+ * Authenticators do not have to fill in this field. If an authenticator does not fill it in, Asterisk will provide one.
+ */
+ const char *opaque;
+ /*!
+ * Nonce string for digest challenge. This corresponds to the "nonce=" portion of a digest authentication.
+ * Authenticators do not have to fill in this field. If an authenticator does not fill it in, Asterisk will provide one.
+ */
+ const char *nonce;
+};
+
+/*!
+ * \brief An interchangeable way of handling digest authentication for SIP.
+ *
+ * An authenticator is responsible for filling in the callbacks provided below. Each is called from a publicly available
+ * function in res_sip. The authenticator can use configuration or other local policy to determine whether authentication
+ * should take place and what credentials should be used when challenging and authenticating a request.
+ */
+struct ast_sip_authenticator {
+ /*!
+ * \brief Check if a request requires authentication
+ * See ast_sip_requires_authentication for more details
+ */
+ int (*requires_authentication)(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
+ /*!
+ * \brief Attempt to authenticate the incoming request
+ * See ast_sip_authenticate_request for more details
+ */
+ int (*authenticate_request)(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
+ /*!
+ * \brief Get digest authentication details
+ * See ast_sip_get_authentication_credentials for more details
+ */
+ int (*get_authentication_credentials)(struct ast_sip_endpoint *endpoint, struct sip_digest_challenge_data *challenge);
+};
+
+/*!
+ * \brief An entity responsible for identifying the source of a SIP message
+ */
+struct ast_sip_endpoint_identifier {
+ /*!
+ * \brief Callback used to identify the source of a message.
+ * See ast_sip_identify_endpoint for more details
+ */
+ struct ast_sip_endpoint *(*identify_endpoint)(struct pjsip_rx_data *data);
+};
+
+/*!
+ * \brief Register a SIP service in Asterisk.
+ *
+ * This is more-or-less a wrapper around pjsip_endpt_register_module().
+ * Registering a service makes it so that PJSIP will call into the
+ * service at appropriate times. For more information about PJSIP module
+ * callbacks, see the PJSIP documentation. Asterisk modules that call
+ * this function will likely do so at module load time.
+ *
+ * \param module The module that is to be registered with PJSIP
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_register_service(pjsip_module *module);
+
+/*!
+ * This is the opposite of ast_sip_register_service(). Unregistering a
+ * service means that PJSIP will no longer call into the module any more.
+ * This will likely occur when an Asterisk module is unloaded.
+ *
+ * \param module The PJSIP module to unregister
+ */
+void ast_sip_unregister_service(pjsip_module *module);
+
+/*!
+ * \brief Register a SIP authenticator
+ *
+ * An authenticator has three main purposes:
+ * 1) Determining if authentication should be performed on an incoming request
+ * 2) Gathering credentials necessary for issuing an authentication challenge
+ * 3) Authenticating a request that has credentials
+ *
+ * Asterisk provides a default authenticator, but it may be replaced by a
+ * custom one if desired.
+ *
+ * \param auth The authenticator to register
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_register_authenticator(struct ast_sip_authenticator *auth);
+
+/*!
+ * \brief Unregister a SIP authenticator
+ *
+ * When there is no authenticator registered, requests cannot be challenged
+ * or authenticated.
+ *
+ * \param auth The authenticator to unregister
+ */
+void ast_sip_unregister_authenticator(struct ast_sip_authenticator *auth);
+
+/*!
+ * \brief Register a SIP endpoint identifier
+ *
+ * An endpoint identifier's purpose is to determine which endpoint a given SIP
+ * message has come from.
+ *
+ * Multiple endpoint identifiers may be registered so that if an endpoint
+ * cannot be identified by one identifier, it may be identified by another.
+ *
+ * Asterisk provides two endpoint identifiers. One identifies endpoints based
+ * on the user part of the From header URI. The other identifies endpoints based
+ * on the source IP address.
+ *
+ * If the order in which endpoint identifiers is run is important to you, then
+ * be sure to load individual endpoint identifier modules in the order you wish
+ * for them to be run in modules.conf
+ *
+ * \param identifier The SIP endpoint identifier to register
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_register_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier);
+
+/*!
+ * \brief Unregister a SIP endpoint identifier
+ *
+ * This stops an endpoint identifier from being used.
+ *
+ * \param identifier The SIP endoint identifier to unregister
+ */
+void ast_sip_unregister_endpoint_identifier(struct ast_sip_endpoint_identifier *identifier);
+
+/*!
+ * \brief Create a new SIP work structure
+ *
+ * A SIP work is a means of grouping together SIP tasks. For instance, one
+ * might create a SIP work so that all tasks for a given SIP dialog will
+ * be grouped together. Grouping the work together ensures that the
+ * threadpool will distribute the tasks in such a way so that grouped work
+ * will execute sequentially. Executing grouped tasks sequentially means
+ * less contention for shared resources.
+ *
+ * \retval NULL Failure
+ * \retval non-NULL Newly-created SIP work
+ */
+struct ast_sip_work *ast_sip_create_work(void);
+
+/*!
+ * \brief Destroy a SIP work structure
+ *
+ * \param work The SIP work to destroy
+ */
+void ast_sip_destroy_work(struct ast_sip_work *work);
+
+/*!
+ * \brief Pushes a task into the SIP threadpool
+ *
+ * This uses the SIP work provided to determine how to push the task.
+ *
+ * \param work The SIP work to which the task belongs
+ * \param sip_task The task to execute
+ * \param task_data The parameter to pass to the task when it executes
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_push_task(struct ast_sip_work *work, int (*sip_task)(void *), void *task_data);
+
+
+/*!
+ * \brief General purpose method for sending a SIP request
+ *
+ * Its typical use would be to send one-off messages such as an out of dialog
+ * SIP MESSAGE.
+ *
+ * \param method The method of the SIP request to send
+ * \param body The message body for the SIP request
+ * \dlg Optional. If specified, the dialog on which to send the message. Otherwise, the message
+ * will be sent out of dialog.
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_send_request(const char *method, const char *body, struct pjsip_dialog *dlg);
+
+/*!
+ * \brief Determine if an incoming request requires authentication
+ *
+ * This calls into the registered authenticator's requires_authentication callback
+ * in order to determine if the request requires authentication.
+ *
+ * If there is no registered authenticator, then authentication will be assumed
+ * not to be required.
+ *
+ * \param endpoint The endpoint from which the request originates
+ * \param rdata The incoming SIP request
+ * \retval non-zero The request requires authentication
+ * \retval 0 The request does not require authentication
+ */
+int ast_sip_requires_authentication(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
+
+/*!
+ * \brief Authenticate an inbound SIP request
+ *
+ * This calls into the registered authenticator's authenticate_request callback
+ * in order to determine if the request contains proper credentials as to be
+ * authenticated.
+ *
+ * If there is no registered authenticator, then the request will assumed to be
+ * authenticated properly.
+ *
+ * \param endpoint The endpoint from which the request originates
+ * \param rdata The incoming SIP request
+ * \retval 0 Successfully authenticated
+ * \retval nonzero Failure to authenticate
+ */
+int ast_sip_authenticate_request(struct ast_sip_endpoint *endpoint, struct pjsip_rx_data *rdata);
+
+/*!
+ * \brief Get authentication credentials in order to challenge a request
+ *
+ * This calls into the registered authenticator's get_authentication_credentials
+ * callback in order to get credentials required for challenging a request.
+ *
+ * \param endpoint The endpoint whose credentials are being gathered
+ * \param[out] challenge The necessary data in order to be able to challenge a request
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_get_authentication_credentials(struct ast_sip_endpoint *endpoint, struct ast_sip_digest_challenge_data *challenge);
+
+/*!
+ * \brief Possible returns from ast_sip_check_authentication
+ */
+enum ast_sip_check_auth_result {
+ /*! Authentication challenge sent */
+ AST_SIP_AUTHENTICATION_CHALLENGE_SENT,
+ /*! Authentication succeeded */
+ AST_SIP_AUTHENTICATION_SUCCESS,
+ /*! Authentication failed */
+ AST_SIP_AUTHENTICATION_FAILED,
+ /*! Authentication not required */
+ AST_SIP_AUTHENTICATION_NOT_REQUIRED,
+};
+
+/*!
+ * \brief Shortcut routine to check for authentication of an incoming request
+ *
+ * This is a wrapper that will call into a registered authenticator to see if a request
+ * should be authenticated. Then if it should be, will attempt to authenticate. If the
+ * request cannot be authenticated, then a challenge will be sent. Calling this can be
+ * a suitable substitute for calling ast_sip_requires_authentication(),
+ * ast_sip_authenticate_request(), and ast_sip_get_authentication_credentials()
+ *
+ * \param endpoint The endpoint from the request was sent
+ * \param rdata The request to potentially authenticate
+ * \return The result of checking authentication.
+ */
+ast_sip_check_authentication(struct ast_sip_endpoint *endpoint, struct pjsip_rxdata *rdata);
+
+/*!
+ * \brief Challenge an inbound SIP request with a 401
+ *
+ *
+ * This method will send an authentication challenge based on the details
+ * given in its parameter
+ *
+ * \param challenge Details to help in constructing a WWW-Authenticate header
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_challenge_request(struct sip_digest_challenge_data *challenge);
+
+/*!
+ * \brief Determine the endpoint that has sent a SIP message
+ *
+ * This will call into each of the registered endpoint identifiers'
+ * identify_endpoint() callbacks until one returns a non-NULL endpoint.
+ * This will return an ao2 object. Its reference count will need to be
+ * decremented when completed using the endpoint.
+ *
+ * \param rdata The inbound SIP message to use when identifying the endpoint.
+ * \retval NULL No matching endpoint
+ * \retval non-NULL The matching endpoint
+ */
+struct ast_sip_endpoint *ast_sip_identify_endpoint(struct pjsip_rx_data *rdata);
+
+/*!
+ * \brief Add a header to an outbound SIP message
+ *
+ * \param tdata The message to add the header to
+ * \param name The header name
+ * \param value The header value
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_add_header(struct pjsip_tx_data *tdata, const char *name, const char *value);
+
+/*!
+ * \brief Add a body to an outbound SIP message
+ *
+ * If this is called multiple times, the latest body will replace the current
+ * body.
+ *
+ * \param tdata The message to add the body to
+ * \param body The message body to add
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_add_body(struct pjsip_tx_data *tdata, const char *body);
+
+/*!
+ * \brief Add a multipart body to an outbound SIP message
+ *
+ * This will treat each part of the input array as part of a multipart body and
+ * add each part to the SIP message.
+ *
+ * \param tdata The message to add the body to
+ * \param bodies The parts of the body to add
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_add_body(struct pjsip_tx_data *tdata, const char *bodies[]);
+
+/*!
+ * \brief Append body data to a SIP message
+ *
+ * This acts mostly the same as ast_sip_add_body, except that rather than replacing
+ * a body if it currently exists, it appends data to an existing body.
+ *
+ * \param tdata The message to append the body to
+ * \param body The string to append to the end of the current body
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_append_body(struct pjsip_tx_data *tdata, const char *body);
+
+#endif /* _RES_SIP_H */
Propchange: team/mmichelson/res_sip/include/asterisk/res_sip.h
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: team/mmichelson/res_sip/include/asterisk/res_sip.h
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: team/mmichelson/res_sip/include/asterisk/res_sip.h
------------------------------------------------------------------------------
svn:mime-type = text/plain
More information about the asterisk-commits
mailing list