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

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

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)

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)

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

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)

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

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

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

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

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.