`ssl` --- ソケットオブジェクト用の TLS/SSL ラッパー¶

Source code: Lib/ssl.py

このモジュールは、クライアント側とサーバー側の両方のネットワークソケットで Transport Layer Security (「Secure Sockets Layer」としてもよく知られています) による暗号化と接続相手の認証を行う機能を提供します。 OpenSSL ライブラリを使用します。

これは optional module です。お使いの CPython に含まれていない場合は、配布元 (Python を提供した組織や人) のドキュメントを確認してください。配布する側の方はオプションのモジュールの要件を参照してください。

注釈

OS のソケット API を呼び出すため、一部の動作はプラットフォームに依存する場合があります。インストールされている OpenSSL のバージョンによって動作が異なることもあります。例えば TLSv1.3 は OpenSSL バージョン 1.1.1 から利用できます。

警告

セキュリティで考慮すべき点を読まずにこのモジュールを使用しないでください。 ssl モジュールのデフォルト設定がアプリケーションに適しているとは限らないため、読まずに使うと安全だと思い込んでしまうおそれがあります。

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは、WebAssembly プラットフォームを見てください。

このセクションでは、 ssl モジュールのオブジェクトと関数を解説します。 TLS, SSL, 証明書に関するより一般的な情報は、末尾にある "See Also" のセクションを参照してください。

このモジュールは socket.socket 型の派生クラス ssl.SSLSocket を提供します。これはソケットのように使えるラッパーで、ソケットを流れるデータの暗号化と復号も SSL で行います。接続相手の証明書を取得する getpeercert()、安全な接続で使っている暗号方式を取得する cipher()、証明書チェインを取得する get_verified_chain() や get_unverified_chain() などの追加メソッドに対応しています。

より洗練されたアプリケーションのために、 ssl.SSLContext クラスが設定と証明書の管理の助けとなるでしょう。それは SSLContext.wrap_socket() メソッドを通して SSL ソケットを作成することで引き継がれます。

バージョン 3.5.3 で変更: OpenSSL 1.1.0 とのリンクに対応しました。

バージョン 3.6 で変更: OpenSSL 0.9.8, 1.0.0, 1.0.1 は廃止されており、もはやサポートされていません。ssl モジュールは、将来的に OpenSSL 1.0.2 または 1.1.0 を必要とするようになります。

バージョン 3.10 で変更: PEP 644 が実装されました。 ssl モジュールは OpenSSL 1.1.1 以降を必要とします。

非推奨の定数や関数を使うと、非推奨の警告が出るようになりました。

関数、定数、例外¶

ソケットの作成¶

SSLSocket のインスタンスは SSLContext.wrap_socket() メソッドで作成しなければなりません。ヘルパー関数 create_default_context() は、安全なデフォルト設定を持つ新しいコンテキストを返します。

デフォルトのコンテキストと IPv4/IPv6 デュアルスタックを使うクライアントソケットの例です。

import socket
import ssl

hostname = 'www.python.org'
context = ssl.create_default_context()

with socket.create_connection((hostname, 443)) as sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())

独自のコンテキストと IPv4 を使うクライアントソケットの例です。

hostname = 'www.python.org'
# PROTOCOL_TLS_CLIENT は有効な証明書チェインとホスト名を必要とする
context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.load_verify_locations('path/to/cabundle.pem')

with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())

ローカルホストの IPv4 で接続を待ち受けるサーバーソケットの例です。

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.load_cert_chain('/path/to/certchain.pem', '/path/to/private.key')

with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
    sock.bind(('127.0.0.1', 8443))
    sock.listen(5)
    with context.wrap_socket(sock, server_side=True) as ssock:
        conn, addr = ssock.accept()
        ...

コンテキストの作成¶

コンビニエンス関数が、共通の目的で使用される SSLContext オブジェクトを作成するのに役立ちます。

ssl.create_default_context(purpose=Purpose.SERVER_AUTH, *, cafile=None, capath=None, cadata=None)¶

指定された purpose に合うデフォルト設定を持つ、新しい SSLContext オブジェクトを返します。設定は ssl モジュールが選び、通常は SSLContext のコンストラクターを直接呼び出す場合よりも高いセキュリティ水準になります。

cafile, capath, cadata は証明書の検証で信用するオプションの CA 証明書で、 SSLContext.load_verify_locations() のものと同じです。これら 3 つすべてが None であれば、この関数は代わりにシステムのデフォルトの CA 証明書を信用して選択することができます。

設定には PROTOCOL_TLS_CLIENT または PROTOCOL_TLS_SERVER、OP_NO_SSLv2、OP_NO_SSLv3 を使い、RC4 と認証を行わない暗号スイートを除いた、強度の高い暗号スイートを選びます。 purpose に SERVER_AUTH を渡すと、verify_mode を CERT_REQUIRED に設定します。さらに、cafile、capath、cadata のいずれかが指定されていればその CA 証明書を読み込み、指定されていなければ SSLContext.load_default_certs() でデフォルトの CA 証明書を読み込みます。

keylog_filename に対応していて環境変数 SSLKEYLOGFILE が設定されている場合、create_default_context() は鍵のログ記録を有効にします。

このコンテキストのデフォルト設定には VERIFY_X509_PARTIAL_CHAIN と VERIFY_X509_STRICT が含まれます。これにより、基盤となる OpenSSL 実装の動作が RFC 5280 により準拠するようになりますが、古い X.509 証明書との互換性がわずかに失われます。

注釈

プロトコル、オプション、暗号方式その他の設定は、事前に非推奨の状態にすることなく、もっと制限の強い値に変更される場合があります。これらの値は、互換性と安全性との妥当なバランスをとって決められます。

もしもあなたのアプリケーションが特定の設定を必要とする場合、 SSLContext を作って自分自身で設定を適用すべきです。

注釈

ある種の古いクライアントやサーバが接続しようと試みてきた場合に、この関数で作られた SSLContext が "Protocol or cipher suite mismatch" で始まるエラーを起こすのを目撃したらそれは、この関数が OP_NO_SSLv3 を使って除外している SSL 3.0 しかサポートしていないのでしょう。SSL 3.0 は完璧にぶっ壊れていることが広く知られています。それでもまだこの関数を使って、ただし SSL 3.0 接続を許可したいと望むならば、これをこのように再有効化できます:

ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
ctx.options &= ~ssl.OP_NO_SSLv3

注釈

このコンテキストはデフォルトで VERIFY_X509_STRICT を有効にするため、無効にしていれば OpenSSL が受け入れる RFC 5280 より前の証明書や不正な形式の証明書を拒否する場合があります。無効にすることは推奨しませんが、次のようにすれば無効にできます。

ctx = ssl.create_default_context()
ctx.verify_flags &= ~ssl.VERIFY_X509_STRICT

Added in version 3.4.

バージョン 3.4.4 で変更: デフォルトの暗号設定から RC4 が除かれました。

バージョン 3.6 で変更: デフォルトの暗号化文字列に ChaCha20/Poly1305 が追加されました。

デフォルトの暗号化文字列から 3DES が除かれました。

バージョン 3.8 で変更: SSLKEYLOGFILE への鍵のログ記録に対応しました。

バージョン 3.10 で変更: このコンテキストは、汎用の PROTOCOL_TLS の代わりに PROTOCOL_TLS_CLIENT または PROTOCOL_TLS_SERVER プロトコルを使うようになりました。

バージョン 3.13 で変更: このコンテキストのデフォルトの検証フラグに VERIFY_X509_PARTIAL_CHAIN と VERIFY_X509_STRICT が含まれるようになりました。

署名アルゴリズム¶

ssl.get_sigalgs()¶

Return a list of available TLS signature algorithm names used by servers to complete the TLS handshake or clients requesting certificate-based authentication. For example:

>>> ssl.get_sigalgs()
['ecdsa_secp256r1_sha256', 'ecdsa_secp384r1_sha384', ...]

これらの名前は、SSLContext.set_client_sigalgs() メソッドや SSLContext.set_server_sigalgs() メソッドに渡す文字列を組み立てる際に使えます。

Added in version 3.15.

例外¶

exception ssl.SSLError¶

(現在のところ OpenSSL ライブラリによって提供されている)下層の SSL 実装からのエラーを伝えるための例外です。このエラーは、低レベルなネットワークの上に載っている、高レベルな暗号化と認証レイヤーでの問題を通知します。このエラーは OSError のサブタイプです。 SSLError インスタンスのエラーコードとメッセージは OpenSSL ライブラリによるものです。

バージョン 3.3 で変更: SSLError は以前は socket.error のサブタイプでした。

library¶: エラーが起こった OpenSSL サブモジュールを示すニーモニック文字列で、 SSL, PEM, X509 などです。取り得る値は OpenSSL のバージョンに依存します。

Added in version 3.3.

reason¶: エラーが起こった原因を示すニーモニック文字列で、 CERTIFICATE_VERIFY_FAILED などです。取り得る値は OpenSSL のバージョンに依存します。

Added in version 3.3.

exception ssl.SSLZeroReturnError¶: SSL 接続が正常に閉じられた後に読み書きを試みたときに送出される SSLError のサブクラスです。これは、基盤となるトランスポート (つまり TCP) が閉じられたことを意味するわけではありません。

Added in version 3.3.

exception ssl.SSLWantReadError¶: 読み出しあるいは書き込みを試みようとした際に、リクエストが遂行される前に下層の TCP 転送で受け取る必要があるデータが不足した場合に non-blocking SSL socket によって送出される SSLError サブクラス例外です。

Added in version 3.3.

exception ssl.SSLWantWriteError¶: 読み出しや書き込みを試みた際に、リクエストを完了するために下層の TCP 転送でさらにデータを送信する必要がある場合に、non-blocking SSL socket が送出する SSLError のサブクラスです。

Added in version 3.3.

exception ssl.SSLSyscallError¶: SSL ソケット上で操作を遂行しようとしていてシステムエラーが起こった場合に送出される SSLError サブクラス例外です。残念ながら元となった errno 番号を調べる簡単な方法はありません。

Added in version 3.3.

exception ssl.SSLEOFError¶: SSL コネクションが唐突に打ち切られた際に送出される SSLError サブクラス例外です。一般的に、このエラーが起こったら下層の転送を再利用しようと試みるべきではありません。

Added in version 3.3.

exception ssl.SSLCertVerificationError¶

証明書の検証に失敗したときに送出される SSLError のサブクラスです。

Added in version 3.7.

verify_code¶: 検証エラーを表す数値のエラー番号。

verify_message¶: 検証エラーを人が読める形で表した文字列。

exception ssl.CertificateError¶: SSLCertVerificationError の別名です。

バージョン 3.7 で変更: 例外は SSLCertVerificationError の別名になりました。

乱数生成¶

ssl.RAND_bytes(num, /)¶

暗号学的に強固な擬似乱数の num バイトを返します。擬似乱数生成器に十分なデータでシードが与えられていない場合や、現在の RAND メソッドに操作がサポートされていない場合は SSLError を送出します。 RAND_status() を使って擬似乱数生成器の状態をチェックできます。 RAND_add() を使って擬似乱数生成器にシードを与えることができます。

ほとんどすべてのアプリケーションでは os.urandom() が望ましいです。

暗号論的に強い擬似乱数生成器に要求されることについては Wikipedia の記事 Cryptographically secure pseudorandom number generator (CSPRNG) (日本語版: 暗号論的擬似乱数生成器) を参照してください。

Added in version 3.3.

ssl.RAND_status()¶: SSL の擬似乱数生成器に「十分な」ランダム性のあるシードが与えられていれば True、そうでなければ False を返します。擬似乱数生成器のランダム性を増やすには ssl.RAND_add() を使ってください。

ssl.RAND_add(bytes, entropy, /)¶: 指定された bytes を SSL の擬似乱数生成器に混ぜ込みます。 entropy 引数 (浮動小数点数) は、この文字列に含まれるエントロピーの下限です (そのため常に 0.0 を使うこともできます)。エントロピー源の詳細は RFC 1750 を参照してください。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

証明書の取り扱い¶

ssl.cert_time_to_seconds(cert_time)¶

証明書の "notBefore" または "notAfter" の日付を、strptime の書式 "%b %d %H:%M:%S %Y %Z" (C ロケール) で表した文字列 cert_time を受け取り、エポックからの経過秒数を返します。

例です。 :

>>> import ssl
>>> import datetime as dt
>>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
>>> timestamp
1515144883
>>> print(dt.datetime.fromtimestamp(timestamp, dt.UTC))
2018-01-05 09:34:43+00:00

"notBefore" や "notAfter" の日付には GMT を使わなければなりません(RFC 5280)。

バージョン 3.5 で変更: 入力文字列の 'GMT' タイムゾーン指定に従い、入力時刻を UTC として解釈するようになりました。以前はローカルタイムゾーンで解釈していました。整数を返します (入力形式には秒の小数部分がありません)。

ssl.get_server_certificate(addr, ssl_version=PROTOCOL_TLS_CLIENT, ca_certs=None[, timeout])¶: SSL で保護されたサーバーのアドレス addr を (hostname、port-number) の対で受け取り、サーバーの証明書を取得して PEM エンコードされた文字列で返します。 ssl_version を指定すると、そのバージョンの SSL プロトコルでサーバーへの接続を試みます。 ca_certs を指定する場合は、SSLContext.load_verify_locations() の cafile 引数と同じ形式で、ルート証明書のリストを含むファイルを指定してください。この関数はそのルート証明書群でサーバー証明書の検証を試み、検証に失敗すると呼び出しも失敗します。 timeout 引数でタイムアウトを指定できます。

