/
SSLeay.pod
1971 lines (1389 loc) · 67 KB
/
SSLeay.pod
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=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関数を利用することができます: