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)[source]

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[source]

New in version 2.4.

This class is used to create OCSPRequest objects.

add_certificate(cert, issuer, algorithm)[source]

Adds a request using a certificate, issuer certificate, and hash algorithm. This can only be called once.

Parameters:
add_extension(extension, critical)[source]

Adds an extension to the request.

Parameters:
  • extension – An extension conforming to the ExtensionType interface.
  • critical – Set to True if the extension must be understood and handled.
build()[source]
Returns:A new OCSPRequest.
>>> from cryptography.hazmat.primitives import serialization
>>> from cryptography.hazmat.primitives.hashes import SHA1
>>> 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()
>>> # SHA1 is in this example because RFC 5019 mandates its use.
>>> builder = builder.add_certificate(cert, issuer, SHA1())
>>> req = builder.build()
>>> base64.b64encode(req.public_bytes(serialization.Encoding.DER))
b'MEMwQTA/MD0wOzAJBgUrDgMCGgUABBRAC0Z68eay0wmDug1gfn5ZN0gkxAQUw5zz/NNGCDS7zkZ/oHxb8+IIy1kCAj8g'

Loading Responses

cryptography.x509.ocsp.load_der_ocsp_response(data)[source]

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[source]

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)[source]

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)[source]

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)[source]

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(extension, critical)[source]

Adds an extension to the response.

Parameters:
  • extension – An extension conforming to the ExtensionType interface.
  • critical – Set to True if the extension must be understood and handled.
sign(private_key, algorithm)[source]

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

Parameters:
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()
>>> # SHA1 is in this example because RFC 5019 mandates its use.
>>> builder = builder.add_response(
...     cert=cert, issuer=issuer, algorithm=hashes.SHA1(),
...     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)[source]

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[source]

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)[source]
Parameters:encoding – The encoding to use. Only DER is supported.
Return bytes:The serialized OCSP request.
class cryptography.x509.ocsp.OCSPResponse[source]

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.
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.
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.
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.
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.
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.
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.
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.
serial_number
Type:int

The serial number of the certificate that was checked.

Raises:ValueError – If response_status is not SUCCESSFUL.
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.

public_bytes(encoding)
Parameters:encoding – The encoding to use. Only DER is supported.
Return bytes:The serialized OCSP response.
class cryptography.x509.ocsp.OCSPResponseStatus[source]

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[source]

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[source]

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.