Skip to content

Latest commit

 

History

History
1760 lines (1185 loc) · 57.5 KB

File metadata and controls

1760 lines (1185 loc) · 57.5 KB

NAME

IO::Socket::SSL -- IO::Socket::INET ��勉�������勉�祉�������ó����������� SSL ��勉�˨����祉�����

SYNOPSIS

use strict;
use IO::Socket::SSL;

my $client = IO::Socket::SSL->new("www.example.com:https") 
        || warn "I encountered a problem: ".IO::Socket::SSL::errstr();
$client->verify_hostname( 'www.example.com','http' )
        || die "hostname verification failed";

print $client "GET / HTTP/1.0\r\n\r\n";
print <$client>;

DESCRIPTION

�����勉�≪�吾�ャ�若�˨�壔�ŝ�≪�若����勉�泣�若�������壔�í�ゃ�≪�潟����̬拶�����������������˨����若�帥�� ����垸����������������� SSL ���篏帥�����IO::Socket::INET ��勌撮��������˨�ŝ����㋚���� 綏勤昭綣���勌撮��水����с����� IO::Socket::SSL ��壠�������ʋ����純�������c�� SSL ��壔�í�ゃ�≪�潟����� ��泣�若����≪����ŝ�宴�若�激�с�潟����吾�����������綽�荀���ɾ�劫�ャ�ʋ����純�������⓾�泣����若�� �����⓾����障��: 茲���違�� SSL ��潟�潟����㏍�鴻���������垩�勰�御�����荐惹����吾�勖��荐若���������� SSL �����若�吾�с�潟�勰�御����� ��������̥�劫�ャ�˨��mod_perl ��с��絎�������罘���純����障�����

SSL �����������障�т戎��c�������������ŝ�������違�������勉�≪�吾�ャ�若�˨��篏帥������������������� 'SSL ��勌戎������'���������篁���蚊��茯㏍����鴻����с�����

�����勉�≪�吾�ャ�若�˨��篁ュ�����篏帥�c�������������������勉�с�������違��茯㏍�睡�������⓾�������������� �����������勉�������若�吾�с�� 0.93 篁ヤ����壚札������ IO::Socket::SSL ��������������ゃ����勐����眼�� ��������������с��(��鴻�̬�������ゃ�̹�≪�����羈������������с����⓾�����������)���

��������㏍����壔�純�宴��������篏帥�c�⓾�������ŝ�����茯㏍�睡�������⓾�����������; �����若�吾�с�� 0.98 ��ч�������㏍����壔�̹�≪����⓾�����������絲上�����菴遵����������⓾����障�����

�����������鴻�㋘�������т戎��������������⓾�������ŝ�����BUGS ��勤ą��������с����⓾��������������

METHODS

(��<�純�����)

IO::Socket::SSL ��� IO::Socket::INET ��������<�純��������膓���帥�����綽�荀����綽������⓾�������� ��ŝ�若����若�í�ゃ�������⓾����障����� SSL�����í�若����������違����<�純����������������壩��篏��� 腥冴�ŝ�鴻��(�����⓾�勉�潟�潟����㏍�鴻����у��)���菴������障����� ��ñ�◑����勤����鴻�����紊���眼����������<�純����������������с�����筝�綺⓾�� �����㏍�ャ�<�潟�������������⓾����障��:

new(...)

��違����� IO::Socket::SSL ��ŝ����吾�с�壔�����篏���������障����� (��ŝ����激�с�潟��)篁ヤ����勉����勉����˨����⓾��IO::Socket::INET ��˨�ゃ����⓾����� 荀ɱ����ŝ�ŝ����激�с�潟�勐����⓾��篏帥�������������堺�ャ�障��:

SSL_version

�����若�帥��荵∫����������������˩戎���������SSL�����㏍����潟�˨�勉����若�吾�с�潟��荐㊤�������障����� ��������í�˨����� SSLv2/3 ��с����� ��������� SSLv2 ��� SSLv3 ��◑�ɱ�������眼�激����ゃ�����茵������障����� �����勉����������������〠⓲��������ŝ����勉�с�������違�� 'SSLv2', 'SSLv3',������������'TLSv1'(紊ф��絖�/絨����絖���壠�阪�ャ�������障�����) ������絎������������������с����障�����

SSL_cipher_list

�����勉�ŝ����激�с�潟��荐㊤������������������・膓���勉�������勖���垩�ŝ�鴻��������絎������������ゃ�˨�ŝ����障��; ��ゃ�障�����'ALL:!LOW:!EXP:!ADH' ��勉�������ŝ����勉�с����� ��������ŝ��荅括完��˨�ゃ����⓾�壔��OpenSSL ��勖���� (http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS) ��� �����с����⓾�������������� �����勉�ŝ����激�с�潟��篏帥����ŝ����������祉�������í�勐�翫����̹�í����⓾����� openssl ��勛����粋昭��帥� ��������í�˨�����篏帥�������障�����

SSL_use_cert