バージョン 3.3 で変更: この関数はIPv6互換になりました。

バージョン 3.5 で変更: ssl_version のデフォルトが、最近のサーバへの最大限の互換性のために PROTOCOL_SSLv3 から PROTOCOL_TLS に変更されました。

バージョン 3.10 で変更: timeout 引数が追加されました。

ssl.DER_cert_to_PEM_cert(der_cert_bytes)¶: DERエンコードされたバイト列として与えられた証明書から、 PEMエンコードされたバージョンの同じ証明書を返します。

ssl.PEM_cert_to_DER_cert(pem_cert_string)¶: PEM 形式のASCII文字列として与えられた証明書から、同じ証明書をDERエンコードしたバイト列を返します。

ssl.get_default_verify_paths()¶

OpenSSL デフォルトの cafile, capath を指すパスを名前付きタプルで返します。パスは SSLContext.set_default_verify_paths() で使われるものと同じです。戻り値は named tuple DefaultVerifyPaths です:

cafile - cafile の解決済みパス、またはファイルが存在しない場合は None
capath - capath の解決済みパス、またはディレクトリが存在しない場合は None
openssl_cafile_env - cafile を指す OpenSSL の環境変数名
openssl_cafile - OpenSSL にハードコードされた cafile のパス
openssl_capath_env - capath を指す OpenSSL の環境変数名
openssl_capath - OpenSSL にハードコードされた capath のパス

Added in version 3.4.

ssl.enum_certificates(store_name)¶

Windows のシステム証明書ストアより証明書を抽出します。 store_name は CA, ROOT, MY のうちどれか一つでしょう。Windows は追加の証明書ストアを提供しているかもしれません。

この関数はタプル (cert_bytes, encoding_type, trust) のリストで返します。encoding_type は cert_bytes のエンコーディングを表します。X.509 ASN.1 に対する x509_asn か PKCS#7 ASN.1 データに対する pkcs_7_asn のいずれかです。trust は、証明書の目的を、OIDS を内容に持つ set として表すか、または証明書がすべての目的で信頼できるならば True です。

以下はプログラム例です:

