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)

Added 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]

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

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

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

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)

Added 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]

Added 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. You can call this method or add_response_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.
cert_status – An item from the OCSPCertStatus enumeration.
this_update – A datetime.datetime object representing the most recent time at which the status being indicated is known by the responder to be correct. If it does not have a timezone, it is assumed to be in UTC.
next_update – A datetime.datetime object or None. The time at or before which newer information will be available about the status of the certificate. If it does not have a timezone, it is assumed to be in UTC.
revocation_time – A datetime.datetime object or None if the cert is not revoked. The time at which the certificate was revoked. If it does not have a timezone, it is assumed to be in UTC.
revocation_reason – An item from the ReasonFlags enumeration or None if the cert is not revoked.

add_response_by_hash(issuer_name_hash, issuer_key_hash, serial_number, algorithm, cert_status, this_update, next_update, revocation_time, revocation_reason)[source]

Added in version 45.0.0.

This method adds status information about the certificate that was requested to the response using the hash values directly, rather than requiring the full certificates. You can call this method or add_response 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.
cert_status – An item from the OCSPCertStatus enumeration.
this_update – A datetime.datetime object representing the most recent time at which the status being indicated is known by the responder to be correct. If it does not have a timezone, it is assumed to be in UTC.
next_update – A datetime.datetime object or None. The time at or before which newer information will be available about the status of the certificate. If it does not have a timezone, it is assumed to be in UTC.
revocation_time – A datetime.datetime object or None if the cert is not revoked. The time at which the certificate was revoked. If it does not have a timezone, it is assumed to be in UTC.
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(extval, critical)[source]

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

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. Please note that SHA1 can not be used here, regardless of if it was used for add_response() or not.

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)[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

Added 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

Added 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

Added 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

Warning

This property is deprecated and will be removed in a future version. Please switch to the timezone-aware variant produced_at_utc().

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

Raises:: ValueError – If response_status is not SUCCESSFUL.

produced_at_utc

Added in version 43.0.0.

Type:: datetime.datetime

A timezone-aware 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

Warning

This property is deprecated and will be removed in a future version. Please switch to the timezone-aware variant revocation_time_utc().

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_time_utc

Added in version 43.0.0.

Type:: datetime.datetime or None

A timezone-aware 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

Warning

This property is deprecated and will be removed in a future version. Please switch to the timezone-aware variant this_update_utc().

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.

this_update_utc

Added in version 43.0.0.

Type:: datetime.datetime

A timezone-aware 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

Warning

This property is deprecated and will be removed in a future version. Please switch to the timezone-aware variant next_update_utc().

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.

next_update_utc

Added in version 43.0.0.

Type:: datetime.datetime

A timezone-aware 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

Added in version 2.9.

Type:: Extensions

The single extensions encoded in the response.

responses

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

Added 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]

Added 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]

Added 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

Added 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

Warning

This property is deprecated and will be removed in a future version. Please switch to the timezone-aware variant revocation_time_utc().

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

revocation_time_utc

Added in version 43.0.0.

Type:: datetime.datetime or None

A timezone-aware 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

Warning

This property is deprecated and will be removed in a future version. Please switch to the timezone-aware variant this_update_utc().

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

this_update_utc

Added in version 43.0.0.

Type:: datetime.datetime

A timezone-aware 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

Warning

This property is deprecated and will be removed in a future version. Please switch to the timezone-aware variant next_update_utc().

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

next_update_utc

Added in version 43.0.0.

Type:: datetime.datetime

A timezone-aware 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.