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
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 202fa2d..a630878 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -72,3 +72,12 @@
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 f97a328..c52ee4d 100644
--- a/docs/hazmat/primitives/asymmetric/dh.rst
+++ b/docs/hazmat/primitives/asymmetric/dh.rst
@@ -142,6 +142,9 @@
.. 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 @@
.. 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 13cd041..a608819 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -278,7 +278,9 @@
.. 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 @@
.. 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 614d7a3..710c11c 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -441,7 +441,10 @@
.. 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 @@
.. 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 152e5ed..97f68c3 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -530,7 +530,9 @@
.. 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 @@
.. 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()