���������荐㊤�����������������SSL ��壔�í�ゃ�≪�潟�������祉�������≪����������⓾�������������с�������� IO::Socket::SSL ��̬┝�����吾�◒�泣��篏帥��������綣桁�吟�������障����� ���������0(��������í�˨��)�� 荐㊤�������������������泣�若����������☀┃絎���������������˨��������荐惹����吾�◒�泣��綽�荀���˨�ŝ����障�����

SSL_server ���荐㊤�����������������SSL_use_cert ��壩��藥���̬┃絎���������障����� 箴水�í�勉�������˨�����������荐㊤����������ŝ����⓾�� (SSL_cert_file ��ŝ�í��) 篏睡��������荐惹����吾��荐㊤�����������������荐㊤����������障�����

SSL_server

��純�宴����������泣�若����������☖戎�����������翫����˨��������荐㊤�������障����� ������������腓榊����̬┃絎������������������純�宴��������篏������������������ Listen ���筝����������������������篁勐�������障�����

SSL_key_file

�����ŝ����� RSA 腱�絲���泣����������í�˨����勐�贋�� (��泣�若�������� certs/server-key.pem��� ��壔�í�ゃ�≪�ゃ�潟�������� certs/client-key.pem) ��˨�ŝ�������違�������������ャ�勐�贋����� ���絎���������������˩戎�����ŝ����激�с�潟����с����� (SSL_passwd_cb ��ŝ����激�с�潟�����絎������ŝ��������) ��泣�� PEM 綵√����˨������������垸����������⓾�������違����純�宴��������篏���������������˨����鴻�壔�若����� ��ュ����������������勉����㏍�潟��������茵◐ず��������障�����

SSL_key

��������� EVP_PKEY* ��с��SSL_key_file ��勌撮��������˩戎��������障����� ��㏍�若�������<�ゃ�˨�勐就��с�壚����������⓾�������������������˩�����������������絖���������� ���緇���������翫�������������с�� (���絖���������� EVP_PKEY* ���緇������˨�� openssl �� PEM_read_bio_PrivateKey ��ŝ�í�������с����⓾�����������)���

SSL_cert_file

�����ŝ����� SSL 荐惹����吾����������í�˨����勐�贋��(��泣�若�������� certs/server-cert.pem��� ��壔�í�ゃ�≪�潟�������� certs/client-cert.pem )��˨�ŝ�������違�������勉�ŝ����激�с�潟��篏帥�c� 荐惹����吾�勐�贋��������絎������ŝ�������違�ŝ����障�������� ��泣�◑┝�����吾�� SSL ��泣�若����勉�������˨����� 綽������с��������������羈���������⓾�������������� �����勉�����茯�荐若�������ŝ����壔�í�ゃ�≪�潟�����荐㊤����������������˨�壔�������������勉�ŝ����激�с�潟�� 荐㊤����������������̥�í�����������綽�荀���壔�������障��������

SSL_cert

��������� X509* ��障����� X509* ��勰�������с����� ��������� X509* ��虁┝�����吾�勐����◑;�憗�с��綣����膓���������勉�虁申�����勤┝�����吾�с����� (SSL �����������㏍�㏍�激�勉��������) ��������̬┝�����吾��篏���������⓾����������� ���絖����������荐惹����吾�����緇������������������������с�� (���絖���������� X509* ���緇������号����˨�ゃ����⓾�� openssl ��� PEM_read_bio_X509 ��ŝ�í�� �����с����⓾�����������)���

SSL_dh_file

Diffie-Hellman ��灸困������茵������������翫�������������ч�ï����ŝ����<�ゃ�˨�����絎���������� SSL_dh 綣���違��篏帥��綽�荀������������障����� ��������ŝ�������宴�˨�ゃ����⓾�� openssl ��� dhparam ��潟����潟����������с����⓾��������������

SSL_dh

SSL_dh_file ������罕���с�������������<�ゃ�˨�����絎�������篁c�������˩�������̬˛��粋昭��������� ������������ DH* ���篏帥����障�����

SSL_passwd_cb

�����ŝ����勛��絲���泣������垸����������⓾�������ŝ����違��Net::SSLeay ��������勉�������í�˨����勉����鴻�壔�若�� �����㏍�潟�������������障�������ŝ����������������障�������� �����勉�ŝ����激�с�潟�夌��絲���泣��緇ï垸�����������������綽�荀������������������鴻�壔�若�����菴���� ��泣����˨�若����潟�吾�勉�ŝ����<�㋘�潟�鴻����������障�����

SSL_ca_file

��御����勤┝�����吾�������<�����������茯�荐弱��(certificate authority)��˨����c�☎讐������������������ 腆肴����������������違��certs/my-ca.pem ��˨�ŝ�������違�������<�����������茯�荐弱���� 荐惹����吾����ャ�c�⓾����������<�ゃ�˨�勐�贋�����腓冴����������������勉�ŝ����激�с�潟�� 篏帥����ŝ�������違�ŝ����障��������

SSL_ca_path

