=encoding euc-jp

=head1 NAME

=begin original

Net::SSLeay - Perl extension for using OpenSSL or SSLeay

=end original

Net::SSLeay - OpenSSLやSSLeayを使うためのPerl拡張

=head1 SYNOPSIS

  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 DESCRIPTION

=begin original

There is a related module called Net::SSLeay::Handle included in this
distribution that you might want to use instead. It has its own pod
documentation.

=end original

あなたが代わりに使いたいかもしれない、このディストリビューションに
含まれているNet::SSLeay::Handleという関連するモジュールがあります。
それは、それ独自のPODドキュメントを持っています。

=begin original

This module offers some high level convinience functions for accessing
web pages on SSL servers, a sslcat() function for writing your own
clients, and finally access to the SSL api of SSLeay/OpenSSL package so you
can write servers or clients for more complicated applications.

=end original

このモジュールは、SSLサーバー上のWebページにアクセスするためのいくつかの
高レベルで便利な関数、独自のクライアントを書くためのsslcat()
関数、そして最終的にはより複雑なアプリケーションのためにサーバーや
クライアントを書くことができるようなSSLeay/OpenSSLパッケージのSSL apiへの
アクセスを提供します。

=begin original

For high level functions it is most convinient to import them to your
main namespace as indicated in the synopsis.

=end original

高レベルの関数については、概要で示したように、あなたのmain名前空間に
インポートすることが、とても便利でしょう。

=begin original

Case 1 demonstrates typical invocation of get_https() to fetch an HTML
page from secure server. The first argument provides host name or ip
in dotted decimal notation of the remote server to contact. Second
argument is the TCP port at the remote end (your own port is picked
arbitrarily from high numbered ports as usual for TCP). The third
argument is the URL of the page without the host name part. If in
doubt consult HTTP specifications at <http://www.w3c.org>

=end original

ケース 1はセキュアなサーバからHTMLページを取り出すためのget_https()の
典型的な呼び出しを示しています。最初の引数は接続するリモートのサーバーの
ホスト名あるいはIPをドット区切られた数字による書き方によって与えます。
2番目の引数はリモート側のTCPポートです（あなた自身のポートは通常のTCPのための
高く番号が振られたものから勝手に選択されます)。3番目の引数はホスト名の
部分を抜いたページのURLです。もし疑問があれば、<http://www.w3c.org>にある
HTTPの仕様をあたってみてください。

=begin original

Case 2 demonstrates full fledged use of get_https(). As can be seen,
get_https() parses the response and response headers and returns them as
a list, which can be captured in a hash for later reference. Also a
fourth argument to get_https() is used to insert some additional headers
in the request. make_headers() is a function that will convert a list or
hash to such headers. By default get_https() supplies Host (make virtual
hosting easy) and Accept (reportedly needed by IIS) headers.

=end original

ケース 2は、完全に一人前のget_https()の使い方を示しています。ご覧になった通り、
get_https()は応答と応答のヘッダを解析し、それをリストで返しています。
それらはハッシュや後者のリファレンスで捉えることができます。またget_https()の
4番目の引数は、応答での追加のヘッダを挿入するために使われます。
make_headers()はリストやハッシュを、そのようなヘッダに変換する関数です。
デフォルトではget_https()はHost（バーチャル・ホストを簡単に行えるように）と
Accept(IISが必要としているとのこと)ヘッダを提供します。

=begin original

Case 2b demonstrates how to get password protected page. Refer to
HTTP protocol specifications for further details (e.g. RFC2617).

=end original

ケース 2bはパスワードで保護されているページを取得する方法を示しています。
更なる詳細に関しては、HTTPプロトコルの仕様を参照してください。（例えばRFC2617）。

=begin original

Case 3 invokes post_https() to submit a HTML/CGI form to secure
server. First four arguments are equal to get_https() (note that empty
string ('') is passed as header argument). The fifth argument is the
contents of the form formatted according to CGI specification. In this
case the helper function make_https() is used to do the formatting,
but you could pass any string. The post_https() automatically adds
Content-Type and Content-Length headers to the request.

=end original

ケース 3はHTML/CGIフォームをセキュアなサーバーで実行するためにpost_https()を
呼び出します。最初の4つの引数はget_https()と同じです(空文字列('')が
ヘッダの引数として渡されていることに注意してください)。5番目の引数は
CGIの仕様に従って形式が整えられたフォームの内容です。この場合、
そのように形式を整えるためにヘルパー関数make_https()が使われますが、
どのような文字列でも渡すことができます。post_https()は自動的にリクエストに
Content-Type と Content-Length ヘッダを付与します。

=begin original

Case 4 shows the fundamental sslcat() function (inspired in spirit by
netcat utility :-). Its your swiss army knife that allows you to
easily contact servers, send some data, and then get the response. You
are responsible for formatting the data and parsing the response -
sslcat() is just a transport.

=end original

ケース 4は、基本的なsslcat()関数を示しています(netcatユーティリティに
心を動かされました :-)。これは単純にサーバーに接続し、データを送信し、
それから応答を取得することを簡単にするスイス・アーミーナイフのような
ものです。データの整形と応答の解析についてはあなたの責任です - sslcat()は
単に転送するだけのものです。

=begin original

Case 5 is a full invocation of sslcat() which allows return of errors
as well as the server (peer) certificate.

=end original

ケース 5は、エラーだけでなくサーバー(相手側)証明書と同様も返すことを
可能にする、sslcat()の完全な呼び出しです。

=begin original

The $trace global variable can be used to control the verbosity of high
level functions. Level 0 guarantees silence, level 1 (the default)
only emits error messages.

=end original

$traceグローバル変数は高レベル関数の冗長さを制御するために使うことが
出来ます。レベル0は何もいわないことを保障します。レベル1（デフォルト）は
エラーメッセージだけを吐き出します。

=head2 Alternate versions of the API

(APIの代替バージョン)

=begin original

The above mentioned functions actually return the response headers as
a list, which only gets converted to hash upon assignment (this
assignment looses information if the same header occurs twice, as may
be the case with cookies). There are also other variants of the
functions that return unprocessed headers and that return a reference
to a hash.

