API¶
Note
So far, public APIs are only available for hostnames (RFC 6125) and IP addresses (RFC 2818).
All IDs specified by RFC 6125 are already implemented though.
If you’d like to play with them and provide feedback have a look at the verify_service_identity
function in the _common module.
pyOpenSSL¶
-
service_identity.pyopenssl.
verify_hostname
(connection, hostname)¶ Verify whether the certificate of connection is valid for hostname.
Parameters: - connection (OpenSSL.SSL.Connection) – A pyOpenSSL connection object.
- hostname (unicode) – The hostname that connection should be connected to.
Raises: - service_identity.VerificationError – If connection does not provide a certificate that is valid for hostname.
- service_identity.CertificateError – If the certificate chain of connection contains a certificate that contains invalid/unexpected data.
Returns: None
In practice, this may look like the following:
from __future__ import absolute_import, division, print_function import socket from OpenSSL import SSL from service_identity import VerificationError from service_identity.pyopenssl import verify_hostname ctx = SSL.Context(SSL.SSLv23_METHOD) ctx.set_verify(SSL.VERIFY_PEER, lambda conn, cert, errno, depth, ok: ok) ctx.set_default_verify_paths() hostname = u"twistedmatrix.com" conn = SSL.Connection(ctx, socket.socket(socket.AF_INET, socket.SOCK_STREAM)) conn.connect((hostname, 443)) try: conn.do_handshake() verify_hostname(conn, hostname) # Do your super-secure stuff here. except SSL.Error as e: print("TLS Handshake failed: {0!r}.".format(e.args[0])) except VerificationError: print("Presented certificate is not valid for {0}.".format(hostname)) finally: conn.shutdown() conn.close()
-
service_identity.pyopenssl.
verify_ip_address
(connection, ip_address)¶ Verify whether the certificate of connection is valid for ip_address.
Parameters: - connection (OpenSSL.SSL.Connection) – A pyOpenSSL connection object.
- ip_address (unicode) – The IP address that connection should be connected to. Can be an IPv4 or IPv6 address.
Raises: - service_identity.VerificationError – If connection does not provide a certificate that is valid for ip_address.
- service_identity.CertificateError – If the certificate chain of connection contains a certificate that contains invalid/unexpected data.
Returns: None
New in version 18.1.0.
PyCA cryptography¶
-
service_identity.cryptography.
verify_certificate_hostname
(certificate, hostname)¶ Verify whether certificate is valid for hostname.
Note
Nothing is verified about the authority of the certificate; the caller must verify that the certificate chains to an appropriate trust root themselves.
Parameters: - certificate (cryptography.x509.Certificate) – A cryptography X509 certificate object.
- hostname (unicode) – The hostname that certificate should be valid for.
Raises: - service_identity.VerificationError – If certificate is not valid for hostname.
- service_identity.CertificateError – If certificate contains invalid/unexpected data.
Returns: None
-
service_identity.cryptography.
verify_certificate_ip_address
(certificate, ip_address)¶ Verify whether certificate is valid for ip_address.
Note
Nothing is verified about the authority of the certificate; the caller must verify that the certificate chains to an appropriate trust root themselves.
Parameters: - certificate (cryptography.x509.Certificate) – A cryptography X509 certificate object.
- ip_address (unicode) – The IP address that connection should be valid for. Can be an IPv4 or IPv6 address.
Raises: - service_identity.VerificationError – If certificate is not valid for ip_address.
- service_identity.CertificateError – If certificate contains invalid/unexpected data.
Returns: None
New in version 18.1.0.
Universal Errors and Warnings¶
-
exception
service_identity.
VerificationError
(errors)¶ Service identity verification failed.
-
exception
service_identity.
CertificateError
¶ Certificate contains invalid or unexpected data.
-
exception
service_identity.
SubjectAltNameWarning
¶ Server Certificate does not contain a
SubjectAltName
.Hostname matching is performed on the
CommonName
which is deprecated.