17.3. "ssl" --- ソケットオブジェクトに対する TLS/SSL ラッパー
*************************************************************

バージョン 2.6 で追加.

**Source code:** Lib/ssl.py

======================================================================

このモジュールは Transport Layer Security (よく "Secure Sockets Layer"
という名前で知られています) 暗号化と、クライアントサイド、サーバーサイ
ド両方のネットワークソケットのためのピア認証の仕組みを提供しています。
このモジュールはOpenSSLライブラリを利用しています。OpenSSLは、全てのモ
ダンなUnixシステム、Windows、Mac OS X、その他幾つかの OpenSSLがインス
トールされているプラットフォームで利用できます。

バージョン 2.7.13 で変更: Updated to support linking with OpenSSL
1.1.0

注釈: OSのソケットAPIに対して実装されているので、幾つかの挙動はプラ
  ットフ ォーム依存になるかもしれません。インストールされているOpenSSL
  のバー ジョンの違いも挙動の違いの原因になるかもしれません。例えば、
  TLSv1.1, TLSv1.2 は openssl version 1.0.1 以降でのみ利用出来ます。

警告: セキュリティで考慮すべき点 を読まずにこのモジュールを使用しな
  いでく ださい。SSL のデフォルト設定はアプリケーションに十分ではない
  ので、読 まない場合はセキュリティに誤った意識を持ってしまうかもしれ
  ません。

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

このモジュールは1つのクラス、 "ssl.SSLSocket" を提供します。このクラス
は "socket.socket" クラスを継承していて、ソケットで通信されるデータを
SSLで暗号化・復号するソケットに似たラッパーになります。また、このクラ
スは追加で、接続の相手側からの証明書を取得する "getpeercert()" メソッ
ド、セキュア接続で使うための暗号方式を取得する "cipher()" のようなメソ
ッドをサポートしています。

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


17.3.1. 関数、定数、例外
========================

exception ssl.SSLError

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

   library

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

      バージョン 2.7.9 で追加.

   reason

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

      バージョン 2.7.9 で追加.

exception ssl.SSLZeroReturnError

   読み出しあるいは書き込みを試みようとした際に SSL コネクションが行儀
   よく閉じられてしまった場合に送出される "SSLError" サブクラス例外で
   す。これは下層の転送(read TCP)が閉じたことは意味しないことに注意し
   てください。

   バージョン 2.7.9 で追加.

exception ssl.SSLWantReadError

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

   バージョン 2.7.9 で追加.

exception ssl.SSLWantWriteError

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

   バージョン 2.7.9 で追加.

exception ssl.SSLSyscallError

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

   バージョン 2.7.9 で追加.

exception ssl.SSLEOFError

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

   バージョン 2.7.9 で追加.

exception ssl.CertificateError

   証明書のエラー(ホスト名のミスマッチのような)を通知するために送出さ
   れます。ただし、OpenSSL によって検出された場合の証明書エラーは
   "SSLError" です。


17.3.1.1. ソケットの作成
------------------------

以下に示す関数は、スタンドアロンでソケットを作りたい場合に使います。
Python 2.7.9 からは、これよりもっと柔軟な "SSLContext.wrap_socket()"
が使えます。

ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version={see docs}, ca_certs=None, do_handshake_on_connect=True, suppress_ragged_eofs=True, ciphers=None)

   "socket.socket" のインスタンス "sock" を受け取り、 "socket.socket"
   のサブタイプである "ssl.SSLSocket" のインスタンスを返します。
   "ssl.SSLSocket" は低レイヤのソケットをSSLコンテキストでラップします
   。 "sock" は "SOCK_STREAM" ソケットでなければなりません; ほかのタイ
   プのソケットはサポートされていません。

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

   オプションの "keyfile" と "certfile" 引数は、接続のこちら側を識別す
   るために利用される証明書を含むファイルを指定します。証明書がどのよ
   うに "certfile" に格納されるかについてのより詳しい情報は、 証明書
   を参照してください。

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

   "cert_reqs" 引数は、接続の相手側からの証明書を必要とするかどうかと
   、それを検証(validate)するかどうかを指定します。これは次の3つの定数
   のどれかで無ければなりません: "CERT_NONE" (証明書は無視されます),
   "CERT_OPTIONAL" (必要としないが、提供された場合は検証する),
   "CERT_REQUIRED" (証明書を必要とし、検証する)。もしこの引数が
   "CERT_NONE" 以外だった場合、 "ca_certs" 引数はCA証明書ファイルを指
   定していなければなりません。

   "ca_certs" ファイルは、接続の相手側から渡された証明書を検証するため
   に使う、一連のCA証明書を結合したものを含んでいます。このファイル内
   にどう証明書を並べるかについての詳しい情報は 証明書 を参照してくだ
   さい。

   "ssl_version" 引数は、使用するSSLプロトコルのバージョンを指定します
   。通常、サーバー側が特定のプロトコルバージョンを選び、クライアント
   側はサーバーの選んだプロトコルを受け入れなければなりません。ほとん
   どのバージョンは他のバージョンと互換性がありません。もしこの引数が
   指定されなかった場合、デフォルトは "PROTOCOL_SSLv23" になります。こ
   のバージョンは、できるだけの互換性を確保するように選ばれています。

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

      +--------------------------+-----------+-----------+------------+-----------+-------------+-------------+
      | *client* / **server**    | **SSLv2** | **SSLv3** | **SSLv23** | **TLSv1** | **TLSv1.1** | **TLSv1.2** |
      +--------------------------+-----------+-----------+------------+-----------+-------------+-------------+
      | *SSLv2*                  | yes       | no        | yes        | no        | no          | no          |
      +--------------------------+-----------+-----------+------------+-----------+-------------+-------------+
      | *SSLv3*                  | no        | yes       | yes        | no        | no          | no          |
      +--------------------------+-----------+-----------+------------+-----------+-------------+-------------+
      | *SSLv23* [1]             | no        | yes       | 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         |
      +--------------------------+-----------+-----------+------------+-----------+-------------+-------------+

   -[ 脚注 ]-

   [1] TLS 1.3 protocol will be available with "PROTOCOL_SSLv23"
       in OpenSSL >= 1.1.1. There is no dedicated PROTOCOL constant
       for just TLS 1.3.

   注釈: どの接続が成功するかは、 OpenSSL のバージョンに依存して大き
     く変わ ります。例えば、OpenSSL 1.0.0 以前は、SSLv23 クライアント
     は常に SSLv2 接続を試みていました。

   The *ciphers* parameter sets the available ciphers for this SSL
   object. It should be a string in the OpenSSL cipher list format.

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

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

   バージョン 2.7 で変更: 新しいオプション引数 *ciphers*