=end original

上記の関数は実際には応答ヘッダをリストで返します。それは代入されたハッシュに
変換されます（もしクッキーの場合がそうであるかもしれないように同じヘッダが
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";
      }
  }

=begin original

All of the above code fragments accomplish the same thing: display all
values of all headers. The API functions ending in "3" return the
headers simply as a scalar string and it is up to the application to
split them up. The functions ending in "4" return a reference to
hash of arrays (see perlref and perllol manual pages if you are
not familiar with complex perl data structures). To access single value
of such header hash you would do something like

=end original

上記の全てのちょっとしたコードは、同じ事を実現します:ヘッダの全ての値を
表示します。"3"で終わるAPI関数はヘッダを単なるスカラーの文字列で返します。
アプリケーションがそれを分割することになります。"4"で終わる関数は
配列のハッシュへのリファレンスを返します(複雑なperlデータ構造体に精通して
いなければperlrefとperllolマニュアル・ページをご覧ください)。そのような
ヘッダ・ハッシュの1つの値にアクセスするためには、以下のようにしてください

  print $headers_ref{COOKIE}[0];

=begin original

The variants 3 and 4 also allow you to discover the server certificate
in case you would like to store or display it, e.g.

=end original

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));
  }

=begin original

Beware that this method only allows after the fact verification of
the certificate: by the time get_https3() has returned the https
request has already been sent to the server, whether you decide to
tryst it or not. To do the verification correctly you must either
employ the OpenSSL certificate verification framework or use
the lower level API to first connect and verify the certificate
and only then send the http data. See implementation of ds_https3()
for guidance on how to do this.

=end original

この方法は証明書の確認の後にだけ可能になるということに注意してください:
そのときには、あなたが信用するかどうかに関わらず、get_https3()は
サーバーに送信されたhttpsリクエストを返してしまっています。
正しく確認するためには、OpenSSL証明書確認フレームワークを採用するか、
最初に接続し、証明書を確認し、そのときにだけhttpデータを送信するため
低レベルAPIを利用するかのどちらかをする必要があります。この
やり方についてのガイダンスはds_https3()の実装をご覧ください。

=head2 Using client certificates

(クライアント証明書の使い方)

=begin original

Secure web communications are encrypted using symmetric crypto keys
exchanged using encryption based on the certificate of the
server. Therefore in all SSL connections the server must have a
certificate. This serves both to authenticate the server to the
clients and to perform the key exchange.

=end original

セキュアなWeb通信はサーバーの証明書をベースにした暗号を使って
交換された対称になった暗号鍵を使って暗号化されます。このため
全てのSSLの通信では、サーバーは証明書を持っていなければなりません。
これはクライアントへのサーバーの認証と鍵の交換の両方を提供します。

=begin original

Sometimes it is necessary to authenticate the client as well. Two
options are available: http basic authentication and client side
certificate. The basic authentication over https is actually quite
safe because https guarantees that the password will not travel in
clear. Never-the-less, problems like easily guessable passwords
remain. The client certificate method involves authentication of the
client at SSL level using a certificate. For this to work, both the
client and the server will have certificates (which typically are
different) and private keys.

=end original

場合によってはクライアントも認証する必要があります。2つの選択を
利用することができます: http基本認証とクライアント側の証明書です。
httpsがパスワードが平文で流れないことを保障するので、https越しの
基本認証は実際には非常に安全です。しかし、そうであったとしても
簡単にわかるようなパスワードのような問題は残ります。クライアント
証明書の方法には証明書を使ったSSLレベルでのクライアントの認証を
意味します。これが機能するためにはクライアントとサーバーの両方が
(典型的には異なる)証明書と秘密鍵を持つ必要があります。

=begin original

The API functions outlined above accept additional arguments that
allow one to supply the client side certificate and key files. The
format of these files is the same as used for server certificates and
the caveat about encrypting private key applies.

=end original

上記で概説された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);

=begin original

Case 2c demonstrates getting password protected page that also requires
client certificate, i.e. it is possible to use both authentication
methods simultaneously.

=end original

ケース 2cはクライアント証明書も必要とする、パスワードで保護された
ページを取得することを示しています。つまり両方の認証方法を同時に
使うことも可能です。

=begin original

Case 3b is full blown post to secure server that requires both password
authentication and client certificate, just like in case 2c.

=end original

ケース 3bは、ケース2cとちょうど同じようにパスワード認証とクライアント
証明書の両方を必要とするセキュアなサーバーへの完全に展開された
postです。

=begin original

Note: Client will not send a certificate unless the server requests one.
This is typically achieved by setting verify mode to VERIFY_PEER on the
server:

=end original

注意:　サーバーが要求しなければ、クライアントは証明書を送信しません。
これは典型的にはサーバーで確認モードをVERIFY_PEERに設定することにより
実現されます:

  Net::SSLeay::set_verify(ssl, Net::SSLeay::VERIFY_PEER, 0);

=begin original

See perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod for full description.

=end original

完全な説明については、perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod をご覧ください。

=head2 Working through Web proxy

(Webプロキシーを通して動かす)

=begin original

Net::SSLeay can use a web proxy to make its connections. You need to
first set the proxy host and port using set_proxy() and then just
use the normal API functions, e.g:

=end original

Net::SSLeayは接続を行うためにWebプロキシーを利用することができます。
最初にset_proxy()を使ってプロキシーホストとポートを設定したら、
後は通常のAPI関数を使うだけです。例えば:

  Net::SSLeay::set_proxy('gateway.myorg.com', 8080);
  ($page) = get_https('www.bacus.pt', 443, '/');

=begin original

If your proxy requires authentication, you can supply username and
password as well

=end original

あなたのプロキシーが認証を必要とするのであれば、ユーザ名とパスワードも
与えることができます

  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",''))
	      );

=begin original

This example demonstrates case where we authenticate to the proxy as
"joe" and to the final web server as "susie". Proxy authentication
requires MIME::Base64 module to work.

=end original

この例は"joe"でプロキシーに、最終的なWebサーバーには"susie"で認証を
行うケースを示しています。プロキシーの認証はMIME::Base64が機能することを
必要とします。