>>> ssl.enum_certificates("CA")
[(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
 (b'data...', 'x509_asn', True)]

利用可能な環境: Windows.

Added in version 3.4.

ssl.enum_crls(store_name)¶

Windows のシステム証明書ストアより CRLs を抽出します。 store_name は CA, ROOT, MY のうちどれか一つでしょう。Windows は追加の証明書ストアを提供しているかもしれません。

この関数はタプル (cert_bytes, encoding_type, trust) のリストで返します。encoding_type は cert_bytes のエンコーディングを表します。X.509 ASN.1 に対する x509_asn か PKCS#7 ASN.1 データに対する pkcs_7_asn のいずれかです。

利用可能な環境: Windows.

Added in version 3.4.

定数¶

すべての定数が enum.IntEnum コレクションまたは enum.IntFlag コレクションになりました。

Added in version 3.6.

ssl.CERT_NONE¶

SSLContext.verify_mode に指定できる値です。 PROTOCOL_TLS_CLIENT を除き、これがデフォルトのモードです。クライアント側のソケットでは、ほぼどのような証明書でも受け入れます。信頼されていない証明書や期限切れの証明書などの検証エラーは無視され、TLS/SSL ハンドシェイクを中断しません。

サーバーモードではクライアントに証明書を要求しないため、クライアントはクライアント証明書認証用の証明書を送りません。

このドキュメントの下の方の、セキュリティで考慮すべき点に関する議論を参照してください。

ssl.CERT_OPTIONAL¶

SSLContext.verify_mode に指定できる値です。クライアントモードでは CERT_OPTIONAL は CERT_REQUIRED と同じ意味になります。クライアント側のソケットでは、代わりに CERT_REQUIRED を使うことをお勧めします。

サーバーモードでは、クライアントに証明書を要求します。クライアントは要求を無視することも、TLS のクライアント証明書認証を行うために証明書を送ることもできます。クライアントが証明書を送った場合は検証し、検証エラーがあれば直ちに TLS ハンドシェイクを中断します。

この設定を使うには、有効な CA 証明書の組を SSLContext.load_verify_locations() に渡す必要があります。

ssl.CERT_REQUIRED¶

SSLContext.verify_mode に指定できる値です。このモードではソケットの接続相手の証明書を必須とし、証明書が提供されない場合や検証に失敗した場合は SSLError を送出します。ただしホスト名を照合しないため、クライアントモードの証明書検証にはこの設定だけでは 不十分 です。証明書が本物であることを検証するには check_hostname も有効にしなければなりません。 PROTOCOL_TLS_CLIENT はデフォルトで CERT_REQUIRED を使い、check_hostname を有効にします。

サーバーソケットでは、このモードで TLS のクライアント証明書認証を必須にします。クライアントに証明書を要求し、クライアントは有効で信頼できる証明書を提供しなければなりません。

この設定を使うには、有効な CA 証明書の組を SSLContext.load_verify_locations() に渡す必要があります。

class ssl.VerifyMode¶: CERT_* 定数の enum.IntEnum コレクションです。

Added in version 3.6.

ssl.VERIFY_DEFAULT¶: SSLContext.verify_flags に渡せる値です。このモードでは、証明書失効リスト(CRLs)はチェックされません。デフォルトでは OpenSSL は CRLs を必要ともしませんし検証にも使いません。

Added in version 3.4.

ssl.VERIFY_CRL_CHECK_LEAF¶: SSLContext.verify_flags に指定できる値です。このモードでは接続先の証明書だけを検証し、中間 CA 証明書は検証しません。接続先証明書の発行者 (その証明書の直接の上位 CA) が署名した有効な CRL が必要です。 SSLContext.load_verify_locations で適切な CRL をロードしていない場合、検証に失敗します。

Added in version 3.4.

ssl.VERIFY_CRL_CHECK_CHAIN¶: SSLContext.verify_flags に渡せる値です。このモードでは、接続先の証明書チェイン内のすべての証明書についての CRLs がチェックされます。

Added in version 3.4.

ssl.VERIFY_X509_STRICT¶: SSLContext.verify_flags に渡せる値で、壊れた X.509 証明書に対するワークアラウンドを無効にします。

Added in version 3.4.

ssl.VERIFY_ALLOW_PROXY_CERTS¶: プロキシ証明書の検証を有効にする、SSLContext.verify_flags に指定できる値です。

Added in version 3.10.

ssl.VERIFY_X509_TRUSTED_FIRST¶: SSLContext.verify_flags に渡せる値です。OpenSSL に対し、証明書検証のために信頼チェインを構築する際、信頼できる証明書を選ぶように指示します。これはデフォルトで有効にされています。

Added in version 3.4.4.

ssl.VERIFY_X509_PARTIAL_CHAIN¶: SSLContext.verify_flags に指定できる値です。 OpenSSL に対し、信頼ストア内の中間 CA を、自己署名されたルート CA 証明書と同様に信頼の起点として扱うよう指示します。これにより、上位のルート CA を信頼せずに、中間 CA が発行した証明書を信頼できます。

Added in version 3.10.

class ssl.VerifyFlags¶: VERIFY_* 定数の enum.IntFlag コレクションです。

Added in version 3.6.

ssl.PROTOCOL_TLS¶: クライアントとサーバの両方がサポートするプロトコルバージョンのうち、最も大きなものを選択します。名前に反して、このオプションは "SSL" と "TLS" プロトコルのいずれも選択できます。

Added in version 3.6.

バージョン 3.10 で非推奨: 安全に通信するためには、TLS クライアントとサーバーでは異なるデフォルト設定が必要です。汎用の TLS プロトコル定数は非推奨となり、代わりに PROTOCOL_TLS_CLIENT と PROTOCOL_TLS_SERVER を使います。

ssl.PROTOCOL_TLS_CLIENT¶: クライアントとサーバーが共に対応する最も新しいプロトコルバージョンを自動的にネゴシエートし、コンテキストをクライアント側の接続用に設定します。このプロトコルはデフォルトで CERT_REQUIRED と check_hostname を有効にします。

Added in version 3.6.

ssl.PROTOCOL_TLS_SERVER¶: クライアントとサーバーが共に対応する最も新しいプロトコルバージョンを自動的にネゴシエートし、コンテキストをサーバー側の接続用に設定します。

Added in version 3.6.

ssl.PROTOCOL_SSLv23¶: PROTOCOL_TLS のエイリアスです。

バージョン 3.6 で非推奨: 代わりに PROTOCOL_TLS を使用してください。

ssl.PROTOCOL_SSLv3¶

チャンネル暗号化プロトコルとしてSSLバージョン3を選択します。

このプロトコルは、 OpenSSL が no-ssl3 オプションをつけてコンパイルされている場合には利用できません。

警告

SSL version 3 は非セキュアです。このプロトコルは強く非推奨です。

バージョン 3.6 で非推奨: OpenSSL はバージョン固有のプロトコルをすべて非推奨にしています。代わりにデフォルトのプロトコル PROTOCOL_TLS_SERVER または PROTOCOL_TLS_CLIENT と、SSLContext.minimum_version、SSLContext.maximum_version を使ってください。

ssl.PROTOCOL_TLSv1¶: チャンネル暗号化プロトコルとしてTLSバージョン1.0を選択します。

バージョン 3.6 で非推奨: OpenSSL はバージョン固有のプロトコルをすべて非推奨にしています。

ssl.PROTOCOL_TLSv1_1¶: チャンネル暗号化プロトコルとしてTLSバージョン1.1を選択します。 openssl version 1.0.1+ のみで利用可能です。

Added in version 3.4.

バージョン 3.6 で非推奨: OpenSSL はバージョン固有のプロトコルをすべて非推奨にしています。

ssl.PROTOCOL_TLSv1_2¶: チャンネル暗号化プロトコルとしてTLSバージョン 1.2 を選択します。 openssl version 1.0.1+ のみで利用可能です。

Added in version 3.4.

バージョン 3.6 で非推奨: OpenSSL はバージョン固有のプロトコルをすべて非推奨にしています。

ssl.OP_ALL¶: 相手にする SSL 実装のさまざまなバグを回避するためのワークアラウンドを有効にします。このオプションはデフォルトで有効です。 OpenSSL の SSL_OP_ALL 定数と同じフラグを設定するとは限りません。

Added in version 3.2.

ssl.OP_NO_SSLv2¶: SSLv2 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして SSLv2 を選択しないようにします。

Added in version 3.2.

バージョン 3.6 で非推奨: SSLv2 は非推奨です

ssl.OP_NO_SSLv3¶: SSLv3 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして SSLv3 を選択しないようにします。

Added in version 3.2.

バージョン 3.6 で非推奨: SSLv3 は非推奨です

ssl.OP_NO_TLSv1¶: TLSv1 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして TLSv1 を選択しないようにします。

Added in version 3.2.

バージョン 3.7 で非推奨: このオプションは OpenSSL 1.1.0 から非推奨です。代わりに新しい SSLContext.minimum_version と SSLContext.maximum_version を使ってください。

ssl.OP_NO_TLSv1_1¶: TLSv1.1 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして TLSv1.1 を選択しないようにします。openssl バージョン 1.0.1 以降でのみ利用できます。

Added in version 3.4.

バージョン 3.7 で非推奨: このオプションは OpenSSL 1.1.0 から非推奨です。

ssl.OP_NO_TLSv1_2¶: TLSv1.2 接続が行われないようにします。このオプションは PROTOCOL_TLS と組み合わされている場合にのみ適用されます。ピアがプロトコルバージョンとして TLSv1.2 を選択しないようにします。openssl バージョン 1.0.1 以降でのみ利用できます。

Added in version 3.4.

バージョン 3.7 で非推奨: このオプションは OpenSSL 1.1.0 から非推奨です。

ssl.OP_NO_TLSv1_3¶: TLSv1.3 接続を禁止します。このオプションは PROTOCOL_TLS と組み合わせた場合にのみ適用され、接続する双方がプロトコルバージョンとして TLSv1.3 を選ばないようにします。 TLS 1.3 は OpenSSL 1.1.1 以降で利用できます。それより古い OpenSSL に対して Python をコンパイルした場合、このフラグのデフォルトは 0 です。

Added in version 3.6.3.

バージョン 3.7 で非推奨: このオプションは OpenSSL 1.1.0 から非推奨です。 OpenSSL 1.0.2 との後方互換性のため、2.7.15 と 3.6.3 に追加されました。

ssl.OP_NO_RENEGOTIATION¶

TLSv1.2 以前で、すべての再ネゴシエーションを無効にします。 HelloRequest メッセージを送信せず、ClientHello による再ネゴシエーション要求を無視します。

このオプションは OpenSSL 1.1.0h 以降のみで使用できます。

Added in version 3.7.

ssl.OP_CIPHER_SERVER_PREFERENCE¶: 暗号の優先順位として、クライアントのものではなくサーバのものを使います。このオプションはクライアントソケットと SSLv2 のサーバソケットでは効果はありません。

Added in version 3.3.

ssl.OP_SINGLE_DH_USE¶: 異なる SSL セッションで同じ DH 鍵を再利用しないようにします。前方秘匿性が高まりますが、より多くの計算リソースが必要になります。このオプションはサーバーソケットにのみ適用されます。

Added in version 3.3.

ssl.OP_SINGLE_ECDH_USE¶: 異なる SSL セッションで同じ ECDH 鍵を再利用しないようにします。前方秘匿性が高まりますが、より多くの計算リソースが必要になります。このオプションはサーバーソケットにのみ適用されます。

Added in version 3.3.

ssl.OP_ENABLE_MIDDLEBOX_COMPAT¶

TLS 1.3 ハンドシェイクでダミーの Change Cipher Spec (CCS) メッセージを送り、TLS 1.3 接続を TLS 1.2 接続に近く見せます。

このオプションは OpenSSL 1.1.1 以降のみで使用できます。

Added in version 3.8.

ssl.OP_NO_COMPRESSION¶: SSL チャネルでの圧縮を無効にします。これはアプリケーションのプロトコルが自身の圧縮方法をサポートする場合に有用です。

Added in version 3.3.

class ssl.Options¶: OP_* 定数の enum.IntFlag コレクションです。

ssl.OP_NO_TICKET¶: クライアントサイドがセッションチケットをリクエストしないようにします。

Added in version 3.6.

ssl.OP_IGNORE_UNEXPECTED_EOF¶

TLS 接続の予期しない切断を無視します。

このオプションは OpenSSL 3.0.0以降のみで使用できます。

Added in version 3.10.

ssl.OP_ENABLE_KTLS¶

カーネル TLS を有効にします。この機能を利用するには、OpenSSL がこの機能を有効にしてコンパイルされている必要があります。また、カーネル TLS が、ネゴシエートされた暗号スイートと拡張機能をサポートしていなければなりません (対応するものはプラットフォームやカーネルのバージョンによって異なります)。

カーネル TLS を有効にすると、一部の暗号操作は利用可能な OpenSSL プロバイダーを経由せず、カーネルが直接行います。例えばアプリケーションがすべての暗号操作に FIPS プロバイダーを使うことを要求する場合、これは望ましくない可能性があります。

このオプションは OpenSSL 3.0.0以降のみで使用できます。

Added in version 3.12.

ssl.OP_LEGACY_SERVER_CONNECT¶: OpenSSL と未修正のサーバーとの間に限り、従来の安全でない再ネゴシエーションを許可します。

Added in version 3.12.

ssl.HAS_ALPN¶: OpenSSL ライブラリが、組み込みで RFC 7301 で記述されている Application-Layer Protocol Negotiation TLS 拡張をサポートしているかどうか。

Added in version 3.5.

ssl.HAS_NEVER_CHECK_COMMON_NAME¶: OpenSSL ライブラリがサブジェクトの共通名を検査しない機能を組み込みで提供し、SSLContext.hostname_checks_common_name が書き込み可能かどうか。

Added in version 3.7.

ssl.HAS_ECDH¶: OpenSSL ライブラリが、組み込みの楕円曲線ディフィー・ヘルマン鍵共有をサポートしているかどうか。これは、ディストリビュータが明示的に無効にしていない限りは、真であるはずです。

Added in version 3.3.

ssl.HAS_SNI¶: OpenSSL ライブラリが、組み込みで (RFC 6066 で記述されている) Server Name Indication 拡張をサポートしているかどうか。

Added in version 3.2.

ssl.HAS_NPN¶: OpenSSL ライブラリが、組み込みで、Application Layer Protocol Negotiation で記述されている Next Protocol Negotiation をサポートしているかどうか。 true であれば、サポートしたいプロトコルを SSLContext.set_npn_protocols() メソッドで提示することができます。

Added in version 3.3.

ssl.HAS_SSLv2¶: OpenSSL ライブラリが、組み込みで SSL 2.0 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.HAS_SSLv3¶: OpenSSL ライブラリが、組み込みで SSL 3.0 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.HAS_TLSv1¶: OpenSSL ライブラリが、組み込みで TLS 1.0 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.HAS_TLSv1_1¶: OpenSSL ライブラリが、組み込みで TLS 1.1 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.HAS_TLSv1_2¶: OpenSSL ライブラリが、組み込みで TLS 1.2 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.HAS_TLSv1_3¶: OpenSSL ライブラリが、組み込みで TLS 1.3 プロトコルをサポートしているかどうか。

Added in version 3.7.

ssl.HAS_PSK¶: OpenSSL ライブラリが TLS-PSK を組み込みでサポートしているかどうか。

Added in version 3.13.

ssl.HAS_PSK_TLS13¶: OpenSSL ライブラリが RFC 9258 に記述された TLS 1.3 の外部 PSK を組み込みでサポートしているかどうか。

Added in version 3.15.

ssl.HAS_PHA¶: OpenSSL ライブラリが TLS-PHA を組み込みでサポートしているかどうか。

Added in version 3.14.

ssl.CHANNEL_BINDING_TYPES¶: サポートされている TLS のチャネルバインディングのタイプのリスト。リスト内の文字列は SSLSocket.get_channel_binding() の引数に渡せます。

Added in version 3.3.

ssl.OPENSSL_VERSION¶

インタプリタによってロードされた OpenSSL ライブラリのバージョン文字列:

>>> ssl.OPENSSL_VERSION
'OpenSSL 1.0.2k  26 Jan 2017'

Added in version 3.2.

ssl.OPENSSL_VERSION_INFO¶

OpenSSL ライブラリのバージョン情報を表す5つの整数のタプル:

>>> ssl.OPENSSL_VERSION_INFO
(1, 0, 2, 11, 15)

Added in version 3.2.

ssl.OPENSSL_VERSION_NUMBER¶

1つの整数の形式の、 OpenSSL ライブラリの生のバージョン番号:

>>> ssl.OPENSSL_VERSION_NUMBER
268443839
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x100020bf'

Added in version 3.2.

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE¶

ssl.ALERT_DESCRIPTION_INTERNAL_ERROR¶

ALERT_DESCRIPTION_*

RFC 5246 その他からのアラートの種類です。 IANA TLS Alert Registry にはこのリストとその意味が定義された RFC へのリファレンスが含まれています。

SSLContext.set_servername_callback() でのコールバック関数の戻り値として使われます。

Added in version 3.4.

class ssl.AlertDescription¶: ALERT_DESCRIPTION_* 定数の enum.IntEnum コレクションです。

Added in version 3.6.

Purpose.SERVER_AUTH¶: create_default_context() と SSLContext.load_default_certs() に渡すオプションです。この値はコンテキストが web サーバの認証に使われることを示します (ですので、クライアントサイドのソケットを作るのに使うことになるでしょう)。

Added in version 3.4.

Purpose.CLIENT_AUTH¶: create_default_context() と SSLContext.load_default_certs() に渡すオプションです。この値はコンテキストが web クライアントの認証に使われることを示します (ですので、サーバサイドのソケットを作るのに使うことになるでしょう)。

Added in version 3.4.

class ssl.SSLErrorNumber¶: SSL_ERROR_* 定数の enum.IntEnum コレクションです。

Added in version 3.6.

class ssl.TLSVersion¶: SSLContext.maximum_version と SSLContext.minimum_version で使う SSL/TLS バージョンの enum.IntEnum コレクションです。

Added in version 3.7.

TLSVersion.MINIMUM_SUPPORTED¶

TLSVersion.MAXIMUM_SUPPORTED¶: サポートされる最小または最大の SSL/TLS バージョンです。これらは特別な意味を持つ定数であり、その値自体は利用可能な最小・最大の TLS/SSL バージョンを表していません。

TLSVersion.SSLv3¶

TLSVersion.TLSv1¶

TLSVersion.TLSv1_1¶

TLSVersion.TLSv1_2¶

TLSVersion.TLSv1_3¶: SSL 3.0 から TLS 1.3。

バージョン 3.10 で非推奨: TLSVersion.TLSv1_2 と TLSVersion.TLSv1_3 を除く、すべての TLSVersion メンバーは非推奨です。

SSL ソケット¶

class ssl.SSLSocket(socket.socket)¶

SSL ソケットは socket オブジェクトの以下のメソッドを提供します:

accept()
bind()
close()
connect()
detach()
fileno()
getpeername(), getsockname()
getsockopt(), setsockopt()
gettimeout(), settimeout(), setblocking()
listen()
makefile()
recv()、recv_into() (ただし flags 引数にゼロ以外の値は渡せません)
send()、sendall() (同じ制約があります)
sendfile() (OP_ENABLE_KTLS を設定してカーネル TLS を有効にしている場合、または平文のソケットの場合にのみ高速に動作する可能性があります。それ以外では send() を使います)
shutdown()

SSL(およびTLS)プロトコルは TCP の上に独自の枠組みを持っているので、SSLソケットの抽象化は、いくつかの点で通常の OSレベルのソケットの仕様から逸脱することがあります。特にノンブロッキングソケットについての注釈を参照してください。

SSLSocket のインスタンスは SSLContext.wrap_socket() メソッドを使用して作成されなければなりません。

バージョン 3.5 で変更: sendfile() メソッドが追加されました。

バージョン 3.5 で変更: shutdown() は、バイトが送受信されるたびにソケットのタイムアウトをリセットしません。ソケットのタイムアウトは、シャットダウンの最大合計時間になりました。

バージョン 3.6 で非推奨: SSLSocket インスタンスを直接作成することは非推奨です。ソケットをラップするために SSLContext.wrap_socket() を使用してください。

バージョン 3.7 で変更: SSLSocket のインスタンスは wrap_socket() で作成しなければなりません。以前のバージョンでは直接作成できましたが、文書化も公式のサポートもされていませんでした。

バージョン 3.10 で変更: Python は内部で SSL_read_ex と SSL_write_ex を使うようになりました。これらの関数は 2 GB を超えるデータの読み書きに対応しています。長さゼロのデータを書き込んでもプロトコル違反エラーで失敗しなくなりました。

バージョン 3.15 で変更: 可能な場合、Python は内部で SSL_sendfile を使うようになりました。この関数はカーネル内で TLS 暗号化を行って追加のコンテキスト切り替えを避けるため、より効率的にファイルを送信します。

SSL ソケットには、以下に示す追加のメソッドと属性もあります:

SSLSocket.read(len=1024, buffer=None)¶

SSL ソケットからデータの len バイトまでを読み出し、読み出した結果を bytes インスタンスで返します。 buffer を指定すると、結果は代わりに buffer に読み込まれ、読み込んだバイト数を返します。

ソケットがノンブロッキングで、読み出しに待機が必要な場合は、SSLWantReadError もしくは SSLWantWriteError が送出されます。

再ネゴシエーションがいつでも可能なので、 read() の呼び出しは書き込み操作も引き起こしえます。

バージョン 3.5 で変更: ソケットのタイムアウトは、バイトが送受信されるたびにリセットされなくなりました。ソケットのタイムアウトは、最大 len バイトを読むのにかかる最大合計時間になりました。

バージョン 3.6 で非推奨: read() の代わりに recv() を使用してください。

SSLSocket.write(data)¶

SSL ソケットに data を書き込み、書き込んだバイト数を返します。 data 引数はバッファインターフェースをサポートするオブジェクトでなければなりません。

ソケットがノンブロッキングで、書き込みに待機が必要な場合は、SSLWantReadError もしくは SSLWantWriteError が送出されます。

再ネゴシエーションがいつでも可能なので、 write() の呼び出しは読み出し操作も引き起こしえます。

バージョン 3.5 で変更: バイトの送受信のたびにソケットのタイムアウトをリセットしなくなりました。タイムアウトは data の書き込み全体にかけられる時間の上限になりました。

バージョン 3.6 で非推奨: write() の代わりに send() を使用してください。

注釈

read() と write() は低水準のメソッドで、暗号化されていないアプリケーションレベルのデータを読み書きし、通信路上の暗号化されたデータとの間で復号・暗号化を行います。これらのメソッドにはアクティブな SSL 接続、つまりハンドシェイクが完了し、SSLSocket.unwrap() が呼ばれていない接続が必要です。

通常はこれらのメソッドの代わりに recv() や send() のようなソケット API メソッドを使うべきです。

SSLSocket.do_handshake(block=False)¶

SSL セットアップのハンドシェイクを実行します。

block が真で、gettimeout() が返すタイムアウトがゼロの場合、ハンドシェイクを行う間はソケットをブロッキングモードにします。

バージョン 3.4 で変更: ソケットの context の check_hostname 属性が真の場合、ハンドシェイクのメソッドは match_hostname() も実行するようになりました。

バージョン 3.5 で変更: ソケットのタイムアウトは、バイトが送受信されるたびにリセットされなくなりました。ソケットのタイムアウトは、ハンドシェイクにかかる最大合計時間になりました。

バージョン 3.7 で変更: ハンドシェイク中に OpenSSL がホスト名または IP アドレスを照合するようになりました。 match_hostname() 関数は使わなくなりました。 OpenSSL がホスト名や IP アドレスを拒否すると、ハンドシェイクを早期に中断し、相手に TLS アラートメッセージを送ります。

SSLSocket.getpeercert(binary_form=False)¶

接続先に証明書が無い場合、 None を返します。SSL ハンドシェイクがまだ行われていない場合は、 ValueError が送出されます。

binary_form が False で接続先から証明書を取得した場合、このメソッドは dict のインスタンスを返します。証明書が認証されていない場合、辞書は空です。証明書が認証されていた場合いくつかのキーを持った辞書を返し、 subject (証明書が発行された principal), issuer (証明書を発行した principal) を含みます。証明書が Subject Alternative Name 拡張(RFC 3280 を参照)のインスタンスを格納していた場合、 subjectAltName キーも辞書に含まれます。

subject, issuer フィールドは、証明書のそれぞれのフィールドについてのデータ構造で与えられる RDN (relative distinguishued name) のシーケンスを格納したタプルで、各 RDN は name-value ペアのシーケンスです。現実世界での例をお見せします:

{'issuer': ((('countryName', 'IL'),),
            (('organizationName', 'StartCom Ltd.'),),
            (('organizationalUnitName',
              'Secure Digital Certificate Signing'),),
            (('commonName',
              'StartCom Class 2 Primary Intermediate Server CA'),)),
 'notAfter': 'Nov 22 08:15:19 2013 GMT',
 'notBefore': 'Nov 21 03:09:52 2011 GMT',
 'serialNumber': '95F0',
 'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'California'),),
             (('localityName', 'San Francisco'),),
             (('organizationName', 'Electronic Frontier Foundation, Inc.'),),
             (('commonName', '*.eff.org'),),
             (('emailAddress', 'hostmaster@eff.org'),)),
 'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),
 'version': 3}