OpenSSL �����㏍�ャ�<�潟����̹��絽吾�̥仮��������⓾�������違��荐惹����吾�勉�ゃ�潟�������壔�鴻��筝�膩��� 篆♂�若��������荐惹����吾����ャ�勉����<�ゃ�˨�������☗�ャ�c�⓾����������c�㋘�壔����ŝ��荐㊤����������⓾����������� ��������障�������� 腆肴����勉�������˨�������勉����c�㋘�壔����ŝ��篏帥�������������違����������⓾����勉����c�㋘�壔����ŝ�� ca/ ��с�ŝ�������違��IO::Socket::SSL ��������с�������鴻����贋�����腓冴���������������� ��ŝ����激�с�潟��篏帥�c�⓾��������������

SSL_verify_mode

�����勉�ŝ����激�с�潟�夌�御����勤┝�����吾�勉�������勛∈茯���≪�若�����荐㊤�������障����� ��������í�˨�� (0x00) ��壚�����茯�荐若��茵������障�������� ��������í�˨�����紊���眼��������������0x01 (��御�����腆肴��), 0x02 (��御����勤┝�����吾�� ��ŝ�������亥∈茯�紊掩��;��壔�í�ゃ�≪�潟�����絲障����⓾�夌�∴��), 0x04 (筝�綺⓾����壔�í�ゃ�≪�潟����夌∈茯�) ���腟���水����������������������с����障����� ��������ŝ�������宴�˨�ゃ����⓾�� OpenSSL man �����若�吾�� SSL_CTX_set_verify ��� �����с����⓾��������������

SSL_verify_callback

If you want to verify certificates yourself, you can pass a sub reference along with this parameter to do so. When the callback is called, it will be passed: 1) a true/false value that indicates what OpenSSL thinks of the certificate, 2) a C-style memory address of the certificate store, 3) a string containing the certificate's issuer attributes and owner attributes, and 4) a string containing any errors encountered (0 if no errors). The function should return 1 or 0, depending on whether it thinks the certificate is valid or invalid. The default is to let OpenSSL do all of the busy work. (TBT)

SSL_verifycn_scheme

Set the scheme used to automatically verify the hostname of the peer. See the information about the verification schemes in verify_hostname. The default is undef, e.g. to not automatically verify the hostname. (TBT)

SSL_verifycn_name

Set the name which is used in verification of hostname. If SSL_verifycn_scheme is set and no SSL_verifycn_name is given it will try to use the PeerHost and PeerAddr settings and fail if no name caan be determined. (TBT)

Using PeerHost or PeerAddr works only if you create the connection directly with IO::Socket::SSL->new, if an IO::Socket::INET object is upgraded with start_SSL the name has to be given in SSL_verifycn_name. (TBT)

SSL_check_crl

If you want to verify that the peer certificate has not been revoked by the signing authority, set this value to true. OpenSSL will search for the CRL in your SSL_ca_path, or use the file specified by SSL_crl_file. See the Net::SSLeay documentation for more details. Note that this functionality appears to be broken with OpenSSL < v0.9.7b, so its use with lower versions will result in an error. (TBT)

SSL_crl_file

If you want to specify the CRL file to be used, set this value to the pathname to be used. This must be used in addition to setting SSL_check_crl. (TBT)

SSL_reuse_ctx

筝�荐���勉�ŝ����激�с��(SSL_version ������ SSL_check_crl; ��������� SSL_cipher_list ��壔�� ��障����˨�障����障�����)������IO::Socket::SSL ��勐����勉�ゃ�潟�鴻�帥�潟�鴻�勉������� 荐㊤�������⓾�������違����������� SSL_reuse_ctx �����í�<�若�帥�勐�ゃ�������〠検�����������˨�������� �����勉�ゃ�潟�鴻�帥�潟�鴻�� SSL ��潟�潟����㏍�鴻����������ñ�������������������с����障����� ��障������・膓���ŝ����激�с�潟�����絎���������˨����������ф検�����������с�� �����帥�勉�潟�潟����㏍�鴻����ŝ����激�с�潟��篏帥�c�� IO::Socket::SSL::SSL_Context ��壔�í�鴻� ��違�������ゃ�潟�鴻�帥�潟�鴻��篏���������������с����障�����

�����勉�ŝ����激�с�潟��篏帥��������new() ��吾�勐�������若�喝�冴����ф検�����������潟�潟����㏍�鴻����̹�∫�c����� �����勌�������⓾�勉�ŝ����激�с�潟�壔��羝<����������潟�潟����㏍�鴻�������≦�鴻�с�ŝ�������������∴����������障����� v0.90 ������������ IO::Socket::SSL �����壠��絲障�˨��set_default_context() ��∽�違�� 篏帥����ŝ�������������違�㏍�若����˨�� SSL ��潟�潟����㏍�鴻����壩��藥���勉����<�˨� 篏帥�������ŝ�����������羈���������⓾��������������

SSL_session_cache_size

If you make repeated connections to the same host/port and the SSL renegotiation time is an issue, you can turn on client-side session caching with this option by specifying a positive cache size. For successive connections, pass the SSL_reuse_ctx option to the new() calls (or use set_default_context()) to make use of the cached sessions. The session cache size refers to the number of unique host/port pairs that can be stored at one time; the oldest sessions in the cache will be removed if new ones are added. (TBT)

SSL_session_cache

Specifies session cache object which should be used instead of creating a new. Overrules SSL_session_cache_size. This option is useful if you want to reuse the cache, but not the rest of the context. (TBT)