=head2 Convenience routines

(便利なルーチン)

=begin original

To be used with Low level API

=end original

低レベルで使うために

    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);

=begin original

randomize() seeds the eay PRNG with /dev/urandom (see top of SSLeay.pm
for how to change or configure this) and optionally with user provided
data. It is very important to properly seed your random numbers, so
do not forget to call this. The high level API functions automatically
call randomize() so it is not needed with them. See also caveats.

=end original

randomize()は/dev/urandomとオプションでユーザに与えられたデータで
eay PRNGを種付けし(これの変更あるいは設定のやり方については、
SSLeay.pmの先頭をご覧ください）。適切に乱数の種付けをすることは非常に
重要です。ですから、これを呼び出すことを忘れないでください。高レベルの
API関数は自動的にrandomize()を呼び出します。そのためそれらでは
必要ありません。注意もご覧ください。

=begin original

set_cert_and_key() takes two file names as arguments and sets
the certificate and private key to those. This can be used to
set either cerver certificates or client certificates.

=end original

set_cert_and_key()は引数として2つのファイル名を取り、
それらを証明書と秘密鍵に設定します。これはサーバー証明書と
クライアント証明書の両方に使うことが出来ます。

=begin original

dump_peer_certificate() allows you to get plaintext description of the
certificate the peer (usually server) presented to us.

=end original

dump_peer_certificate()は相手側(通常はサーバー)が提出した
証明書の平文の説明を取得することを可能にします。

=begin original

ssl_read_all() and ssl_write_all() provide true blocking semantics for
these operations (see limitation, below, for explanation). These are
much preferred to the low level API equivalents (which implement BSD
blocking semantics). The message argument to ssl_write_all() can be
reference. This is helpful to avoid unnecessary copy when writing
something big, e.g:

=end original

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";

=begin original

ssl_read_CRLF() uses ssl_read_all() to read in a line terminated with a
carriage return followed by a linefeed (CRLF).  The CRLF is included in
the returned scalar.

=end original

ssl_read_CRLF() はssl_read_all()を使ってラインフィードが後ろについた
キャリッジ・リターン(CRLF)で終わる行を読み込みます。CRLFは返される
スカラーに含まれます。

=begin original

ssl_read_until() uses ssl_read_all() to read from the SSL input
stream until it encounters a programmer specified delimiter.
If the delimiter is undefined, $/ is used.  If $/ is undefined,
\n is used.  One can optionally set a maximum length of bytes to read
from the SSL input stream.

=end original

ssl_read_until() ssl_read_all()を使ってSSL入力インプットからプログラマに
よって指定された区切り文字まで読み込みます。区切り文字が未定義であれば
$/が使われます。$/が未定義であれば、\nが使われます。SSL入力ストリームからの
読み込む最大バイト長をオプションで設定することができます。

=begin original

ssl_write_CRLF() writes $message and appends CRLF to the SSL output stream.

=end original

ssl_write_CRLF()はSSL出力ストリームに$messageを出力し、CRLFを追加します。

=head2 Low level API

(低レベルAPI)

=begin original

In addition to the high level functions outlined above, this module
contains straight forward access to SSL part of OpenSSL C api. Only the SSL
subpart of OpenSSL is implemented (if anyone wants to implement other
parts, feel free to submit patches).

=end original

上記で説明した高レベル関数に加えて、このモジュールにはOpenSSL C apiの
SSL部分にそのままアクセスすることもできます。OpenSSLのSSLサブパートだけが
実装されています(他の部分も実装したければ、パッチを提供することをためらわない
でください)。

=begin original

See ssl.h header from OpenSSL C distribution for list of low lever
SSLeay functions to call (to check if some function has been
implemented see directly in SSLeay.xs). The module strips SSLeay names
of the initial "SSL_", generally you should use Net::SSLeay:: in
place. For example:

=end original

低レベルSSLeay関数の呼び出し方の一覧については、OpenSSL Cディストリビューション
のssl.hヘッダをご覧ください(関数が実装されているかをチェックするためには、直接
SSLeay.xlをご覧ください)。このモジュールではSSLeayの名前から先頭の"SSL_"を
はずしています。一般的にはその場所にNet::SSLeayを使わなければなりません。
例えば:

=begin original

In C:

=end original

Cでは:

=begin original

	#include <ssl.h>
	
	err = SSL_set_verify (ssl, SSL_VERIFY_CLIENT_ONCE,
				   &your_call_back_here);
	
In perl:

=end original

	#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);

=begin original

If the function does not start by SSL_ you should use the full
function name, e.g.:

=end original

SSL_で始まらない関数では、関数名全体を使わなければなりません。例えば:

	$err = &Net::SSLeay::ERR_get_error;

=begin original

Following new functions behave in perlish way:

=end original

以下の新しい関数はperl的に振舞います:

=begin original

	$got = Net::SSLeay::read($ssl);
                                    # Performs SSL_read, but returns $got
                                    # resized according to data received.
                                    # Returns undef on failure.

=end original

	$got = Net::SSLeay::read($ssl);
                                    # SSL_readを行いますが、受け取られたデータに
                                    # 従って大きさが変更された$gotを返します
                                    # 失敗したときにはundefを返します。

=begin original

	Net::SSLeay::write($ssl, $foo) || die;
                                    # Performs SSL_write, but automatically
                                    # figures out the size of $foo

=end original

	Net::SSLeay::write($ssl, $foo) || die;
                                    # SSL_writeを実行します。しかし自動的に
                                    # $fooの大きさを計算します。

=begin original

In order to use the low level API you should start your programs with
the following encantation:

=end original

低レベルAPIを使うためには、あなたのプログラムは以下のように始まらなければ
なりません:

=begin original

	use Net::SSLeay qw(die_now die_if_ssl_error);
	Net::SSLeay::load_error_strings();
	Net::SSLeay::SSLeay_add_ssl_algorithms();   # Important!
        Net::SSLeay::randomize();

=end original

	use Net::SSLeay qw(die_now die_if_ssl_error);
	Net::SSLeay::load_error_strings();
	Net::SSLeay::SSLeay_add_ssl_algorithms();   # 重要!
        Net::SSLeay::randomize();

=begin original

die_now() and die_if_ssl_error() are used to conveniently print SSLeay error
stack when something goes wrong, thusly:

=end original

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 ($!)");

=begin original

You can also use Net::SSLeay::print_errs() to dump the error stack without
exiting the program. As can be seen, your code becomes much more readable
if you import the error reporting functions to your main name space.

=end original

プログラムを終了させることなくエラースタックをダンプさせるために
Net::SSLeay::print_errs()を使うことも出来ます。今見たように、main名前空間に
エラー報告関数をインポートすれば、あなたのコードは、さらにとても読みやすく
なります。

=begin original

I can not emphasize enough the need to check error returns. Use these
functions even in most simple programs, they will reduce debugging
time greatly. Do not ask questions in mailing list without having
first sprinkled these in your code.

=end original

エラーの戻り値をチェックする必要性はいくら強調しても足りません。
非常に単純なプログラムであっても、これらの関数を使ってください。
これらはデバッグにかかる時間を大幅に削減します。先にこれらのものを
あなたコードのあちこちに入れることなく、メーリングリストに質問しないで
ください。

=head2 Sockets

(ソケット)

=begin original

Perl uses file handles for all I/O. While SSLeay has quite flexible BIO
mechanism and perl has evolved PerlIO mechanism, this module still
sticks to using file descriptors. Thus to attach SSLeay to socket you
should use fileno() to extract the underlying file descriptor:

=end original

Perlは全てのI/Oにファイルハンドルを使います。SSLeayは非常に柔軟性のある
BIO機構を持っていますし、perlはPerlIO機構を進化させていますが、
このモジュールはファイル記述子を使うことにこだわっています。
このためSSLeayをソケットにつけるためには、元になっているファイル記述子を
取り出すためにfineno()を使わなければなりません:

=begin original

    Net::SSLeay::set_fd($ssl, fileno(S));   # Must use fileno

=end original

    Net::SSLeay::set_fd($ssl, fileno(S));   # finenoを使わなければなりません

=begin original

You should also use "$|=1;" to eliminate STDIO buffering so you do not
get confused if you use perl I/O functions to manipulate your socket
handle.

=end original

あなたのソケットハンドルを操作するためにperlのI/O関数を使のであれば、
混乱しないよう、STDIOのバッファリングを止めさせるためには、"$|=1;"を
使わなければなりません。

=begin original

If you need to select(2) on the socket, go right ahead, but be warned
that OpenSSL does some internal buffering so SSL_read does not always
return data even if socket selected for reading (just keep on
selecting and trying to read). Net::SSLeay.pm is no different from the
C language OpenSSL in this respect.

=end original

ソケットにselect(2)する必要があれば、すぐに行ってください。ただし
OpenSSLは内部バッファリングを行っていて、そのためソケットが読み込みの
ために選択されているときでも(単に選択し、読み込もうとし続けるだけ)、
常にデータを返すわけではないことに注意してください。この点で
Net::SSLeay.pmはC言語OpenSSLとは違います。

=head2 Callbacks

(コールバック)

=begin original

WARNING: as of 1.04 the callbacks have changed and have not been tested.

=end original

警告: 1.04で、コールバックは変更され、テストされていません。

=begin original

At this moment the implementation of verify_callback is crippeled in
the sense that at any given time there can be only one call back which
is shared by all SSL contexts, sessions and connections. This is
due to having to keep the reference to the perl call back in a
static variable so that the callback C glue can find it. To remove
this restriction would require either a more complex data structure
(like a hash?) in XSUB to map the call backs to their owners or,
cleaner, adding a context pointer in the SSL structure. This context would
then be passed to the C callback, which in our case would be the glue
to look up the proper Perl function from the context and call it.

=end original

今の時点では、全てのコンテキスト、セッション、接続によって
共有されている1つのコールバックしかないときにはいつでも、
verify_callbackの実装は台無しになってしまいます。これは
コールバックのCのグルーがそれを見つけられるように、スタティックな
変数にperlコールバックへのリファレンスを入れておくためです。
この制限を取り除くためには、SSL構造体でのコンテキスト・ポインタに加えて、
その所有者とコールバックを対応付けるためにXSUBの中での、
さらに複雑なデータ構造体(ハッシュのような?)を持つか、後始末をするものが必要です。
そのときには、このコンテキストはコ−ルバックに渡されます。それは私たちのケースでは
コンテキストから適切なPerl関数を探し出す、呼び出すための仲介役となります。

=begin original

---- inaccurate ----
The verify call back looks like this in C:

=end original

---- 不正確 ----
verifyコールバックはCでは以下のようになります:

	int (*callback)(int ok,X509 *subj_cert,X509 *issuer_cert,
                        int depth,int errorcode,char *arg,STACK *cert_chain)

=begin original

The corresponding Perl function should be something like this:

=end original

対応するPerl関数は以下のようにものになります:

	sub verify {
	    my ($ok, $subj_cert, $issuer_cert, $depth, $errorcode,
		$arg, $chain) = @_;
	    print "Verifying certificate...\n";
		...
	    return $ok;
	}

=begin original

It is used like this:

=end original

こｒは以下のように使われます:

	Net::SSLeay::set_verify ($ssl, Net::SSLeay::VERIFY_PEER, \&verify);

=begin original

Callbacks for decrypting private keys are implemented, but have the
same limitation as the verify_callback implementation (one password
callback shared between all contexts.)  You might use it something
like this:

=end original

復号化するための秘密鍵のためのコールバックは実装されています。しかし
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";

=begin original

No other callbacks are implemented. You do not need to use any
callback for simple (i.e. normal) cases where the SSLeay built-in
verify mechanism satisfies your needs.
---- end inaccurate ----

=end original

その他のコールバックは実装されていません。SSLeay組込の確認機構があなたの
ニーズを満足させているところでは、単純な(つまり通常の）ケースでは
何もコールバックを使う必要はありません。
---- 不正確　ここまで ----

=begin original

If you want to use callback stuff, see examples/callback.pl! Its the
only one I am able to make work reliably.

=end original

コールバックを使いたければ、examples/callback.plをご覧ください!それは
私が信頼して動かすことができる唯一のものです。

=head2 X509 and RAND stuff

(X509 と RAND について)

=begin original

This module largely lacks interface to the X509 and RAND routines, but
as I was lazy and needed them, the following kludges are implemented:

=end original

このモジュールではX509とRANDルーチンへのインターフェースが大きく欠けて
いますが、私は怠け者で、それらを必要としていました。以下のものが実装
されています:

=begin original

    $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);   # Perlishly figures out buf size
    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);

