Code autogenerated from Kurento/doc-kurento@186d2d2

source/features/security.rst

@@ -124,13 +124,17 @@ WebRTC requires HTTPS, so your JavaScript application must be served by a secure
    sudo apt-get install --yes nodejs
    sudo npm install -g http-server
 
-* You will need to provide a valid SSL certificate in order to enable HTTPS. Here, there are two alternatives:
+* You will need to provide a valid SSL certificate in order to enable HTTPS. There are two alternatives:
 
-  1. Request a certificate from a local Certification Authority (*CA*).
+  1. Obtain a certificate from a trusted Certification Authority (*CA*).
 
-  2. Create your own self-signed certificate as explained `here <https://www.akadia.com/services/ssh_test_certificate.html>`__. This link will teach you how to create the required files: *server.crt*, *server.key*, and *server.csr*.
+  2. Create your own untrusted self-signed certificate. You can search articles online that explain how to do this, for example `this one <https://www.akadia.com/services/ssh_test_certificate.html>`__.
 
-* Start the web server using the SSL certificate:
+     Alternatively, it can be much easier and convenient using a self-signed certificate generation tool, such as `mkcert <https://github.com/FiloSottile/mkcert>`__.
+
+     Note that while a self-signed certificate can be used, browsers will show a big security warning. Users will see this warning, and must click to accept the unsafe certificate before proceeding to the page.
+
+* Start the HTTPS web server, using the SSL certificate:
 
   .. code-block:: bash
 
@@ -143,66 +147,83 @@ WebRTC requires HTTPS, so your JavaScript application must be served by a secure
 Securing Kurento Media Server
 =============================
 
-First, you need to change the configuration file of Kurento Media Server, i.e.
-``/etc/kurento/kurento.conf.json``, uncommenting the following lines::
+With the default configuration, Kurento Media Server will listen for non-secure WebSocket connections (``ws://``) on the port 8888. Application Servers will establish a WebSocket connection with KMS, in order to control it and send messages conforming to the :doc:`/features/kurento_api`.
+
+This is fine for initial stages of application development, but before deploying on production environments you'll probably want to use Secure WebSocket (``wss://``) connections.
+
+To enable WSS, edit the main KMS configuration file, **/etc/kurento/kurento.conf.json**, and un-comment the following lines:
+
+.. code-block:: text
 
    "secure": {
      "port": 8433,
-     "certificate": "defaultCertificate.pem",
-     "password": ""
-   },
+     "certificate": "cert+key.pem",
+     "password": "KEY_PASSWORD"
+   }
+
+If you will be using a signed certificate issued by a trusted Certificate Authority such as Verisign or Let's Encrypt, then you are done. Just skip to the next section: :ref:`features-security-kms-wss-connect`.
 
-If this PEM certificate is a signed certificate (by a Certificate Authority such
-as Verisign), then you are done. If you are going to use a self-signed
-certificate (suitable for development), then there is still more work to do.
+However, if you are going to use an untrusted self-signed certificate (typically done during for development), then there is still more work to do.
 
-You can generate a self signed certificate by doing this::
+You can generate a self signed certificate by doing this:
+
+.. code-block:: shell
 
    certtool --generate-privkey --outfile defaultCertificate.pem
-   echo 'organization = your organization name' > certtool.tmpl
+
+   echo 'organization = your organization name' >certtool.tmpl
+
    certtool --generate-self-signed --load-privkey defaultCertificate.pem \
-      --template certtool.tmpl >> defaultCertificate.pem
+      --template certtool.tmpl >>defaultCertificate.pem
+
    sudo chown kurento defaultCertificate.pem
 
-Due to the fact that the certificate is self-signed, applications will reject it
-by default. For this reason, you'll need to force them to accept it.
+Alternatively, it can be much easier and convenient using a self-signed certificate generation tool, such as `mkcert <https://github.com/FiloSottile/mkcert>`__.
+
+Because self-signed certificates are untrusted by nature, client browsers and server applications will reject it by default. You'll need to force them to accept it:
 
-* Browser applications: You'll need to manually accept the certificate as
-  trusted one before secure WebSocket connections can be established. By
-  default, this can be done by connecting to https://localhost:8433/kurento
-  and accepting the certificate in the browser.
+* **Java applications**: Follow the instructions of `this link <https://www.mkyong.com/webservices/jax-ws/suncertpathbuilderexception-unable-to-find-valid-certification-path-to-requested-target/>`__ (get ``InstallCert.java`` from `here <https://code.google.com/p/java-use-examples/source/browse/trunk/src/com/aw/ad/util/InstallCert.java>`__).
 