17.3.1.2. コンテキストの作成
----------------------------

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

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

   新規の "SSLContext" オブジェクトを、与えられた *purpose* のデフォル
   ト設定で返します。設定は "ssl" モジュールで選択され、通常は
   "SSLContext" のコンストラクタを直接呼び出すよりも高いセキュリティレ
   ベルを表現します。

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

   これで作られる設定はこのようになります: RC4 を除く、高レベルで、未
   認証のものを含まない暗号化一式と "PROTOCOL_SSLv23", "OP_NO_SSLv2",
   "OP_NO_SSLv3" 。 *purpose* に "SERVER_AUTH" を渡すと、
   "verify_mode" には "CERT_REQUIRED" がセットされ、(*cafile*,
   *capath*, *cadata* のいずれかが与えられれば) CA 証明書がロードされ
   るかまたはデフォルトの CA 証明書をロードするために
   "SSLContext.load_default_certs()" が使われます。

   注釈: プロトコル、オプション、暗号その他設定はもっと制限された、
     過去の 廃れたものを含まない値にいつでも出来るでしょう。この値は互
     換性と 安全性の公平なバランスを表明しています。もしもあなたのアプ
     リケー ションがそのような設定を必要とするのであれば、
     "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

   バージョン 2.7.9 で追加.

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

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

ssl._https_verify_certificates(enable=True)

   Specifies whether or not server certificates are verified when
   creating client HTTPS connections without specifying a particular
   SSL context.

   Starting with Python 2.7.9, "httplib" and modules which use it,
   such as "urllib2" and "xmlrpclib", default to verifying remote
   server certificates received when establishing client HTTPS
   connections. This default verification checks that the certificate
   is signed by a Certificate Authority in the system trust store and
   that the Common Name (or Subject Alternate Name) on the presented
   certificate matches the requested host.

   Setting *enable* to "True" ensures this default behaviour is in
   effect.

   Setting *enable* to "False" reverts the default HTTPS certificate
   handling to that of Python 2.7.8 and earlier, allowing connections
   to servers using self-signed certificates, servers using
   certificates signed by a Certicate Authority not present in the
   system trust store, and servers where the hostname does not match
   the presented server certificate.

   The leading underscore on this function denotes that it
   intentionally does not exist in any implementation of Python 3 and
   may not be present in all Python 2.7 implementations. The portable
   approach to bypassing certificate checks or the system trust store
   when necessary is for tools to enable that on a case-by-case basis
   by explicitly passing in a suitably configured SSL context, rather
   than reverting the default behaviour of the standard library client
   modules.

   バージョン 2.7.12 で追加.

   参考:

     * CVE-2014-9365 -- HTTPS man-in-the-middle attack against
       Python clients using default settings

     * **PEP 476** -- Enabling certificate verification by default
       for HTTPS

     * **PEP 493** -- HTTPS verification migration tools for Python
       2.7


17.3.1.3. 乱数生成
------------------

   バージョン 2.7.13 で非推奨: OpenSSL は "ssl.RAND_pseudo_bytes()" を
   廃止しました。代わりに "ssl.RAND_bytes()" を使用してください。

ssl.RAND_status()

   SSL 擬似乱数生成器が十分なランダム性(randomness)を受け取っている時
   に "True" を、それ以外の場合は *False* を返します。
   "ssl.RAND_egd()" と "ssl.RAND_add()" を使って擬似乱数生成機にランダ
   ム性を加えることができます。

ssl.RAND_egd(path)

   もしエントロピー収集デーモン(EGD=entropy-gathering daemon)が動いて
   いて、 *path* がEGDへのソケットのパスだった場合、この関数はそのソケ
   ットから 256バイトのランダム性を読み込み、SSL擬似乱数生成器にそれを
   渡すことで、生成される暗号鍵のセキュリティを向上させることができま
   す。これは、より良いランダム性のソースが無いシステムでのみ必要です
   。

   エントロピー収集デーモンについては、 http://egd.sourceforge.net/ や
   http://prngd.sourceforge.net/ を参照してください。

   利用出来る環境: LibreSSL および 1.1.0 を超えるバージョンの OpenSSL
   では利用できません。

