Clarify Token secrecy in docs (#5768)

Author: ollien

lib/phoenix/token.ex

@@ -1,12 +1,18 @@
 defmodule Phoenix.Token do
   @moduledoc """
-  Tokens provide a way to generate and verify bearer
-  tokens for use in Channels or API authentication.
-
-  The data stored in the token is signed to prevent tampering
-  but not encrypted. This means it is safe to store identification
-  information (such as user IDs) but should not be used to store
-  confidential information (such as credit card numbers).
+  Conveniences to sign/encrypt data inside tokens
+  for use in Channels, API authentication, and more.
+
+  The data stored in the token is signed to prevent tampering, and is
+  optionally encrypted.  This means that, so long as the
+  key (see below) remains secret, you can be assured that the data
+  stored in the token has not been tampered with by a third party.
+  However, unless the token is encrypted, it is not safe to use this
+  token to store private information, such as a user's sensitive
+  identification data, as it can be trivially decoded. If the
+  token is encrypted, its contents will kept secret from the client,
+  but it is still a best practice to encode as little secret
+  information as possible, to minimize the impact of key leakage.
 
   ## Example
 
@@ -24,7 +30,8 @@ defmodule Phoenix.Token do
   `endpoint`. We guarantee the token will only be valid for one day
   by setting a max age (recommended).
 
-  The first argument to both `sign/4` and `verify/4` can be one of:
+  The first argument to `sign/4`, `verify/4`, `encrypt/4`, and
+  `decrypt/4` can be one of:
 
     * the module name of a Phoenix endpoint (shown above) - where
       the secret key base is extracted from the endpoint
@@ -37,10 +44,10 @@ defmodule Phoenix.Token do
       to provide adequate entropy
 
   The second argument is a [cryptographic salt](https://en.wikipedia.org/wiki/Salt_(cryptography))
-  which must be the same in both calls to `sign/4` and `verify/4`.
-  For instance, it may be called "user auth" and treated as namespace
-  when generating a token that will be used to authenticate users on
-  channels or on your APIs.
+  which must be the same in both calls to `sign/4` and `verify/4`, or
+  both calls to `encrypt/4` and decrypt/4`. For instance, it may be
+  called "user auth" and treated as namespace when generating a token
+  that will be used to authenticate users on channels or on your APIs.
 
   The third argument can be any term (string, int, list, etc.)
   that you wish to codify into the token. Upon valid verification,
@@ -131,7 +138,9 @@ defmodule Phoenix.Token do
   end
 
   @doc """
-  Encodes, encrypts, and signs data into a token you can send to clients.
+  Encodes, encrypts, and signs data into a token you can send to
+  clients. Its usage is identical to that of `sign/4`, but the data
+  is extracted using `decrypt/4`, rather than `verify/4`.
 
   ## Options
 
@@ -218,6 +227,8 @@ defmodule Phoenix.Token do
   @doc """
   Decrypts the original data from the token and verifies its integrity.
 
+  Its usage is identical to `verify/4` but for encrypted tokens.
+
   ## Options
 
     * `:key_iterations` - option passed to `Plug.Crypto.KeyGenerator`