=end original

    $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);

=begin original

Actually you should consider using the following helper functions:

=end original

実際には、以下のヘルパー関数を使うことを考えるべきです:

    print Net::SSLeay::dump_peer_certificate($ssl);
    Net::SSLeay::randomize();

=head2 RSA interface

(RSA インターフェース)

=begin original

Some RSA functions are available:

=end original

いくつかのRSA関数を利用することができます:

$rsakey = Net::SSLeay::RSA_generate_key();
Net::SSLeay::CTX_set_tmp_rsa($ctx, $rsakey);
Net::SSLeay::RSA_free($rsakey);

=head2 BIO interface

(BIO インターフェース)

=begin original

Some BIO functions are available:

=end original

いくつかの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 Low level API

(低レベル API)

=begin original

Some very low level API functions are available:

=end original

いくつかの非常に低レベルの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 EXAMPLES

=begin original

One very good example is to look at the implementation of sslcat() in the
SSLeay.pm file.

=end original

1つの非常に素晴らしい例は、SSLeay.pmファイルにあるsslcat()の実装を
見ることです。

=begin original

Following is a simple SSLeay client (with too little error checking :-(

=end original

(あまりにもエラー・チェックが少ない :-()簡単な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();

=begin original

    ($dest_serv, $port, $msg) = @ARGV;      # Read command line
    $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);   # Eliminate STDIO buffering
    
    # The network connection is now open, lets fire up SSL    

=end original

    ($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に火をつけましょう...

=begin original

    $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));   # Must use fileno
    $res = Net::SSLeay::connect($ssl) and die_if_ssl_error("ssl connect");
    print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
    
    # Exchange data
    
    $res = Net::SSLeay::write($ssl, $msg);  # Perl knows how long $msg is
    die_if_ssl_error("ssl write");
    CORE::shutdown S, 1;  # Half close --> No more output, sends EOF to server
    $got = Net::SSLeay::read($ssl);         # Perl returns undef on failure
    die_if_ssl_error("ssl read");
    print $got;
	    
    Net::SSLeay::free ($ssl);               # Tear down connection
    Net::SSLeay::CTX_free ($ctx);
    close S;

=end original

    $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;

=begin original

Following is a simple SSLeay echo server (non forking):

=end original

簡単なSSLeay echoサーバー(forkなし)を以下に示します:

=begin original

    #!/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"; # Bind to all interfaces
    $port = 1235;							 
    $sockaddr_template = 'S n a4 x8';
    $our_serv_params = pack ($sockaddr_template, &AF_INET, $port, $our_ip);

=end original

    #!/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");

    # Following will ask password unless private key is not encrypted
    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);  # Piping hot!
    
        ($af,$client_port,$client_ip) = unpack($sockaddr_template,$addr);
        @inetaddr = unpack('C4',$client_ip);
        print "$af connection from " .
	    join ('.', @inetaddr) . ":$client_port\n";
    
	# We now have a network connection, lets fire up SSLeay...

