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.

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 ( 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>

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

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

Parameters :: encoding – The encoding to use. Only DER is supported.
Return bytes :: The serialized OCSP request.

class cryptography.x509.ocsp. OCSPResponse [source] 

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

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 

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

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

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

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.