For Gauche 0.9.12Search (procedure/syntax/module):

Next: , Previous: , Up: ライブラリモジュール - ユーティリティ   [Contents][Index]

12.50 rfc.tls - トランスポート・レイヤ・セキュリティ

Module: rfc.tls

このモジュールはTCPソケット上のセキュアな接続を処理します。 rfc.httpで、https接続を実現するのに使われています (HTTP参照)。

CA certificates

サーバの認証を適切に行うためには、CA証明書が必要です。 Gaucheは自前でCA証明書を持っておらず、デフォルトでシステムのCA証明書バンドルを利用します。 Unixベースのシステムでは、いくつかのよくあるパスを探索します。 例えばLinuxディストリビューションならca-certificatesやそれに類する パッケージをインストールしておくと良いでしょう。 OSXではopensslをHomebrewでインストールしておくのをおすすめします。 WindowsではWincrypt API経由でシステムの証明書ストアを使います。

デフォルトのコンフィグレーションでは、Gaucheは初期化時にシステムのCA証明書バンドルを探し、 見つかればそれを使うようになっています。かわりとなるCA証明書バンドルのパスを指定したり、 接続毎に独自の証明書を与えることもできます。

もし、何らかの理由で、システム全体で使えるCA証明書バンドルがインストールできない場合、 独自にCurlのCA証明書バンドルをhttps://curl.haxx.se/ca/cacert.pemから ダウンロードしてGaucheのインストールディレクトリに置いておくことができます。 便利なスクリプトが用意してあります。 Gaucheをインストールした後、次のコマンドを実行してください。

gosh rfc/tls/get-cacert.scm

curlがシステムにインストールされている必要があります。また、Gaucheをインストールする時に root権限で行ったのであれば、このコマンドがCA証明書バンドルをインストールする時に sudoのパスワードを尋ねるでしょう。

もしこの方法を取ることに決めたなら、時々このコマンドを実行してCA証明書バンドルを 最新版に更新するのを忘れないようにしてください。 CA証明書は期限が切れたり無効化されることがあります。

Parameter: tls-ca-bundle-path :optional path

{rfc.tls} CA証明書バンドルのパスを保持しています。値は、CA証明書バンドルファイルの パス名、シンボルsystem、あるいは#fのいずれかです。

この値がsystemの場合、Gaucheはシステムのデフォルトの証明書バンドルを 使おうとします。もしそれが見つからなければ接続時にエラーが報告されます。

この値が#fの場合、CA証明書は自動的にロードされないので、 tls-load-objectを使って自分で適切な証明書をロードしてやる必要があります。 (このオプションは<ax-tls>のみ有効です。 <mbed-tls>を使う場合は、必ず有効なCA証明書バンドルが必要です。)

デフォルトのコンフィグレーションでは、Gaucheはrfc.tlsモジュール初期化時に システムのCA証明書バンドルが使えるかどうか調べて、使えるならtls-ca-bundle-pathの 初期値をsystemに、使えないなら#fにセットします。 したがって、デフォルトのコンフィグレーションで使っている限り、 この値がsystemであればシステムのCA証明書を使えると考えて良いでしょう。

このデフォルトの振る舞いはconfigure時に--with-ca-bundleオプションで 変えられます。使っているGaucheのコンフィグレーションが変えられているかどうかは、 gauche-config --reconfigureコマンドを実行して--with-ca-bundle オプションがあるかどうかを見ればわかります。

Supported TLS subsystems

