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: - 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 – The
-
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.
- extension – An extension conforming to the
-
build
()¶ Returns: A new OCSPRequest
.
>>> 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) >>> issuer = load_pem_x509_certificate(pem_issuer) >>> 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 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)¶ 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.
- cert – The
-
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 callingsign
. - encoding – Either
HASH
orNAME
.
- responder_cert – The
-
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.
- extension – An extension conforming to the
-
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
orEd448PrivateKey
that will be used to sign the certificate. - 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.
Returns: A new
OCSPResponse
.- private_key – The
>>> 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() >>> # 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 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
¶ 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
andissuer_name_hash
.
-
extensions
¶ Type: Extensions
The extensions encoded in the request.
-
-
class
cryptography.x509.ocsp.
OCSPResponse
¶ New in version 2.4.
An
OCSPResponse
is the data provided by an OCSP responder in response to anOCSPRequest
.-
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 notSUCCESSFUL
.
-
signature_hash_algorithm
¶ New in version 2.5.
Type: HashAlgorithm
Returns the
HashAlgorithm
which was used in signing this response. Can beNone
if signature did not use separate hash (ED25519
,ED448
).
-
signature
¶ Type: bytes The signature bytes.
Raises: ValueError – If response_status
is notSUCCESSFUL
.
-
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 notSUCCESSFUL
.
-
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 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 NoneThe responder’s
Name
orNone
if the response has aresponder_key_hash
.Raises: ValueError – If response_status
is notSUCCESSFUL
.
-
produced_at
¶ Type: datetime.datetime
A naïve datetime representing the time when the response was produced.
Raises: ValueError – If response_status
is notSUCCESSFUL
.
-
certificate_status
¶ Type: OCSPCertStatus
The status of the certificate being checked.
Raises: ValueError – If response_status
is notSUCCESSFUL
.
-
revocation_time
¶ Type: datetime.datetime
or NoneA 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
.
-
revocation_reason
¶ Type: ReasonFlags
or NoneThe reason the certificate was revoked or
None
if not specified or not revoked.Raises: ValueError – If response_status
is notSUCCESSFUL
.
-
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 notSUCCESSFUL
.
-
next_update
¶ Type: datetime.datetime
A naïve datetime representing the time when newer information will be available.
Raises: ValueError – If response_status
is notSUCCESSFUL
.
-
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 notSUCCESSFUL
.
-
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 notSUCCESSFUL
.
-
hash_algorithm
¶ Type: HashAlgorithm
The algorithm used to generate the
issuer_key_hash
andissuer_name_hash
.Raises: ValueError – If response_status
is notSUCCESSFUL
.
-
serial_number
¶ Type: int The serial number of the certificate that was checked.
Raises: ValueError – If response_status
is notSUCCESSFUL
.
-
extensions
¶ Type: Extensions
The extensions encoded in the response.
-
single_extensions
¶ New in version 2.9.
Type: Extensions
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
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.
-