=begin original

        $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";
    
        # Connected. Exchange some data.
    
        $got = Net::SSLeay::read($ssl);     # Returns undef on fail
        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);           # Tear down connection
        close NS;
    }

=end original

    # 以下の行は秘密鍵が暗号化されてないということがなければ、パスワードを尋ねます
    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;
    }

=begin original

Yet another echo server. This one runs from /etc/inetd.conf so it avoids
all the socket code overhead. Only caveat is opening rsa key file -
it had better be without any encryption or else it will not know where
to ask for the password. Note how STDIN and STDOUT are wired to SSL.

=end original

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();

=begin original

    chdir '/key/dir' or die "chdir: $!";
    $| = 1;  # Piping hot!
    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");

=end original

    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");

=begin original

    # We get already open network connection from inetd, now we just
    # need to attach SSLeay to STDIN and STDOUT
    Net::SSLeay::set_rfd($ssl, fileno(STDIN));
    Net::SSLeay::set_wfd($ssl, fileno(STDOUT));

=end original

    # 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");

=begin original

    Net::SSLeay::free ($ssl);         # Tear down the connection
    Net::SSLeay::CTX_free ($ctx);
    close LOG;

=end original

    Net::SSLeay::free ($ssl);         # 接続を終わらせます
    Net::SSLeay::CTX_free ($ctx);
    close LOG;

=begin original

There are also a number of example/test programs in the examples directory:

=end original

examplesディレクトリにも例/テストプログラムがたくさん入っています:

=begin original

    sslecho.pl   -  A simple server, not unlike the one above
    minicli.pl   -  Implements a client using low level SSLeay routines
    sslcat.pl    -  Demonstrates using high level sslcat utility function
    get_page.pl  -  Is a utility for getting html pages from secure servers
    callback.pl  -  Demonstrates certificate verification and callback usage
    stdio_bulk.pl       - Does SSL over Unix pipes
    ssl-inetd-serv.pl   - SSL server that can be invoked from inetd.conf
    httpd-proxy-snif.pl - Utility that allows you to see how a browser
                          sends https request to given server and what reply
                          it gets back (very educative :-)
    makecert.pl  -  Creates a self signed cert (does not use this module)

=end original

    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 LIMITATIONS

(制約)

=begin original

Net::SSLeay::read uses internal buffer of 32KB, thus no single read
will return more. In practice one read returns much less, usually
as much as fits in one network packet. To work around this,
you should use a loop like this:

=end original