ssl.RAND_add(bytes, entropy)

   与えられた *bytes* をSSL擬似乱数生成器に混ぜます。 *entropy* 引数
   (float値)は、その文字列に含まれるエントロピーの下限(lower bound)で
   す。 (なので、いつでも "0.0" を使うことができます。) エントロピーの
   ソースについてのより詳しい情報は、 **RFC 1750** を参照してください
   。


17.3.1.4. 証明書の取り扱い
--------------------------

ssl.match_hostname(cert, hostname)

   ("SSLSocket.getpeercert()" が返してきたようなデコードされたフォーマ
   ットの) *cert* が、与えられた *hostname* に合致するかを検証します。
   HTTPS サーバの身元をチェックするために適用されるルールは **RFC
   2818**, **RFC 6125** で概説されているものです。ただし IP アドレスに
   よるものは現在サポートされていません。HTTPS に加え、この関数は他の
   SSL ベースのプロトコル、例えば FTPS, IMAPS, POPS などのサーバの身元
   をチェックするのに相応しいはずです。

   失敗すれば "CertificateError" が送出されます。成功すれば、この関数
   は何も返しません:

      >>> cert = {'subject': ((('commonName', 'example.com'),),)}
      >>> ssl.match_hostname(cert, "example.com")
      >>> ssl.match_hostname(cert, "example.org")
      Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
        File "/home/py3k/Lib/ssl.py", line 130, in match_hostname
      ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'

   バージョン 2.7.9 で追加.

ssl.cert_time_to_seconds(cert_time)

   "cert_time" として証明書内の "notBefore" や "notAfter" の ""%b %d
   %H:%M:%S %Y %Z"" strptime フォーマット (C locale) 日付を渡すと、エ
   ポックからの積算秒を返します。

   例です。 :

      >>> import ssl
      >>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
      >>> timestamp
      1515144883
      >>> from datetime import datetime
      >>> print(datetime.utcfromtimestamp(timestamp))
      2018-01-05 09:34:43

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

   バージョン 2.7.9 で変更: 入力文字列に指定された 'GMT' タイムゾーン
   を UTC として解釈するようになりました。以前はローカルタイムで解釈し
   ていました。また、整数を返すようになりました(入力に含まれる秒の端数
   を含まない)。

ssl.get_server_certificate(addr, ssl_version=PROTOCOL_SSLv23, ca_certs=None)

   SSLで保護されたサーバーのアドレス "addr" を (*hostname*, *port-
   number*) の形で受け取り、そのサーバーから証明書を取得し、それを PEM
   エンコードされた文字列として返します。 "ssl_version" が指定された場
   合は、サーバーに接続を試みるときにそのバージョンのSSLプロトコルを利
   用します。 "ca_certs" が指定された場合、それは "wrap_socket()" の同
   名の引数と同じフォーマットで、ルート証明書のリストを含むファイルで
   なければなりません。この関数はサーバー証明書をルート証明書リストに
   対して認証し、認証が失敗した場合にこの関数も失敗します。

   バージョン 2.7.9 で変更: この関数は IPv6 互換になりました。
   *ssl_version* のデフォルトが、最近のサーバへの最大限の互換性のため
   に "PROTOCOL_SSLv3" から "PROTOCOL_SSLv23" に変更されました。

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 のパス

   利用出来る環境: LibreSSL では環境変数 "openssl_cafile_env" と
   "openssl_capath_env" が無視されます

   バージョン 2.7.9 で追加.

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.

   バージョン 2.7.9 で追加.

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.

   バージョン 2.7.9 で追加.


17.3.1.5. 定数
--------------

ssl.CERT_NONE

   "SSLContext.verify_mode" または "wrap_socket()" の "cert_reqs" パラ
   メータに使用する値です。このモード(これがデフォルトです)では、ソケ
   ット接続先からの証明書やその認証を必要としません。接続先から証明書
   を受け取っても検証は試みられません。

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

ssl.CERT_OPTIONAL

   "SSLContext.verify_mode" または "wrap_socket()" の "cert_reqs" パラ
   メータに使用する値です。このモードでは、ソケット接続先からの証明書
   やその認証を必要としませんが、証明書が提供されれば検証が試みられ、
   検証失敗時には "SSLError" が送出されます。

   この設定では、正当なCA証明書のセットを
   "SSLContext.load_verify_locations()" または "wrap_socket()" の
   "ca_certs" パラメータのどちらかに渡す必要があります。

ssl.CERT_REQUIRED

   "SSLContext.verify_mode" または "wrap_socket()" の "cert_reqs" パラ
   メータに使用する値です。このモードでは、ソケット接続先からの証明書
   やその認証を必要とされ、証明書が提供されないかその検証失敗時には
   "SSLError" が送出されます。

   この設定では、正当なCA証明書のセットを
   "SSLContext.load_verify_locations()" または "wrap_socket()" の
   "ca_certs" パラメータのどちらかに渡す必要があります。