binary_form 引数が True だった場合、証明書が渡されていればこのメソッドはDERエンコードされた証明書全体をバイト列として返し、接続先が証明書を提示しなかった場合は None を返します。接続先が証明書を提供するかどうかは SSL ソケットの役割に依存します:

クライアント SSL ソケットでは、認証が要求されているかどうかに関わらず、サーバは常に証明書を提供します。
サーバ SSL ソケットでは、クライアントはサーバによって認証が要求されている場合にのみ証明書を提供します。したがって、 (CERT_OPTIONAL や CERT_REQUIRED ではなく) CERT_NONE を使用した場合 getpeercert() は None を返します。

SSLContext.check_hostname も参照してください。

バージョン 3.2 で変更: 返される辞書に issuer, notBefore のような追加アイテムを含むようになりました。

バージョン 3.4 で変更: ハンドシェイクが済んでいなければ ValueError を投げるようになりました。返される辞書に crlDistributionPoints, caIssuers, OCSP URI のような X509v3 拡張アイテムを含むようになりました。

バージョン 3.9 で変更: IPv6 アドレス文字列の末尾に改行が付かなくなりました。

SSLSocket.get_verified_chain()¶

SSL チャネルの接続相手が提供した検証済みの証明書チェインを、DER エンコードされたバイト列のリストとして返します。証明書の検証が無効な場合は、get_unverified_chain() と同じ動作をします。

検証済みのチェインはセッションに保存されないため、セッションを再開した場合は空のリストになります (session_reused を参照)。

Added in version 3.13.

SSLSocket.get_unverified_chain()¶

SSL チャネルの接続相手が提供した証明書チェインを、未検証のまま DER エンコードされたバイト列のリストとして返します。

セッションの再開時には証明書を交換しません (session_reused を参照)。その場合、リストにはセッションに保存された内容が入ります。サーバー側でチケットからセッションを再開した場合は、相手自身の証明書だけが含まれます。

Added in version 3.13.

SSLSocket.cipher()¶: 利用されている暗号の名前、その暗号の利用を定義しているSSLプロトコルのバージョン、利用されている鍵のbit長の3つの値を含むタプルを返します。もし接続が確立されていない場合、 None を返します。

SSLSocket.shared_ciphers()¶: クライアントとサーバーの両方で利用できる暗号方式のリストを返します。返されるリストの各要素は 3つの値を含むタプルで、その値はそれぞれ、暗号方式の名前、その暗号の利用を定義している SSL プロトコルのバージョン、暗号で使用される秘密鍵のビット長です。接続が確立されていないか、ソケットがクライアントソケットである場合、shared_ciphers() は None を返します。

Added in version 3.5.

SSLSocket.group()¶: この接続で鍵共有に使われたグループを返します。接続が確立されていない場合は None を返します。

Added in version 3.15.

SSLSocket.client_sigalg()¶: この接続の証明書によるクライアント認証に使われた署名アルゴリズムを返します。接続が確立されていない場合やクライアント認証が行われていない場合は None を返します。

Added in version 3.15.

SSLSocket.server_sigalg()¶: この接続の TLS ハンドシェイクを完了するためにサーバーが使った署名アルゴリズムを返します。接続が確立されていない場合や暗号スイートが署名を使わない場合は None を返します。

Added in version 3.15.

SSLSocket.compression()¶

使われている圧縮アルゴリズムを文字列で返します。接続が圧縮されていなければ None を返します。

上位レベルのプロトコルが自身で圧縮メカニズムをサポートする場合、SSL レベルでの圧縮を OP_NO_COMPRESSION を使って無効にできます。

Added in version 3.3.

SSLSocket.get_channel_binding(cb_type='tls-unique')¶

現在の接続のチャネルバインディングデータを bytes オブジェクトとして取得します。未接続の場合やハンドシェイクが完了していない場合は None を返します。

cb_type パラメータにより、望みのチャネルバインディングのタイプを選択できます。チャネルバインディングのタイプの妥当なものは CHANNEL_BINDING_TYPES でリストされています。現在のところは RFC 5929 で定義されている 'tls-unique' のみがサポートされています。未サポートのチャネルバインディングのタイプが要求された場合、 ValueError を送出します。

Added in version 3.3.

SSLSocket.selected_alpn_protocol()¶: TLS ハンドシェイクで選択されたプロトコルを返します。 SSLContext.set_alpn_protocols() が呼ばれていない場合、相手側が ALPN をサポートしていない場合、クライアントが提案したプロトコルのどれもソケットがサポートしない場合、あるいはハンドシェイクがまだ行われていない場合には、 None が返されます。

Added in version 3.5.

SSLSocket.selected_npn_protocol()¶: TLS/SSL ハンドシェイクで選択された上位レベルのプロトコルを返します。 SSLContext.set_npn_protocols() が呼ばれていない場合、相手側が NPN をサポートしていない場合、あるいはハンドシェイクがまだ行われていない場合には、 None が返されます。

Added in version 3.3.

バージョン 3.10 で非推奨: NPN は ALPN に置き換えられました。

SSLSocket.unwrap()¶: SSLシャットダウンハンドシェイクを実行します。これは下位レイヤーのソケットからTLSレイヤーを取り除き、下位レイヤーのソケットオブジェクトを返します。これは暗号化されたオペレーションから暗号化されていない接続に移行するときに利用されます。以降の通信には、オリジナルのソケットではなくこのメソッドが返したソケットのみを利用するべきです。

SSLSocket.verify_client_post_handshake()¶

TLS 1.3 クライアントにハンドシェイク後認証 (PHA) を要求します。 PHA を開始できるのは、TLS 1.3 接続の最初の TLS ハンドシェイクが完了しており、両側で PHA が有効になっている場合に限られます。開始するのはサーバー側のソケットです。 SSLContext.post_handshake_auth を参照してください。

このメソッドは直ちに証明書を交換するわけではありません。サーバー側は次の書き込みイベントで CertificateRequest を送り、次の読み込みイベントでクライアントからの証明書による応答を待ちます。

前提条件が満たされない場合 (TLS 1.3 でない、PHA が有効でないなど) は SSLError を送出します。

注釈

OpenSSL 1.1.1 で TLS 1.3 を有効にしている場合にのみ利用できます。 TLS 1.3 をサポートしていなければ、このメソッドは NotImplementedError を送出します。

Added in version 3.8.

SSLSocket.version()¶: コネクションによって実際にネゴシエイトされた SSL プロトコルバージョンを文字列で、または、セキュアなコネクションが確立していなければ None を返します。これを書いている時点では、 "SSLv2", "SSLv3", "TLSv1", "TLSv1.1", "TLSv1.2" などが返ります。最新の OpenSSL はもっと色々な値を定義しているかもしれません。

Added in version 3.5.

SSLSocket.pending()¶: 接続上に保留されている、復号済みで読み出し可能なデータのバイト数を返します。

SSLSocket.context¶: この SSL ソケットに関連付けられた SSLContext オブジェクト。

Added in version 3.2.

SSLSocket.server_side¶: サーバサイドのソケットに対して True 、クライアントサイドのソケットに対して False となる真偽値です。

Added in version 3.2.

SSLSocket.server_hostname¶: サーバのホスト名: str 型、またはサーバサイドのソケットの場合とコンストラクタで hostname が指定されなかった場合は None

Added in version 3.2.

バージョン 3.7 で変更: この属性は常に ASCII テキストになりました。 server_hostname が国際化ドメイン名 (IDN) の場合、U-label 形式 ("pythön.org") ではなく A-label 形式 ("xn--pythn-mua.org") を保持します。

SSLSocket.session¶: この SSL 接続に対する SSLSession です。このセッションは、TLS ハンドシェイクの実行後、クライアントサイドとサーバサイドのソケットで使用できます。クライアントソケットでは、このセッションを do_handshake() が呼ばれる前に設定して、セッションを再利用できます。

Added in version 3.6.

SSLSocket.session_reused¶: Added in version 3.6.

SSL コンテキスト¶

Added in version 3.2.

SSL コンテキストは、SSL 構成オプション、証明書(群)や秘密鍵(群)などのような、一回の SSL 接続よりも長生きするさまざまなデータを保持します。これはサーバサイドソケットの SSL セッションのキャッシュも管理し、同じクライアントからの繰り返しの接続時の速度向上に一役買います。

class ssl.SSLContext(protocol=None)¶

新しい SSL コンテキストを作成します。 protocol を指定する場合は、このモジュールで定義された PROTOCOL_* 定数のいずれかでなければなりません。この引数は使用する SSL プロトコルのバージョンを指定します。通常、サーバーが特定のプロトコルバージョンを選び、クライアントがそれに合わせる必要があります。ほとんどのバージョンは、他のバージョンと相互運用できません。省略した場合のデフォルトは PROTOCOL_TLS で、他のバージョンとの互換性が最も高くなります。

次のテーブルは、どのクライアントのバージョンがどのサーバのバージョンに接続できるかを示しています:

client / server	SSLv2	SSLv3	TLS [3]	TLSv1	TLSv1.1	TLSv1.2
SSLv2	yes	no	no [1]	no	no	no
SSLv3	no	yes	no [2]	no	no	no
TLS (SSLv23) [3]	no [1]	no [2]	yes	yes	yes	yes
TLSv1	no	no	yes	yes	no	no
TLSv1.1	no	no	yes	no	yes	no
TLSv1.2	no	no	yes	no	no	yes

脚注

参考

create_default_context() を使うと、指定した目的に合ったセキュリティ設定を ssl モジュールに選ばせられます。

バージョン 3.6 で変更: コンテキストは安全なデフォルト値で作成されます。デフォルトでは OP_NO_COMPRESSION、OP_CIPHER_SERVER_PREFERENCE、OP_SINGLE_DH_USE、OP_SINGLE_ECDH_USE、OP_NO_SSLv2、OP_NO_SSLv3 (PROTOCOL_SSLv3 の場合を除く) が設定されます。初期の暗号スイート一覧は HIGH の暗号だけを含み、NULL や MD5 の暗号は含みません。

バージョン 3.10 で非推奨: プロトコル引数を指定しない SSLContext の作成は非推奨です。将来、このクラスには PROTOCOL_TLS_CLIENT または PROTOCOL_TLS_SERVER の指定が必要になります。

バージョン 3.10 で変更: デフォルトの暗号スイートは、前方秘匿性とセキュリティレベル 2 を備えた、安全な AES と ChaCha20 の暗号だけになりました。 2048 ビット未満の RSA 鍵と DH 鍵、および 224 ビット未満の ECC 鍵は禁止されます。 PROTOCOL_TLS、PROTOCOL_TLS_CLIENT、PROTOCOL_TLS_SERVER は TLS 1.2 を最小の TLS バージョンとして使います。

注釈

SSLContext は、一度接続に使った後は変更できる項目が限られます。内部の信頼ストアへの証明書の追加は可能ですが、暗号方式、検証設定、mTLS 証明書を変更すると予想外の動作になることがあります。

注釈

SSLContext は複数の接続で共有して使うよう設計されています。そのため、一度接続に使った後に再設定しなければスレッドセーフです。

SSLContext オブジェクトは以下のメソッドと属性を持っています:

SSLContext.cert_store_stats()¶

ロードされた X.509 証明書の数、CA 証明書としてフラグが設定された X.509 証明書の数、証明書失効リストの数を辞書として取得します。

一つの CA と他の一つの証明書を持ったコンテキストでの例です:

>>> context.cert_store_stats()
{'crl': 0, 'x509_ca': 1, 'x509': 2}

Added in version 3.4.

SSLContext.load_cert_chain(certfile, keyfile=None, password=None)¶

秘密鍵と対応する証明書をロードします。 certfile は、証明書と、証明書認証で必要とされる任意の数の CA 証明書を含む、PEM フォーマットの単一ファイルへのパスでなければなりません。 keyfile 文字列を指定する場合、秘密鍵が含まれるファイルを指すものでなければなりません。指定しない場合、秘密鍵も certfile から取得されます。 certfile への証明書の格納についての詳細は、証明書の議論を参照してください。

