Merge pull request #632 from alex/glossary-public-key

Document public key and private keys in teh glossary

1 files changed, 21 insertions, 1 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 4421fca3..ef422a6e 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -26,9 +26,29 @@ Glossary
         Cryptographic operations where encryption and decryption use the same
         key.
 
+    public-key cryptography
     asymmetric cryptography
         Cryptographic operations where encryption and decryption use different
-        keys. There are separate encryption and decryption keys.
+        keys. There are separate encryption and decryption keys. Typically
+        encryption is performed using a :term:`public key`, and it can then be
+        decrypted using a :term:`private key`. Asymmetric cryptography can also
+        be used to create signatures, which can be generated with a
+        :term:`private key` and verified with a :term:`public key`.
+
+    public key
+        This is one of two keys involved in :term:`public-key cryptography`. It
+        can be used to encrypt messages for someone possessing the
+        corresponding :term:`private key` and to verify signatures created with
+        the corresponding :term:`private key`. This can be distributed
+        publicly, hence the name.
+
+    private key
+        This is one of two keys involved in :term:`public-key cryptography`. It
+        can be used to decrypt messages which were encrypted with the
+        corresponding :term:`public key`, as well as to create signatures,
+        which can be verified with the corresponding :term:`public key`. These
+        **must** be kept secret, if they are exposed, all encrypted messages
+        are compromised, and an attacker will be able to forge signatures.
 
     authentication
         The process of verifying that a message was created by a specific