diff options
Diffstat (limited to 'docs/api.rst')
| -rw-r--r-- | docs/api.rst | 56 |
1 files changed, 56 insertions, 0 deletions
diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..f80ea7f --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,56 @@ +=== +API +=== + +.. note:: + + The APIs for RFC 6125 verification beyond DNS-IDs (i.e. hostnames) aren't public yet. + They are in place and used by the documented high-level APIs though. + Eventually they will become public. + If you'd like to play with them and provide feedback have a look at the ``verify_service_identity`` function in the `_common module <https://github.com/pyca/service_identity/blob/master/src/service_identity/_common.py>`_. + + +.. currentmodule:: service_identity.pyopenssl + + +.. autofunction:: verify_hostname(connection, hostname) + + 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() + + +.. currentmodule:: service_identity + +.. autoexception:: VerificationError + +.. autoexception:: CertificateError + +.. autoexception:: SubjectAltNameWarning
\ No newline at end of file |