ssl.VERIFY_DEFAULT

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

   バージョン 2.7.9 で追加.

ssl.VERIFY_CRL_CHECK_LEAF

   "SSLContext.verify_flags" に渡せる値です。このモードでは、接続先の
   証明書のチェックのみで仲介の CA 証明書はチェックしません。接続先証
   明書の発行者(その CA の直接の祖先)によって署名された妥当な CRL が必
   要です。 "SSLContext.load_verify_locations" が相応しいものをロード
   していなければ、検証は失敗するでしょう。

   バージョン 2.7.9 で追加.

ssl.VERIFY_CRL_CHECK_CHAIN

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

   バージョン 2.7.9 で追加.

ssl.VERIFY_X509_STRICT

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

   バージョン 2.7.9 で追加.

ssl.VERIFY_X509_TRUSTED_FIRST

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

   バージョン 2.7.10 で追加.

ssl.PROTOCOL_TLS

   チャンネル暗号化プロトコルとして、クライアントとサーバの両方がサポ
   ートする中の、プロトコルバージョンが最も大きなものを選択します。そ
   の名前にも関わらず、このオプションは "SSL" とともに "TLS" プロトコ
   ルも選択できます。

   バージョン 2.7.13 で追加.

ssl.PROTOCOL_SSLv23

   Alias for "PROTOCOL_TLS".

   バージョン 2.7.13 で非推奨: Use "PROTOCOL_TLS" instead.

ssl.PROTOCOL_SSLv2

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

   このプロトコルは、 OpenSSL が "OPENSSL_NO_SSL2" フラグが有効な状態
   でコンパイルされている場合には利用できません。

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

   バージョン 2.7.13 で非推奨: OpenSSL は SSLv2 へのサポートを打切りま
   した。

ssl.PROTOCOL_SSLv3

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

   このプロトコルは、 OpenSSL が "OPENSSL_NO_SSLv3" フラグが有効な状態
   でコンパイルされている場合には利用できません。

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

   バージョン 2.7.13 で非推奨: OpenSSL has deprecated all version
   specific protocols. Use the default protocol with flags like
   "OP_NO_SSLv3" instead.

ssl.PROTOCOL_TLSv1

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

   バージョン 2.7.13 で非推奨: OpenSSL has deprecated all version
   specific protocols. Use the default protocol with flags like
   "OP_NO_SSLv3" instead.

ssl.PROTOCOL_TLSv1_1

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

   バージョン 2.7.9 で追加.

   バージョン 2.7.13 で非推奨: OpenSSL has deprecated all version
   specific protocols. Use the default protocol with flags like
   "OP_NO_SSLv3" instead.

ssl.PROTOCOL_TLSv1_2

   チャンネル暗号化プロトコルとしてTLSバージョン1.2を選択します。これ
   は最も現代的で、接続の両サイドが利用できる場合は、たぶん最も安全な
   選択肢です。 openssl version 1.0.1+ のみで利用可能です。

   バージョン 2.7.9 で追加.

   バージョン 2.7.13 で非推奨: OpenSSL has deprecated all version
   specific protocols. Use the default protocol with flags like
   "OP_NO_SSLv3" instead.

ssl.OP_ALL

   相手にする SSL 実装のさまざまなバグを回避するためのワークアラウンド
   を有効にします。このオプションはデフォルトで有効です。これを有効に
   する場合 OpenSSL 用の同じ意味のフラグ "SSL_OP_ALL" をセットする必要
   はありません。

   バージョン 2.7.9 で追加.

ssl.OP_NO_SSLv2

   SSLv2 接続が行われないようにします。このオプションは
   "PROTOCOL_SSLv23" と組み合わせでのみ意味を持ちます。ピア間で SSLv2
   がプロトコルバージョンとして選択されることを防ぎます。

   バージョン 2.7.9 で追加.

ssl.OP_NO_SSLv3

   SSLv3 接続が行われないようにします。このオプションは
   "PROTOCOL_SSLv23" と組み合わせでのみ意味を持ちます。ピア間で SSLv3
   がプロトコルバージョンとして選択されることを防ぎます。

   バージョン 2.7.9 で追加.

ssl.OP_NO_TLSv1

   TLSv1 接続が行われないようにします。このオプションは
   "PROTOCOL_SSLv23" と組み合わせでのみ意味を持ちます。ピア間で TLSv1
   がプロトコルバージョンとして選択されることを防ぎます。

   バージョン 2.7.9 で追加.

ssl.OP_NO_TLSv1_1

   TLSv1.1 接続が行われないようにします。このオプションは
   "PROTOCOL_SSLv23" と組み合わせでのみ意味を持ちます。ピア間で
   TLSv1.1 がプロトコルバージョンとして選択されることを防ぎます。
   openssl version 1.0.1+ でのみ利用できます。

   バージョン 2.7.9 で追加.

ssl.OP_NO_TLSv1_2

   TLSv1.2 接続が行われないようにします。このオプションは
   "PROTOCOL_SSLv23" と組み合わせでのみ意味を持ちます。ピア間で
   TLSv1.2 がプロトコルバージョンとして選択されることを防ぎます。
   openssl version 1.0.1+ でのみ利用できます。

   バージョン 2.7.9 で追加.