password 引数に、秘密鍵を復号するためのパスワードを返す関数を与えることができます。その関数は秘密鍵が暗号化されていて、なおかつパスワードが必要な場合にのみ呼び出されます。その関数は引数なしで呼び出され、文字列、bytes、または bytearray を返さなければなりません。戻り値が文字列の場合は、鍵の復号に使う前に UTF-8 でエンコードされます。関数の代わりに、文字列、bytes、または bytearray の値を password 引数に直接指定することもできます。秘密鍵が暗号化されておらず、パスワードが不要な場合は、指定は無視されます。

password が与えられず、そしてパスワードが必要な場合には、OpenSSL 組み込みのパスワード問い合わせメカニズムが、ユーザに対話的にパスワードを問い合わせます。

秘密鍵が証明書に合致しなければ、 SSLError が送出されます。

バージョン 3.3 で変更: 新しいオプション引数 password。

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)¶

デフォルトの場所から "認証局" (CA=certification authority) 証明書ファイル一式をロードします。Windows では、CA 証明書はシステム記憶域の CA と ROOT からロードします。全てのシステムでは、この関数は SSLContext.set_default_verify_paths() を呼び出します。将来的にはこのメソッドは、他の場所からも CA 証明書をロードするかもしれません。

purpose フラグは、読み込む CA 証明書の種類を指定します。デフォルトの Purpose.SERVER_AUTH は、TLS Web サーバーの認証用としてフラグが設定され、信頼されている証明書を読み込みます (クライアント側のソケット用)。 Purpose.CLIENT_AUTH は、サーバー側でクライアント証明書を検証するための CA 証明書を読み込みます。

Added in version 3.4.

SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)¶

verify_mode が CERT_NONE でない場合に接続先の証明書ファイルの正当性検証に使われる "認証局" (CA=certification authority) 証明書ファイル一式をロードします。少なくとも cafile か capath のどちらかは指定しなければなりません。

このメソッドは PEM または DER フォーマットの証明書失効リスト (CRLs=certification revocation lists)もロードできます。CRLs のために使うには、 SSLContext.verify_flags を適切に設定しなければなりません。

cafile を指定する場合は、PEM フォーマットで CA 証明書が結合されたファイルへのパスを指定してください。このファイル内で証明書をどのように編成すれば良いのかについての詳しい情報については、証明書の議論を参照してください。

capath 文字列を指定する場合は、OpenSSL 固有の配置に従った、PEM 形式の CA 証明書を複数含むディレクトリのパスを渡してください。

cadata オブジェクトを指定する場合は、PEM エンコードの証明書一つ以上の ASCII 文字列か、DER エンコードの証明書の bytes-like object オブジェクトのどちらかを指定してください。PEM エンコードの証明書の周囲の余分な行は無視されますが、少なくとも一つの証明書が含まれている必要があります。

バージョン 3.4 で変更: 新しいオプション引数 cadata 。

SSLContext.get_ca_certs(binary_form=False)¶: ロードされた "認証局" (CA=certification authority) 証明書のリストを取得します。 binary_form 引数が False である場合、リストのそれぞれのエントリは SSLSocket.getpeercert() が出力するような辞書になります。True である場合、このメソッドは、DER エンコード形式の証明書のリストを返します。返却されるリストには、 SSL 接続によって証明書がリクエストおよびロードされない限り、 capath からの証明書は含まれません。

注釈

capath ディレクトリ内の証明書は一度でも使われない限りはロードされません。

Added in version 3.4.

SSLContext.get_ciphers()¶

有効な暗号化のリストを取得します。リストは暗号化優先度順に並びます。SSLContext.set_ciphers() を参照してください。

以下はプログラム例です:

>>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
>>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
>>> ctx.get_ciphers()
[{'aead': True,
  'alg_bits': 256,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(256) Mac=AEAD',
  'digest': None,
  'id': 50380848,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  'protocol': 'TLSv1.2',
  'strength_bits': 256,
  'symmetric': 'aes-256-gcm'},
 {'aead': True,
  'alg_bits': 128,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(128) Mac=AEAD',
  'digest': None,
  'id': 50380847,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  'protocol': 'TLSv1.2',
  'strength_bits': 128,
  'symmetric': 'aes-128-gcm'}]

Added in version 3.6.

SSLContext.get_groups(*, include_aliases=False)¶

現在の TLS の minimum_version と maximum_version を考慮して、鍵共有用に実装されているグループの一覧を取得します。例えば次のように使います。

>>> ctx = ssl.create_default_context()
>>> ctx.minimum_version = ssl.TLSVersion.TLSv1_3
>>> ctx.maximum_version = ssl.TLSVersion.TLSv1_3
>>> ctx.get_groups()
['secp256r1', 'secp384r1', 'secp521r1', 'x25519', 'x448', ...]

デフォルトでは、利用可能なグループの IANA 推奨名だけを返します。 include_aliases 引数を True にすると、古い OpenSSL がサポートする ECDH 曲線名など、対応する別名も返します。

Added in version 3.15.

SSLContext.set_default_verify_paths()¶: OpenSSL ライブラリのビルド時に定義されたファイルシステム上のパスから、デフォルトの認証局 (CA) 証明書を読み込みます。証明書が見つからなくてもエラーを返さないため、このメソッドが成功したかを簡単に知る方法はありません。ただし、OpenSSL が OS の一部として提供されている場合は、適切に設定されている可能性が高いでしょう。

SSLContext.set_ciphers(ciphers, /)¶

このコンテキストで作成したソケットが TLS 1.2 以前で接続するときに許可する暗号方式を設定します。 ciphers 引数には OpenSSL の暗号リスト形式の文字列を指定してください。 TLS 1.3 で許可する暗号方式を設定するには SSLContext.set_ciphersuites() を使います。

選択可能な暗号方式がない場合 (コンパイル時のオプションや他の設定によって、指定した暗号方式がすべて禁止されている場合) は SSLError を送出します。

注釈

接続後は、SSL ソケットの SSLSocket.cipher() メソッドで、ネゴシエートされた暗号方式の詳細を取得できます。

SSLContext.set_ciphersuites(ciphersuites, /)¶: このコンテキストで作成したソケットが TLS 1.3 で接続するときに許可する暗号方式を設定します。 ciphersuites 引数には、TLS 1.3 の暗号名をコロンで区切った文字列を指定してください。選択可能な暗号方式がない場合 (コンパイル時のオプションや他の設定によって、指定した暗号方式がすべて禁止されている場合) は SSLError を送出します。

注釈

接続後は、SSL ソケットの SSLSocket.cipher() メソッドで、ネゴシエートされた暗号方式の詳細を取得できます。

Added in version 3.15.

SSLContext.set_groups(groups, /)¶: このコンテキストで作成したソケットの鍵共有で許可するグループを設定します。 groups 引数には OpenSSL のグループリスト形式の文字列を指定してください。

注釈

接続後は、SSL ソケットの SSLSocket.group() メソッドで、その接続の鍵共有に使われたグループを取得できます。

Added in version 3.15.

SSLContext.set_client_sigalgs(sigalgs, /)¶: 証明書によるクライアント認証で許可する署名アルゴリズムを設定します。 sigalgs 引数には OpenSSL のクライアント署名アルゴリズムリスト形式の文字列を指定してください。

注釈

接続後は、SSL ソケットの SSLSocket.client_sigalg() メソッドで、その接続の証明書によるクライアント認証に使われた署名アルゴリズムを取得できます。

Added in version 3.15.

SSLContext.set_server_sigalgs(sigalgs, /)¶: サーバーが TLS ハンドシェイクを完了するために使うことを許可する署名アルゴリズムを設定します。 sigalgs 引数には OpenSSL の署名アルゴリズムリスト形式の文字列を指定してください。

注釈

接続後は、SSL ソケットの SSLSocket.server_sigalg() メソッドで、その接続の TLS ハンドシェイクを完了するためにサーバーが使った署名アルゴリズムを取得できます。

Added in version 3.15.

SSLContext.set_alpn_protocols(alpn_protocols)¶

SSL/TLS ハンドシェイク時にソケットが提示すべきプロトコルを指定します。 ['http/1.1', 'spdy/2'] のような推奨順に並べた ASCII 文字列のリストでなければなりません。プロトコルの選択は RFC 7301 に従いハンドシェイク中に行われます。ハンドシェイクが正常に終了した後、 SSLSocket.selected_alpn_protocol() メソッドは合意されたプロトコルを返します。

このメソッドは HAS_ALPN が False の場合 NotImplementedError を送出します。

Added in version 3.5.

SSLContext.set_npn_protocols(npn_protocols)¶

SSL/TLS ハンドシェイク時にソケットが提示すべきプロトコルを指定します。 ['http/1.1', 'spdy/2'] のような推奨順に並べた文字列のリストでなければなりません。プロトコルの選択は Application Layer Protocol Negotiation に従いハンドシェイク中に行われます。ハンドシェイクが正常に終了した後、 SSLSocket.selected_npn_protocol() メソッドは合意されたプロトコルを返します。

このメソッドは HAS_NPN が False の場合 NotImplementedError を送出します。

Added in version 3.3.

バージョン 3.10 で非推奨: NPN は ALPN に置き換えられました。

SSLContext.sni_callback¶

TLS クライアントがサーバ名表示を指定した際の、SSL/TLS サーバによって TLS Client Hello ハンドシェイクメッセージが受け取られたあとで呼び出されるコールバック関数を登録します。サーバ名表示メカニズムは RFC 6066 セクション 3 - Server Name Indication で述べられています。

SSLContext ごとに一つだけコールバックをセットできます。 sni_callback を None にすればコールバックは無効になります。この関数を続けて呼ぶと、以前に登録されたコールバックを上書きします。

コールバック関数は三つの引数で呼び出されます。最初の引数は ssl.SSLSocket、二つ目はクライアントが通信しようとしているサーバー名の文字列 (TLS Client Hello にサーバー名がなければ None)、三つ目は元の SSLContext です。サーバー名の引数はテキストです。国際化ドメイン名の場合、サーバー名は IDN A-label ("xn--pythn-mua.org") になります。

このコールバックの典型的な利用方法は、 ssl.SSLSocket の SSLSocket.context 属性を、サーバ名に合致する証明書チェインを持つ新しい SSLContext オブジェクトに変更することです。

コールバックが SSLSocket.context に新しいコンテキストを代入した場合、同じ接続で後から届く ClientHello メッセージ (例えば TLS 1.3 の HelloRetryRequest の後) は、新しいコンテキストに sni_callback があればそこへ渡されます。その接続で元のコールバックが再び呼ばれることはありません。

TLS 接続のネゴシエーションの初期段階なので、SSLSocket.selected_alpn_protocol() や SSLSocket.context など限られたメソッドと属性だけを使えます。 SSLSocket.getpeercert()、SSLSocket.get_verified_chain()、SSLSocket.get_unverified_chain()、SSLSocket.cipher()、SSLSocket.compression() は、接続が TLS Client Hello より先に進んでいる必要があるため、意味のある値を返さず、安全に呼び出すこともできません。

TLS ネゴシエーションを継続させるならば、 sni_callback 関数は None を返さなければなりません。TLS が失敗することを必要とするなら、 constant ALERT_DESCRIPTION_* を返してください。ここにない値を返すと、致命エラー ALERT_DESCRIPTION_INTERNAL_ERROR を引き起こします。

sni_callback 関数が例外を送出した場合、TLS 接続は TLS の致命的アラートメッセージ ALERT_DESCRIPTION_HANDSHAKE_FAILURE とともに終了します。

このメソッドは OpenSSL ライブラリが OPENSSL_NO_TLSEXT を定義してビルドされている場合、 NotImplementedError を送出します。

Added in version 3.7.

バージョン 3.15 で変更: コールバックが新しい SSLSocket.context を代入すると、その接続で後から届く ClientHello メッセージは新しいコンテキストの sni_callback に渡されるようになりました。

SSLContext.set_servername_callback(server_name_callback)¶

これは後方互換性のために残されている古い API です。可能なら代わりに sni_callback を使ってください。指定する server_name_callback は sni_callback と似ていますが、サーバーホスト名が IDN エンコードされた国際化ドメイン名の場合、server_name_callback はデコード済みの U-label ("pythön.org") を受け取ります。

サーバー名のデコードエラーが起きると、クライアントに致命的な TLS アラート ALERT_DESCRIPTION_INTERNAL_ERROR を送って TLS 接続を終了します。

Added in version 3.4.

SSLContext.load_dh_params(dhfile, /)¶

ディフィー・ヘルマン(DH)鍵交換のための鍵生成パラメータをロードします。 DH 鍵交換を用いることは、(サーバ、クライアントともに)計算機リソースに高い処理負荷をかけますが前方秘匿性を向上させます。 dhfile パラメータは PEM フォーマットの DH パラメータを含んだファイルへのパスでなければなりません。

この設定はクライアントソケットには適用されません。さらにセキュリティを改善するのに OP_SINGLE_DH_USE オプションも利用できます。

Added in version 3.3.

SSLContext.set_ecdh_curve(curve_name, /)¶

楕円曲線ディフィー・ヘルマン(ECDH)鍵交換の曲線名を指定します。ECDH はもとの DH に較べて、ほぼ間違いなく同程度に安全である一方で、顕著に高速です。 curve_name パラメータは既知の楕円曲線を表す文字列でなければなりません。例えば prime256v1 が広くサポートされている曲線です。