A session cache object can be created using IO::Socket::SSL::Session_Cache->new( cachesize ). (TBT)

Use set_default_session_cache() to set a global cache object. (TBT)

SSL_error_trap

When using the accept() or connect() methods, it may be the case that the actual socket connection works but the SSL negotiation fails, as in the case of an HTTP client connecting to an HTTPS server. Passing a subroutine ref attached to this parameter allows you to gain control of the orphaned socket instead of having it be closed forcibly. The subroutine, if called, will be passed two parameters: a reference to the socket on which the SSL negotiation failed and and the full text of the error message. (TBT)

close(...)

close() ���篏帥����������˨�ゃ����〠絵��������ŝ�������違��wait ��̹�∫�c����⓾�������ゃ���� �����c�������ɾ�������������障����� ��障����������˨�純�宴�������� shutdown() ���篏帥�c�⓾�������������������˨����� ��違�c����������˨�ŝ����障����� SSL �����㏍����潟�˨�壔�純�宴����������壔�㏍�若�阪����� SSL "close notify" ��<����祉�若�吾�� ���篆<��������������罔ó�����筝���������純�宴�������勖�梧昭��帥����c����˨����壔�㏍�若�冴����� shutdown() ��� close() ��若�喝�冴����������潟�違�������⓾����障����障����� ��������������ɾ����宴�с��(��泣�若����� fork ������������)��純�宴�������勉�潟����若�� close �����������������������������勉�純�宴�������˨��綵演�帥��筝������障����� �����������勐�馹���������帥�������������� 篁ヤ����勉����í�<�若�帥�� 1 ��ゃ����������虁����違�с�ŝ����吾�с�壔����������勖�吾���� (箴������� socket->close(SSL_no_shutdown => 1)) ��� close() ��� ��若�喝�冴����⓾��������������

SSL_no_shutdown

true ��ゃ�̬┃絎������������������勉�ŝ����激�с�潟�壔��shutdown() �����純�宴�������勉�潟����若� ��������⓾�������ŝ����違��close() ��˨��close ���篏������馹���ŝ�鎘�篋���с�������������� ��������������純�宴��������絲障����� SSL_shutdown() ���篏帥����ŝ����������˨�������障�����

SSL_fast_shutdown

If set to true only a unidirectional shutdown will be done, e.g. only the close_notify (see SSL_shutdown(3)) will be called. Otherwise a bidrectional shutdown will be done. If used within close() it defaults to true, if used within stop_SSL() it defaults to false. (TBT)

SSL_ctx_free

�����������壔�㏍�若�冴�������������������勉�純�宴�������� SSL ��潟�潟����㏍�鴻�������翫�������������������� 腆阪����˨�������������違�������勉�ŝ����激�с�潟�� true ��ゃ�̬┃絎������⓾��������������

peek(...)

�����勰�∽�違��sysread()�����������������吾����鴻�������障����� ��������⓾�祉�������ï�����篁�篋����茵������障��(��純�宴����������������若�帥��茯㏍�粋昭��帥�障��)��� �����������g�������☗�����綣���違�� peek() �����若�喝�冴�����������腟�������菴������������˨�� 茯㏍�粋昭��推��臀勉����蚊����障�������� �����勰�∽�違��罘���純�������������˨�壔��OpenSSL 0.9.6a 篁ラ�����綽�荀���с�����

pending()

�����勰�∽�違�壔�������˨�純�宴�����������茯㏍�粋昭������������羣���������с����������若�帥�勉����ゃ����違�� ��������⓾�������障����� ��������夌�鴻�˨����㏍����壔�������純�宴�������ц˛��粋昭��帥�������⓾�������������������純�宴�����莇������ ��違����������若�帥�����篆<����������������ャ����������������勉�������˨�夌�鴻�˩戎��������������с�����������

get_cipher()

IO::Socket::SSL ���篏帥�c�⓾���������垩�����絖������勐就��ц�������障�����

dump_peer_certificate()

��御����� SSL 荐惹����吾�������御�������c�若�˨�������ャ�c��茹f���櫝�純�ʋ��絖�������菴������障����� �����勉�<�純�������� Net::SSLeay ��� dump_peer_certificate() ��<�純�������勛����������贋・��� 菴������障�����

peer_certificate($field)

��御����勤┝�����吾����������違�������勰�∽�違�壔�������������ゃ����������冴����障����� �����c�若�˨��������絎���������ŝ����c����翫����� Net::SSLeay ��������勤┝�����吾� �����◑;�憗��菴���������障����� 篁ヤ����勉����c�若�˨����������������������������������с����障��:

authority (alias issuer)

荐惹����吾�̥讐��������⓾�����茯�荐弱�����

owner (alias subject)

荐惹����吾�勛�肴��������

commonName (alias cn) - only for Net::SSLeay version >=1.30

筝���㋚��; ���絽吾�� SSL 荐惹����吾�勉�泣�若��������

subjectAltNames - only for Net::SSLeay version >=1.33

Alternative names for the subject, usually different names for the same server, like example.org, example.com, *.example.com. (TBT)