ssl.OP_NO_TLSv1_3

   Prevents a TLSv1.3 connection. This option is only applicable in
   conjunction with "PROTOCOL_TLS". It prevents the peers from
   choosing TLSv1.3 as the protocol version. TLS 1.3 is available with
   OpenSSL 1.1.1 or later. When Python has been compiled against an
   older version of OpenSSL, the flag defaults to *0*.

   バージョン 2.7.15 で追加.

ssl.OP_CIPHER_SERVER_PREFERENCE

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

   バージョン 2.7.9 で追加.

ssl.OP_SINGLE_DH_USE

   SSL セッションを区別するのに同じ DH 鍵を再利用しないようにします。
   これはセキュリティを向上させますが、より多くの計算機リソースを必要
   とします。このオプションはサーバソケットに適用されます。

   バージョン 2.7.9 で追加.

ssl.OP_SINGLE_ECDH_USE

   SSL セッションを区別するのに同じ ECDH 鍵を再利用しないようにします
   。これはセキュリティを向上させますが、より多くの計算機リソースを必
   要とします。このオプションはサーバソケットに適用されます。

   バージョン 2.7.9 で追加.

ssl.OP_ENABLE_MIDDLEBOX_COMPAT

   Send dummy Change Cipher Spec (CCS) messages in TLS 1.3 handshake
   to make a TLS 1.3 connection look more like a TLS 1.2 connection.

   This option is only available with OpenSSL 1.1.1 and later.

   バージョン 2.7.16 で追加.

ssl.OP_NO_COMPRESSION

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

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

   バージョン 2.7.9 で追加.

ssl.HAS_ALPN

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

   バージョン 2.7.10 で追加.

ssl.HAS_ECDH

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

   バージョン 2.7.9 で追加.

ssl.HAS_SNI

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

   バージョン 2.7.9 で追加.

ssl.HAS_NPN

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

   バージョン 2.7.9 で追加.

ssl.HAS_TLSv1_3

   Whether the OpenSSL library has built-in support for the TLS 1.3
   protocol.

   バージョン 2.7.15 で追加.

ssl.CHANNEL_BINDING_TYPES

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

   バージョン 2.7.9 で追加.

ssl.OPENSSL_VERSION

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

      >>> ssl.OPENSSL_VERSION
      'OpenSSL 0.9.8k 25 Mar 2009'

   バージョン 2.7 で追加.

ssl.OPENSSL_VERSION_INFO

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

      >>> ssl.OPENSSL_VERSION_INFO
      (0, 9, 8, 11, 15)

   バージョン 2.7 で追加.

ssl.OPENSSL_VERSION_NUMBER

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

      >>> ssl.OPENSSL_VERSION_NUMBER
      9470143L
      >>> hex(ssl.OPENSSL_VERSION_NUMBER)
      '0x9080bfL'

   バージョン 2.7 で追加.

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE
ssl.ALERT_DESCRIPTION_INTERNAL_ERROR
ALERT_DESCRIPTION_*

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

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

   バージョン 2.7.9 で追加.

Purpose.SERVER_AUTH

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

   バージョン 2.7.9 で追加.

Purpose.CLIENT_AUTH

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

   バージョン 2.7.9 で追加.


17.3.2. SSL ソケット
====================

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

* "accept()"

* "bind()"

* "close()"

* "connect()"

* "fileno()"

* "getpeername()", "getsockname()"

* "getsockopt()", "setsockopt()"

* "gettimeout()", "settimeout()", "setblocking()"

* "listen()"

* "makefile()"

* "recv()", "recv_into()" (非ゼロの "flags" は渡せません)

* "send()", "sendall()" (非ゼロの "flags" は渡せません)

* "shutdown()"

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

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

SSLSocket.do_handshake()

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

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

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}

   注釈: 特定のサービスのために証明書の検証がしたければ、
     "match_hostname()" 関数を使うことが出来ます。

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

   * クライアント側ソケットでは、認証が要求されているかどうかに関わ
     ら ず、サーバは常に証明書を提供します;

   * サーバ側ソケットでは、クライアントはサーバによって認証が要求さ
     れ ている場合にのみ証明書を提供します; ですので、
     ("CERT_OPTIONAL" や "CERT_REQUIRED" ではなく) "CERT_NONE" を使う
     と "getpeercert()" は "None" を返します。

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

SSLSocket.cipher()

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

SSLSocket.compression()

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

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

   バージョン 2.7.9 で追加.

SSLSocket.get_channel_binding(cb_type="tls-unique")

   現在の接続におけるチャネルバインディングのデータを取得します。未接
   続あるいはハンドシェイクが完了していなければ "None" を返します。

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

   バージョン 2.7.9 で追加.

SSLSocket.selected_alpn_protocol()

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

   バージョン 2.7.10 で追加.

SSLSocket.selected_npn_protocol()

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

   バージョン 2.7.9 で追加.

SSLSocket.unwrap()

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

SSLSocket.version()

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

   バージョン 2.7.9 で追加.

SSLSocket.context

   この SSL ソケットに結び付けられた "SSLContext" オブジェクトです。
   SSL ソケットが ("SSLContext.wrap_socket()" ではなく)トップレベルの
   "wrap_socket()" 関数を使って作られた場合、これはこの SSL ソケットの
   ために作られたカスタムコンテキストオブジェクトです。

   バージョン 2.7.9 で追加.