この設定はクライアントソケットには適用されません。さらにセキュリティを改善するのに OP_SINGLE_ECDH_USE オプションも利用できます。

このメソッドは HAS_ECDH が False の場合は利用できません。

Added in version 3.3.

参考

SSL/TLS と完全前方秘匿性: Vincent Bernat.

SSLContext.wrap_socket(sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True, server_hostname=None, session=None)¶

既存の Python ソケット sock をラップし、SSLContext.sslsocket_class (デフォルトは SSLSocket) のインスタンスを返します。返された SSL ソケットは、そのコンテキストと設定、証明書に関連付けられます。 sock は SOCK_STREAM ソケットでなければならず、他のソケット種別には対応していません。

server_side 引数は真偽値で、このソケットがサーバサイドとクライアントサイドのどちらの動作をするのかを指定します。

クライアントサイドソケットにおいて、コンテキストの生成は遅延されます。つまり、低レイヤのソケットがまだ接続されていない場合、コンテキストの生成はそのソケットの connect() メソッドが呼ばれた後に行われます。サーバサイドソケットの場合、そのソケットに接続先が居なければそれは listen 用ソケットだと判断されます。 accept() メソッドで生成されるクライアント接続に対してのサーバサイド SSLラップは自動的に行われます。メソッドは SSLError を送出することがあります。

クライアントからの接続では、 server_hostname で接続先サービスのホスト名を指定できます。これは HTTP バーチャルホストにかなり似て、シングルサーバで複数の SSL ベースのサービスを別々の証明書でホストしているようなサーバに対して使えます。 server_side が True の場合に server_hostname を指定すると ValueError を送出します。

do_handshake_on_connect 引数は、 socket.connect() の後に自動的に SSLハンドシェイクを行うか、それともアプリケーションが明示的に SSLSocket.do_handshake() メソッドを実行するかを指定します。 SSLSocket.do_handshake() を明示的に呼びだすことで、ハンドシェイクによるソケットI/Oのブロッキング動作を制御できます。

suppress_ragged_eofs 引数は、 SSLSocket.recv() メソッドが、接続先から予期しないEOF を受け取った時に通知する方法を指定します。 True (デフォルト) の場合、下位のソケットレイヤーから予期せぬEOFエラーが来た場合、通常のEOF (空のバイト列オブジェクト)を返します。 False の場合、呼び出し元に例外を投げて通知します。

session, session を参照してください。

SSLSocket を別の SSLSocket でラップするには SSLContext.wrap_bio() を使ってください。

バージョン 3.5 で変更: OpenSSL が SNI をサポートしなくても server_hostname を許容するようになりました。

バージョン 3.6 で変更: session 引数が追加されました。

バージョン 3.7 で変更: 固定の SSLSocket ではなく、SSLContext.sslsocket_class のインスタンスを返すようになりました。

SSLContext.sslsocket_class¶: SSLContext.wrap_socket() の戻り値の型で、デフォルトは SSLSocket です。 SSLContext のインスタンスでこの属性に代入すると、独自の SSLSocket サブクラスを返すようにできます。

Added in version 3.7.

SSLContext.wrap_bio(incoming, outgoing, server_side=False, server_hostname=None, session=None)¶

BIO オブジェクト incoming と outgoing をラップし、SSLContext.sslobject_class (デフォルトは SSLObject) のインスタンスを返します。 SSL の処理は入力 BIO からデータを読み込み、出力 BIO にデータを書き込みます。

server_side、server_hostname、session 引数の意味は SSLContext.wrap_socket() と同じで、検証も同様に行います。特に check_hostname が有効なのに server_hostname が指定されていない場合、相手の証明書と照合する名前がないため ValueError を送出します。

バージョン 3.6 で変更: session 引数が追加されました。

バージョン 3.7 で変更: 固定の SSLObject ではなく、SSLContext.sslobject_class のインスタンスを返すようになりました。

バージョン 3.15 で変更: server_side、server_hostname、session 引数を SSLContext.wrap_socket() と同じように検証するようになりました。以前は check_hostname が有効でも server_hostname がないコンテキストを受け入れ、証明書チェインだけを検証して相手の同一性は検証していませんでした。

SSLContext.sslobject_class¶: SSLContext.wrap_bio() の戻り値の型で、デフォルトは SSLObject です。クラスのインスタンスでこの属性を上書きすると、独自の SSLObject サブクラスを返すようにできます。

Added in version 3.7.

SSLContext.session_stats()¶

このコンテキストが作成または管理する SSL セッションの統計を取得します。各情報項目の名前を数値に対応付ける辞書を返します。例えば次の例は、コンテキスト作成以降のセッションキャッシュのヒット数とミス数の合計です。

>>> stats = context.session_stats()
>>> stats['hits'], stats['misses']
(0, 0)

SSLContext.check_hostname¶

SSLSocket.do_handshake() で相手の証明書のホスト名を照合するかどうかを指定します。ホスト名を照合するには、コンテキストの verify_mode を CERT_OPTIONAL または CERT_REQUIRED に設定し、wrap_socket() に server_hostname を渡さなければなりません。ホスト名の検査を有効にすると、verify_mode は CERT_NONE から CERT_REQUIRED に自動的に変更されます。ホスト名の検査が有効な間は CERT_NONE に戻せません。 PROTOCOL_TLS_CLIENT プロトコルはデフォルトでホスト名の検査を有効にします。他のプロトコルでは明示的に有効にする必要があります。

以下はプログラム例です:

import socket, ssl

context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
context.verify_mode = ssl.CERT_REQUIRED
context.check_hostname = True
context.load_default_certs()

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com')
ssl_sock.connect(('www.verisign.com', 443))

Added in version 3.4.

バージョン 3.7 で変更: verify_mode が CERT_NONE のときにホスト名の検査を有効にすると、verify_mode が CERT_REQUIRED に自動的に変更されるようになりました。以前はこの操作が ValueError で失敗していました。

SSLContext.keylog_filename¶: 鍵素材を生成または受信するたびに、TLS 鍵を鍵ログファイルに書き込みます。このファイルはデバッグ専用です。形式は NSS によって規定され、Wireshark など多くの通信解析ツールで使われています。ログファイルは追記専用モードで開きます。書き込みはスレッド間では同期しますが、プロセス間では同期しません。

Added in version 3.8.

SSLContext.maximum_version¶

サポートする TLS バージョンの上限を表す TLSVersion 列挙型のメンバーです。デフォルト値は TLSVersion.MAXIMUM_SUPPORTED です。 PROTOCOL_TLS、PROTOCOL_TLS_CLIENT、PROTOCOL_TLS_SERVER 以外のプロトコルでは、この属性は読み取り専用です。

maximum_version、minimum_version、SSLContext.options の各属性はいずれも、コンテキストがサポートする SSL/TLS バージョンに影響します。実装は不正な組み合わせを防ぎません。例えば options に OP_NO_TLSv1_2 を指定し、maximum_version を TLSVersion.TLSv1_2 にしたコンテキストでは、TLS 1.2 接続を確立できません。

Added in version 3.7.

SSLContext.minimum_version¶: SSLContext.maximum_version と同様ですが、サポートするバージョンの下限、または TLSVersion.MINIMUM_SUPPORTED を表します。

Added in version 3.7.

SSLContext.num_tickets¶: PROTOCOL_TLS_SERVER コンテキストの TLS 1.3 セッションチケット数を制御します。この設定は TLS 1.0 から 1.2 の接続には影響しません。

Added in version 3.8.

SSLContext.options¶

このコンテキストで有効になっている SSL オプションを表す整数。デフォルトの値は OP_ALL ですが、 OP_NO_SSLv2 のような他の値をビット OR 演算で指定できます。

バージョン 3.6 で変更: SSLContext.options は次のように Options のフラグを返します。

>>> ssl.create_default_context().options
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>

バージョン 3.7 で非推奨: すべての OP_NO_SSL* オプションと OP_NO_TLS* オプションは Python 3.7 から非推奨です。代わりに SSLContext.minimum_version と SSLContext.maximum_version を使ってください。

SSLContext.post_handshake_auth¶

TLS 1.3 のハンドシェイク後クライアント認証を有効にします。デフォルトでは無効で、サーバーは最初のハンドシェイク中にだけ TLS クライアント証明書を要求できます。有効にすると、ハンドシェイク後の任意の時点で要求できます。

クライアント側のソケットで有効にすると、クライアントはハンドシェイク後認証に対応していることをサーバーに通知します。

サーバー側のソケットで有効にする場合は、SSLContext.verify_mode も CERT_OPTIONAL または CERT_REQUIRED に設定しなければなりません。実際のクライアント証明書の交換は、SSLSocket.verify_client_post_handshake() を呼び出して I/O を行うまで遅延します。

Added in version 3.8.

SSLContext.protocol¶: コンテキストの構築時に選択されたプロトコルバージョン。この属性は読み出し専用です。

SSLContext.hostname_checks_common_name¶: check_hostname が、サブジェクトの別名拡張がない場合に証明書のサブジェクトの共通名を代わりに検証するかどうかを指定します (デフォルトは真)。

Added in version 3.7.

バージョン 3.10 で変更: OpenSSL 1.1.1l より前ではこのフラグは効果がありませんでした。 Python 3.8.9、3.9.3、3.10 には、それより前のバージョンに対処する処理が含まれています。

SSLContext.security_level¶: コンテキストのセキュリティレベルを表す整数です。この属性は読み取り専用です。

Added in version 3.10.

SSLContext.verify_flags¶

証明書の検証操作のためのフラグです。 VERIFY_CRL_CHECK_LEAF などのフラグをビット OR 演算でセットできます。デフォルトでは OpenSSL は証明書失効リスト (CRLs) を必要としませんし検証にも使いません。

Added in version 3.4.

バージョン 3.6 で変更: SSLContext.verify_flags は次のように VerifyFlags のフラグを返します。

>>> ssl.create_default_context().verify_flags
<VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>

SSLContext.verify_mode¶

接続先の証明書の検証を試みるかどうか、また、検証が失敗した場合にどのように振舞うべきかを制御します。この属性は CERT_NONE, CERT_OPTIONAL, CERT_REQUIRED のうちどれか一つでなければなりません。

バージョン 3.6 で変更: SSLContext.verify_mode は次のように VerifyMode enum (列挙) を返します。

>>> ssl.create_default_context().verify_mode
<VerifyMode.CERT_REQUIRED: 2>

SSLContext.set_psk_client_callback(callback)¶

クライアント側の接続で TLS-PSK (事前共有鍵) 認証を有効にします。

一般に、この方式よりも証明書による認証を優先すべきです。

callback 引数は、def callback(hint: str | None) -> tuple[str | None, bytes] というシグネチャを持つ呼び出し可能オブジェクトです。 hint 引数は、サーバーが任意で送る識別情報のヒントです。戻り値は (client-identity, psk) 形式のタプルです。 client-identity は省略可能な文字列で、サーバーがそのクライアントに対応する PSK を選ぶために使えます。この文字列は UTF-8 エンコード後に 256 オクテット以下でなければなりません。 PSK は事前共有鍵を表す bytes-like object です。 TLS 1.2 以前では、長さゼロの PSK を返すと接続を拒否できます。

callback を None にすると、既存のコールバックを削除します。

注釈

TLS 1.3 を使う場合:

hint 引数は常に None です。
client-identity は空でない文字列でなければなりません。
PSK はサーバーに提示されるだけで、サーバーはそれを断って代わりに証明書で認証する場合があります。その証明書は verify_mode に従って検査されるため、サーバーの認証を PSK に依存するクライアントは、この属性を CERT_NONE にすべきではありません。または、PSK が使われた場合に真になる SSLSocket.session_reused を検査してください。 PSK のハンドシェイクでは、CERT_REQUIRED を使っていても CA 証明書を読み込む必要はありません。
長さゼロの PSK は接続を拒否せず、PSK を提示しないことだけを意味します。コールバックが例外を送出した場合も同じです。
PSK はハンドシェイクのダイジェストに SHA-256 を使うため、サーバーが PSK を受け入れられるのは SHA-256 を使う暗号スイートの場合だけです。

使用例:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.check_hostname = False
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# 単純なラムダ式:
psk = bytes.fromhex('c0ffee')
context.set_psk_client_callback(lambda hint: (None, psk))

# サーバーからのヒントを使うテーブル:
psk_table = { 'ServerId_1': bytes.fromhex('c0ffee'),
              'ServerId_2': bytes.fromhex('facade')
}
def callback(hint):
    return 'ClientId_1', psk_table.get(hint, b'')
context.set_psk_client_callback(callback)

HAS_PSK が False の場合、このメソッドは NotImplementedError を送出します。

Added in version 3.13.

SSLContext.set_psk_server_callback(callback, identity_hint=None)¶

サーバー側の接続で TLS-PSK (事前共有鍵) 認証を有効にします。

一般に、この方式よりも証明書による認証を優先すべきです。

callback 引数は、def callback(identity: str | None) -> bytes というシグネチャを持つ呼び出し可能オブジェクトです。 identity 引数は、クライアントが任意で送る識別情報で、対応する PSK を選ぶために使えます。戻り値は事前共有鍵を表す bytes-like object です。 TLS 1.2 以前では、長さゼロの PSK を返すと接続を拒否できます。

