ktats****@users*****
ktats****@users*****
2009年 12月 21日 (月) 13:09:18 JST
Index: docs/modules/Net-SSLeay-1.20/SSLeay.pod
diff -u /dev/null docs/modules/Net-SSLeay-1.20/SSLeay.pod:1.1
--- /dev/null Mon Dec 21 13:09:18 2009
+++ docs/modules/Net-SSLeay-1.20/SSLeay.pod Mon Dec 21 13:09:18 2009
@@ -0,0 +1,889 @@
+=head1 名前
+
+Net::SSLeay - OpenSSLやSSLeayを使うためのPerl拡張
+
+=head1 概要
+
+ use Net::SSLeay, qw(get_https post_https sslcat make_headers make_form);
+
+ ($page) = get_https('www.bacus.pt', 443, '/'); # 1
+
+ ($page, $response, %reply_headers)
+ = get_https('www.bacus.pt', 443, '/', # 2
+ make_headers(User-Agent => 'Cryptozilla/5.0b1',
+ Referer => 'https://www.bacus.pt'
+ ));
+
+ ($page, $result, %headers) = # 2b
+ = get_https('www.bacus.pt', 443, '/protected.html',
+ make_headers(Authorization =>
+ 'Basic ' . MIME::Base64::encode("$user:$pass",''))
+ );
+
+ ($page, $response, %reply_headers)
+ = post_https('www.bacus.pt', 443, '/foo.cgi', '', # 3
+ make_form(OK => '1',
+ name => 'Sampo'
+ ));
+
+ $reply = sslcat($host, $port, $request); # 4
+
+ ($reply, $err, $server_cert) = sslcat($host, $port, $request); # 5
+
+ $Net::SSLeay::trace = 2; # 0=no debugging, 1=ciphers, 2=trace, 3=dump data
+
+=head1 説明
+
+あなたが代わりに使いたいかもしれない、このディストリビューションに
+含まれているNet::SSLeay::Handleという関連するモジュールがあります。
+それは、それ独自のPODドキュメントを持っています。
+
+このモジュールは、SSLサーバー上のWebページにアクセスするためのいくつかの
+高レベルで便利な関数、独自のクライアントを書くためのsslcat()
+関数、そして最終的にはより複雑なアプリケーションのためにサーバーや
+クライアントを書くことができるようなSSLeay/OpenSSLパッケージのSSL apiへの
+アクセスを提供します。
+
+高レベルの関数については、概要で示したように、あなたのmain名前空間に
+インポートすることが、とても便利でしょう。
+
+ケース 1はセキュアなサーバからHTMLページを取り出すためのget_https()の
+典型的な呼び出しを示しています。最初の引数は接続するリモートのサーバーの
+ホスト名あるいはIPをドット区切られた数字による書き方によって与えます。
+2番目の引数はリモート側のTCPポートです（あなた自身のポートは通常のTCPのための
+高く番号が振られたものから勝手に選択されます)。3番目の引数はホスト名の
+部分を抜いたページのURLです。もし疑問があれば、<http://www.w3c.org>にある
+HTTPの仕様をあたってみてください。
+
+ケース 2は、完全に一人前のget_https()の使い方を示しています。ご覧になった通り、
+get_https()は応答と応答のヘッダを解析し、それをリストで返しています。
+それらはハッシュや後者のリファレンスで捉えることができます。またget_https()の
+4番目の引数は、応答での追加のヘッダを挿入するために使われます。
+make_headers()はリストやハッシュを、そのようなヘッダに変換する関数です。
+デフォルトではget_https()はHost（バーチャル・ホストを簡単に行えるように）と
+Accept(IISが必要としているとのこと)ヘッダを提供します。
+
+ケース 2bはパスワードで保護されているページを取得する方法を示しています。
+更なる詳細に関しては、HTTPプロトコルの仕様を参照してください。（例えばRFC2617）。
+
+ケース 3はHTML/CGIフォームをセキュアなサーバーで実行するためにpost_https()を
+呼び出します。最初の4つの引数はget_https()と同じです(空文字列('')が
+ヘッダの引数として渡されていることに注意してください)。5番目の引数は
+CGIの仕様に従って形式が整えられたフォームの内容です。この場合、
+そのように形式を整えるためにヘルパー関数make_https()が使われますが、
+どのような文字列でも渡すことができます。post_https()は自動的にリクエストに
+Content-Type と Content-Length ヘッダを付与します。
+
+ケース 4は、基本的なsslcat()関数を示しています(netcatユーティリティに
+心を動かされました :-)。これは単純にサーバーに接続し、データを送信し、
+それから応答を取得することを簡単にするスイス・アーミーナイフのような
+ものです。データの整形と応答の解析についてはあなたの責任です - sslcat()は
+単に転送するだけのものです。
+
+ケース 5は、エラーだけでなくサーバー(相手側)証明書と同様も返すことを
+可能にする、sslcat()の完全な呼び出しです。
+
+$traceグローバル変数は高レベル関数の冗長さを制御するために使うことが
+出来ます。レベル0は何もいわないことを保障します。レベル1（デフォルト）は
+エラーメッセージだけを吐き出します。
+
+=head2 APIの代替バージョン
+
+上記の関数は実際には応答ヘッダをリストで返します。それは代入されたハッシュに
+変換されます（もしクッキーの場合がそうであるかもしれないように同じヘッダが
+2回発生すると、この代入によって情報が失われるかもしれません)。処理されて
+いないヘッダとハッシュへのリファレンスを返す関数の別の形もあります。
+
+ ($page, $response, @headers) = get_https('www.bacus.pt', 443, '/');
+ for ($i = 0; $i < $#headers; $i+=2) {
+ print "$headers[$i] = " . $headers[$i+1] . "\n";
+ }
+
+ ($page, $response, $headers, $server_cert)
+ = get_https3('www.bacus.pt', 443, '/');
+ print "$headers\n";
+
+ ($page, $response, %headers_ref, $server_cert)
+ = get_https4('www.bacus.pt', 443, '/');
+ for $k (sort keys %{headers_ref}) {
+ for $v (@{$headers_ref{$k}}) {
+ print "$k = $v\n";
+ }
+ }
+
+上記の全てのちょっとしたコードは、同じ事を実現します:ヘッダの全ての値を
+表示します。"3"で終わるAPI関数はヘッダを単なるスカラーの文字列で返します。
+アプリケーションがそれを分割することになります。"4"で終わる関数は
+配列のハッシュへのリファレンスを返します(複雑なperlデータ構造体に精通して
+いなければperlrefとperllolマニュアル・ページをご覧ください)。そのような
+ヘッダ・ハッシュの1つの値にアクセスするためには、以下のようにしてください
+
+ print $headers_ref{COOKIE}[0];
+
+3と4の形は、それを格納したり表示したいときサーバー証明書を見つけることも
+可能にします。例えば
+
+ ($p, $resp, $hdrs, $server_cert) = get_https3('www.bacus.pt', 443, '/');
+ if (!defined($server_cert) || ($server_cert == 0)) {
+ warn "Subject Name: undefined, Issuer Name: undefined";
+ } else {
+ warn 'Subject Name: '
+ . Net::SSLeay::X509_NAME_oneline(
+ Net::SSLeay::X509_get_subject_name($server_cert))
+ . 'Issuer Name: '
+ . Net::SSLeay::X509_NAME_oneline(
+ Net::SSLeay::X509_get_issuer_name($server_cert));
+ }
+
+この方法は証明書の確認の後にだけ可能になるということに注意してください:
+そのときには、あなたが信用するかどうかに関わらず、get_https3()は
+サーバーに送信されたhttpsリクエストを返してしまっています。
+正しく確認するためには、OpenSSL証明書確認フレームワークを採用するか、
+最初に接続し、証明書を確認し、そのときにだけhttpデータを送信するため
+低レベルAPIを利用するかのどちらかをする必要があります。この
+やり方についてのガイダンスはds_https3()の実装をご覧ください。
+
+=head2 クライアント証明書の使い方
+
+セキュアなWeb通信はサーバーの証明書をベースにした暗号を使って
+交換された対称になった暗号鍵を使って暗号化されます。このため
+全てのSSLの通信では、サーバーは証明書を持っていなければなりません。
+これはクライアントへのサーバーの認証と鍵の交換の両方を提供します。
+
+場合によってはクライアントも認証する必要があります。2つの選択を
+利用することができます: http基本認証とクライアント側の証明書です。
+httpsがパスワードが平文で流れないことを保障するので、https越しの
+基本認証は実際には非常に安全です。しかし、そうであったとしても
+簡単にわかるようなパスワードのような問題は残ります。クライアント
+証明書の方法には証明書を使ったSSLレベルでのクライアントの認証を
+意味します。これが機能するためにはクライアントとサーバーの両方が
+(典型的には異なる)証明書と秘密鍵を持つ必要があります。
+
+上記で概説されたAPI関数は、クライアント側の証明書と鍵ファイルを
+提供することができる追加の引数を受け取ります。これらのファイルの
+形式はサーバー証明書で使われているものと同じです。そして秘密鍵の
+暗号化に関する注意も当てはまります。
+
+ ($page, $result, %headers) = # 2c
+ = get_https('www.bacus.pt', 443, '/protected.html',
+ make_headers(Authorization =>
+ 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
+ '', $mime_type6, $path_to_crt7, $path_to_key8);
+
+ ($page, $response, %reply_headers)
+ = post_https('www.bacus.pt', 443, '/foo.cgi', # 3b
+ make_headers('Authorization' =>
+ 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
+ make_form(OK => '1', name => 'Sampo'),
+ $mime_type6, $path_to_crt7, $path_to_key8);
+
+ケース 2cはクライアント証明書も必要とする、パスワードで保護された
+ページを取得することを示しています。つまり両方の認証方法を同時に
+使うことも可能です。
+
+ケース 3bは、ケース2cとちょうど同じようにパスワード認証とクライアント
+証明書の両方を必要とするセキュアなサーバーへの完全に展開された
+postです。
+
+注意: サーバーが要求しなければ、クライアントは証明書を送信しません。
+これは典型的にはサーバーで確認モードをVERIFY_PEERに設定することにより
+実現されます:
+
+ Net::SSLeay::set_verify(ssl, Net::SSLeay::VERIFY_PEER, 0);
+
+完全な説明については、perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod をご覧ください。
+
+=head2 Webプロキシーを通して動かす
+
+Net::SSLeayは接続を行うためにWebプロキシーを利用することができます。
+最初にset_proxy()を使ってプロキシーホストとポートを設定したら、
+後は通常のAPI関数を使うだけです。例えば:
+
+ Net::SSLeay::set_proxy('gateway.myorg.com', 8080);
+ ($page) = get_https('www.bacus.pt', 443, '/');
+
+あなたのプロキシーが認証を必要とするのであれば、ユーザ名とパスワードも
+与えることができます
+
+ Net::SSLeay::set_proxy('gateway.myorg.com', 8080, 'joe', 'salainen');
+ ($page, $result, %headers) =
+ = get_https('www.bacus.pt', 443, '/protected.html',
+ make_headers(Authorization =>
+ 'Basic ' . MIME::Base64::encode("susie:pass",''))
+ );
+
+この例は"joe"でプロキシーに、最終的なWebサーバーには"susie"で認証を
+行うケースを示しています。プロキシーの認証はMIME::Base64が機能することを
+必要とします。
+
+=head2 便利なルーチン
+
+低レベルで使うために
+
+ Net::SSLeay::randomize($rn_seed_file,$additional_seed);
+ Net::SSLeay::set_cert_and_key($ctx, $cert_path, $key_path);
+ $cert = Net::SSLeay::dump_peer_certificate($ssl);
+ Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
+ $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
+
+ $got = Net::SSLeay::ssl_read_CRLF($ssl [, $max_length]);
+ $got = Net::SSLeay::ssl_read_until($ssl [, $delimit [, $max_length]]);
+ Net::SSLeay::ssl_write_CRLF($ssl, $message);
+
+randomize()は/dev/urandomとオプションでユーザに与えられたデータで
+eay PRNGを種付けし(これの変更あるいは設定のやり方については、
+SSLeay.pmの先頭をご覧ください）。適切に乱数の種付けをすることは非常に
+重要です。ですから、これを呼び出すことを忘れないでください。高レベルの
+API関数は自動的にrandomize()を呼び出します。そのためそれらでは
+必要ありません。注意もご覧ください。
+
+set_cert_and_key()は引数として2つのファイル名を取り、
+それらを証明書と秘密鍵に設定します。これはサーバー証明書と
+クライアント証明書の両方に使うことが出来ます。
+
+dump_peer_certificate()は相手側(通常はサーバー)が提出した
+証明書の平文の説明を取得することを可能にします。
+
+ssl_read_all()とssl_write_all()は、これらの処理のための
+本当のブロック化の意味論で提供します(説明については下記の制限を
+ご覧ください)。これらは低レベルAPIと同じものとして非常に好まれます
+(これはBSDブロック化セマンティクを実装しています)。ssl_write_all()
+へのmessage引数はリファレンスにすることができます。これは
+何か大きなものを出力するとき、不必要なコピーを避けるために便利です。
+例えば:
+
+ $data = 'A' x 1000000000;
+ Net::SSLeay::ssl_write_all($ssl, \$data) or die "ssl write failed";
+
+ssl_read_CRLF() はssl_read_all()を使ってラインフィードが後ろについた
+キャリッジ・リターン(CRLF)で終わる行を読み込みます。CRLFは返される
+スカラーに含まれます。
+
+ssl_read_until() ssl_read_all()を使ってSSL入力インプットからプログラマに
+よって指定された区切り文字まで読み込みます。区切り文字が未定義であれば
+$/が使われます。$/が未定義であれば、\nが使われます。SSL入力ストリームからの
+読み込む最大バイト長をオプションで設定することができます。
+
+ssl_write_CRLF()はSSL出力ストリームに$messageを出力し、CRLFを追加します。
+
+=head2 低レベルAPI
+
+上記で説明した高レベル関数に加えて、このモジュールにはOpenSSL C apiの
+SSL部分にそのままアクセスすることもできます。OpenSSLのSSLサブパートだけが
+実装されています(他の部分も実装したければ、パッチを提供することをためらわない
+でください)。
+
+低レベルSSLeay関数の呼び出し方の一覧については、OpenSSL Cディストリビューション
+のssl.hヘッダをご覧ください(関数が実装されているかをチェックするためには、直接
+SSLeay.xlをご覧ください)。このモジュールではSSLeayの名前から先頭の"SSL_"を
+はずしています。一般的にはその場所にNet::SSLeayを使わなければなりません。
+例えば:
+
+Cでは:
+
+ #include <ssl.h>
+
+ err = SSL_set_verify (ssl, SSL_VERIFY_CLIENT_ONCE,
+ &your_call_back_here);
+
+perlでは:
+
+ use Net::SSLeay;
+
+ $err = Net::SSLeay::set_verify ($ssl,
+ &Net::SSLeay::VERIFY_CLIENT_ONCE,
+ \&your_call_back_here);
+
+SSL_で始まらない関数では、関数名全体を使わなければなりません。例えば:
+
+ $err = &Net::SSLeay::ERR_get_error;
+
+以下の新しい関数はperl的に振舞います:
+Following new functions behave in perlish way:
+
+ $got = Net::SSLeay::read($ssl);
+ # SSL_readを行いますが、受け取られたデータに
+ # 従って大きさが変更された$gotを返します
+ # 失敗したときにはundefを返します。
+
+ Net::SSLeay::write($ssl, $foo) || die;
+ # SSL_writeを実行します。しかし自動的に
+ # $fooの大きさを計算します。
+
+低レベルAPIを使うためには、あなたのプログラムは以下のように始まらなければ
+なりません:
+
+ use Net::SSLeay qw(die_now die_if_ssl_error);
+ Net::SSLeay::load_error_strings();
+ Net::SSLeay::SSLeay_add_ssl_algorithms(); # 重要!
+ Net::SSLeay::randomize();
+
+die_now()とdie_if_ssl_error()は、以下のように何かがおかしくなったとき
+簡単にSSLeayエラー・スタックを出力するために使用されます:
+
+ Net::SSLeay:connect($ssl) or die_now("Failed SSL connect ($!)");
+ Net::SSLeay::write($ssl, "foo") or die_if_ssl_error("SSL write ($!)");
+
+プログラムを終了させることなくエラースタックをダンプさせるために
+Net::SSLeay::print_errs()を使うことも出来ます。今見たように、main名前空間に
+エラー報告関数をインポートすれば、あなたのコードは、さらにとても読みやすく
+なります。
+
+エラーの戻り値をチェックする必要性はいくら強調しても足りません。
+非常に単純なプログラムであっても、これらの関数を使ってください。
+これらはデバッグにかかる時間を大幅に削減します。先にこれらのものを
+あなたコードのあちこちに入れることなく、メーリングリストに質問しないで
+ください。
+
+=head2 ソケット
+
+Perlは全てのI/Oにファイルハンドルを使います。SSLeayは非常に柔軟性のある
+BIO機構を持っていますし、perlはPerlIO機構を進化させていますが、
+このモジュールはファイル記述子を使うことにこだわっています。
+このためSSLeayをソケットにつけるためには、元になっているファイル記述子を
+取り出すためにfineno()を使わなければなりません:
+
+ Net::SSLeay::set_fd($ssl, fileno(S)); # finenoを使わなければなりません
+
+あなたのソケットハンドルを操作するためにperlのI/O関数を使のであれば、
+混乱しないよう、STDIOのバッファリングを止めさせるためには、"$|=1;"を
+使わなければなりません。
+
+ソケットにselect(2)する必要があれば、すぐに行ってください。ただし
+OpenSSLは内部バッファリングを行っていて、そのためソケットが読み込みの
+ために選択されているときでも(単に選択し、読み込もうとし続けるだけ)、
+常にデータを返すわけではないことに注意してください。この点で
+Net::SSLeay.pmはC言語OpenSSLとは違います。
+
+=head2 コールバック
+
+警告: 1.04で、コールバックは変更され、テストされていません。
+
+今の時点では、全てのコンテキスト、セッション、接続によって
+共有されている1つのコールバックしかないときにはいつでも、
+verify_callbackの実装は台無しになってしまいます。これは
+コールバックのCのグルーがそれを見つけられるように、スタティックな
+変数にperlコールバックへのリファレンスを入れておくためです。
+この制限を取り除くためには、SSL構造体でのコンテキスト・ポインタに加えて、
+その所有者とコールバックを対応付けるためにXSUBの中での、
+さらに複雑なデータ構造体(ハッシュのような?)を持つか、後始末をするものが必要です。
+そのときには、このコンテキストはコ−ルバックに渡されます。それは私たちのケースでは
+コンテキストから適切なPerl関数を探し出す、呼び出すための仲介役となります。
+
+---- 不正確 ----
+verifyコールバックはCでは以下のようになります:
+
+ int (*callback)(int ok,X509 *subj_cert,X509 *issuer_cert,
+ int depth,int errorcode,char *arg,STACK *cert_chain)
+
+対応するPerl関数は以下のようにものになります:
+
+ sub verify {
+ my ($ok, $subj_cert, $issuer_cert, $depth, $errorcode,
+ $arg, $chain) = @_;
+ print "Verifying certificate...\n";
+ ...
+ return $ok;
+ }
+
+こｒは以下のように使われます:
+
+ Net::SSLeay::set_verify ($ssl, Net::SSLeay::VERIFY_PEER, \&verify);
+
+復号化するための秘密鍵のためのコールバックは実装されています。しかし
+verify_callbackの実装と同じ制限を持ちます(全てのコンテキストで
+共有されている1つのパスワード・コールバック)。以下のように使うことが
+できるでしょう:
+
+ Net::SSLeay::CTX_set_default_passwd_cb($ctx, sub { "top-secret" });
+ Net::SSLeay::CTX_use_PrivateKey_file($ctx, "key.pem",
+ Net::SSLeay::FILETYPE_PEM)
+ or die "Error reading private key";
+
+その他のコールバックは実装されていません。SSLeay組込の確認機構があなたの
+ニーズを満足させているところでは、単純な(つまり通常の）ケースでは
+何もコールバックを使う必要はありません。
+---- 不正確 ここまで ----
+
+コールバックを使いたければ、examples/callback.plをご覧ください!それは
+私が信頼して動かすことができる唯一のものです。
+
+=head2 X509 と RAND について
+
+このモジュールではX509とRANDルーチンへのインターフェースが大きく欠けて
+いますが、私は怠け者で、それらを必要としていました。以下のものが実装
+されています:
+
+ $x509_name = Net::SSLeay::X509_get_subject_name($x509_cert);
+ $x509_name = Net::SSLeay::X509_get_issuer_name($x509_cert);
+ print Net::SSLeay::X509_NAME_oneline($x509_name);
+ Net::SSLeay::RAND_seed($buf); # Perl的に大きさを計算します
+ Net::SSLeay::RAND_cleanup();
+ Net::SSLeay::RAND_load_file($file_name, $how_many_bytes);
+ Net::SSLeay::RAND_write_file($file_name);
+ Net::SSLeay::RAND_egd($path);
+ $text = Net::SSLeay::X509_NAME_get_text_by_NID($name, $nid);
+
+実際には、以下のヘルパー関数を使うことを考えるべきです:
+
+ print Net::SSLeay::dump_peer_certificate($ssl);
+ Net::SSLeay::randomize();
+
+=head2 RSAインターフェース
+
+いくつかのRSA関数を利用することができます:
+
+$rsakey = Net::SSLeay::RSA_generate_key();
+Net::SSLeay::CTX_set_tmp_rsa($ctx, $rsakey);
+Net::SSLeay::RSA_free($rsakey);
+
+=head2 BIOインターフェース
+
+いくつかのBIO関数を利用することができます:
+
+ Net::SSLeay::BIO_s_mem();
+ $bio = Net::SSLeay::BIO_new(BIO_s_mem())
+ $bio = Net::SSLeay::BIO_new_file($filename, $mode);
+ Net::SSLeay::BIO_free($bio)
+ $count = Net::SSLeay::BIO_write($data);
+ $data = Net::SSLeay::BIO_read($bio);
+ $data = Net::SSLeay::BIO_read($bio, $maxbytes);
+ $is_eof = Net::SSLeay::BIO_eof($bio);
+ $count = Net::SSLeay::BIO_pending($bio);
+ $count = Net::SSLeay::BIO_wpending ($bio);
+
+=head2 低レベルAPI
+いくつかの非常に低レベルのAPI関数を使うことが出来ます:
+ $client_random = &Net::SSLeay::get_client_random($ssl);
+ $server_random = &Net::SSLeay::get_server_random($ssl);
+ $session = &Net::SSLeay::get_session($ssl);
+ $master_key = &Net::SSLeay::SESSION_get_master_key($session);
+
+=head1 使用例
+
+1つの非常に素晴らしい例は、SSLeay.pmファイルにあるsslcat()の実装を
+見ることです。
+
+(あまりにもエラー・チェックが少ない :-()簡単なSSLeayクライアントを以下に
+示します:
+
+ #!/usr/local/bin/perl
+ use Socket;
+ use Net::SSLeay qw(die_now die_if_ssl_error) ;
+ Net::SSLeay::load_error_strings();
+ Net::SSLeay::SSLeay_add_ssl_algorithms();
+ Net::SSLeay::randomize();
+
+ ($dest_serv, $port, $msg) = @ARGV; # コマンドラインを読み込みます
+ $port = getservbyname ($port, 'tcp') unless $port =~ /^\d+$/;
+ $dest_ip = gethostbyname ($dest_serv);
+ $dest_serv_params = sockaddr_in($port, $dest_ip);
+
+ socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
+ connect (S, $dest_serv_params) or die "connect: $!";
+ select (S); $| = 1; select (STDOUT); # STDIOへのバッファリングの抑止
+
+ # ネットワークへの接続が今、開きました。SSLeayに火をつけましょう...
+
+ $ctx = Net::SSLeay::CTX_new() or die_now("Failed to create SSL_CTX $!");
+ Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
+ and die_if_ssl_error("ssl ctx set options");
+ $ssl = Net::SSLeay::new($ctx) or die_now("Failed to create SSL $!");
+ Net::SSLeay::set_fd($ssl, fileno(S)); # filenoを使わなければなりません
+ $res = Net::SSLeay::connect($ssl) and die_if_ssl_error("ssl connect");
+ print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
+
+ # データの交換
+
+ $res = Net::SSLeay::write($ssl, $msg); # Perlは$msgの長さがわかります
+ die_if_ssl_error("ssl write");
+ CORE::shutdown S, 1; # 半分クローズ --> 出力はありません、サーバーにEOFを送信します
+ $got = Net::SSLeay::read($ssl); # Perlは失敗するとundefを返します
+ die_if_ssl_error("ssl read");
+ print $got;
+
+ Net::SSLeay::free ($ssl); # 接続を終了させます
+ Net::SSLeay::CTX_free ($ctx);
+ close S;
+
+簡単なSSLeay echoサーバー(forkなし)を以下に示します:
+
+ #!/usr/local/bin/perl -w
+ use Socket;
+ use Net::SSLeay qw(die_now die_if_ssl_error);
+ Net::SSLeay::load_error_strings();
+ Net::SSLeay::SSLeay_add_ssl_algorithms();
+ Net::SSLeay::randomize();
+
+ $our_ip = "\0\0\0\0"; # 全てのインターフェースにバインド
+ $port = 1235;
+ $sockaddr_template = 'S n a4 x8';
+ $our_serv_params = pack ($sockaddr_template, &AF_INET, $port, $our_ip);
+
+ socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
+ bind (S, $our_serv_params) or die "bind: $!";
+ listen (S, 5) or die "listen: $!";
+ $ctx = Net::SSLeay::CTX_new () or die_now("CTX_new ($ctx): $!");
+ Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
+ and die_if_ssl_error("ssl ctx set options");
+
+ # 以下の行は秘密鍵が暗号化されてないということがなければ、パスワードを尋ねます
+ Net::SSLeay::CTX_use_RSAPrivateKey_file ($ctx, 'plain-rsa.pem',
+ &Net::SSLeay::FILETYPE_PEM);
+ die_if_ssl_error("private key");
+ Net::SSLeay::CTX_use_certificate_file ($ctx, 'plain-cert.pem',
+ &Net::SSLeay::FILETYPE_PEM);
+ die_if_ssl_error("certificate");
+
+ while (1) {
+ print "Accepting connections...\n";
+ ($addr = accept (NS, S)) or die "accept: $!";
+ select (NS); $| = 1; select (STDOUT); # パイプがホット!
+
+ ($af,$client_port,$client_ip) = unpack($sockaddr_template,$addr);
+ @inetaddr = unpack('C4',$client_ip);
+ print "$af connection from " .
+ join ('.', @inetaddr) . ":$client_port\n";
+
+ # これでネットワーク接続を持っています、SSLeayに火をつけましょう...
+
+ $ssl = Net::SSLeay::new($ctx) or die_now("SSL_new ($ssl): $!");
+ Net::SSLeay::set_fd($ssl, fileno(NS));
+
+ $err = Net::SSLeay::accept($ssl) and die_if_ssl_error('ssl accept');
+ print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
+
+ # 接続しました。データを交換しましょう。
+
+ $got = Net::SSLeay::read($ssl); # 失敗したときにはundefを返します
+ die_if_ssl_error("ssl read");
+ print "Got `$got' (" . length ($got) . " chars)\n";
+
+ Net::SSLeay::write ($ssl, uc ($got)) or die "write: $!";
+ die_if_ssl_error("ssl write");
+
+ Net::SSLeay::free ($ssl); # 接続を終了させます
+ close NS;
+ }
+
+echoサーバをもう1つ。今度のものは/etc/inetd.confから走ります。
+そのためソケット・コードのオーバーヘッドを全て回避します。唯一の注意は、
+rsa鍵ファイルを開くことです - 暗号化をしないほうがよりうまくいきます。
+そうでなければパスワードをどこで聞けばいいのかわかりません。どのように
+STDINとSTDOUTがSSLにつながれるかに注意してください。
+
+ #!/usr/local/bin/perl
+ # /etc/inetd.conf
+ # ssltst stream tcp nowait root /path/to/server.pl server.pl
+ # /etc/services
+ # ssltst 1234/tcp
+
+ use Net::SSLeay qw(die_now die_if_ssl_error);
+ Net::SSLeay::load_error_strings();
+ Net::SSLeay::SSLeay_add_ssl_algorithms();
+ Net::SSLeay::randomize();
+
+ chdir '/key/dir' or die "chdir: $!";
+ $| = 1; # パイプがホット!
+ open LOG, ">>/dev/console" or die "Can't open log file $!";
+ select LOG; print "server.pl started\n";
+
+ $ctx = Net::SSLeay::CTX_new() or die_now "CTX_new ($ctx) ($!)";
+ $ssl = Net::SSLeay::new($ctx) or die_now "new ($ssl) ($!)";
+ Net::SSLeay::set_options($ssl, &Net::SSLeay::OP_ALL)
+ and die_if_ssl_error("ssl set options");
+
+ # inetdからネットワーク接続は既にオープンしてあるので、
+ # STDINとSTDOUTにSSLeayをつける必要があるだけです
+ Net::SSLeay::set_rfd($ssl, fileno(STDIN));
+ Net::SSLeay::set_wfd($ssl, fileno(STDOUT));
+
+ Net::SSLeay::use_RSAPrivateKey_file ($ssl, 'plain-rsa.pem',
+ &Net::SSLeay::FILETYPE_PEM);
+ die_if_ssl_error("private key");
+ Net::SSLeay::use_certificate_file ($ssl, 'plain-cert.pem',
+ &Net::SSLeay::FILETYPE_PEM);
+ die_if_ssl_error("certificate");
+
+ Net::SSLeay::accept($ssl) and die_if_ssl_err("ssl accept: $!");
+ print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
+
+ $got = Net::SSLeay::read($ssl);
+ die_if_ssl_error("ssl read");
+ print "Got `$got' (" . length ($got) . " chars)\n";
+
+ Net::SSLeay::write ($ssl, uc($got)) or die "write: $!";
+ die_if_ssl_error("ssl write");
+
+ Net::SSLeay::free ($ssl); # 接続を終わらせます
+ Net::SSLeay::CTX_free ($ctx);
+ close LOG;
+
+examplesディレクトリにも例/テストプログラムがたくさん入っています:
+
+ sslecho.pl - 上記のものと違わない簡単なサーバー
+ minicli.pl - 低レベルSSLeayルーチンを使ったクライアントを実装しています
+ sslcat.pl - 高レベルsslcatユーティリティ関数の使い方を示しています
+ get_page.pl - セキュアなサーバーからHTMLページを取り出すためのユーティリティ
+ callback.pl - 証明書の確認とコールバックの使い方を示しています
+ stdio_bulk.pl - Unixパイプ越しにSSLを行います
+ ssl-inetd-serv.pl - inetd.confから呼び出すことができるSSLサーバー
+ httpd-proxy-snif.pl - ブラウザが与えられたどのようにhttpsリクエストを送信するのか、
+ そして応答として何を受け取ったのかを見えるようにするユーティリティ
+ (とっても教育的 :-)
+ makecert.pl - 自分で署名した証明書を作成します(このモジュールを使いません)
+
+=head1 制約
+
+Net::SSLeay::readは32KBの内部バッファを利用しています。そのため1回の読み込みは、それ以上、
+多く返すことはありません。実際、通常通り1つのネットワーク・パケットに収まっているかぎり、
+1回の読み込みは、これよりもかなり少なく返します。これを回避するためには以下のように
+ループを使わなければなりません:
+
+ $reply = '';
+ while ($got = Net::SSLeay::read($ssl)) {
+ last if print_errs('SSL_read');
+ $reply .= $got;
+ }
+
+Net::SSLeay::writeには組み込まれた制約はありませんが、ネットワーク・パケット
+サイズの制限は、ここでも当てはまります。そこで以下のようにしてください:
+
+ $written = 0;
+
+ while ($written < length($message)) {
+ $written += Net::SSLeay::write($ssl, substr($message, $written));
+ last if print_errs('SSL_write');
+ }
+
+あるいは、代わりに単に以下の便利な関数を使うことも出来ます:
+
+ Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
+ $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
+
+=head1 既知のバグと注意
+
+die_if_ssl_errorがautoload可能であると、Autoloader 以下の警告を吐き出します
+
+ Argument "xxx" isn't numeric in entersub at blib/lib/Net/SSLeay.pm'
+
+
+なぜだかわかったら、私に連絡してください。
+
+SSL_set_verify()を使って設定されたコールバックが動かないようです。
+これはeayの問題かもしれません(例えばssl/ssl_lib.cの1029行をご覧ください)。
+代わりにSSL_CTX_set_verify()を使ってみてください。そして将来のバージョンで
+これが動かないようになっても驚かないでください。
+
+コールバックと証明書の確認に関しては、一般的に余りにも少ししかテストされて
+いません。
+
+特に/dev/random そして/あるいは /dev/urandom を持っていなければ、
+(Solarisプラットホームのように - しかし私はSUNskiパッケージからの
+cryptorandデーモンが、これを解決するという提案を受けたことがあります）
+乱数は十分にランダムに初期化されません。この場合、これらのデバイスを
+エミュレートすることができるサード・パーティのソフトウェア、例えば
+あるプログラムへの名前付きパイプによる方法などを調査する必要があります。
+
+乱数の初期化に関して、もう1つわかっていることは乱数が枯渇することです。
+OpenSSL、Apache-SSL、そしてApache-mod_sslフォーラムで
+広く議論されていますが、この現象は、/dev/randomを使うならば、あなたの
+スクリプトをブロックすることを、あるいは/dev/urandomを使うならば、
+セキュアでなく操作することを引き起こすかもしれません。
+発生していることは、あまりにも多くの乱数がシステムの乱数プールから
+引っ張られたとき、乱数が一時的に利用不能になることがあります。
+/dev/randomはこの問題は、十分な乱数が集められるまで待つことにより解決
+します - そしてこれには長い時間がかかることがあります。ブロックすること
+がマシンでの活動を減らしてしまい、活動が少なくなると乱数イベントも
+少なくなるためです:悪循環です。/dev/urandomは、このジレンマをより
+実用的に簡単に予測できる"ランダムな"数を返すことにより解決します。
+しかしながら、いくつかの/dev/urandomエミュレーション・ソフトウェアは
+実際には/dev/randomのセマンティクを実装しているようです。
+利用者はご注意を(Caveat emptor)。
+
+私はSolaris 8でそれらを使っているMik Firestone <mik@@speed.stdio._com>から、
+そのような2つのデーモンを指摘されました。
+
+ 1. Entropy Gathering Daemon (EGD) http://www.lothar.com/tech/crypto/
+ 2. Pseudo-random number generating daemon (PRNGD)
+ http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html
+
+他のSSL実装と通信するために低レベルAPI関数を使っているのであれば、
+以下のようにして、他のいくるかのSSL実装での、よく知られているバグをうまく
+処理するよう、以下のように呼び出すとうまくいきます
+
+ Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
+ and die_if_ssl_error("ssl ctx set options");
+
+高レベルAPI関数は常に全てのわかっている互換性オプションを設定します。
+
+時折、sslcat(そしてそれを基に構築された高レベルhttps関数)が、
+レガシーなhttpsサーバーにEOFの合図を出すのが速すぎることがあります。
+これによりサーバーが空のページを返してしまいます。この問題を回避する
+ためには、グローバル変数を設定することができます
+
+ $Net::SSLeay::slowly = 1; # 壊れたサーバーでも保持できるようsleepを追加します
+
+http/1.1はサポートされていません。明確に、このモジュールは
+接続ごとに複数のhttpリクエストを発行したり、それをサービスすることを
+知りません。これは重大な短所です。しかしサーバーでSSLセッション・キャッシュを
+使うことがCPUの負荷をいくぶん軽くすることを助けてくれます。
+
+バージョン1.09では多くの新しいOpenSSL補助関数が追加されました(
+SSLeayxsではREM_AUTOMATICALLY_GENERATED_1_09が前に付いています）。
+残念ながらこれらをテストする機会を持つことができていません。
+それらのいくつかは私が"動くだけ"だと思うに十分なほどささいなものです。
+しかし他のものは機能ポインタや全てで、どちらかといえば複雑な
+インターフェースを持っています。これらの場合には、大いに注意する
+必要があります。
+
+このモジュールはデフォルトで、自動的にもう一方が話すSSLプロトコル・コードの
+バージョンを検出するためのOpenSSL自動プロトコル・ネゴシエイションの
+コードを使います。ほとんどのWebサーバーでは、これはうまく機能します。
+しかし私は時折、モジュールがある種のWebサーバーでは動かないという
+苦情を受けます。通常これは、明示的にプロトコル・バージョンを
+設定することにより解決することができます。例えば
+
+ $Net::SSLeay::ssl_version = 2; # SSLv2を要求します
+ $Net::SSLeay::ssl_version = 3; # SSLv3を要求します
+ $Net::SSLeay::ssl_version = 10; # TLSv1を要求します
+
+自動ネゴシエイションは素晴らしいのですが、SSL標準では公式には
+そのような機能を規定していません。世界中のほとんどがSSLeay/OpenSSLの
+やり方をデファクト・スダンダードとして受け入れています。しかし
+中には違う考えを持つ人には、明示的に正しいバージョンを話さなければ
+なりません。これは本当はバグではありません。むしろ標準での欠落です。
+もしサイトが応答を拒絶したり、無意味なエラーコードを送り返してきたら、
+私にメールする前に、このオプションを試してみてください。
+
+高レベルAPIは相手側の証明書を返します。これにより、どんな証明書が
+提供されたかをチェックすることができます。しかしその事の後にだけ、
+証明書をチェックすることができます。つまり
+彼らを信頼しないことがわかったときには、あなたは既にあなたの
+フォームデータを送信しているのです。アリャマ。
+
+そこで、その事が後に証明書を知ることができることが便利だとしても、
+セキュリティを気にする人たちは、先に接続し証明書の確認を行い、
+その後にだけそのサイトとデータを交換することを選択するでしょう。
+現在、これを行う高レベルのAPI関数はありません。このため低レベルの
+APIを使ってプログラムしなければなりません。
+Net::SSLeay::http_cat()関数がどのように実装されているかを見ることから
+はじめるといいでしょう。
+
+=head1 診断情報
+
+"Random number generator not seeded!!!"
+ (日本語訳:"乱数発生装置が種付けされていません!!!")
+ この警告はrandomize()が/dev/random あるいは /dev/urandomを
+ 読むことができなかったことをしめします。おそらくあなたのシステムが
+ それらを持っていないか、別の名前になっているからでしょう。これでもSSLを
+ 使うことは出来ます。しかし暗号化はあまり強力ではありません。
+
+"open_tcp_connection: destination host not found:`server' (port 123) ($!)"
+ (日本語訳:"open_tcp_connection: 出力先ホストが見つかりませんでした:`server' (ポート 123) ($!)"
+ `server'名前のホストの名前検索が失敗しました。
+
+"open_tcp_connection: failed `server', 123 ($!)"
+ (日本語訳:"open_tcp_connection: 失敗:`server' (ポート 123) ($!)"
+ 名前は解決されましたが、TCP接続の確立が失敗しました。
+
+"msg 123: 1 - error:140770F8:SSL routines:SSL23_GET_SERVER_HELLO:unknown proto"
+ (日本語訳:"msg 123: 1 - error:140770F8:SSLルーチン:SSL23_GET_SERVER_HELLO:proto不明")
+ SSLeayエラー文字列。最初の(123)番号はPID、2番目の数字(1)はSSLeayエラー
+ スタックでのエラーメッセージの位置を示します。階段状になったエラーで、これらの
+ メッセージが重なったものを、しばしば目にするでしょう。
+
+"msg 123: 1 - error:02001002::lib(2) :func(1) :reason(2)"
+ (日本語訳:"msg 123: 1 - error:02001002::lib(2) :関数(1) :理由(2)")
+ 上記と同じ。しかしload_error_strings()を呼ばなかったので、SSLeayは
+ 多くの言葉でエラーを説明することができませんでした。それでも、
+ それがどんな意味かは以下のコマンドにより知ることができます:
+
+ /usr/local/ssl/bin/ssleay errstr 02001002
+
+秘密鍵のためのパスワードを聞かれる
+ あなたの秘密鍵が暗号化されていれば、これは通常の動きです。パスワードを
+ 与えるか、暗号化されていない秘密鍵を使うかのどちらかをする必要があります。
+ これをどのように行うかのFAQについてはOpenSSL.orgをよく見てください。
+ (あるいは単純に、`make test'の時、それを行うためだけに使われる
+ examples/makecert.plを勉強してください)
+
+=head1 バグの報告とサポート
+
+完全なバグ報告の手順はREADMEをご覧ください。一般的に、私は只では、
+馬鹿げた質問やあなたが宿題をやっていない質問について回答しません。
+
+Net::SSLeayの商用サポートは、以下のところで得られるでしょう
+
+ Symlabs (netss****@symla*****)
+ Tel: +351-214.222.630
+ Fax: +351-214.222.637
+
+=head1 バージョン
+
+このmanページ・ドキュメントは バージョン1.14、2002.3.25にリリースされました。
+
+現在2つのperlモジュールがOpenSSL Cライブラリを使っています:
+Net::SSLeay (私によってメンテされています）とSSLeay(OpenSSLチームにより
+メンテされています）。このモジュールはNet::SSLeayの一種です。
+
+このリリースを作成している辞典では、Ericのモジュールはまだ非常に不完全で、
+実務に使うことは出来ませんでした。そのためこのメンテナンス・リリースを作る
+気になりました。このモジュールはさらなる機能を入れるように進化する計画は
+ありません。つまり私はTCPソケット越しの単純なSSL接続を作ることだけに
+集中するつもりです。いつか、Eric自身のモジュールがSSLeay APIの全てを提供
+するでしょう。
+
+このモジュールはOpenSSL-0.9.6cを使っています。これは前のバージョンでは
+動きません。そしてこの後のバージョンでも動くという保障はありません。
+しかしC APIが変更されない限り、動くはずです。このモジュールはperl5.005
+あるいは5.6.0(それ以上?)を必要とします。しかし私はperl5.002以降でビルド
+できると思っています。
+
+=head1 作者
+
+Sampo Kellomaki <sampo****@symla*****>
+
+バグレポートは上記のアドレスの送ってください。一般的な質問は私あるいは
+メーリングリスト(opens****@opens***** にメールを送るか
+http://www.openssl.org/support/ にあるWebインターフェースによって
+参加してください)
+
+=head1 著作権(COPYRIGHT)
+
+Copyright (c) 1996-2002 Sampo Kellomaki <sampo****@symla*****>
+All Rights Reserved.
+
+Distribution and use of this module is under the same terms as the
+OpenSSL package itself (i.e. free, but mandatory attribution; NO
+WARRANTY). Please consult LICENSE file in the root of the OpenSSL
+distribution.
+
+While the source distribution of this perl module does not contain
+Eric's or OpenSSL's code, if you use this module you will use OpenSSL
+library. Please give Eric and OpenSSL team credit (as required by
+their licenses).
+
+And remember, you, and nobody else but you, are responsible for
+auditing this module and OpenSSL library for security problems,
+backdoors, and general suitability for your application.
+
+=head1 参考資料
+
+ Net::SSLeay::Handle - ファイル・ハンドルのインターフェース
+ ./Net_SSLeay/examples - サーバーとクライアントの例
+ <http://symlabs.com/Net_SSLeay/index.html> - Net::SSLeay.pm ホーム
+ <http://symlabs.com/Net_SSLeay/smime.html> - OpenSSLを使っている別のモジュール
+ <http://www.openssl.org/> - OpenSSL ソース、ドキュメントなど
+ opens****@opens***** - 一般的なOpenSSLメーリングリスト
+ <http://home.netscape.com/newsref/std/SSL.html> - SSL ドラフトの仕様
+ <http://www.w3c.org> - HTTPの仕様
+ <http://www.ietf.org/rfc/rfc2617.txt> - パスワードの送信方法
+ <http://www.lothar.com/tech/crypto/> - Entropy Gathering Daemon (EGD)
+ <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
+ - pseudo-random number generating daemon (PRNGD)
+ perl(1)
+ perlref(1)
+ perllol(1)
+ perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod
+