# OCSP

OCSP (Online Certificate Status Protocol) is a method of checking the revocation status of certificates. It is specified in RFC 6960, as well as other obsoleted RFCs.

## Loading Requests

cryptography.x509.ocsp.load_der_ocsp_request(data)

  New in version 2.4.

  Deserialize an OCSP request from DER encoded data.

  Parameters:

    data (bytes) – The DER encoded OCSP request data.

  Returns:

    An instance of `OCSPRequest`.

      >>> from cryptography.x509 import ocsp
      >>> ocsp_req = ocsp.load_der_ocsp_request(der_ocsp_req)
      >>> print(ocsp_req.serial_number)
      872625873161273451176241581705670534707360122361

## Creating Requests

class cryptography.x509.ocsp.OCSPRequestBuilder

  New in version 2.4.

  This class is used to create `OCSPRequest` objects.

  add_certificate(cert, issuer, algorithm)

    Adds a request using a certificate, issuer certificate, and hash algorithm. You can call this method or `add_certificate_by_hash` only once.

    Parameters:

      - cert – The `Certificate` whose validity is being checked.

      - issuer – The issuer `Certificate` of the certificate that is being checked.

      - algorithm – A `HashAlgorithm` instance. For OCSP only `SHA1`, `SHA224`, `SHA256`, `SHA384`, and `SHA512` are allowed.

  add_certificate_by_hash(issuer_name_hash, issuer_key_hash, serial_number, algorithm)

    New in version 39.0.0.

    Adds a request using the issuer’s name hash, key hash, the certificate serial number and hash algorithm. You can call this method or `add_certificate` only once.

    Parameters:

      - issuer_name_hash (bytes) – The hash of the issuer’s DER encoded name using the same hash algorithm as the one specified in the `algorithm` parameter.

      - issuer_key_hash (bytes) – The hash of the issuer’s public key bit string DER encoding using the same hash algorithm as the one specified in the `algorithm` parameter.

      - serial_number (int) – The serial number of the certificate being checked.

      - algorithm – A `HashAlgorithm` instance. For OCSP only `SHA1`, `SHA224`, `SHA256`, `SHA384`, and `SHA512` are allowed.

  add_extension(extval, critical)

    Adds an extension to the request.

    Parameters:

      - extval – An extension conforming to the `ExtensionType` interface.

      - critical – Set to `True` if the extension must be understood and handled.

  build()
    Returns:

      A new `OCSPRequest`.

      >>> from cryptography.hazmat.primitives import serialization
      >>> from cryptography.hazmat.primitives.hashes import SHA256
      >>> from cryptography.x509 import load_pem_x509_certificate, ocsp
      >>> cert = load_pem_x509_certificate(pem_cert)
      >>> issuer = load_pem_x509_certificate(pem_issuer)
      >>> builder = ocsp.OCSPRequestBuilder()
      >>> # SHA256 is in this example because while RFC 5019 originally
      >>> # required SHA1 RFC 6960 updates that to SHA256.
      >>> # However, depending on your requirements you may need to use SHA1
      >>> # for compatibility reasons.
      >>> builder = builder.add_certificate(cert, issuer, SHA256())
      >>> req = builder.build()
      >>> base64.b64encode(req.public_bytes(serialization.Encoding.DER))
      b'MF8wXTBbMFkwVzANBglghkgBZQMEAgEFAAQgn3BowBaoh77h17ULfkX6781dUDPD82Taj8wO1jZWhZoEINxPgjoQth3w7q4AouKKerMxIMIuUG4EuWU2pZfwih52AgI/IA=='

## Loading Responses

cryptography.x509.ocsp.load_der_ocsp_response(data)

  New in version 2.4.

  Deserialize an OCSP response from DER encoded data.

  Parameters:

    data (bytes) – The DER encoded OCSP response data.

  Returns:

    An instance of `OCSPResponse`.

      >>> from cryptography.x509 import ocsp
      >>> ocsp_resp = ocsp.load_der_ocsp_response(der_ocsp_resp_unauth)
      >>> print(ocsp_resp.response_status)
      OCSPResponseStatus.UNAUTHORIZED

## Creating Responses