17.3.3. SSL コンテキスト
========================

バージョン 2.7.9 で追加.

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

class ssl.SSLContext(protocol)

   新しい SSL コンテキストを作成します。 *protocol* にはこのモジュール
   で定義されている "PROTOCOL_*" 定数のうち一つを指定しなければなりま
   せん。最大限の互換性のためには、現時点での推奨は "PROTOCOL_SSLv23"
   です。

   参考: "create_default_context()" は "ssl" モジュールに、目的に合
     ったセ キュリティ設定を選ばせます。

   バージョン 2.7.16 で変更: The context is created with secure
   default values. The options "OP_NO_COMPRESSION",
   "OP_CIPHER_SERVER_PREFERENCE", "OP_SINGLE_DH_USE",
   "OP_SINGLE_ECDH_USE", "OP_NO_SSLv2" (except for "PROTOCOL_SSLv2"),
   and "OP_NO_SSLv3" (except for "PROTOCOL_SSLv3") are set by default.
   The initial cipher suite list contains only "HIGH" ciphers, no
   "NULL" ciphers and no "MD5" ciphers (except for "PROTOCOL_SSLv2").

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

SSLContext.cert_store_stats()

   ロードされた X.509 証明書の数、CA 証明書で活性の X.509 証明書の数、
   証明書失効リストの数、についての統計情報を辞書として取得します。

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

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

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

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

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

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

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

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 証明書をロードします。

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 証明書が結合された
   ファイルへのパスを指定してください。このファイル内で証明書をどのよ
   うに編成すれば良いのかについての詳しい情報については、 証明書 の議
   論を参照してください。

   The *capath* string, if present, is the path to a directory
   containing several CA certificates in PEM format, following an
   OpenSSL specific layout.

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

SSLContext.get_ca_certs(binary_form=False)

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

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

SSLContext.set_default_verify_paths()

   デフォルトの "認証局" (CA=certification authority) 証明書を、
   OpenSSL ライブラリがビルドされた際に定義されたファイルシステム上の
   パスからロードします。残念ながらこのメソッドが成功したかどうかを知
   るための簡単な方法はありません: 証明書が見つからなくてもエラーは返
   りません。OpenSSL ライブラリがオペレーティングシステムの一部として
   提供されている際にはどうやら適切に構成できるようですが。

SSLContext.set_ciphers(ciphers)

   Set the available ciphers for sockets created with this context. It
   should be a string in the OpenSSL cipher list format. If no cipher
   can be selected (because compile-time options or other
   configuration forbids use of all the specified ciphers), an
   "SSLError" will be raised.

   注釈: 接続時に SSL ソケットの "SSLSocket.cipher()" メソッドが、現
     在選択 されているその暗号を使います。OpenSSL 1.1.1 has TLS 1.3
     cipher suites enabled by default. The suites cannot be disabled
     with "set_ciphers()".

SSLContext.set_alpn_protocols(protocols)

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

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

   OpenSSL 1.1.0 to 1.1.0e will abort the handshake and raise
   "SSLError" when both sides support ALPN but cannot agree on a
   protocol. 1.1.0f+ behaves like 1.0.2,
   "SSLSocket.selected_alpn_protocol()" returns None.

   バージョン 2.7.10 で追加.

SSLContext.set_npn_protocols(protocols)

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

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

SSLContext.set_servername_callback(server_name_callback)

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

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

   コールバック関数 *server_name_callback* は 3 つの引数で呼び出されま
   す; 最初の引数は "ssl.SSLSocket" です。2 つ目の引数は、クライアント
   が相手をしようと意図しているサーバ名を表す文字列 (または TLS Client
   Hello がサーバ名を含まない場合は "None") です。そして 3 つ目の引数
   はオリジナルの "SSLContext" です。サーバ名引数は IDNA デコードされ
   たサーバ名です。

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

   TLS 接続の初期ネゴシエーションのフェーズですから、
   "SSLSocket.selected_alpn_protocol()", "SSLSocket.context" のような
   限られたメソッドと属性のみ使えます。 "SSLSocket.getpeercert()",
   "SSLSocket.getpeercert()", "SSLSocket.cipher()",
   "SSLSocket.compress()" メソッドは TLS 接続が TLS Client Hello より
   も先に進行していることを必要としますから、これらは意味のある値を返
   しませんし、安全に呼び出すことも出来ません。

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

   サーバ名に対する IDNA デコードのエラーがあれば、TLS 接続はクライア
   ントに対する TLS の致命的アラートメッセージ
   "ALERT_DESCRIPTION_INTERNAL_ERROR" とともに終了します。

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

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

SSLContext.load_dh_params(dhfile)

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

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

SSLContext.set_ecdh_curve(curve_name)

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

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

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

   参考:

     SSL/TLS & Perfect Forward Secrecy
        Vincent Bernat.

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

   既存の Python ソケット *sock* をラップして "ssl.SSLSocket" オブジェ
   クトを返します。 *sock* は "SOCK_STREAM" ソケットでなければなりませ
   ん; ほかのタイプのソケットはサポートされていません。

   返される SSL ソケットは、コンテキスト、その設定と証明書に関連付けら
   れます。パラメータ *server_side*, *do_handshake_on_connect*,
   *suppress_ragged_eofs* はトップレベルの関数 "wrap_socket()" のもの
   と同じ意味です。

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

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