It returns a list of (typ,value) with typ GEN_DNS, GEN_IPADD etc (these constants are exported from IO::Socket::SSL). See Net::SSLeay::X509_get_subjectAltNames. (TBT)

verify_hostname($hostname,$scheme)

This verifies the given hostname against the peer certificate using the given scheme. Hostname is usually what you specify within the PeerAddr. (TBT)

Verification of hostname against a certificate is different between various applications and RFCs. Some scheme allow wildcards for hostnames, some only in subjectAltNames, and even their different wildcard schemes are possible. (TBT)

To ease the verification the following schemes are predefined: (TBT)

ldap (rfc4513), pop3,imap,acap (rfc2995), nntp (rfc4642)

Simple wildcards in subjectAltNames are possible, e.g. *.example.org matches www.example.org but not lala.www.example.org. If nothing from subjectAltNames match it checks against the common name, but there are no wildcards allowed. (TBT)

http (rfc2818), alias is www

Extended wildcards in subjectAltNames are possible, e.g. *.example.org or even www*.example.org. Wildcards in the common name are not allowed. The common name will be only checked if no names are given in subjectAltNames. (TBT)

smtp (rfc3207)

This RFC doesn't say much useful about the verification so it just assumes that subjectAltNames are possible, but no wildcards are possible anywhere. (TBT)

The scheme can be given either by specifying the name for one of the above predefined schemes, by using a callback (see below) or by using a hash which can have the following keys and values: (TBT)

check_cn: 0|'always'|'when_only'

Determines if the common name gets checked. If 'always' it will always be checked (like in ldap), if 'when_only' it will only be checked if no names are given in subjectAltNames (like in http), for any other values the common name will not be checked. (TBT)

wildcards_in_alt: 0|'leftmost'|'anywhere'

Determines if and where wildcards in subjectAltNames are possible. If 'leftmost' only cases like *.example.org will be possible (like in ldap), for 'anywhere' www*.example.org is possible too (like http), dangerous things like but www.*.org or even '*' will not be allowed. (TBT)

wildcards_in_cn: 0|'leftmost'|'anywhere'

Similar to wildcards_in_alt, but checks the common name. There is no predefined scheme which allows wildcards in common names. (TBT)

If you give a subroutine for verification it will be called with the arguments ($hostname,$commonName,@subjectAltNames), where hostname is the name given for verification, commonName is the result from peer_certificate('cn') and subjectAltNames is the result from peer_certificate('subjectAltNames'). (TBT)

errstr()

��榊�����������緇���勉����í�若��(���絖����綵√�����)菴������障����� �����勉�<�純��������絎�茵��������������� ��㋜�í�勉�ŝ����吾�с�壔����������c�⓾����ŝ�������違��篁c�������� IO::Socket::SSL::errstr() ��� ��若�喝�冴����⓾��������������

�����㏍����壔����⓾����ŝ����純�宴�������勤˛��粋昭��帥����梧昭��帥�˨�������勉�<�純�������壔�� ������筝���鴻�勐�眼����純�宴�������������勤˛��粋昭��帥����吾��莨若�帥��緇���c�⓾����⓾�������ŝ����� 篏����������������羣�莇潟�������〠⓲��������������c�⓾�������������������潟�������� SSL wants a read first! ������������ SSL wants a write first! ��� ���絖���������ャ�������������������障�������� ��������������若�吾�с�� 0.98 ��������壔����違�㏍�若����˨�˨����壔�鴻����若�����������紊��� $SSL_ERROR �����������壔�鴻����若�������������激�潟����� SSL_WANT_READ �������� SSL_WANT_WRITE ���罸�莠���������鴻����������с�����

opened()

This returns false if the socket could not be opened, 1 if the socket could be opened and the SSL handshake was successful done and -1 if the underlying IO::Handle is open, but the SSL handshake failed. (TBT)

IO::Socket::SSL->start_SSL($socket, ... )

��������壔�������ŝ�����筝������� glob ��ŝ����<�㋘�潟�鴻����純�宴�������� IO::Socket::SSL ��ŝ����吾�с�壔�����紊���������障����� ��潟�潟����㏍�鴻����� new() �����若�喝�冴����������勉�������ʋ・膓���ŝ����激�с�潟�����絎���������������� �����í�<�若�帥��羝<�������������с����障����� �����������勰�∽�違�� accept() �����������純�宴�������˩戎�����勉�с�������違�� �����í�<�若�� "SSL_server" ��� 1 ��̬┃絎������ŝ�������違�ŝ����障�������� ��ゃ�障�� IO::Socket::SSL->start_SSL($socket, SSL_server => 1) ��с����� IO::Socket::SSL ������膓���帥�������壔�í�鴻�������c�⓾����⓾�� 篁c�������̬�ɱ����ʃ昆��勉�壔�í�鴻�� $socket ��� bless �����������������壔�� �����帥�勐�号�����緇������������� MyClass->start_SSL($socket) ���篏帥�c�⓾��������������

Note that if start_SSL() fails in SSL negotiation, $socket will remain blessed in its original class. For non-blocking sockets you better just upgrade the socket to IO::Socket::SSL and call accept_SSL or connect_SSL and the upgraded object. To just upgrade the socket set SSL_startHandshake explicitly to 0. If you call start_SSL w/o this parameter it will revert to blocking behavior for accept_SSL and connect_SSL. (TBT)

If given the parameter "Timeout" it will stop if after the timeout no SSL connection was established. This parameter is only used for blocking sockets, if it is not given the default Timeout from the underlying IO::Socket will be used. (TBT)

stop_SSL(...)

This is the opposite of start_SSL(), e.g. it will shutdown the SSL connection and return to the class before start_SSL(). It gets the same arguments as close(), in fact close() calls stop_SSL() (but without downgrading the class). (TBT)

Will return true if it suceeded and undef if failed. This might be the case for non-blocking sockets. In this case $! is set to EAGAIN and the ssl error to SSL_WANT_READ or SSL_WANT_WRITE. In this case the call should be retried again with the same arguments once the socket is ready is until it succeeds. (TBT)

IO::Socket::SSL->new_from_fd($fd, ...)

This will convert a socket identified via a file descriptor into an SSL socket. Note that the argument list does not include a "MODE" argument; if you supply one, it will be thoughtfully ignored (for compatibility with IO::Socket::INET). Instead, a mode of '+<' is assumed, and the file descriptor passed must be able to handle such I/O because the initial SSL handshake requires bidirectional communication. (TBT)

IO::Socket::SSL::set_default_context(...)

You may use this to make IO::Socket::SSL automatically re-use a given context (unless specifically overridden in a call to new()). It accepts one argument, which should be either an IO::Socket::SSL object or an IO::Socket::SSL::SSL_Context object. See the SSL_reuse_ctx option of new() for more details. Note that this sets the default context globally, so use with caution (esp. in mod_perl scripts). (TBT)

IO::Socket::SSL::set_default_session_cache(...)

You may use this to make IO::Socket::SSL automatically re-use a given session cache (unless specifically overridden in a call to new()). It accepts one argument, which should be an IO::Socket::SSL::Session_Cache object or similar (e.g something which implements get_session and add_session like IO::Socket::SSL::Session_Cache does). See the SSL_session_cache option of new() for more details. Note that this sets the default cache globally, so use with caution. (TBT)

IO::Socket::SSL::set_ctx_defaults(%args)

With this function one can set defaults for all SSL_* parameter used for creation of the context, like the SSL_verify* parameter. (TBT)

mode - set default SSL_verify_mode
callback - set default SSL_verify_callback
scheme - set default SSL_verifycn_scheme
name - set default SSL_verifycn_name

If not given and scheme is hash reference with key callback it will be set to 'unknown' (TBT)

篁ヤ����勉�<�純�������壔�泣����若����������⓾����障�����(綵鴻�̥�������ŝ���� �����c�⓾�������������с�壔�������障�����!) ��������⓾����ŝ�����������������篏帥����祉�í�勉�ŝ����˨�������с�������違��IO::Socket::SSL �� 綏�紊с�� CROAK() �����������冴����������˨�ŝ����障�����

truncate
stat
ungetc
setbuf
setvbuf
fdopen
send/recv

Note that send() and recv() cannot be reliably trapped by a tied filehandle (such as that used by IO::Socket::SSL) and so may send unencrypted data over the socket. Object-oriented calls to these functions will fail, telling you to use the print/printf/syswrite and read/sysread families instead. (TBT)

IPv6

Support for IPv6 with IO::Socket::SSL is expected to work and basic testing is done. If IO::Socket::INET6 is available it will automatically use it instead of IO::Socket::INET4. (TBT)

Please be aware of the associated problems: If you give a name as a host and the host resolves to both IPv6 and IPv4 it will try IPv6 first and if there is no IPv6 connectivity it will fail. (TBT)

To avoid these problems you can either force IPv4 by specifying and AF_INET as the Domain (this is per socket) or load IO::Socket::SSL with the option 'inet4' (This is a global setting, e.g. affects all IO::Socket::SSL objects in the program). (TBT)

RETURN VALUES

A few changes have gone into IO::Socket::SSL v0.93 and later with respect to return values. The behavior on success remains unchanged, but for all functions, the return value on error is now an empty list. Therefore, the return value will be false in all contexts, but those who have been using the return values as arguments to subroutines (like mysub(IO::Socket::SSL(...)-new, ...)>) may run into problems. The moral of the story: always check the return values of these functions before using them in any way that you consider meaningful. (TBT)

DEBUGGING

(������������)