class cryptography.x509.ocsp.OCSPResponseBuilder

  New in version 2.4.

  This class is used to create `OCSPResponse` objects. You cannot set `produced_at` on OCSP responses at this time. Instead the field is set to current UTC time when calling `sign`. For unsuccessful statuses call the class method `build_unsuccessful()`.

  add_response(cert, issuer, algorithm, cert_status, this_update, next_update, revocation_time, revocation_reason)

    This method adds status information about the certificate that was requested to the response.

    Parameters:

      - cert – The `Certificate` whose validity is being checked.

      - issuer – The issuer `Certificate` of the certificate that is being checked.

      - algorithm – A `HashAlgorithm` instance. For OCSP only `SHA1`, `SHA224`, `SHA256`, `SHA384`, and `SHA512` are allowed.

      - cert_status – An item from the `OCSPCertStatus` enumeration.

      - this_update – A naïve `datetime.datetime` object representing the most recent time in UTC at which the status being indicated is known by the responder to be correct.

      - next_update – A naïve `datetime.datetime` object or `None`. The time in UTC at or before which newer information will be available about the status of the certificate.

      - revocation_time – A naïve `datetime.datetime` object or `None` if the `cert` is not revoked. The time in UTC at which the certificate was revoked.

      - revocation_reason – An item from the `ReasonFlags` enumeration or `None` if the `cert` is not revoked.

  certificates(certs)

    Add additional certificates that should be used to verify the signature on the response. This is typically used when the responder utilizes an OCSP delegate.

    Parameters:

      certs (list) – A list of `Certificate` objects.

  responder_id(encoding, responder_cert)

    Set the `responderID` on the OCSP response. This is the data a client will use to determine what certificate signed the response.

    Parameters:

      - responder_cert – The `Certificate` object for the certificate whose private key will sign the OCSP response. If the certificate and key do not match an error will be raised when calling `sign`.

      - encoding – Either `HASH` or `NAME`.

  add_extension(extval, critical)

    Adds an extension to the response.

    Parameters:

      - extval – An extension conforming to the `ExtensionType` interface.

      - critical – Set to `True` if the extension must be understood and handled.

  sign(private_key, algorithm)

    Creates the OCSP response that can then be serialized and sent to clients. This method will create a `SUCCESSFUL` response.

    Parameters:

      - private_key – The `RSAPrivateKey`, `DSAPrivateKey`, `EllipticCurvePrivateKey`, `Ed25519PrivateKey` or `Ed448PrivateKey` that will be used to sign the response.

      - algorithm – The `HashAlgorithm` that will be used to generate the signature. This must be `None` if the `private_key` is an `Ed25519PrivateKey` or an `Ed448PrivateKey` and an instance of a `HashAlgorithm` otherwise.

    Returns:

      A new `OCSPResponse`.

      >>> import datetime
      >>> from cryptography.hazmat.primitives import hashes, serialization
      >>> from cryptography.x509 import load_pem_x509_certificate, ocsp
      >>> cert = load_pem_x509_certificate(pem_cert)
      >>> issuer = load_pem_x509_certificate(pem_issuer)
      >>> responder_cert = load_pem_x509_certificate(pem_responder_cert)
      >>> responder_key = serialization.load_pem_private_key(pem_responder_key, None)
      >>> builder = ocsp.OCSPResponseBuilder()
      >>> # SHA256 is in this example because while RFC 5019 originally
      >>> # required SHA1 RFC 6960 updates that to SHA256.
      >>> # However, depending on your requirements you may need to use SHA1
      >>> # for compatibility reasons.
      >>> builder = builder.add_response(
      ...     cert=cert, issuer=issuer, algorithm=hashes.SHA256(),
      ...     cert_status=ocsp.OCSPCertStatus.GOOD,
      ...     this_update=datetime.datetime.now(),
      ...     next_update=datetime.datetime.now(),
      ...     revocation_time=None, revocation_reason=None
      ... ).responder_id(
      ...     ocsp.OCSPResponderEncoding.HASH, responder_cert
      ... )
      >>> response = builder.sign(responder_key, hashes.SHA256())
      >>> response.certificate_status
      <OCSPCertStatus.GOOD: 0>

  classmethod build_unsuccessful(response_status)

    Creates an unsigned OCSP response which can then be serialized and sent to clients. `build_unsuccessful` may only be called with a `OCSPResponseStatus` that is not `SUCCESSFUL`. Since this is a class method note that no other methods can or should be called as unsuccessful statuses do not encode additional data.

    Returns:

      A new `OCSPResponse`.

      >>> from cryptography.hazmat.primitives import hashes, serialization
      >>> from cryptography.x509 import load_pem_x509_certificate, ocsp
      >>> response = ocsp.OCSPResponseBuilder.build_unsuccessful(
      ...     ocsp.OCSPResponseStatus.UNAUTHORIZED
      ... )
      >>> response.response_status
      <OCSPResponseStatus.UNAUTHORIZED: 6>

