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
OCSPRequestobjects.-
add_certificate(cert, issuer, algorithm)¶ Adds a request using a certificate, issuer certificate, and hash algorithm. This can only be called once.
- Parameters
cert – The
Certificatewhose validity is being checked.issuer – The issuer
Certificateof the certificate that is being checked.algorithm – A
HashAlgorithminstance. For OCSP onlySHA1,SHA224,SHA256,SHA384, andSHA512are allowed.
-
add_extension(extension, critical)¶ Adds an extension to the request.
- Parameters
extension – An extension conforming to the
ExtensionTypeinterface.critical – Set to
Trueif 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
OCSPResponseobjects. You cannot setproduced_aton OCSP responses at this time. Instead the field is set to current UTC time when callingsign. For unsuccessful statuses call the class methodbuild_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
Certificatewhose validity is being checked.issuer – The issuer
Certificateof the certificate that is being checked.algorithm – A
HashAlgorithminstance. For OCSP onlySHA1,SHA224,SHA256,SHA384, andSHA512are allowed.cert_status – An item from the
OCSPCertStatusenumeration.this_update – A naïve
datetime.datetimeobject 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.datetimeobject orNone. 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.datetimeobject orNoneif thecertis not revoked. The time in UTC at which the certificate was revoked.revocation_reason – An item from the
ReasonFlagsenumeration orNoneif thecertis 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
Certificateobjects.
-
responder_id(encoding, responder_cert)¶ Set the
responderIDon the OCSP response. This is the data a client will use to determine what certificate signed the response.- Parameters
responder_cert – The
Certificateobject 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 callingsign.
-
add_extension(extension, critical)¶ Adds an extension to the response.
- Parameters
extension – An extension conforming to the
ExtensionTypeinterface.critical – Set to
Trueif 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
SUCCESSFULresponse.- Parameters
private_key – The
RSAPrivateKey,DSAPrivateKey,EllipticCurvePrivateKey,Ed25519PrivateKeyorEd448PrivateKeythat will be used to sign the certificate.algorithm – The
HashAlgorithmthat will be used to generate the signature. This must beNoneif theprivate_keyis anEd25519PrivateKeyor anEd448PrivateKeyand an instance of aHashAlgorithmotherwise.
- 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_unsuccessfulmay only be called with aOCSPResponseStatusthat is notSUCCESSFUL. 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
OCSPRequestis an object containing information about a certificate whose status is being checked.-
issuer_key_hash¶ - Type
The hash of the certificate issuer’s key. The hash algorithm used is defined by the
hash_algorithmproperty.
-
issuer_name_hash¶ - Type
The hash of the certificate issuer’s name. The hash algorithm used is defined by the
hash_algorithmproperty.
-
hash_algorithm¶ - Type
The algorithm used to generate the
issuer_key_hashandissuer_name_hash.
-
extensions¶ - Type
The extensions encoded in the request.
-
-
class
cryptography.x509.ocsp.OCSPResponse¶ New in version 2.4.
An
OCSPResponseis the data provided by an OCSP responder in response to anOCSPRequest.-
response_status¶ - Type
The status of the response.
-
signature_algorithm_oid¶ - Type
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_statusis notSUCCESSFUL.
-
signature_hash_algorithm¶ New in version 2.5.
- Type
Returns the
HashAlgorithmwhich was used in signing this response. Can beNoneif signature did not use separate hash (ED25519,ED448).
-
signature¶ - Type
The signature bytes.
- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
tbs_response_bytes¶ - Type
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_statusis notSUCCESSFUL.
-
certificates¶ - Type
A list of zero or more
Certificateobjects 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_statusis notSUCCESSFUL.
-
responder_key_hash¶ -
The responder’s key hash or
Noneif the response has aresponder_name.- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
responder_name¶ - Type
Nameor None
The responder’s
NameorNoneif the response has aresponder_key_hash.- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
produced_at¶ - Type
A naïve datetime representing the time when the response was produced.
- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
certificate_status¶ - Type
The status of the certificate being checked.
- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
revocation_time¶ - Type
datetime.datetimeor None
A naïve datetime representing the time when the certificate was revoked or
Noneif the certificate has not been revoked.- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
revocation_reason¶ - Type
ReasonFlagsor None
The reason the certificate was revoked or
Noneif not specified or not revoked.- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
this_update¶ - Type
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_statusis notSUCCESSFUL.
-
next_update¶ - Type
A naïve datetime representing the time when newer information will be available.
- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
issuer_key_hash¶ - Type
The hash of the certificate issuer’s key. The hash algorithm used is defined by the
hash_algorithmproperty.- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
issuer_name_hash¶ - Type
The hash of the certificate issuer’s name. The hash algorithm used is defined by the
hash_algorithmproperty.- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
hash_algorithm¶ - Type
The algorithm used to generate the
issuer_key_hashandissuer_name_hash.- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
serial_number¶ - Type
The serial number of the certificate that was checked.
- Raises
ValueError – If
response_statusis notSUCCESSFUL.
-
extensions¶ - Type
The extensions encoded in the response.
-
single_extensions¶ New in version 2.9.
- Type
The single extensions encoded in the 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
responderIDencodings that can be passed toresponder_id().-
HASH¶ Encode the hash of the public key whose corresponding private key signed the response.
-
NAME¶ Encode the X.509
Nameof the certificate whose private key signed the response.
-