SSLContext.session_stats()

   Get statistics about the SSL sessions created or managed by this
   context. A dictionary is returned which maps the names of each
   piece of information to their numeric values.  For example, here is
   the total number of hits and misses in the session cache since the
   context was created:

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

SSLContext.check_hostname

   "SSLSocket.do_handshake()" 呼び出し時に、 "match_hostname()" を使っ
   て接続先証明書のホスト名の合致を見るかどうか。コンテキストの
   "verify_mode" には "CERT_OPTIONAL" か "CERT_REQUIRED" をセットしな
   ければなりません。また "wrap_socket()" にはホスト名の合致をみるため
   の *server_hostname* を渡さなければなりません。

   例:

      import socket, ssl

      context = ssl.SSLContext(ssl.PROTOCOL_TLS)
      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))

   注釈: この機能にはOpenSSL0.9.8f以降が必要です。

SSLContext.options

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

   注釈: OpenSSL の 0.9.8m より古いバージョンを使う場合、値はセット
     は出来 ますがクリアが出来ません。オプションを(対応するビットをリ
     セットす ることで)クリアしようとすると "ValueError" が送出されま
     す。

SSLContext.protocol

   コンテキストの構築時に選択されたプロトコルバージョン。この属性は読
   み取り専用です。

SSLContext.verify_flags

   証明書の検証操作のためのフラグです。 "VERIFY_CRL_CHECK_LEAF" などの
   フラグをビットOR演算でセット出来ます。デフォルトでは OpenSSL は証明
   書失効リスト(CRLs)を必要ともしませんし検証にも使いません。openssl
   version 0.9.8+ でのみ利用可能です。

SSLContext.verify_mode

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


17.3.4. 証明書
==============

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

A certificate contains information about two principals.  It contains
the name of a *subject*, and the subject's public key.  It also
contains a statement by a second principal, the *issuer*, that the
subject is who they claim to be, and that this is indeed the subject's
public key.  The issuer's statement is signed with the issuer's
private key, which only the issuer knows.  However, anyone can verify
the issuer's statement by finding the issuer's public key, decrypting
the statement with it, and comparing it to the other information in
the certificate. The certificate also contains information about the
time period over which it is valid.  This is expressed as two fields,
called "notBefore" and "notAfter".

Python において証明書を利用する場合、クライアントもサーバーも自分を証
明するために証明書を利用することができます。ネットワーク接続の相手側に
証明書の提示を要求する事ができ、そのクライアントやサーバーが認証を必要
とするならその証明書を認証することができます。認証が失敗した場合、接続
は例外を発生させます。認証は下位層のOpenSSLフレームワークが自動的に行
います。アプリケーションは認証機構について意識する必要はありません。し
かし、アプリケーションは認証プロセスのために幾つかの証明書を提供する必
要があるかもしれません。

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

   -----BEGIN CERTIFICATE-----
   ... (certificate in base64 PEM encoding) ...
   -----END CERTIFICATE-----


17.3.4.1. 証明書チェイン
------------------------

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

   -----BEGIN CERTIFICATE-----
   ... (certificate for your server)...
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   ... (the certificate for the CA)...
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   ... (the root certificate for the CA's issuer)...
   -----END CERTIFICATE-----


17.3.4.2. CA 証明書
-------------------

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


17.3.4.3. 秘密鍵と証明書を一緒にする
------------------------------------

多くの場合、証明書と同じファイルに秘密鍵も格納されています。この場合、
"SSLContext.load_cert_chain()", "wrap_socket()" には "certfile" 引数だ
けが必要とされます。秘密鍵が証明書ファイルに格納されている場合、秘密鍵
は証明書チェインの最初の証明書よりも先にないといけません。

   -----BEGIN RSA PRIVATE KEY-----
   ... (private key in base64 encoding) ...
   -----END RSA PRIVATE KEY-----
   -----BEGIN CERTIFICATE-----
   ... (certificate in base64 PEM encoding) ...
   -----END CERTIFICATE-----


17.3.4.4. 自己署名証明書
------------------------

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
   %

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


17.3.5. 例
==========


17.3.5.1. SSLサポートをテストする
---------------------------------

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

   try:
       import ssl
   except ImportError:
       pass
   else:
       ...  # do something that requires SSL support


17.3.5.2. クライアントサイドの処理
----------------------------------

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

   >>> context = ssl.create_default_context()

あなた自身でセキュリティ設定を調整したいと望むなら、スクラッチからコン
テキストを作ることは出来ます(ですが正しくない設定をしてしまいがちなこ
とに警戒してください)

   >>> context = ssl.SSLContext(ssl.PROTOCOL_TLS)
   >>> context.verify_mode = ssl.CERT_REQUIRED
   >>> context.check_hostname = True
   >>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

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

サーバへの接続にこのコンテキストを使うと、 "CERT_REQUIRED" でサーバの
証明書の検証が行われます: サーバの証明書が 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.python.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'']

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


17.3.5.3. サーバーサイドの処理
------------------------------