Net::SSLeay::readは32KBの内部バッファを利用しています。そのため1回の読み込みは、それ以上、
多く返すことはありません。実際、通常通り1つのネットワーク・パケットに収まっているかぎり、
1回の読み込みは、これよりもかなり少なく返します。これを回避するためには以下のように
ループを使わなければなりません:

    $reply = '';
    while ($got = Net::SSLeay::read($ssl)) {
	last if print_errs('SSL_read');
	$reply .= $got;
    }

=begin original

Although there is no built-in limit in Net::SSLeay::write, the network
packet size limitation applies here as well, thus use:

=end original

Net::SSLeay::writeには組み込まれた制約はありませんが、ネットワーク・パケット
サイズの制限は、ここでも当てはまります。そこで以下のようにしてください:

    $written = 0;

    while ($written < length($message)) {
	$written += Net::SSLeay::write($ssl, substr($message, $written));
	last if print_errs('SSL_write');
    }

=begin original

Or alternatively you can just use the following convinence functions:

=end original

あるいは、代わりに単に以下の便利な関数を使うことも出来ます:

    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 KNOWN BUGS AND CAVEATS

(既知のバグと注意)

=begin original

Autoloader emits

=end original

die_if_ssl_errorがautoload可能であると、Autoloader 以下の警告を吐き出します

    Argument "xxx" isn't numeric in entersub at blib/lib/Net/SSLeay.pm'

=begin original

warning if die_if_ssl_error is made autoloadable. If you figure out why,
drop me a line.

=end original

なぜだかわかったら、私に連絡してください。

=begin original

Callback set using SSL_set_verify() does not appear to work. This may
well be eay problem (e.g. see ssl/ssl_lib.c line 1029). Try using
SSL_CTX_set_verify() instead and do not be surprised if even this stops
working in future versions.

=end original

SSL_set_verify()を使って設定されたコールバックが動かないようです。
これはeayの問題かもしれません(例えばssl/ssl_lib.cの1029行をご覧ください)。
代わりにSSL_CTX_set_verify()を使ってみてください。そして将来のバージョンで
これが動かないようになっても驚かないでください。

=begin original

Callback and certificate verification stuff is generally too little tested.

=end original

コールバックと証明書の確認に関しては、一般的に余りにも少ししかテストされて
いません。

=begin original

Random numbers are not initialized randomly enough, especially if you
do not have /dev/random and/or /dev/urandom (such as in Solaris
platforms - but I've been suggested that cryptorand daemon from SUNski
package solves this). In this case you should investigate third party
software that can emulate these devices, e.g. by way of a named pipe
to some program.

=end original

