From 26c425dd74d941b0d010325f8f150d898585a015 Mon Sep 17 00:00:00 2001
From: Paul Kehrer <paul.l.kehrer@gmail.com>
Date: Sat, 1 Sep 2018 16:58:26 -0400
Subject: document that OCSPResponse attributes can raise valuerror (#4453)

---
 docs/x509/ocsp.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

(limited to 'docs/x509/ocsp.rst')

diff --git a/docs/x509/ocsp.rst b/docs/x509/ocsp.rst
index edf4f5ae..b706b323 100644
--- a/docs/x509/ocsp.rst
+++ b/docs/x509/ocsp.rst
@@ -219,12 +219,18 @@ Interfaces
         to sign the response. This will be one of the OIDs from
         :class:`~cryptography.x509.oid.SignatureAlgorithmOID`.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: signature
 
         :type: bytes
 
         The signature bytes.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: tbs_response_bytes
 
         :type: bytes
@@ -232,6 +238,9 @@ Interfaces
         The DER encoded bytes payload that is hashed and then signed. This
         data may be used to validate the signature on the OCSP response.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: certificates
 
         :type: list
@@ -240,6 +249,9 @@ Interfaces
         used to help build a chain to verify the OCSP response. This situation
         occurs when the OCSP responder uses a delegate certificate.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: responder_key_hash
 
         :type: bytes or None
@@ -247,6 +259,9 @@ Interfaces
         The responder's key hash or ``None`` if the response has a
         ``responder_name``.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: responder_name
 
         :type: :class:`~cryptography.x509.Name` or None
@@ -254,18 +269,27 @@ Interfaces
         The responder's ``Name`` or ``None`` if the response has a
         ``responder_key_hash``.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: produced_at
 
         :type: :class:`datetime.datetime`
 
         A naïve datetime representing the time when the response was produced.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: certificate_status
 
         :type: :class:`~cryptography.x509.ocsp.OCSPCertStatus`
 
         The status of the certificate being checked.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: revocation_time
 
         :type: :class:`datetime.datetime` or None
@@ -273,6 +297,9 @@ Interfaces
         A naïve datetime representing the time when the certificate was revoked
         or ``None`` if the certificate has not been revoked.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: revocation_reason
 
         :type: :class:`~cryptography.x509.ReasonFlags` or None
@@ -280,6 +307,9 @@ Interfaces
         The reason the certificate was revoked or ``None`` if not specified or
         not revoked.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: this_update
 
         :type: :class:`datetime.datetime`
@@ -287,6 +317,9 @@ Interfaces
         A naïve datetime representing the most recent time at which the status
         being indicated is known by the responder to have been correct.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: next_update
 
         :type: :class:`datetime.datetime`
@@ -294,6 +327,9 @@ Interfaces
         A naïve datetime representing the time when newer information will
         be available.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: issuer_key_hash
 
         :type: bytes
@@ -301,6 +337,9 @@ Interfaces
         The hash of the certificate issuer's key. The hash algorithm used
         is defined by the ``hash_algorithm`` property.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: issuer_name_hash
 
         :type: bytes
@@ -308,6 +347,9 @@ Interfaces
         The hash of the certificate issuer's name. The hash algorithm used
         is defined by the ``hash_algorithm`` property.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: hash_algorithm
 
         :type: An instance of a
@@ -316,12 +358,18 @@ Interfaces
         The algorithm used to generate the ``issuer_key_hash`` and
         ``issuer_name_hash``.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
     .. attribute:: serial_number
 
         :type: int
 
         The serial number of the certificate that was checked.
 
+        :raises ValueError: If ``response_status`` is not
+            :class:`~cryptography.x509.ocsp.OCSPResponseStatus.SUCCESSFUL`.
+
 
 .. class:: OCSPResponseStatus
 
-- 
cgit v1.2.3