Merge pull request #4098 from NPDebs/main

Proofread and Improve security-basics.rst

docs/source/getting-started/security-basics.rst

@@ -5,8 +5,8 @@ Security settings
 
    You should not run JupyterHub without SSL encryption on a public network.
 
-Security is the most important aspect of configuring Jupyter. Three
+Security is the most important aspect of configuring Jupyter.
-configuration settings are the main aspects of security configuration:
+Three (3) configuration settings are the main aspects of security configuration:
 
 1. :ref:`SSL encryption <ssl-encryption>` (to enable HTTPS)
 2. :ref:`Cookie secret <cookie-secret>` (a key for encrypting browser cookies)
@@ -15,7 +15,7 @@ configuration settings are the main aspects of security configuration:
 
 The Hub hashes all secrets (e.g., auth tokens) before storing them in its
 database. A loss of control over read-access to the database should have
-minimal impact on your deployment; if your database has been compromised, it
+minimal impact on your deployment. If your database has been compromised, it
 is still a good idea to revoke existing tokens.
 
 .. _ssl-encryption:
@@ -31,7 +31,7 @@ Using an SSL certificate
 
 This will require you to obtain an official, trusted SSL certificate or create a
 self-signed certificate. Once you have obtained and installed a key and
-certificate you need to specify their locations in the ``jupyterhub_config.py``
+certificate, you need to specify their locations in the ``jupyterhub_config.py``
 configuration file as follows:
 
 .. code-block:: python
@@ -72,13 +72,13 @@ would be the needed configuration:
 If SSL termination happens outside of the Hub
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In certain cases, for example if the hub is running behind a reverse proxy, and
+In certain cases, for example, if the hub is running behind a reverse proxy, and
 `SSL termination is being provided by NGINX <https://www.nginx.com/resources/admin-guide/nginx-ssl-termination/>`_,
 it is reasonable to run the hub without SSL.
 
 To achieve this, simply omit the configuration settings
 ``c.JupyterHub.ssl_key`` and ``c.JupyterHub.ssl_cert``
-(setting them to ``None`` does not have the same effect, and is an error).
+(setting them to ``None`` does not have the same effect, but results in an error).
 
 .. _authentication-token:
 
@@ -92,7 +92,7 @@ use an auth token.
 
 The value of this token should be a random string (for example, generated by
 ``openssl rand -hex 32``). You can store it in the configuration file or an
-environment variable
+environment variable.
 
 Generating and storing token in the configuration file
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -119,7 +119,7 @@ Default if token is not set
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you don't set the Proxy authentication token, the Hub will generate a random
-key itself, which means that any time you restart the Hub you **must also
+key itself. This means that any time you restart the Hub, you **must also
 restart the Proxy**. If the proxy is a subprocess of the Hub, this should happen
 automatically (this is the default configuration).
 
@@ -128,7 +128,7 @@ automatically (this is the default configuration).
 Cookie secret
 -------------
 
-The cookie secret is an encryption key, used to encrypt the browser cookies
+The cookie secret is an encryption key, used to encrypt the browser cookies,
 which are used for authentication. Three common methods are described for
 generating and configuring the cookie secret.
 
@@ -136,8 +136,8 @@ Generating and storing as a cookie secret file
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The cookie secret should be 32 random bytes, encoded as hex, and is typically
-stored in a ``jupyterhub_cookie_secret`` file. An example command to generate the
+stored in a ``jupyterhub_cookie_secret`` file. Below, is an example command to generate the
-``jupyterhub_cookie_secret`` file is:
+``jupyterhub_cookie_secret`` file:
 
 .. code-block:: bash
 
@@ -155,7 +155,7 @@ The location of the ``jupyterhub_cookie_secret`` file can be specified in the
 
 If the cookie secret file doesn't exist when the Hub starts, a new cookie
 secret is generated and stored in the file. The file must not be readable by
-``group`` or ``other`` or the server won't start. The recommended permissions
+``group`` or ``other``, otherwise the server won't start. The recommended permissions
 for the cookie secret file are ``600`` (owner-only rw).
 
 Generating and storing as an environment variable
@@ -176,8 +176,8 @@ the Hub starts.
 Generating and storing as a binary string
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can also set the cookie secret in the configuration file
+You can also set the cookie secret, as a binary string,
-itself, ``jupyterhub_config.py``, as a binary string:
+in the configuration file (``jupyterhub_config.py``) itself:
 
 .. code-block:: python
 
@@ -198,7 +198,7 @@ jupyterhub-hub-login
 ~~~~~~~~~~~~~~~~~~~~
 
 This is the login token used when visiting Hub-served pages that are
-protected by authentication such as the main home, the spawn form, etc.
+protected by authentication, such as the main home, the spawn form, etc.
 If this cookie is set, then the user is logged in.
 
 Resetting the Hub cookie secret effectively revokes this cookie.
@@ -209,7 +209,7 @@ jupyterhub-user-<username>
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is the cookie used for authenticating with a single-user server.
-It is set by the single-user server after OAuth with the Hub.
+It is set by the single-user server, after OAuth with the Hub.
 
 Effectively the same as ``jupyterhub-hub-login``, but for the
 single-user server instead of the Hub. It contains an OAuth access token,
@@ -218,14 +218,13 @@ which is checked with the Hub to authenticate the browser.
 Each OAuth access token is associated with a session id (see ``jupyterhub-session-id`` section
 below).
 
-To avoid hitting the Hub on every request, the authentication response
+To avoid hitting the Hub on every request, the authentication response is cached.
-is cached. And to avoid a stale cache the cache key is comprised of both
+The cache key is comprised of both the token and session id, to avoid a stale cache.
-the token and session id.
 
 Resetting the Hub cookie secret effectively revokes this cookie.
 
-This cookie is restricted to the path ``/user/<username>``, so that
+This cookie is restricted to the path ``/user/<username>``,
-only the user’s server receives it.
+to ensure that only the user’s server receives it.
 
 jupyterhub-session-id
 ~~~~~~~~~~~~~~~~~~~~~
@@ -235,7 +234,7 @@ shared by the Hub and single-user servers.
 
 Its sole purpose is to coordinate logout of the multiple OAuth cookies.
 
-This cookie is set to ``/`` so all endpoints can receive it, or clear it, etc.
+This cookie is set to ``/`` so all endpoints can receive it, clear it, etc.
 
 jupyterhub-user-<username>-oauth-state
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -245,7 +244,7 @@ It is only set while OAuth between the single-user server and the Hub
 is processing.
 
 If you use your browser development tools, you should see this cookie
-for a very brief moment before your are logged in,
+for a very brief moment before you are logged in,
 with an expiration date shorter than ``jupyterhub-hub-login`` or
 ``jupyterhub-user-<username>``.