特に/dev/random そして/あるいは /dev/urandom を持っていなければ、
(Solarisプラットホームのように - しかし私はSUNskiパッケージからの
cryptorandデーモンが、これを解決するという提案を受けたことがあります）
乱数は十分にランダムに初期化されません。この場合、これらのデバイスを
エミュレートすることができるサード・パーティのソフトウェア、例えば
あるプログラムへの名前付きパイプによる方法などを調査する必要があります。

=begin original

Another gotcha with random number initialization is randomness
depletion. This phenomenon, which has been extensively discussed in
OpenSSL, Apache-SSL, and Apache-mod_ssl forums, can cause your
script to block if you use /dev/random or to operate insecurely
if you use /dev/urandom. What happens is that when too much
randomness is drawn from the operating system's randomness pool
then randomness can temporarily be unavailable. /dev/random solves
this problem by waiting until enough randomness can be gathered - and
this can take a long time since blocking reduces activity in the
machine and less activity provides less random events: a vicious circle.
/dev/urandom solves this dilemma more pragmatically by simply returning
predictable "random" numbers. Some /dev/urandom emulation software
however actually seems to implement /dev/random semantics. Caveat emptor.

=end original

乱数の初期化に関して、もう1つわかっていることは乱数が枯渇することです。
OpenSSL、Apache-SSL、そしてApache-mod_sslフォーラムで
広く議論されていますが、この現象は、/dev/randomを使うならば、あなたの
スクリプトをブロックすることを、あるいは/dev/urandomを使うならば、
セキュアでなく操作することを引き起こすかもしれません。
発生していることは、あまりにも多くの乱数がシステムの乱数プールから
引っ張られたとき、乱数が一時的に利用不能になることがあります。
/dev/randomはこの問題は、十分な乱数が集められるまで待つことにより解決
します - そしてこれには長い時間がかかることがあります。ブロックすること
がマシンでの活動を減らしてしまい、活動が少なくなると乱数イベントも
少なくなるためです:悪循環です。/dev/urandomは、このジレンマをより
実用的に簡単に予測できる"ランダムな"数を返すことにより解決します。
しかしながら、いくつかの/dev/urandomエミュレーション・ソフトウェアは
実際には/dev/randomのセマンティクを実装しているようです。
利用者はご注意を(Caveat emptor)。

=begin original

I've been pointed to two such daemons by Mik Firestone <mik@@speed.stdio._com>
who has used them on Solaris 8

=end original

私はSolaris 8でそれらを使っているMik Firestone <mik@@speed.stdio._com>から、
そのような2つのデーモンを指摘されました。

   1. Entropy Gathering Daemon (EGD) at http://www.lothar.com/tech/crypto/
   2. Pseudo-random number generating daemon (PRNGD) at
        http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html

=begin original

If you are using the low level API functions to communicate with other
SSL implementations, you would do well to call

=end original

他のSSL実装と通信するために低レベルAPI関数を使っているのであれば、
以下のようにして、他のいくるかのSSL実装での、よく知られているバグをうまく
処理するよう、以下のように呼び出すとうまくいきます

    Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
         and die_if_ssl_error("ssl ctx set options");

=begin original

to cope with some well know bugs in some other SSL
implementations. The high level API functions always set all known
compatibility options.

=end original

高レベルAPI関数は常に全てのわかっている互換性オプションを設定します。

=begin original

Sometimes sslcat (and the high level https functions that build on it)
is too fast in signaling the EOF to legacy https servers. This causes
the server to return empty page. To work around this problem you can
set global variable

=end original

時折、sslcat(そしてそれを基に構築された高レベルhttps関数)が、
レガシーなhttpsサーバーにEOFの合図を出すのが速すぎることがあります。
これによりサーバーが空のページを返してしまいます。この問題を回避する
ためには、グローバル変数を設定することができます

=begin original

    $Net::SSLeay::slowly = 1;   # Add sleep so broken servers can keep up

=end original

    $Net::SSLeay::slowly = 1;   # 壊れたサーバーでも保持できるようsleepを追加します

=begin original

http/1.1 is not supported. Specifically this module does not know to
issue or serve multiple http requests per connection. This is a serious
short coming, but using SSL session cache on your server helps to
alleviate the CPU load somewhat.

=end original

http/1.1はサポートされていません。明確に、このモジュールは
接続ごとに複数のhttpリクエストを発行したり、それをサービスすることを
知りません。これは重大な短所です。しかしサーバーでSSLセッション・キャッシュを
使うことがCPUの負荷をいくぶん軽くすることを助けてくれます。

=begin original

As of version 1.09 many newer OpenSSL auxiliary functions were
added (from REM_AUTOMATICALLY_GENERATED_1_09 onwards in SSLeay.xs).
Unfortunately I have not had any opportunity to test these. Some of
them are trivial enough that I believe they "just work", but others
have rather complex interfaces with function pointers and all. In these
cases you should proceed wit great caution.

=end original

バージョン1.09では多くの新しいOpenSSL補助関数が追加されました(
SSLeayxsではREM_AUTOMATICALLY_GENERATED_1_09が前に付いています）。
残念ながらこれらをテストする機会を持つことができていません。
それらのいくつかは私が"動くだけ"だと思うに十分なほどささいなものです。
しかし他のものは機能ポインタや全てで、どちらかといえば複雑な
インターフェースを持っています。これらの場合には、大いに注意する
必要があります。

=begin original

This module defaults to using OpenSSL automatic protocol negotiation
code for automatically detecting the version of the SSL protocol
that the other end talks. With most web servers this works just
fine, but once in a while I get complaints from people that the module
does not work with some web servers. Usually this can be solved
by explicitly setting the protocol version, e.g.

=end original

このモジュールはデフォルトで、自動的にもう一方が話すSSLプロトコル・コードの
バージョンを検出するためのOpenSSL自動プロトコル・ネゴシエイションの
コードを使います。ほとんどのWebサーバーでは、これはうまく機能します。
しかし私は時折、モジュールがある種のWebサーバーでは動かないという
苦情を受けます。通常これは、明示的にプロトコル・バージョンを
設定することにより解決することができます。例えば

=begin original

   $Net::SSLeay::ssl_version = 2;  # Insist on SSLv2
   $Net::SSLeay::ssl_version = 3;  # Insist on SSLv3
   $Net::SSLeay::ssl_version = 10; # Insist on TLSv1

=end original

   $Net::SSLeay::ssl_version = 2;  # SSLv2を要求します
   $Net::SSLeay::ssl_version = 3;  # SSLv3を要求します
   $Net::SSLeay::ssl_version = 10; # TLSv1を要求します

=begin original

Although the autonegotiation is nice to have, the SSL standards
do not formally specify any such mechanism. Most of the world has
accepted the SSLeay/OpenSSL way of doing it as the de facto standard. But
for the few that think differently, you have to explicitly speak
the correct version. This is not really a bug, but rather a deficiency
in the standards. If a site refuses to respond or sends back some
nonsensical error codes (at SSL handshake level), try this option
before mailing me.

=end original

自動ネゴシエイションは素晴らしいのですが、SSL標準では公式には
そのような機能を規定していません。世界中のほとんどがSSLeay/OpenSSLの
やり方をデファクト・スダンダードとして受け入れています。しかし
中には違う考えを持つ人には、明示的に正しいバージョンを話さなければ
なりません。これは本当はバグではありません。むしろ標準での欠落です。
もしサイトが応答を拒絶したり、無意味なエラーコードを送り返してきたら、
私にメールする前に、このオプションを試してみてください。

=begin original

The high level API returns the certificate of the peer, thus allowing
one to check what certificate was supplied. However, you will only be
able to check the certificate after the fact, i.e. you already sent
your form data by the time you find out that you did not trust them,
oops.

=end original

高レベルAPIは相手側の証明書を返します。これにより、どんな証明書が
提供されたかをチェックすることができます。しかしその事の後にだけ、
証明書をチェックすることができます。つまり
彼らを信頼しないことがわかったときには、あなたは既にあなたの
フォームデータを送信しているのです。アリャマ。

=begin original

So, while being able to know the certificate after the fact is surely
useful, the security minded would still choose to do the connection
and certificate verification first and only after that exchange data
with the site. Currently none of the high level API functions do
this, thus you would have to program it using the low level API. A
good place to start is to see how Net::SSLeay::http_cat() function
is implemented.

=end original

そこで、その事が後に証明書を知ることができることが便利だとしても、
セキュリティを気にする人たちは、先に接続し証明書の確認を行い、
その後にだけそのサイトとデータを交換することを選択するでしょう。
現在、これを行う高レベルのAPI関数はありません。このため低レベルの
APIを使ってプログラムしなければなりません。
Net::SSLeay::http_cat()関数がどのように実装されているかを見ることから
はじめるといいでしょう。

=head1 DIAGNOSTICS

(診断情報)

=begin original

"Random number generator not seeded!!!"
  This warning indicates that randomize() was not able to read
  /dev/random or /dev/urandom, possibly because your system does not
  have them or they are differently named. You can still use SSL, but
  the encryption will not be as strong.

=end original

"Random number generator not seeded!!!"
  (日本語訳:"乱数発生装置が種付けされていません!!!")
  この警告はrandomize()が/dev/random あるいは /dev/urandomを
  読むことができなかったことをしめします。おそらくあなたのシステムが
  それらを持っていないか、別の名前になっているからでしょう。これでもSSLを
  使うことは出来ます。しかし暗号化はあまり強力ではありません。

=begin original

"open_tcp_connection: destination host not found:`server' (port 123) ($!)"
  Name lookup for host named `server' failed.

=end original

"open_tcp_connection: destination host not found:`server' (port 123) ($!)"
  (日本語訳:"open_tcp_connection: 出力先ホストが見つかりませんでした:`server' (ポート 123) ($!)"
  `server'名前のホストの名前検索が失敗しました。

=begin original

"open_tcp_connection: failed `server', 123 ($!)"
  The name was resolved, but establising the TCP connection failed.

=end original

"open_tcp_connection: failed `server', 123 ($!)"
  (日本語訳:"open_tcp_connection: 失敗:`server' (ポート 123) ($!)"
  名前は解決されましたが、TCP接続の確立が失敗しました。

=begin original

"msg 123: 1 - error:140770F8:SSL routines:SSL23_GET_SERVER_HELLO:unknown proto"
  SSLeay error string. First (123) number is PID, second number (1) indicates
  the position of the error message in SSLeay error stack. You often see
  a pile of these messages as errors cascade.

=end original

"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エラー
  スタックでのエラーメッセージの位置を示します。階段状になったエラーで、これらの
  メッセージが重なったものを、しばしば目にするでしょう。

=begin original

"msg 123: 1 - error:02001002::lib(2) :func(1) :reason(2)"
  The same as above, but you didn't call load_error_strings() so SSLeay
  couldn't verbosely explain the error. You can still find out what it
  means with this command:

=end original

"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

=begin original

Password is being asked for private key
  This is normal behaviour if your private key is encrypted. Either
  you have to supply the password or you have to use unencrypted
  private key. Scan OpenSSL.org for the FAQ that explains how to
  do this (or just study examples/makecert.pl which is used
  during `make test' to do just that).

=end original

秘密鍵のためのパスワードを聞かれる
  あなたの秘密鍵が暗号化されていれば、これは通常の動きです。パスワードを
  与えるか、暗号化されていない秘密鍵を使うかのどちらかをする必要があります。
  これをどのように行うかのFAQについてはOpenSSL.orgをよく見てください。
  (あるいは単純に、`make test'の時、それを行うためだけに使われる
   examples/makecert.plを勉強してください)

=head1 REPORTING BUGS AND SUPPORT

(バグの報告とサポート)

=begin original

Please see README for full bug reporting instructions. In general I do
not answer for free stupid questions or questions where you did not
do your home work.

=end original

完全なバグ報告の手順はREADMEをご覧ください。一般的に、私は只では、
馬鹿げた質問やあなたが宿題をやっていない質問について回答しません。

=begin original

Commercial support for Net::SSLeay may be obtained from

=end original

Net::SSLeayの商用サポートは、以下のところで得られるでしょう

   Symlabs (netssleay@symlabs.com)
   Tel: +351-214.222.630
   Fax: +351-214.222.637

=head1 VERSION

(バージョン)

=begin original

This man page documents version 1.14, released on 25.3.2002.

=end original

このmanページ・ドキュメントは バージョン1.14、2002.3.25にリリースされました。

=begin original

There are currently two perl modules for using OpenSSL C
library: Net::SSLeay (maintaned by me) and SSLeay (maintained by OpenSSL
team). This module is the Net::SSLeay variant.

=end original

現在2つのperlモジュールがOpenSSL Cライブラリを使っています:
Net::SSLeay　(私によってメンテされています）とSSLeay(OpenSSLチームにより
メンテされています）。このモジュールはNet::SSLeayの一種です。

=begin original

At the time of making this release, Eric's module was still quite
sketchy and could not be used for real work, thus I felt motivated to
make this maintenance release. This module is not planned to evolve to
contain any further functionality, i.e. I will concentrate on just
making a simple SSL connection over TCP socket. Presumably Eric's own
module will offer full SSLeay API one day.

=end original

このリリースを作成している辞典では、Ericのモジュールはまだ非常に不完全で、
実務に使うことは出来ませんでした。そのためこのメンテナンス・リリースを作る
気になりました。このモジュールはさらなる機能を入れるように進化する計画は
ありません。つまり私はTCPソケット越しの単純なSSL接続を作ることだけに
集中するつもりです。いつか、Eric自身のモジュールがSSLeay APIの全てを提供
するでしょう。

=begin original

This module uses OpenSSL-0.9.6c. It does not work with any earlier
version and there is no guarantee that it will work with later
versions either, though as long as C API does not change, it
should. This module requires perl5.005, or 5.6.0 (or better?) though I
believe it would build with any perl5.002 or newer.

=end original

このモジュールはOpenSSL-0.9.6cを使っています。これは前のバージョンでは
動きません。そしてこの後のバージョンでも動くという保障はありません。
しかしC APIが変更されない限り、動くはずです。このモジュールはperl5.005
あるいは5.6.0(それ以上?)を必要とします。しかし私はperl5.002以降でビルド
できると思っています。

=head1 AUTHOR

(作者)

Sampo Kellomaki <sampo@symlabs.com>

=begin original

Please send bug reports to the above address. General questions should be
sent either to me or to the mailing list (subscribe by sending mail
to openssl-users-request@openssl.org or using web interface at
http://www.openssl.org/support/).

=end original

バグレポートは上記のアドレスの送ってください。一般的な質問は私あるいは
メーリングリスト(openssl-users-request@openssl.org にメールを送るか
http://www.openssl.org/support/ にあるWebインターフェースによって
参加してください)

=head1 COPYRIGHT

Copyright (c) 1996-2002 Sampo Kellomaki <sampo@symlabs.com>
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 SEE ALSO

=begin original

  Net::SSLeay::Handle                      - File handle interface
  ./Net_SSLeay/examples                    - Example servers and a clients
  <http://symlabs.com/Net_SSLeay/index.html>  - Net::SSLeay.pm home
  <http://symlabs.com/Net_SSLeay/smime.html>  - Another module using OpenSSL
  <http://www.openssl.org/>                - OpenSSL source, documentation, etc
  openssl-users-request@openssl.org        - General OpenSSL mailing list
  <http://home.netscape.com/newsref/std/SSL.html>  - SSL Draft specification
  <http://www.w3c.org>                     - HTTP specifications
  <http://www.ietf.org/rfc/rfc2617.txt>    - How to send password
  <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

=end original

  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 ソース、ドキュメントなど
  openssl-users-request@openssl.org        - 一般的な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

=cut