doc the relationship between PrivateKey and PrivateKeyWithSerialization (#3721)

* doc the relationship between PrivateKey and PrivateKeyWithSerialization

Or at least do it better.

* let's talk about opaque keys

5 files changed, 34 insertions, 8 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 202fa2de..a630878c 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -72,3 +72,12 @@ Glossary
         or pseudo-random number (see :doc:`Random number generation
         </random-numbers>`). Since a nonce does not have to be unpredictable,
         it can also take a form of a counter.
+
+    opaque key
+        An opaque key is a type of key that allows you to perform cryptographic
+        operations such as encryption, decryption, signing, and verification,
+        but does not allow access to the key itself. Typically an opaque key is
+        loaded from a `hardware security module`_ (HSM).
+
+
+.. _`hardware security module`: https://en.wikipedia.org/wiki/Hardware_security_module
diff --git a/docs/hazmat/primitives/asymmetric/dh.rst b/docs/hazmat/primitives/asymmetric/dh.rst
index f97a328b..c52ee4d1 100644
--- a/docs/hazmat/primitives/asymmetric/dh.rst
+++ b/docs/hazmat/primitives/asymmetric/dh.rst
@@ -142,6 +142,9 @@ Key interfaces
 
     .. versionadded:: 0.9
 
+    A DH private key that is not an :term:`opaque key` also implements
+    :class:`DHPrivateKeyWithSerialization` to provide serialization methods.
+
     .. attribute:: key_size
 
         The bit length of the prime modulus.
@@ -172,8 +175,9 @@ Key interfaces
 
     .. versionadded:: 0.9
 
-    Inherits from
-    :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey`.
+    This interface contains additional methods relating to serialization.
+    Any object with this interface also has all the methods from
+    :class:`DHPrivateKey`.
 
     .. method:: private_numbers()
 
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 13cd0412..a6088190 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -278,7 +278,9 @@ Key interfaces
 
     .. versionadded:: 0.3
 
-    A `DSA`_ private key.
+    A `DSA`_ private key. A DSA private key that is not an
+    :term:`opaque key` also implements :class:`DSAPrivateKeyWithSerialization`
+    to provide serialization methods.
 
     .. method:: public_key()
 
@@ -322,7 +324,9 @@ Key interfaces
 
     .. versionadded:: 0.8
 
-    Extends :class:`DSAPrivateKey`.
+    This interface contains additional methods relating to serialization.
+    Any object with this interface also has all the methods from
+    :class:`DSAPrivateKey`.
 
     .. method:: private_numbers()
 
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 614d7a32..710c11ca 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -441,7 +441,10 @@ Key Interfaces
     .. versionadded:: 0.5
 
     An elliptic curve private key for use with an algorithm such as `ECDSA`_ or
-    `EdDSA`_.
+    `EdDSA`_. An elliptic curve private key that is not an
+    :term:`opaque key` also implements
+    :class:`EllipticCurvePrivateKeyWithSerialization` to provide serialization
+    methods.
 
     .. method:: exchange(algorithm, peer_public_key)
 
@@ -495,7 +498,9 @@ Key Interfaces
 
     .. versionadded:: 0.8
 
-    Extends :class:`EllipticCurvePrivateKey`.
+    This interface contains additional methods relating to serialization.
+    Any object with this interface also has all the methods from
+    :class:`EllipticCurvePrivateKey`.
 
     .. method:: private_numbers()
 
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index 152e5ed8..97f68c3a 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -530,7 +530,9 @@ Key interfaces
 
     .. versionadded:: 0.2
 
-    An `RSA`_ private key.
+    An `RSA`_ private key. An RSA private key that is not an
+    :term:`opaque key` also implements :class:`RSAPrivateKeyWithSerialization`
+    to provide serialization methods.
 
     .. method:: decrypt(ciphertext, padding)
 
@@ -584,7 +586,9 @@ Key interfaces
 
     .. versionadded:: 0.8
 
-    Extends :class:`RSAPrivateKey`.
+    This interface contains additional methods relating to serialization.
+    Any object with this interface also has all the methods from
+    :class:`RSAPrivateKey`.
 
     .. method:: private_numbers()