## Interfaces

class cryptography.x509.ocsp.OCSPRequest

  New in version 2.4.

  An `OCSPRequest` is an object containing information about a certificate whose status is being checked.

  issuer_key_hash
    Type:

      bytes

    The hash of the certificate issuer’s key. The hash algorithm used is defined by the `hash_algorithm` property.

  issuer_name_hash
    Type:

      bytes

    The hash of the certificate issuer’s name. The hash algorithm used is defined by the `hash_algorithm` property.

  hash_algorithm
    Type:

      `HashAlgorithm`

    The algorithm used to generate the `issuer_key_hash` and `issuer_name_hash`.

  serial_number
    Type:

      int

    The serial number of the certificate to check.

  extensions
    Type:

      `Extensions`

    The extensions encoded in the request.

  public_bytes(encoding)
    Parameters:

      encoding – The encoding to use. Only `DER` is supported.

    Return bytes:

      The serialized OCSP request.

class cryptography.x509.ocsp.OCSPResponse

  New in version 2.4.

  An `OCSPResponse` is the data provided by an OCSP responder in response to an `OCSPRequest`.

  response_status
    Type:

      `OCSPResponseStatus`

    The status of the response.

  signature_algorithm_oid
    Type:

      `ObjectIdentifier`

    Returns the object identifier of the signature algorithm used to sign the response. This will be one of the OIDs from `SignatureAlgorithmOID`.

    Raises:

      ValueError – If `response_status` is not `SUCCESSFUL`.

  signature_hash_algorithm

    New in version 2.5.

    Type:

      `HashAlgorithm`

    Returns the `HashAlgorithm` which was used in signing this response. Can be `None` if signature did not use separate hash (`ED25519`, `ED448`).

  signature
    Type:

      bytes

    The signature bytes.

    Raises:

      ValueError – If `response_status` is not `SUCCESSFUL`.

  tbs_response_bytes
    Type:

      bytes

    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 `SUCCESSFUL`.

  certificates
    Type:

      list

    A list of zero or more `Certificate` objects 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 `SUCCESSFUL`.

  responder_key_hash
    Type:

      bytes or None

    The responder’s key hash or `None` if the response has a `responder_name`.

    Raises:

      ValueError – If `response_status` is not `SUCCESSFUL`.

  responder_name
    Type:

      `Name` or None

    The responder’s `Name` or `None` if the response has a `responder_key_hash`.

    Raises:

      ValueError – If `response_status` is not `SUCCESSFUL`.

  produced_at
    Type:

      `datetime.datetime`

    A naïve datetime representing the time when the response was produced.

    Raises:

      ValueError – If `response_status` is not `SUCCESSFUL`.

  certificate_status
    Type:

      `OCSPCertStatus`

    The status of the certificate being checked.

    Raises:

      ValueError – If `response_status` is not `SUCCESSFUL` or if multiple SINGLERESPs are present.

  revocation_time
    Type:

      `datetime.datetime` or None

    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 `SUCCESSFUL` or if multiple SINGLERESPs are present.

  revocation_reason
    Type:

      `ReasonFlags` or None

    The reason the certificate was revoked or `None` if not specified or not revoked.

    Raises:

      ValueError – If `response_status` is not `SUCCESSFUL` or if multiple SINGLERESPs are present.

  this_update
    Type:

      `datetime.datetime`

    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 `SUCCESSFUL` or if multiple SINGLERESPs are present.

  next_update
    Type:

      `datetime.datetime`

    A naïve datetime representing the time when newer information will be available.

    Raises:

      ValueError – If `response_status` is not `SUCCESSFUL` or if multiple SINGLERESPs are present.

  issuer_key_hash
    Type:

      bytes

    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 `SUCCESSFUL` or if multiple SINGLERESPs are present.

  issuer_name_hash
    Type:

      bytes

    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 `SUCCESSFUL` or if multiple SINGLERESPs are present.

  hash_algorithm
    Type:

      `HashAlgorithm`

    The algorithm used to generate the `issuer_key_hash` and `issuer_name_hash`.

    Raises:

      ValueError – If `response_status` is not `SUCCESSFUL` or if multiple SINGLERESPs are present.

  serial_number
    Type:

      int

    The serial number of the certificate that was checked.

    Raises:

      ValueError – If `response_status` is not `SUCCESSFUL` or if multiple SINGLERESPs are present.

  extensions
    Type:

      `Extensions`

    The extensions encoded in the response.

  single_extensions

    New in version 2.9.

    Type:

      `Extensions`

    The single extensions encoded in the response.

  responses

    New in version 37.0.0.

    Type:

      an iterator over `OCSPSingleResponse`

    An iterator to access individual SINGLERESP structures.

  public_bytes(encoding)
    Parameters:

      encoding – The encoding to use. Only `DER` is supported.

    Return bytes:

      The serialized OCSP response.

