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