-* Java applications: Follow the instructions of `this link <https://www.mkyong.com/webservices/jax-ws/suncertpathbuilderexception-unable-to-find-valid-certification-path-to-requested-target/>`__
-  (get ``InstallCert.java`` from
-  `here <https://code.google.com/p/java-use-examples/source/browse/trunk/src/com/aw/ad/util/InstallCert.java>`__).
-  You'll need to instruct the ``KurentoClient`` needs to be configured to allow
-  the use of certificates. For this purpose, we need to create our own
-  ``JsonRpcClient``:
+  You'll need to instruct the ``KurentoClient`` to allow using certificates. For this purpose, create an ``JsonRpcClient``:
 
-.. sourcecode:: java
+.. code-block:: java
 
    SslContextFactory sec = new SslContextFactory(true);
    sec.setValidateCerts(false);
    JsonRpcClientWebSocket rpcClient = new JsonRpcClientWebSocket(uri, sec);
-   KurentoClient kuretoClient = KurentoClient.createFromJsonRpcClient(rpcClient);
+   KurentoClient kurentoClient = KurentoClient.createFromJsonRpcClient(rpcClient);
+
+* **Node applications**: Take a look at this page: `Painless Self Signed Certificates in node.js <https://git.coolaj86.com/coolaj86/ssl-root-cas.js/src/branch/master/Painless-Self-Signed-Certificates-in-node.js.md>`__.
+
+* **Browser JavaScript applications**: Some browsers require the user to accept a security warning before Secure WebSocket connections can be established. This is done by directly opening the KMS WebSocket URL: https://KMS_HOST:8433/kurento
+
+  As of this writing, Firefox 75.0 requires doing this, while Chrome 81.0 doesn't require it.
+
+
+
+.. _features-security-kms-wss-connect:
+
+Connecting to a secured KMS
+---------------------------
+
+Now that KMS is listening for Secure WebSocket connections, and (if using a self-signed certificate) your Application Server is configured to accept the certificate used in KMS, you have to change the WebSocket URL used in your application logic.
+
+Make sure your application uses a WebSocket URL that starts with ``wss://`` instead of ``ws://``. Depending on the platform, this is done in different ways:
 
-* Node applications: Take a look at `this page <https://github.com/coolaj86/node-ssl-root-cas/wiki/Painless-Self-Signed-Certificates-in-node.js>`__.
+* **Java**: Launch with a ``kms.url`` property. For example:
 
-After having configured the certificate in your Application Server, you have to change the WebSocket URI in your application logic, and make sure the WebSocket URL starts with ``wss://`` instead of the insecure version ``ws://``. For instance, in the *hello-world* application within the tutorials, this would be done as follows:
+  .. code-block:: java
 
-* Java: Changing this line in
-  `HelloWorldApp.java <https://github.com/Kurento/kurento-tutorial-java/blob/master/kurento-hello-world/src/main/java/org/kurento/tutorial/helloworld/HelloWorldApp.java>`__::
+     mvn clean spring-boot:run -Dkms.url="wss://KMS_HOST:8433/kurento"
 
-   final static String DEFAULT_KMS_WS_URI = "wss://localhost:8433/kurento";
+* **Node.js**: Launch with the ``ws_uri`` command-line argument. For example:
 
-* Browser JavaScript: Changing this line in
-  `index.js <https://github.com/Kurento/kurento-tutorial-js/blob/master/kurento-hello-world/js/index.js>`__::
+  .. code-block:: js
 
-   const ws_uri = 'wss://' + location.hostname + ':8433/kurento';
+     npm start -- --ws_uri="wss://KMS_HOST:8433/kurento"
 
-* Node.js: Changing this line in
-  `server.js <https://github.com/Kurento/kurento-tutorial-node/blob/master/kurento-hello-world/server.js>`__::
+* **Browser JavaScript**: Application-specific method. For example, using hardcoded values:
 
-   const ws_uri = "wss://localhost:8433/kurento";
+  .. code-block:: js
 
