Shuffle RESTful URL's around.

This patch moves the RESTful URL's around to more appropriate
locations for release.

The /stasis URL's are moved to /ari, since Asterisk REST Interface was
a more appropriate name than Stasis-HTTP. (Most of the code still has
stasis_http references, but they will be cleaned up after there are no
more outstanding branches that would have merge conflicts with such a
change).

A larger change was moving the ARI events WebSocket off of the shared
/ws URL to its permanent home on /ari/events. The Swagger code
generator was extended to handle "upgrade: websocket" and
"websocketProtocol:" attributes on an operation.

The WebSocket module was modified to better handle WebSocket servers
that have a single registered protocol handler. If a client
connections does not specify the Sec-WebSocket-Protocol header, and
the server has a single protocol handler registered, the WebSocket
server will go ahead and accept the client for that subprotocol.

(closes issue ASTERISK-21857)
Review: https://reviewboard.asterisk.org/r/2621/



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@393528 65c4cc65-6c06-0410-ace0-fbb531ad65f3

4 files changed, 120 insertions, 11 deletions

diff --git a/include/asterisk/autoconfig.h.in b/include/asterisk/autoconfig.h.in
index 2251ab9af..ecbba0d2b 100644
--- a/include/asterisk/autoconfig.h.in
+++ b/include/asterisk/autoconfig.h.in
@@ -149,9 +149,15 @@
 /* Define to 1 if you have the `cosl' function. */
 #undef HAVE_COSL
 
+/* Define to 1 if you have the `crypt' function. */
+#undef HAVE_CRYPT
+
 /* Define to 1 if you have the OpenSSL Cryptography library. */
 #undef HAVE_CRYPTO
 
+/* Define to 1 if you have the `crypt_r' function. */
+#undef HAVE_CRYPT_R
+
 /* Define to 1 if you have a functional curl library. */
 #undef HAVE_CURL
 