callback を None にすると、既存のコールバックを削除します。

identity_hint 引数は、クライアントに送る省略可能な識別情報のヒント文字列です。 UTF-8 エンコード後に 256 オクテット以下でなければなりません。

注釈

TLS 1.3 を使う場合:

identity_hint 引数はクライアントに送られません。
長さゼロの PSK やコールバックからの例外送出は、クライアントの PSK を断るだけです。 load_cert_chain() で証明書を読み込んでいる場合、ハンドシェイクは失敗せずに証明書認証で続行します。そのため、クライアントの認証を PSK に依存するサーバーは、証明書を読み込まないようにするか、PSK が使われた場合に真になる SSLSocket.session_reused を検査してください。
PSK を受け入れられるのは SHA-256 を使う暗号スイートの場合だけです。証明書を読み込んでいる場合、OpenSSL のデフォルトの TLS 1.3 暗号スイートの順序では SHA-384 のスイートが選ばれるため、PSK が一致していても断られます。

使用例:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# 単純なラムダ式:
psk = bytes.fromhex('c0ffee')
context.set_psk_server_callback(lambda identity: psk)

# クライアントの識別情報を使うテーブル:
psk_table = { 'ClientId_1': bytes.fromhex('c0ffee'),
              'ClientId_2': bytes.fromhex('facade')
}
def callback(identity):
    return psk_table.get(identity, b'')
context.set_psk_server_callback(callback, 'ServerId_1')

HAS_PSK が False の場合、このメソッドは NotImplementedError を送出します。

Added in version 3.13.

証明書¶

証明書を大まかに説明すると、公開鍵/秘密鍵システムの一種です。このシステムでは、各 principal (これはマシン、人、組織などです) は、ユニークな2つの暗号鍵を割り当てられます。1つは公開され、 公開鍵(public key) と呼ばれます。もう一方は秘密にされ、 秘密鍵(private key) と呼ばれます。 2つの鍵は関連しており、片方の鍵で暗号化したメッセージは、もう片方の鍵のみで復号できます。

証明書は2つの principal の情報を含んでいます。証明書は subject 名とその公開鍵を含んでいます。また、もう一つの principal である 発行者(issuer) からの、 subject が本人であることと、その公開鍵が正しいことの宣言(statement)を含んでいます。発行者からの宣言は、その発行者の秘密鍵で署名されています。発行者の秘密鍵は発行者しか知りませんが、誰もがその発行者の公開鍵を利用して宣言を復号し、証明書内の別の情報と比較することで認証することができます。証明書はまた、その証明書が有効である期限に関する情報も含んでいます。この期限は "notBefore" と "notAfter" と呼ばれる2つのフィールドで表現されています。

Python では、クライアントもサーバーも証明書を使って自身の身元を証明できます。接続相手に証明書の提示を要求し、要求した側のクライアントやサーバーが必要とする検証を行うこともできます。検証に失敗した場合は接続時に例外を送出するよう設定できます。検証は基盤となる OpenSSL が自動的に行うため、アプリケーションがその仕組みを扱う必要はありません。ただし通常は、この処理のためにアプリケーションが証明書の組を提供する必要があります。

Python は証明書を格納したファイルを利用します。そのファイルは "PEM" (RFC 1422 参照) フォーマットという、ヘッダー行とフッター行の間にbase-64エンコードされた形をとっている必要があります。

-----BEGIN CERTIFICATE-----
... (base64 PEM エンコードされた証明書) ...
-----END CERTIFICATE-----

証明書チェイン¶

Pythonが利用する証明書を格納したファイルは、ときには 証明書チェイン(certificate chain) と呼ばれる証明書のシーケンスを格納します。このチェインの先頭には、まずクライアントやサーバーである principal の証明書を置き、それ以降には、その証明書の発行者(issuer)の証明書などを続け、最後に証明対象(subject)と発行者が同じ 自己署名(self-signed) 証明書で終わります。この最後の証明書は ルート証明書(root certificate と呼ばれます。これらの証明書チェインは単純に1つの証明書ファイルに結合してください。例えば、3つの証明書からなる証明書チェインがある場合、私たちのサーバーの証明書から、私たちのサーバーに署名した認証局の証明書、そして認証局の証明書を発行した機関のルート証明書と続きます:

-----BEGIN CERTIFICATE-----
... (自分のサーバーの証明書)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (CA の証明書)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (CA の発行者のルート証明書)...
-----END CERTIFICATE-----

CA 証明書¶

もし相手から送られてきた証明書の認証をしたい場合、信頼している各発行者の証明書チェインが入った "CA certs" ファイルを提供する必要があります。繰り返しますが、このファイルは単純に、各チェインを結合しただけのものです。認証のために、Pythonはそのファイルの中の最初にマッチしたチェインを利用します。SSLContext.load_default_certs() を呼び出すことでプラットフォームの証明書ファイルも使われますが、これは create_default_context() によって自動的に行われます。

秘密鍵と証明書の組み合わせ¶

秘密鍵は証明書と同じファイルに保存されることがよくあります。その場合、SSLContext.load_cert_chain() には certfile 引数だけを渡せば十分です。秘密鍵を証明書と一緒に保存する場合は、証明書チェインの最初の証明書より前に置いてください。

-----BEGIN RSA PRIVATE KEY-----
... (base64 エンコードされた秘密鍵) ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... (base64 PEM エンコードされた証明書) ...
-----END CERTIFICATE-----

自己署名証明書¶

SSL暗号化接続サービスを提供するサーバーを建てる場合、適切な証明書を取得するには、認証局から買うなどの幾つかの方法があります。また、自己署名証明書を作るケースもあります。 OpenSSLを使って自己署名証明書を作るには、次のようにします。

% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
Generating a 1024 bit RSA private key
.......++++++
.............................++++++
writing new private key to 'cert.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MyState
Locality Name (eg, city) []:Some City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
Organizational Unit Name (eg, section) []:My Group
Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
Email Address []:ops@myserver.mygroup.myorganization.com
%

自己署名証明書の欠点は、それ自身がルート証明書であり、他の人はその証明書を持っていない (そして信頼しない)ことです。

使用例¶

SSLサポートをテストする¶

インストールされているPythonがSSLをサポートしているかどうかをテストするために、ユーザーコードは次のイディオムを利用することができます。

try:
    import ssl
except ImportError:
    pass
else:
    ...  # SSL が必要な処理を行う

クライアントサイドの処理¶

この例では、自動的に証明書の検証を行うことを含む望ましいセキュリティ設定でクライアントソケットの SSL コンテキストを作ります:

>>> context = ssl.create_default_context()

自分自身でセキュリティ設定を調整したい場合、コンテキストを一から作ることはできます (ただし、正しくない設定をしてしまいがちなことに注意してください):

>>> context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

(このスニペットはすべての CA 証明書が /etc/ssl/certs/ca-bundle.crt にバンドルされていることを仮定しています; もし違っていればエラーになりますので、適宜修正してください)

PROTOCOL_TLS_CLIENT プロトコルは、証明書とホスト名を検証するようコンテキストを設定します。 verify_mode は CERT_REQUIRED、check_hostname は True に設定されます。それ以外のプロトコルはすべて、安全でないデフォルト設定の SSL コンテキストを作成します。

このコンテキストでサーバーに接続すると、CERT_REQUIRED と check_hostname によってサーバー証明書を検証します。具体的には、サーバー証明書が CA 証明書のいずれかで署名されていることと署名の正しさを確認し、有効性やホスト名の一致なども検証します。

>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
...                            server_hostname="www.python.org")
>>> conn.connect(("www.python.org", 443))

そして証明書を持ってくることができます:

>>> cert = conn.getpeercert()

証明書が、期待しているサービス (つまり、 HTTPS ホスト www.python.org) の身元を特定していることを視覚的に点検してみましょう:

