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 onlySHA1
,SHA224
,SHA256
,SHA384
, andSHA512
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 onlySHA1
,SHA224
,SHA256
,SHA384
, andSHA512
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 setproduced_at
on 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)[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 onlySHA1
,SHA224
,SHA256
,SHA384
, andSHA512
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 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.datetime
object orNone
if thecert
is not revoked. The time in UTC at which the certificate was revoked.revocation_reason – An item from the
ReasonFlags
enumeration orNone
if thecert
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 callingsign
.
- 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
orEd448PrivateKey
that will be used to sign the response.algorithm – The
HashAlgorithm
that will be used to generate the signature. This must beNone
if theprivate_key
is anEd25519PrivateKey
or anEd448PrivateKey
and an instance of aHashAlgorithm
otherwise. Please note thatSHA1
can not be used here, regardless of if it was used foradd_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 aOCSPResponseStatus
that 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.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:
The hash of the certificate issuer’s key. The hash algorithm used is defined by the
hash_algorithm
property.
- issuer_name_hash
- Type:
The hash of the certificate issuer’s name. The hash algorithm used is defined by the
hash_algorithm
property.
- hash_algorithm
- Type:
The algorithm used to generate the
issuer_key_hash
andissuer_name_hash
.
- extensions
- Type:
The extensions encoded in the request.
- class cryptography.x509.ocsp.OCSPResponse
Added in version 2.4.
An
OCSPResponse
is 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_status
is notSUCCESSFUL
.
- signature_hash_algorithm
Added in version 2.5.
- Type:
Returns the
HashAlgorithm
which was used in signing this response. Can beNone
if signature did not use separate hash (ED25519
,ED448
).
- signature
- Type:
The signature bytes.
- Raises:
ValueError – If
response_status
is 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_status
is notSUCCESSFUL
.
- certificates
- Type:
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 notSUCCESSFUL
.
- responder_key_hash
- Type:
bytes or None
The responder’s key hash or
None
if the response has aresponder_name
.- Raises:
ValueError – If
response_status
is notSUCCESSFUL
.
- responder_name
- Type:
Name
or None
The responder’s
Name
orNone
if the response has aresponder_key_hash
.- Raises:
ValueError – If
response_status
is notSUCCESSFUL
.
- produced_at
- Type:
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 notSUCCESSFUL
.
- produced_at_utc
Added in version 43.0.0.
- Type:
A timezone-aware datetime representing the time when the response was produced.
- Raises:
ValueError – If
response_status
is notSUCCESSFUL
.
- certificate_status
- Type:
The status of the certificate being checked.
- Raises:
ValueError – If
response_status
is notSUCCESSFUL
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 notSUCCESSFUL
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 notSUCCESSFUL
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 notSUCCESSFUL
or if multiple SINGLERESPs are present.
- this_update
- Type:
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 notSUCCESSFUL
or if multiple SINGLERESPs are present.
- this_update_utc
Added in version 43.0.0.
- Type:
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 notSUCCESSFUL
or if multiple SINGLERESPs are present.
- next_update
- Type:
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 notSUCCESSFUL
or if multiple SINGLERESPs are present.
- next_update_utc
Added in version 43.0.0.
- Type:
A timezone-aware datetime representing the time when newer information will be available.
- Raises:
ValueError – If
response_status
is notSUCCESSFUL
or if multiple SINGLERESPs are present.
- issuer_key_hash
- Type:
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 notSUCCESSFUL
or if multiple SINGLERESPs are present.
- issuer_name_hash
- Type:
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 notSUCCESSFUL
or if multiple SINGLERESPs are present.
- hash_algorithm
- Type:
The algorithm used to generate the
issuer_key_hash
andissuer_name_hash
.- Raises:
ValueError – If
response_status
is notSUCCESSFUL
or if multiple SINGLERESPs are present.
- serial_number
- Type:
The serial number of the certificate that was checked.
- Raises:
ValueError – If
response_status
is notSUCCESSFUL
or if multiple SINGLERESPs are present.
- extensions
- Type:
The extensions encoded in the response.
- single_extensions
Added in version 2.9.
- Type:
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.
- 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 toresponder_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:
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:
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:
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:
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:
A timezone-aware datetime representing the time when newer information will be available.
- issuer_key_hash
- Type:
The hash of the certificate issuer’s key. The hash algorithm used is defined by the
hash_algorithm
property.
- issuer_name_hash
- Type:
The hash of the certificate issuer’s name. The hash algorithm used is defined by the
hash_algorithm
property.
- hash_algorithm
- Type:
The algorithm used to generate the
issuer_key_hash
andissuer_name_hash
.