-* All: Passing the WebSocket URL to the Application as a startup parameter (see each individual tutorial page to get the syntax for doing so).
+     const ws_uri: "wss://" + location.hostname + ":8433/kurento";

source/langdoc/client-javadoc/org/kurento/client/class-use/Continuation.html

@@ -131,14 +131,14 @@ <h3>Uses of <a href="../../../../org/kurento/client/Continuation.html" title="in
 </tr>
 <tr class="altColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><span class="typeNameLabel">PlayerEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/PlayerEndpoint.html#addEndOfStreamListener-org.kurento.client.EventListener-org.kurento.client.Continuation-">addEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client">EventListener</a>&lt;<a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client">EndOfStreamEvent</a>&gt;&nbsp;listener,
+<td class="colLast"><span class="typeNameLabel">HttpPostEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/HttpPostEndpoint.html#addEndOfStreamListener-org.kurento.client.EventListener-org.kurento.client.Continuation-">addEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client">EventListener</a>&lt;<a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client">EndOfStreamEvent</a>&gt;&nbsp;listener,
                       <a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&gt;&nbsp;cont)</code>
 <div class="block">Add a <a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client"><code>EventListener</code></a> for event <a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client"><code>EndOfStreamEvent</code></a>.</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><span class="typeNameLabel">HttpPostEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/HttpPostEndpoint.html#addEndOfStreamListener-org.kurento.client.EventListener-org.kurento.client.Continuation-">addEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client">EventListener</a>&lt;<a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client">EndOfStreamEvent</a>&gt;&nbsp;listener,
+<td class="colLast"><span class="typeNameLabel">PlayerEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/PlayerEndpoint.html#addEndOfStreamListener-org.kurento.client.EventListener-org.kurento.client.Continuation-">addEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client">EventListener</a>&lt;<a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client">EndOfStreamEvent</a>&gt;&nbsp;listener,
                       <a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&gt;&nbsp;cont)</code>
 <div class="block">Add a <a href="../../../../org/kurento/client/EventListener.html" title="interface in org.kurento.client"><code>EventListener</code></a> for event <a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client"><code>EndOfStreamEvent</code></a>.</div>
 </td>
@@ -1152,14 +1152,14 @@ <h3>Uses of <a href="../../../../org/kurento/client/Continuation.html" title="in
 </tr>
 <tr class="altColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><span class="typeNameLabel">PlayerEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/PlayerEndpoint.html#removeEndOfStreamListener-org.kurento.client.ListenerSubscription-org.kurento.client.Continuation-">removeEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&nbsp;listenerSubscription,
+<td class="colLast"><span class="typeNameLabel">HttpPostEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/HttpPostEndpoint.html#removeEndOfStreamListener-org.kurento.client.ListenerSubscription-org.kurento.client.Continuation-">removeEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&nbsp;listenerSubscription,
                          <a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Void.html?is-external=true" title="class or interface in java.lang">Void</a>&gt;&nbsp;cont)</code>
 <div class="block">Remove a <a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client"><code>ListenerSubscription</code></a> for event <a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client"><code>EndOfStreamEvent</code></a>.</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><span class="typeNameLabel">HttpPostEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/HttpPostEndpoint.html#removeEndOfStreamListener-org.kurento.client.ListenerSubscription-org.kurento.client.Continuation-">removeEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&nbsp;listenerSubscription,
+<td class="colLast"><span class="typeNameLabel">PlayerEndpoint.</span><code><span class="memberNameLink"><a href="../../../../org/kurento/client/PlayerEndpoint.html#removeEndOfStreamListener-org.kurento.client.ListenerSubscription-org.kurento.client.Continuation-">removeEndOfStreamListener</a></span>(<a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client">ListenerSubscription</a>&nbsp;listenerSubscription,
                          <a href="../../../../org/kurento/client/Continuation.html" title="interface in org.kurento.client">Continuation</a>&lt;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Void.html?is-external=true" title="class or interface in java.lang">Void</a>&gt;&nbsp;cont)</code>
 <div class="block">Remove a <a href="../../../../org/kurento/client/ListenerSubscription.html" title="interface in org.kurento.client"><code>ListenerSubscription</code></a> for event <a href="../../../../org/kurento/client/EndOfStreamEvent.html" title="class in org.kurento.client"><code>EndOfStreamEvent</code></a>.</div>
 </td>