>>> pprint.pprint(cert)
{'OCSP': ('http://ocsp.digicert.com',),
 'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
                           'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
 'issuer': ((('countryName', 'US'),),
            (('organizationName', 'DigiCert Inc'),),
            (('organizationalUnitName', 'www.digicert.com'),),
            (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
 'notAfter': 'Sep  9 12:00:00 2016 GMT',
 'notBefore': 'Sep  5 00:00:00 2014 GMT',
 'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
 'subject': ((('businessCategory', 'Private Organization'),),
             (('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
             (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
             (('serialNumber', '3359300'),),
             (('streetAddress', '16 Allen Rd'),),
             (('postalCode', '03894-4801'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'NH'),),
             (('localityName', 'Wolfeboro'),),
             (('organizationName', 'Python Software Foundation'),),
             (('commonName', 'www.python.org'),)),
 'subjectAltName': (('DNS', 'www.python.org'),
                    ('DNS', 'python.org'),
                    ('DNS', 'pypi.org'),
                    ('DNS', 'docs.python.org'),
                    ('DNS', 'testpypi.org'),
                    ('DNS', 'bugs.python.org'),
                    ('DNS', 'wiki.python.org'),
                    ('DNS', 'hg.python.org'),
                    ('DNS', 'mail.python.org'),
                    ('DNS', 'packaging.python.org'),
                    ('DNS', 'pythonhosted.org'),
                    ('DNS', 'www.pythonhosted.org'),
                    ('DNS', 'test.pythonhosted.org'),
                    ('DNS', 'us.pycon.org'),
                    ('DNS', 'id.python.org')),
 'version': 3}

SSL チャネルは今や確立されて証明書が検証されているので、サーバとのお喋りを続けることができます:

>>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
>>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
[b'HTTP/1.1 200 OK',
 b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
 b'Server: nginx',
 b'Content-Type: text/html; charset=utf-8',
 b'X-Frame-Options: SAMEORIGIN',
 b'Content-Length: 45679',
 b'Accept-Ranges: bytes',
 b'Via: 1.1 varnish',
 b'Age: 2188',
 b'X-Served-By: cache-lcy1134-LCY',
 b'X-Cache: HIT',
 b'X-Cache-Hits: 11',
 b'Vary: Cookie',
 b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
 b'Connection: close',
 b'',
 b'']

このドキュメントの下の方の、セキュリティで考慮すべき点に関する議論を参照してください。

サーバサイドの処理¶

サーバサイドの処理では、通常、サーバー証明書と秘密鍵がそれぞれファイルに格納された形で必要です。最初に秘密鍵と証明書が保持されたコンテキストを作成し、クライアントがあなたの信憑性をチェックできるようにします。そののちにソケットを開き、ポートにバインドし、そのソケットの listen() を呼び、クライアントからの接続を待ちます。

import socket, ssl

context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")

bindsocket = socket.socket()
bindsocket.bind(('myaddr.example.com', 10023))
bindsocket.listen(5)

クライアントが接続してきた場合、 accept() を呼んで新しいソケットを作成し、接続のためにサーバサイドの SSL ソケットを、コンテキストの SSLContext.wrap_socket() メソッドで作ります:

while True:
    newsocket, fromaddr = bindsocket.accept()
    connstream = context.wrap_socket(newsocket, server_side=True)
    try:
        deal_with_client(connstream)
    finally:
        connstream.shutdown(socket.SHUT_RDWR)
        connstream.close()

そして、 connstream からデータを読み、クライアントと切断する(あるいはクライアントが切断してくる)まで何か処理をします。

def deal_with_client(connstream):
    data = connstream.recv(1024)
    # 空のデータはクライアントとの通信が終わったことを示す
    while data:
        if not do_something(connstream, data):
            # クライアントとの通信が終わると do_something が
            # False を返すものとする
            break
        data = connstream.recv(1024)
    # クライアントとの通信が終了

そして新しいクライアント接続のために listen に戻ります。 (もちろん現実のサーバは、おそらく個々のクライアント接続ごとに別のスレッドで処理するか、ソケットをノンブロッキングモードにし、イベントループを使うでしょう。)

ノンブロッキングソケットについての注意事項¶

SSL ソケットはノンブロッキングモードにおいては、普通のソケットとは少し違った振る舞いをします。ですのでノンブロッキングソケットとともに使う場合、いくつか気をつけなければならない事項があります:

ほとんどの SSLSocket のメソッドは、I/O 操作に待機が必要な場合、BlockingIOError ではなく SSLWantWriteError か SSLWantReadError のどちらかを送出します。 SSLWantReadError は下層のソケットで読み出しが必要な場合に送出され、SSLWantWriteError は下層のソケットで書き込みが必要な場合に送出されます。 SSL ソケットに対して 書き込み を試みると下層のソケットから最初に 読み出す 必要がある場合があり、SSL ソケットに対して 読み出し を試みると下層のソケットに先に 書き込む 必要がある場合もあることに注意してください。

バージョン 3.5 で変更: 以前の Python バージョンでは、 SSLSocket.send() メソッドは SSLWantWriteError または SSLWantReadError を送出するのではなく、ゼロを返していました。
select() 呼び出しは OS レベルでのソケットが読み出し可能(または書き込み可能)になったことを教えてくれますが、上位の SSL レイヤーでの十分なデータがあることを意味するわけではありません。例えば、SSL フレームの一部が届いただけかもしれません。ですから、 SSLSocket.recv() と SSLSocket.send() の失敗を処理することに備え、ほかの select() 呼び出し後にリトライしなければなりません。
反対に、SSL レイヤーは独自の枠組みを持っているため、select() が気付かない読み出し可能なデータを SSL ソケットが持っている場合があります。したがって、入手可能な可能性のあるデータをすべて引き出すために最初に SSLSocket.recv() を呼び出し、次にそれでもまだ必要な場合にだけ select() 呼び出しでブロックすべきです。

(当然のことながら、ほかのプリミティブ、例えば poll() や selectors モジュール内のものを使う際にも似た但し書きが付きます)
SSL ハンドシェイクそのものがノンブロッキングになります: SSLSocket.do_handshake() メソッドは成功するまでリトライしなければなりません。 select() を用いてソケットの準備が整うのを待つためには、およそ以下のようにします:
```
while True:
    try:
        sock.do_handshake()
        break
    except ssl.SSLWantReadError:
        select.select([sock], [], [])
    except ssl.SSLWantWriteError:
        select.select([], [sock], [])
```

参考

asyncio モジュールはノンブロッキング SSL ソケットに対応し、より高水準の Streams API を提供します。 selectors モジュールでイベントをポーリングし、SSLWantWriteError、SSLWantReadError、BlockingIOError の各例外を処理します。 SSL ハンドシェイクも非同期に実行します。

メモリ BIO のサポート¶

Added in version 3.5.

Python 2.6 で SSL モジュールが導入されて以降、SSLSocket クラスは、以下の互いに関連するが別々の機能を提供してきました。

SSL プロトコル処理
ネットワーク IO

ネットワーク IO API は、socket.socket が提供するものと同じです。SSLSocket も、そのクラスから継承しています。これにより、SSL ソケットは標準のソケットをそっくりそのまま置き換えるものとして使用できるため、既存のアプリケーションを SSL に対応させるのが非常に簡単になります。

SSL プロトコルの処理とネットワーク IO を組み合わせた場合、通常は問題なく動作しますが、問題が発生する場合があります。一例を挙げると、非同期 IO フレームワークが別の多重化モデルを使用する場合、これは socket.socket と内部 OpenSSL ソケット IO ルーティンが想定する「ファイル記述子上の select/poll」モデル（準備状態ベース）とは異なります。これは、このモデルが非効率的になる Windows などのプラットフォームに主に該当します。そのため、スコープを限定した SSLSocket の変種、 SSLObject が提供されています。

class ssl.SSLObject¶

ネットワーク IO メソッドを含まない SSL プロトコルインスタンスを表す、スコープを限定した SSLSocket の変種です。一般的にこ、のクラスを使用するのは、メモリバッファを通じて SSL のための非同期 IO を実装するフレームワーク作成者です。

このクラスは、OpenSSL が実装する低水準 SSL オブジェクトの上にインターフェースを実装します。このオブジェクトは SSL 接続の状態をキャプチャしますが、ネットワーク IO 自体は提供しません。IO は、OpenSSL の IO 抽象レイヤである別の「BIO」オブジェクトを通じて実行する必要があります。

このクラスには公開されたコンストラクタがありません。SSLObject インスタンスは、 wrap_bio() メソッドを使用して作成しなければなりません。このメソッドは、SSLObject インスタンスを作成し、2 つの BIO に束縛します。incoming BIO は、Python から SSL プロトコルインスタンスにデータを渡すために使用され、outgoing BIO は、データを反対向きに渡すために使用されます。

次のメソッドがサポートされています:

SSLSocket と比較すると、このオブジェクトでは以下の機能が不足しています。

Any form of network IO; recv() and send() read and write only to the underlying MemoryBIO buffers.
do_handshake_on_connect 機構はありません。必ず手動で do_handshake() を呼んで、ハンドシェイクを開始する必要があります。
suppress_ragged_eofs は処理されません。プロトコルに違反するファイル末尾状態は、 SSLEOFError 例外を通じて報告されます。
unwrap() メソッドの呼び出しは、下層のソケットを返す SSL ソケットとは異なり、何も返しません。
SSLContext.set_servername_callback() に渡される server_name_callback コールバックは、1 つ目の引数として SSLSocket インスタンスではなく SSLObject インスタンスを受け取ります。

SSLObject の使用に関する注意:

SSLObject 上のすべての IO は non-blocking です。例えば、read() は入力 BIO が持つデータよりも多くのデータを必要とする場合、SSLWantReadError を送出します。

バージョン 3.7 で変更: SSLObject のインスタンスは wrap_bio() で作成しなければなりません。以前のバージョンでは直接作成できましたが、文書化も公式のサポートもされていませんでした。

SSLObject は、メモリバッファを使用して外界と通信します。MemoryBIO クラスは、以下のように OpenSSL メモリ BIO (Basic IO) オブジェクトをラップし、この目的に使用できるメモリバッファを提供します。

class ssl.MemoryBIO¶

Python と SSL プロトコルインスタンス間でデータをやり取りするために使用できるメモリバッファ。

pending¶: 現在メモリバッファ中にあるバイト数を返します。

eof¶: メモリ BIOが現在ファイルの末尾にあるかを表す真偽値です。

read(n=-1, /)¶: メモリバッファから最大 n バイト読み取ります。 n が指定されていないか負の場合は、すべてのバイトを返します。

write(buf, /)¶

buf からメモリ BIO にバイトを書き込みます。buf 引数は、バッファプロトコルをサポートするオブジェクトでなければなりません。

戻り値は、書き込まれるバイト数であり、常に buf の長さと等しくなります。

write_eof()¶: EOF マーカーをメモリ BIO に書き込みます。このメソッドが呼び出された後に write() を呼ぶことはできません。eof 属性は、バッファ内のすべてのデータが読み出された後に True になります。

SSL セッション¶

Added in version 3.6.

class ssl.SSLSession¶

session が使用するセッションオブジェクトです。

id¶

time¶

timeout¶

ticket_lifetime_hint¶

has_ticket¶

セキュリティで考慮すべき点¶

最善のデフォルト値¶

クライアントでの使用 では、セキュリティポリシーによる特殊な要件がない限りは、 create_default_context() 関数を使用して SSL コンテキストを作成することを強くお勧めします。この関数は、システムの信頼済み CA 証明書をロードし、証明書の検証とホスト名のチェックを有効化し、十分にセキュアなプロトコルと暗号を選択しようとします。

例として、 smtplib.SMTP クラスを使用して SMTP サーバーに対して信頼できるセキュアな接続を行う方法を以下に示します:

>>> import ssl, smtplib
>>> smtp = smtplib.SMTP("mail.python.org", port=587)
>>> context = ssl.create_default_context()
>>> smtp.starttls(context=context)
(220, b'2.0.0 Ready to start TLS')

接続にクライアントの証明書が必要な場合、 SSLContext.load_cert_chain() によって追加できます。

対照的に、自分自身で SSLContext クラスのコンストラクタを呼び出すことによって SSL コンテキストを作ると、デフォルトでは証明書検証もホスト名チェックも有効になりません。自分で設定を行う場合は、十分なセキュリティレベルを達成するために、以下のパラグラフをお読みください。

手動での設定¶

証明書の検証¶

When calling the SSLContext constructor directly, CERT_NONE is the default. Since it does not authenticate the other peer, it can be insecure, especially in client mode where most of the time you would like to ensure the authenticity of the server you're talking to. Therefore, when in client mode, it is highly recommended to use CERT_REQUIRED. However, it is in itself not sufficient; you also have to check that the server certificate, which can be obtained by calling SSLSocket.getpeercert(), matches the desired service. For many protocols and applications, the service can be identified by the hostname. This common check is automatically performed when SSLContext.check_hostname is enabled.

バージョン 3.7 で変更: ホスト名の照合は OpenSSL が行うようになりました。 Python は match_hostname() を使わなくなりました。

サーバモードにおいて、(より上位のレベルでの認証メカニズムではなく) SSL レイヤーを使ってあなたのクライアントを認証したいならば、 CERT_REQUIRED を指定して同じようにクライアントの証明書を検証すべきでしょう。

プロトコルのバージョン¶

SSL バージョン 2 と 3 は安全性に欠けると考えられており、使用するのは危険です。クライアントとサーバ間の互換性を最大限に確保したい場合、プロトコルバージョンとして PROTOCOL_TLS_CLIENT または PROTOCOL_TLS_SERVER を使用してください。 SSLv2 と SSLv3 はデフォルトで無効になっています。

>>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> client_context.minimum_version = ssl.TLSVersion.TLSv1_2
>>> client_context.maximum_version = ssl.TLSVersion.TLSv1_3

上で作成した SSL クライアントコンテキストは、サーバーへの接続に TLSv1.2 と TLSv1.3 (システムが対応している場合) だけを許可します。 PROTOCOL_TLS_CLIENT はデフォルトで証明書とホスト名の検証を有効にします。コンテキストには証明書を読み込む必要があります。

暗号の選択¶

高度なセキュリティ要件がある場合は、SSLContext.set_ciphers() メソッドで SSL セッションのネゴシエーション時に有効な暗号方式を細かく調整できます。 Python 3.2.3 以降、ssl モジュールは一部の弱い暗号をデフォルトで無効にしていますが、選択肢をさらに制限したい場合もあるでしょう。 OpenSSL の暗号リスト形式のドキュメントを必ず読んでください。指定した暗号リストで有効になる暗号方式を確認するには、SSLContext.get_ciphers() またはシステムの openssl ciphers コマンドを使ってください。

マルチプロセス化¶

If using this module as part of a multi-processed application (using, for example the multiprocessing or concurrent.futures modules), be aware that OpenSSL's internal random number generator does not properly handle forked processes. Applications must change the PRNG state of the parent process if they use any SSL feature with os.fork(). Any successful call of RAND_add() or RAND_bytes() is sufficient.

TLS 1.3¶

Added in version 3.7.

TLS 1.3 プロトコルの動作は、それ以前の TLS/SSL と少し異なります。 TLS 1.3 の新機能の一部はまだ利用できません。

TLS 1.3 は、それ以前とは別の暗号スイート群を使います。すべての AES-GCM と ChaCha20 の暗号スイートがデフォルトで有効です。許可する TLS 1.3 の暗号方式を制限するには、SSLContext.set_ciphersuites() を呼び出してください。 SSLContext.set_ciphers() は古い TLS バージョンの暗号方式にしか影響しません。 SSLContext.get_ciphers() は TLS 1.3 とそれ以前の両方の暗号方式について情報を返し、接続後の SSLSocket.cipher() はどちらのバージョンでもネゴシエートされた暗号方式の情報を返します。
セッションチケットは最初のハンドシェイクの一部としては送られなくなり、扱いも異なります。 SSLSocket.session と SSLSession は TLS 1.3 と互換性がありません。
Client-side certificates are also no longer verified during the initial handshake. A server can request a certificate at any time. Clients process certificate requests while they send or receive application data from the server.
TLS 1.3 features like early data, deferred TLS client cert request, and rekeying are not supported yet.

参考

socket.socket クラス: 下位レイヤーの socket クラスのドキュメント
SSL/TLS Strong Encryption: An Introduction: Apache HTTPサーバのドキュメンテーションのイントロ
RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management: Steve Kent
RFC 4086: Randomness Requirements for Security: Donald E. Eastlake, Jeffrey I. Schiller, Steve Crocker
RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile: David Cooper et al.
RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2: Tim Dierks and Eric Rescorla.
RFC 6066: Transport Layer Security (TLS) Extensions: Donald E. Eastlake
IANA TLS: Transport Layer Security (TLS) Parameters: IANA
RFC 7525: Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS): IETF
Mozilla's Server Side TLS recommendations: Mozilla

`ssl` --- ソケットオブジェクト用の TLS/SSL ラッパー¶

関数、定数、例外¶

ソケットの作成¶

コンテキストの作成¶

署名アルゴリズム¶

例外¶

乱数生成¶

証明書の取り扱い¶

定数¶

SSL ソケット¶

SSL コンテキスト¶

証明書¶

証明書チェイン¶

CA 証明書¶

秘密鍵と証明書の組み合わせ¶

自己署名証明書¶

使用例¶

SSLサポートをテストする¶

クライアントサイドの処理¶

サーバサイドの処理¶

ノンブロッキングソケットについての注意事項¶

メモリ BIO のサポート¶

SSL セッション¶

セキュリティで考慮すべき点¶

最善のデフォルト値¶

手動での設定¶

証明書の検証¶

プロトコルのバージョン¶

暗号の選択¶

マルチプロセス化¶

TLS 1.3¶

目次

前のトピックへ

次のトピックへ

このページ

ssl --- ソケットオブジェクト用の TLS/SSL ラッパー¶

関数、定数、例外¶

ソケットの作成¶

コンテキストの作成¶

署名アルゴリズム¶

例外¶

乱数生成¶

証明書の取り扱い¶

定数¶

SSL ソケット¶

SSL コンテキスト¶

証明書¶

証明書チェイン¶

CA 証明書¶

秘密鍵と証明書の組み合わせ¶

自己署名証明書¶

使用例¶

SSLサポートをテストする¶

クライアントサイドの処理¶

サーバサイドの処理¶

ノンブロッキングソケットについての注意事項¶

メモリ BIO のサポート¶

SSL セッション¶

セキュリティで考慮すべき点¶

最善のデフォルト値¶

手動での設定¶

証明書の検証¶

プロトコルのバージョン¶

暗号の選択¶

マルチプロセス化¶

TLS 1.3¶

`ssl` --- ソケットオブジェクト用の TLS/SSL ラッパー¶