'SSL ��勌戎������(=Using SSL)'�����í����˨����ゃ�������������勉����㏍�ャ�<�潟����勐���� ��祉�壔�激�с�潟�����荐若����������������с�������˨����≪�������� IO::Socket::SSL ���篏帥�c�⓾���� ��馹���������c�⓾�������勉�с�������違�������������違�������鴻�˨����⓾�帥����鴻����с����� �����������違�㋘����˨�����絎���������������˨�壠�若�喝�冴�����������'debug#'(# ��� 0 ������ 3 ��障�с� ��医��)��� IO::Socket::SSL ���羝<����⓾�������������� �����������違�㋘����˨�� Net::SSLeay::trace ��˨��荐㊤����������障��; Net::SSLeay ��� �����с����⓾�����������:

use IO::Socket::SSL qw(debug0);

�����������違�ŝ��(��������í�˨��)

use IO::Socket::SSL qw(debug1);

IO::Socket::SSL ��������勉����í�若�� Net::SSLeay ��������勖���垩����阪�����

use IO::Socket::SSL qw(debug2);

IO::Socket::SSL ��������勐�若�喝�冴�������㏍�若�� Net::SSLeay ��������勰�我�������宴����阪�����

use IO::Socket::SSL qw(debug3);

IO::Socket::SSL ��������� Net::SSLeay ��������勌�������勉����若�帥����潟�������阪�����

EXAMPLES

'example'�����c�㋘�壔����ŝ�����荀с��������������

BUGS

IO::Socket::SSL is not threadsafe. This is because IO::Socket::SSL is based on Net::SSLeay which uses a global object to access some of the API of openssl and is therefore not threadsafe. It might probably work if you don't use SSL_verify_callback and SSL_password_cb. (TBT)

IO::Socket::SSL does not work together with Storable::fd_retrieve/fd_store. See BUGS file for more information and how to work around the problem. (TBT)

Non-blocking and timeouts (which are based on non-blocking) are not supported on Win32, because the underlying IO::Socket::INET does not support non-blocking on this platform. (TBT)

LIMITATIONS

(��狗��)

IO::Socket::SSL ��壔��SSL ��勰�√�������������������吾�勛����眼����������ゃ�潟�帥�若����с�若�鴻�с����� OpenSSL ��吾�勛����眼����������ゃ�潟�帥�若����с�若�鴻�������� Net::SSLeay ���篏帥�c�⓾����障����� �����勛�������������勉�≪�吾�ャ�若�˨��篏帥�������� Net::SSLeay ��� OpenSSL ��勌検��鴻�������ŝ����勉�潟�潟����ャ�若�帥��綽�荀������ŝ����障�����

If you have Scalar::Util (standard with Perl 5.8.0 and above) or WeakRef, IO::Socket::SSL sockets will auto-close when they go out of scope, just like IO::Socket::INET sockets. If you do not have one of these modules, then IO::Socket::SSL sockets will stay open until the program ends or you explicitly close them. This is due to the fact that a circular reference is required to make IO::Socket::SSL sockets act simultaneously like objects and glob references. (TBT)

DEPRECATIONS

(綮�罩≫��絎�)

篁ヤ����勰�∽�違�壠��罩≫��絎�(deprecate)��˨�ŝ�����篋������с�勉�������������̥境�����������⓾����障��:

context_init()

��潟�潟����㏍�鴻����������ñ����������������違��SSL_reuse_ctx ��ŝ����激�с�潟��篏帥�c�⓾�����������

socketToSSL() and socket_to_SSL()

篁c�������� IO::Socket::SSL->start_SSL() ���篏帥�c�⓾�����������

get_peer_certificate()

篁c�������� peer_certificate() ��∽�違��篏帥�c�⓾�������������� Used to return X509_Certificate with methods subject_name and issuer_name. Now simply returns $self which has these methods (although depreceated). (TBT)

issuer_name()

篁c�������� peer_certificate( 'issuer' ) ���篏帥�c�⓾�����������

subject_name()

篁c�������� peer_certificate( 'subject' ) ���篏帥�c�⓾�����������

篁ヤ����勉�壔�í�鴻�壠����ゃ�������⓾����障��:

SSL_SSL

(�����������˨����⓾�������������̥�贋・��≪�壔�祉�鴻�������с����с�壔�������障�������с�����):

X509_Certificate

(�����������������с�����get_peer_certificate() ��壩③������篋������������ŝ����障�� (Do The Right Thing))

SEE ALSO

IO::Socket::INET, IO::Socket::INET6, Net::SSLeay.

AUTHORS

Steffen Ullrich, <steffen at genua.de> ��夌憜����勉�<�潟�������с�����

Peter Behroozi, <behrooz at fas.harvard.edu> ("behrooz" ��勖��緇���� "i" �����ŝ�����������羈���

Marko Asplund, <marko.asplund at kronodoc.fi> �� IO::Socket::SSL ��勐����勉�<�潟�������с�����

罕������ŭ査���������腟���粋昭��障����������������˨�ゃ����⓾�� Changes �����<�ゃ�˨�� �����с����⓾��������������

COPYRIGHT

��������㏍����壔�勐��篏�絲上����� Steffen Ullrich ��˨����c�☀申�����������障��������

�����勉�≪�吾�ャ�若�˨�勖�吾�����������: Copyright (C) 2002-2005 Peter Behroozi.

�����勉�≪�吾�ャ�若�˨�勐����勉����若�吾�с�潟��: Copyright (C) 1999-2002 Marko Asplund.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Appendix: Using SSL

(篁����: SSL ���篏帥��)

OpenSSL ��勐�������鴻����������ャ����ŝ����勉�с�������違����������堺�ャ����ŝ����<�㋘�潟�鴻�� "Network Security with OpenSSL" (Oreilly & Assoc.) �����������㋘�� Web ��泣�ゃ�� http://www.tldp.org/HOWTO/SSL-Certificates-HOWTO/ ��˨�������障����� 膂≦����ʋ��荀���˨�ゃ����⓾�虁˛��睡�������⓾��������������

The Long of It (Detail)

(��激�������� (荅括完))

SSL ���篏帥����勰����勛����宴�壔����ŝ����勉����若�帥��絎������˩����ゃ�������с����� ��ゃ�障�������������壔�若�壔�������c�☀拶�����������������������若�帥������垸����������������с�壔�ŝ����� 罩c�����篋冴�������若�帥�����緇����������������腆阪����˨����ŝ�������違�ŝ����障�������� ��������� SSL ��у���憗�������������˨�壔��荐惹����吾��篏帥����ŝ�������違�ŝ����障�������� 荐惹����吾�壩�水�������肴�������� ID ���(絨���ŝ��������篆∞�������������������堺�ャ�����������������������) ���絽吾�˨����鋍若�⓾����障����� ID ��˨�壠��������篏������勉�������ʃ����ャ�������������勉�������ゃ����勖����宴����ャ�c�⓾����障����� ��������☁��絽吾�壩�水����勖�粋��(Government Approval)��勐�違����若�������⓾����障����� ���茫�筝������������壔�������ŝ����壔����勉�˨�若����˨����������宴��篆♂�若����������勉�˨�若���� ���������������綣����茵���c�⓾����������������������潟����障����� �����勐��������������SSL荐惹����吾��綵���⓾�壔����障����� ��������壔�������ゃ����勤����ユ����宴�������c�⓾����⓾����������̬����ユ����宴��腆肴���������� 篆∞�������������������с��������������(茯�荐弱��(=Certificate Authority) ��˨�������� "��違����若�������⓾����障��"[��祉�������í�勌査�����壔�����������篁c������� 臀峨�������� �����������障��]��� �����勐�翫�������������ゃ����勤晦�����医⑥���茫���勉����������с����違����若����☎�������初���������������� ���絽吾����育�c�с����� ������筝���ゃ�勖�医⑥���茫���勖�������ɾ�������壔�������若�帥��(荐惹����吾�˨����������宴��篏帥�c��) ����垸��������荐惹����吾�勖�����������������緇ï垸�������������������с�������������˨��荐惹����吾�� ����垸����☎����̥����割�������������⓾�������������с�����

��������壔����ŝ����˨����c�⓾�í�勉�������ʋ����潟�������ゃ�с�������������� 蕋蚊�睡�í��緇������������˨�壔�������若����c�若�勌賢��у����ŝ�������� 1 篋冴�� ID ��������c�⓾����� 綽�荀���������������������������с�� :-) ��障�������ʃº��������ŝ����勉����若�帥��絎������с��������������腆阪����˨�������������˨�壔�� ��潟����ャ����宴�若�激�с�潟�����篋冴����勉����<�� 1 篋冴�虁┝�����吾����������ŝ�������違�ŝ����障�������� ��壔�í�ゃ�≪�潟��/��泣�若����勐嚳荅宴�с�壔����泣�若����� 絽吾�� 荐惹����吾�� �����c�⓾����ŝ�������違�ŝ����障�������� ��������泣�若�������壔�í�ゃ�≪�潟�����絎������с��������������腆肴����������������違����壔�í�ゃ�≪�潟����� ���篋榊����ʃ┝�����吾����������ŝ�������違�ŝ����障�������� 荐惹����吾��絎������с��������������腆肴����������������˨�壔����������с��������������腆肴�������������� 荐惹����吾����若�������⓾�����"���"[筝���㋜�����I <����垸�������ゃ�吾�с�鴻��/��������激��/臀峨��> �� ��若�違����障��]��◑��荐弱����勐�㋚�����"���"���罸�莠������障����� �����������������ŝ����������˨�壔�� [罧�綽泣�ŝ����������������ゃ����⓾�����] 茯�荐弱���� 荐惹����吾��綽�荀���������障����� �����������勐����⓾����������˨�������違��SSL �・膓����荐㊤����������������������ŝ����勉����若�帥�� 茯㏍����с����ŝ����������������̥∈篆<����������������с����障�����

The Short of It (Summary)

(��㏍�������� (荀�膣�))

��泣�若����с�壔������埇��絲���泣��������������荐惹����梧��羆����������������綽�荀������������障����� ��㋚����勤┝�����吾�����緇�������������荐惹����梧��羆����茯�荐弱����̹��篁������ŝ�������違�ŝ����障�������� 荐惹����吾�����緇�������緇�篋冴����˨�泣�若����鴻�����箴���с�������������˨�ŝ����障����� ��壔�í�ゃ�≪�潟����с�壔����泣�若�����腆肴�����羆������ŝ����������壚�����綽�荀���������障�������� �����勐�翫����˨�����腱�絲���泣����㋚����勤┝�����吾��綽�荀������ŝ����障����� ���������������緇���号����˨�ゃ����⓾�勖�眼�ŝ��荅括完��壔�� http://www.modssl.org/docs/2.8/ssl_faq.html#ToC24 ������荀с��������������