Several updates to our security docs:

- Document what we consider a vulnerability
- Update my prefered PGP key identifier
- Clarify that we only provide security support for the most recent release (this has empirically been true for all of our releases

1 files changed, 35 insertions, 2 deletions

diff --git a/docs/security.rst b/docs/security.rst
index 13f99960..424fdb6c 100644
--- a/docs/security.rst
+++ b/docs/security.rst
@@ -5,6 +5,39 @@ We take the security of ``cryptography`` seriously. The following are a set of
 policies we have adopted to ensure that security issues are addressed in a
 timely fashion.
 
+What is a security issue?
+-------------------------
+
+Anytime it's possible to write code using ``cryptography``'s public API which
+does not provide the guarntees that a reasonable developer would expect it to
+based on our documentation.
+
+That's a bit academic, but basically it means the scope of what we consider a
+vulnerability is broad, and we do not require a proof of concept or even a
+specific exploit, merely a reasonable threat model under which ``cryptography``
+could be attacked.
+
+To give a few examples of things we would consider security issues:
+
+* If a recipe, such as Fernet, made it easy for a user to bypass
+  confidentiality or integrity with the public API (e.g. if the API let a user
+  reuse nonces).
+* If, under any circumstances, we used a CSPRNG which wasn't fork-safe.
+* If ``cryptography`` used an API in an underlying C library and failed to
+  handle error conditions safely.
+
+Examples of things we wouldn't consider security issues:
+
+* Offering ECB mode for symmetric encryption. Though ECB is critically weak, it
+  is documented as being weak in our documentation.
+* Using a variable time comparison somewhere, if it's not possible to
+  articulate any particular program in which this would result in problematic
+  information disclosure.
+
+In general, if you're unsure, we request that you to default to treating things
+as security issues and handling them sensitively, the worst thing that can
+happen is that we'll ask you to file a bug issue.
+
 Reporting a security issue
 --------------------------
 
@@ -14,7 +47,7 @@ tracker.
 If you believe you've identified a security issue with ``cryptography``, please
 report it to ``alex.gaynor@gmail.com``. Messages may be optionally encrypted
 with PGP using key fingerprint
-``E27D 4AA0 1651 72CB C5D2  AF2B 125F 5C67 DFE9 4084`` (this public key is
+``F7FC 698F AAE2 D2EF BECD  E98E D1B3 ADC0 E023 8CA6`` (this public key is
 available from most commonly-used key servers).
 
 Once you've submitted an issue via email, you should receive an acknowledgment
@@ -25,7 +58,7 @@ Supported Versions
 ------------------
 
 At any given time, we will provide security support for the `master`_ branch
-as well as the 2 most recent releases.
+as well as the most recent release.
 
 New releases for OpenSSL updates
 --------------------------------