diff --git a/include/asterisk/http.h b/include/asterisk/http.h
index 9efcad7f7..59e185a6f 100644
--- a/include/asterisk/http.h
+++ b/include/asterisk/http.h
@@ -112,6 +112,26 @@ struct ast_http_uri {
 /*! \brief Get cookie from Request headers */
 struct ast_variable *ast_http_get_cookies(struct ast_variable *headers);
 
+/*! \brief HTTP authentication information. */
+struct ast_http_auth {
+	/*! Provided userid. */
+	char *userid;
+	/*! For Basic auth, the provided password. */
+	char *password;
+};
+
+/*!
+ * \brief Get HTTP authentication information from headers.
+ *
+ * The returned object is AO2 managed, so clean up with ao2_cleanup().
+ *
+ * \param headers HTTP request headers.
+ * \return HTTP auth structure.
+ * \return \c NULL if no supported HTTP auth headers present.
+ * \since 12
+ */
+struct ast_http_auth *ast_http_get_auth(struct ast_variable *headers);
+
 /*! \brief Register a URI handler */
 int ast_http_uri_link(struct ast_http_uri *urihandler);
 
diff --git a/include/asterisk/stasis_http.h b/include/asterisk/stasis_http.h
index f20a90106..05e9dded7 100644
--- a/include/asterisk/stasis_http.h
+++ b/include/asterisk/stasis_http.h
@@ -53,13 +53,17 @@ typedef void (*stasis_rest_callback)(struct ast_variable *get_params,
 struct stasis_rest_handlers {
 	/*! Path segement to handle */
 	const char *path_segment;
-	/*! If true (non-zero), path_segment is a wildcard, and will match all values.
+	/*! If true (non-zero), path_segment is a wildcard, and will match all
+	 * values.
 	 *
-	 * Value of the segement will be passed into the \a path_vars parameter of the callback.
+	 * Value of the segement will be passed into the \a path_vars parameter
+	 * of the callback.
 	 */
 	int is_wildcard;
 	/*! Callbacks for all handled HTTP methods. */
 	stasis_rest_callback callbacks[AST_HTTP_MAX_METHOD];
+	/*! WebSocket server for handling WebSocket upgrades. */
+	struct ast_websocket_server *ws_server;
 	/*! Number of children in the children array */
 	size_t num_children;
 	/*! Handlers for sub-paths */
@@ -78,7 +82,9 @@ struct stasis_http_response {
 	 * See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html */
 	int response_code;
 	/*! Corresponding text for the response code */
-	const char *response_text; // Shouldn't http.c handle this?
+	const char *response_text; /* Shouldn't http.c handle this? */
+	/*! Flag to indicate that no further response is needed */
+	int no_response:1;
 };
 
 /*!
@@ -104,14 +110,17 @@ int stasis_http_remove_handler(struct stasis_rest_handlers *handler);
  * Only call from res_stasis_http and test_stasis_http. Only public to allow
  * for unit testing.
  *
+ * \param ser TCP/TLS connection.
  * \param uri HTTP URI, relative to the API path.
  * \param method HTTP method.
  * \param get_params HTTP \c GET parameters.
  * \param headers HTTP headers.
  * \param[out] response RESTful HTTP response.
  */
-void stasis_http_invoke(const char *uri, enum ast_http_method method, struct ast_variable *get_params,
-			struct ast_variable *headers, struct stasis_http_response *response);
+void stasis_http_invoke(struct ast_tcptls_session_instance *ser,
+	const char *uri, enum ast_http_method method,
+	struct ast_variable *get_params, struct ast_variable *headers,
+	struct stasis_http_response *response);
 
 /*!
  * \internal
@@ -126,14 +135,49 @@ void stasis_http_invoke(const char *uri, enum ast_http_method method, struct ast
  */
 void stasis_http_get_docs(const char *uri, struct ast_variable *headers, struct stasis_http_response *response);
 
+/*! \brief Abstraction for reading/writing JSON to a WebSocket */
+struct ari_websocket_session;
+
 /*!
- * \internal
- * \brief Stasis WebSocket connection handler
- * \param session WebSocket session.
- * \param parameters HTTP \c GET parameters.
- * \param headers HTTP headers.
+ * \brief Create an ARI WebSocket session.
+ *
+ * \param ws_session Underlying WebSocket session.
+ * \return New ARI WebSocket session.
+ * \return \c NULL on error.
+ */
+struct ari_websocket_session *ari_websocket_session_create(
+	struct ast_websocket *ws_session);
+
+/*!
+ * \brief Read a message from an ARI WebSocket.
+ *
+ * \param session Session to read from.
+ * \return Message received.
+ * \return \c NULL if WebSocket could not be read.
+ */
+struct ast_json *ari_websocket_session_read(
+	struct ari_websocket_session *session);
+
+/*!
+ * \brief Send a message to an ARI WebSocket.
+ *
+ * \param session Session to write to.
+ * \param message Message to send.
+ * \return 0 on success.
+ * \return Non-zero on error.
+ */
+int ari_websocket_session_write(struct ari_websocket_session *session,
+	struct ast_json *message);
+
+/*!
+ * \brief The stock message to return when out of memory.
+ *
+ * The refcount is NOT bumped on this object, so ast_json_ref() if you want to
+ * keep the reference.
+ *
+ * \return JSON message specifying an out-of-memory error.
  */
-void stasis_websocket_callback(struct ast_websocket *session, struct ast_variable *parameters, struct ast_variable *headers);
+struct ast_json *ari_oom_json(void);
 
 /*!
  * \brief Fill in an error \a stasis_http_response.
diff --git a/include/asterisk/utils.h b/include/asterisk/utils.h
index 6f041f953..ce6db0965 100644
--- a/include/asterisk/utils.h
+++ b/include/asterisk/utils.h
@@ -938,4 +938,43 @@ char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size);
     void _dtor_ ## varname (vartype * v) { dtor(*v); } \
     vartype varname __attribute__((cleanup(_dtor_ ## varname))) = (initval)
 
+/*!
+ * \brief Asterisk wrapper around crypt(3).
+ *
+ * The interpretation of the salt (which determines the password hashing
+ * algorithm) is system specific. Application code should prefer to use
+ * ast_crypt_encrypt() or ast_crypt_validate().
+ *
+ * The returned string is heap allocated, and should be freed with ast_free().
+ *
+ * \param key User's password to crypt.
+ * \param salt Salt to crypt with.
+ * \return Crypted password.
+ * \return \c NULL on error.
+ */
+char *ast_crypt(const char *key, const char *salt);
+
+/*
+ * \brief Asterisk wrapper around crypt(3) for encrypting passwords.
+ *
+ * This function will generate a random salt and encrypt the given password.
+ *
+ * The returned string is heap allocated, and should be freed with ast_free().
+ *
+ * \param key User's password to crypt.
+ * \return Crypted password.
+ * \return \c NULL on error.
+ */
+char *ast_crypt_encrypt(const char *key);
+
+/*
+ * \brief Asterisk wrapper around crypt(3) for validating passwords.
+ *
+ * \param key User's password to validate.
+ * \param expected Expected result from crypt.
+ * \return True (non-zero) if \a key matches \a expected.
+ * \return False (zero) if \a key doesn't match.
+ */
+int ast_crypt_validate(const char *key, const char *expected);
+
 #endif /* _ASTERISK_UTILS_H */