class cryptography.x509.ocsp.OCSPResponseStatus

  New in version 2.4.

  An enumeration of response statuses.

  SUCCESSFUL

    Represents a successful OCSP response.

  MALFORMED_REQUEST

    May be returned by an OCSP responder that is unable to parse a given request.

  INTERNAL_ERROR

    May be returned by an OCSP responder that is currently experiencing operational problems.

  TRY_LATER

    May be returned by an OCSP responder that is overloaded.

  SIG_REQUIRED

    May be returned by an OCSP responder that requires signed OCSP requests.

  UNAUTHORIZED

    May be returned by an OCSP responder when queried for a certificate for which the responder is unaware or an issuer for which the responder is not authoritative.

class cryptography.x509.ocsp.OCSPCertStatus

  New in version 2.4.

  An enumeration of certificate statuses in an OCSP response.

  GOOD

    The value for a certificate that is not revoked.

  REVOKED

    The certificate being checked is revoked.

  UNKNOWN

    The certificate being checked is not known to the OCSP responder.

class cryptography.x509.ocsp.OCSPResponderEncoding

  New in version 2.4.

  An enumeration of `responderID` encodings that can be passed to `responder_id()`.

  HASH

    Encode the hash of the public key whose corresponding private key signed the response.

  NAME

    Encode the X.509 `Name` of the certificate whose private key signed the response.

class cryptography.x509.ocsp.OCSPSingleResponse

  New in version 37.0.0.

  A class representing a single certificate response bundled into a larger OCSPResponse. Accessed via OCSPResponse.responses.

  certificate_status
    Type:

      `OCSPCertStatus`

    The status of the certificate being checked.

  revocation_time
    Type:

      `datetime.datetime` or None

    A naïve datetime representing the time when the certificate was revoked or `None` if the certificate has not been revoked.

  revocation_reason
    Type:

      `ReasonFlags` or None

    The reason the certificate was revoked or `None` if not specified or not revoked.

  this_update
    Type:

      `datetime.datetime`

    A naïve datetime representing the most recent time at which the status being indicated is known by the responder to have been correct.

  next_update
    Type:

      `datetime.datetime`

    A naïve datetime representing the time when newer information will be available.

  issuer_key_hash
    Type:

      bytes

    The hash of the certificate issuer’s key. The hash algorithm used is defined by the `hash_algorithm` property.

  issuer_name_hash
    Type:

      bytes

    The hash of the certificate issuer’s name. The hash algorithm used is defined by the `hash_algorithm` property.

  hash_algorithm
    Type:

      `HashAlgorithm`

    The algorithm used to generate the `issuer_key_hash` and `issuer_name_hash`.

  serial_number
    Type:

      int

    The serial number of the certificate that was checked.