サーバーサイドの処理では、通常、サーバー証明書と秘密鍵がそれぞれファイ
ルに格納された形で必要です。最初に秘密鍵と証明書が保持されたコンテキス
トを作成し、クライアントがあなたの信憑性をチェック出来るようにします。
そののちにソケットを開き、ポートにバインドし、そのソケットの
"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.mydomain.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.read()
       # null data means the client is finished with us
       while data:
           if not do_something(connstream, data):
               # we'll assume do_something returns False
               # when we're finished with client
               break
           data = connstream.read()
       # finished with client

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


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

ノンブロッキングソケットとともに使う場合、いくつか気をつけなければなら
ない事項があります:

* "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], [])


17.3.7. セキュリティで考慮すべき点
==================================


17.3.7.1. 最善のデフォルト値
----------------------------

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

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

対照的に、 "SSLContext" クラスのコンストラクタを自身で呼び出すことによ
って SSL コンテキストを作ると、デフォルトでは証明書検証もホスト名チェ
ックも行わないものになります。もしそうするのであれば、良いセキュリティ
レベルを知るために、どうか下の方にあるパラグラフをお読みください。


17.3.7.2. 手動での設定
----------------------


17.3.7.2.1. 証明書の検証
~~~~~~~~~~~~~~~~~~~~~~~~

"SSLContext" のコンストラクタを直接呼び出した場合、 "CERT_NONE" がデフ
ォルトとして使われます。これは接続先の身元特定をしないので安全ではあり
ませんし、特にクライアントモードでは大抵相手となるサーバの信憑性を保障
したいでしょう。ですから、クライアントモードでは "CERT_REQUIRED" を強
くお勧めします。ですが、それだけでは不十分です;
"SSLSocket.getpeercert()" を呼び出してサーバ証明書が望んだサービスと合
致するかのチェックもしなければなりません。多くのプロトコルとアプリケー
ションにとって、サービスはホスト名で特定されます; この場合、
"match_hostname()" が使えます。これらの共通的なチェックは
"SSLContext.check_hostname" が有効な場合、自動的に行われます。

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

   注釈: クライアントモードでは anonymous ciphers が有効(デフォルト
     では無 効)でない限り、 "CERT_OPTIONAL" と "CERT_REQUIRED" は同じ
     意味にな ります。


17.3.7.2.2. プロトコルのバージョン
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

SSL versions 2 と 3 は非セキュアと考えられており、それゆえその使用は危
険です。クライアントとサーバの最大限の互換性が欲しいならば、
"SSLContext.options" 属性で明示的に SSLv2, SSLv3 を無効にして
"PROTOCOL_SSLv23" を使ってください:

   context = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
   context.options |= ssl.OP_NO_SSLv2
   context.options |= ssl.OP_NO_SSLv3

上で作った SSL コンテキストは TLSv1 かそれ以降(あなたのシステムでサポ
ートされていれば)だけでの接続を許可します。


17.3.7.2.3. 暗号の選択
~~~~~~~~~~~~~~~~~~~~~~

If you have advanced security requirements, fine-tuning of the ciphers
enabled when negotiating a SSL session is possible through the
"SSLContext.set_ciphers()" method.  Starting from Python 2.7.9, the
ssl module disables certain weak ciphers by default, but you may want
to further restrict the cipher choice. Be sure to read OpenSSL's
documentation about the cipher list format. If you want to check which
ciphers are enabled by a given cipher list, use the "openssl ciphers"
command on your system.


17.3.7.3. マルチプロセス化
--------------------------

(例えば "multiprocessing" や "concurrent.futures" を使って、)マルチプ
ロセスアプリケーションの一部としてこのモジュールを使う場合、OpenSSL の
内部の乱数発生器は fork したプロセスを適切に処理しないことに気を付けて
下さい。SSL の機能を "os.fork()" とともに使う場合、アプリケーションは
親プロセスの PRNG 状態を変更しなければなりません。 "RAND_add()",
"RAND_bytes()", "RAND_pseudo_bytes()" のいずれかの呼び出し成功があれば
十分です。


17.3.8. LibreSSL support
========================

LibreSSL is a fork of OpenSSL 1.0.1. The ssl module has limited
support for LibreSSL. Some features are not available when the ssl
module is compiled with LibreSSL.

* LibreSSL >= 2.6.1 no longer supports NPN. The methods
  "SSLContext.set_npn_protocols()" and
  "SSLSocket.selected_npn_protocol()" are not available.

* "SSLContext.set_default_verify_paths()" ignores the env vars
  "SSL_CERT_FILE" and "SSL_CERT_PATH" although
  "get_default_verify_paths()" still reports them.

参考:

  "socket.socket" クラス
     下位レイヤーの "socket" クラスのドキュメント

  SSL/TLS Strong Encryption: An Introduction
     Apache WEBサーバのドキュメンテーションのイントロ

  RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II:
  Certificate-Based Key Management
     Steve Kent

  RFC 1750: Randomness Recommendations for Security
     D. Eastlake et. al.

  RFC 3280: Internet X.509 Public Key Infrastructure Certificate and
  CRL Profile
     Housley et. al.

  RFC 4366: Transport Layer Security (TLS) Extensions
     Blake-Wilson et. al.

  RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2
     T. Dierks et. al.

  RFC 6066: Transport Layer Security (TLS) Extensions
     D. 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
