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. This can only be called once.

Parameters:
add_extension(extension, critical)

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()
Returns:A new OCSPRequest. 
>>> from cryptography.hazmat.backends import default_backend
>>> 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, default_backend())
>>> issuer = load_pem_x509_certificate(pem_issuer, default_backend())
>>> 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)

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

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)

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.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes, serialization
>>> from cryptography.x509 import load_pem_x509_certificate, ocsp
>>> cert = load_pem_x509_certificate(pem_cert, default_backend())
>>> issuer = load_pem_x509_certificate(pem_issuer, default_backend())
>>> responder_cert = load_pem_x509_certificate(pem_responder_cert, default_backend())
>>> responder_key = serialization.load_pem_private_key(pem_responder_key, None, default_backend())
>>> 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)

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.backends import default_backend
>>> 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.
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.

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.