Gaucheは二つのTLSサブシステムをサポートしています。 ひとつはMbedTLS(https://tls.mbed.org/)、です。 もうひとつはAxTLS(http://axtls.sourceforge.net/)です。 configureのオプションによって組み込まれるものが変わります。 デフォルトでは、ビルド時にシステムにMbedTLSがあればそれが含まれます。 また、MbedTLSをGaucheに埋め込むことによって、 実行時にシステムにMbedTLSライブラリを必要としないバイナリを作ることもできます。 詳しくはソースツリーのINSTALL.adocを参照してください。

Gaucheは実行時に使える範囲で適切なTLSサブシステムを選択するので、 ユーザが違いを意識する必要はほとんどありません。自分でGaucheをビルドする場合は、 MbedTLSがインストールされた環境で、デフォルトのコンフィグレーションでビルドすることを 推奨します。それが最も柔軟な選択となるでしょう。

Gaucheに何らかのTLSサポートが組み込まれているかどうかは機能識別子 gauche.net.tlsで、それぞれのサブシステムが使えるかどうかは 機能識別子gauche.net.tls.axtlsgauche.net.tls.mbedtlsで 検査できます。機能識別子については機能条件式を参照してください。

Class: <tls>

{rfc.tls} An abstract base class of TLS implementations.

Class: <mbed-tls>

{rfc.tls} A class that implements mbedTLS subsystem interface.

Class: <ax-tls>

{rfc.tls} A class that implements axTLS subsystem interface.

Parameter: default-tls-class :optional class

{rfc.tls} Set/get the default TLS subsystem to be used. Without arguments, it return a class (either <ax-tls> or <mbed-tls> to be used. With one argument, which must be either <ax-tls> or <mbed-tls>, changes the default and returns the previous value.

TLS interface

Function: make-tls initargs …

{rfc.tls} Creates and returns a new TLS instance of the class default-tls-class. The returned TLS instance can be used for the tls procedures below.

The arguments must be a keyword-value list, and passed to the constructor of the TLS class.

:server-name

Server name to be used for TLS Server Name Indication extension.

:num-sessions

[AxTLS only] The number of sessions ot be used for session caching. 0 indicates no sessino caching.

:options

[AxTLS only] Bitflags of options. Logical OR of the following numeric constants.

SSL_SERVER_VERIFY_LATER

(client only) Let handshake success even the server authentication fails.

SSL_CLIENT_AUTHENTICATION

(server only) Request client sertificate to be authenticated.

Function: tls-connect tls host port proto
Function: tls-connect tls socket

{rfc.tls} Establishes TLS connection as a client. The first form is the recommended API. The second form is only kept for the backward compatibility, may not work on the newer MbedTLS, and will be removed in future.

The tls argument must be an unconnected TLS object. The host and port arguments are strings to specify server’s hostname and port. Besides the common hostname, IP notation (e.g. "127.0.0.1" or "[::1]") are allowed in host. Numeric notation (e.g. "443") or service name (e.g. "https") are allowed in port. The proto argument must be either one of the symbols tcp or udp.

On success, it returns tls, which is in connected state. It can be used to read/write data from/to the connected peer.

In the second, deprecated form, the socket argument must be a connected socket. The socket is owned by tls object and should not be directly accessed after calling this procedure.

Function: tls-accept tls socket

{rfc.tls} NB: This API is deprecated. It is incompatible to the newer MbedTLS. We plan to provide an alternative API, with which you can “bind” a tls object and then “accept” the client connection, without touching the underlying sockets.

Establishes TLS connection as a server. The tls argument must be an unconnected TLS object, and the socket argument must be a listening socket. On success, it returns tls, which is in connected state. It can be used to read/write data from/to the connected peer.

Function: tls-close tls

{rfc.tls} Shuts down the underling connection. The peer will notified the connection is closed. Once tls is closed, it can no longer be used, but the reosurces won’t be collected until tls is GC-ed or tls-destroy is called. We recommend the user call tls-destroy explicitly.

Function: tls-destroy tls

{rfc.tls} Releases resources associated to tls.

Function: tls-input-port tls
Function: tls-output-port tls

{rfc.tls} If tls is connected, it returns input and output port to communicate with the peer, respectively.

If tls is not connected, #f is returned.

Function: tls-load-object tls type filename :optional password

{rfc.tls} This procedure is only meaningful for <axl-tls>. For <mbed-tls>, this procedure does nothing.

Load private keys or certificates stored in a file specified by filenames. The type of object is specified by type argument with one of the following numberic constants. If the file requires a password, it should be given to password.

SSL_OBJ_X509_CERT
SSL_OBJ_X509_CACERT
SSL_OBJ_RSA_KEY
SSL_OBJ_PKCS8
SSL_OBJ_PKC12
Constant: SSL_OBJ_X509_CERT
Constant: SSL_OBJ_X509_CACERT
Constant: SSL_OBJ_RSA_KEY
Constant: SSL_OBJ_PKCS8
Constant: SSL_OBJ_PKCS12

{rfc.tls}


Next: , Previous: , Up: ライブラリモジュール - ユーティリティ   [Contents][Index]


For Gauche 0.9.12Search (procedure/syntax/module):