Why is in documentation of IO::Socket::SSL that I can set SSL_version to SSLv3 and when I do so, I get error that this version is not supported?

As you have provided neither an SSCCE nor the version of IO::Socket::SSL which you are using it's pretty much impossible to say. Here's a counterexample though:

#!/usr/bin/env perl 
use strict;
use warnings;
use IO::Socket::SSL;

print "IO::Socket::SSL version $IO::Socket::SSL::VERSION\n";

for my $proto ('SSLv3', 'TLSv1_2') {
    my $ssl = IO::Socket::SSL->new (
        PeerHost => 'perlmonks.pairsite.com',
        PeerPort => 443,
        SSL_version => $proto
    );

    print "SSL connection with $proto " .
        ($ssl ? 'set up' : 'failed') . "\n";
}
[download]

Which when run by me produces:

IO::Socket::SSL version 2.012
SSL connection with SSLv3 failed
SSL connection with TLSv1_2 set up
[download]

Try it and see how you get on. Note that the results of this help to illustrate that no secure site is going to support SSLv3 these days anyway so the purpose of specifying it in the first place is a little suspect.

I'm sorry, but I don't understand why everyone is shouting SSCCE immediately. Also hippo's example doesn't show anything you already knew: That when you try to use SSLv3 the program fails. I think your question 1 is a perfectly sound question. If I read a bit between your lines, not knowing what versions are involved I think I can understand what you are talking about. The question is that according to the documentation IO::Socket::SSL supports SSLv3? This is mentioned in the latest documentation so let's start from there.

What could have been answered here is that the documentation for IO::Socket::SSL is actually correct. The library does support SSLv3! However, here is the trick: IO::Socket::SSL depends on Net::SSLeay and that module relies on OpenSSL. The only thing the documentation of Net::SSLeay (v1.85) mentions is: "On some systems, OpenSSL may be compiled without support for SSLv2. If this is the case, Net::SSLeay will warn if ssl_version has been set to 2". But as far as I know, OpenSSL is no longer default compiled with support for SSLv3 either for Perl (and for very good reasons!). And so it seems that here there is some missing information in the documents regards disabling SSLv3 but maybe it has been mentioned in release notes. If you examine SSLeay.xs (inside the download package) you will see that in some point of time OpenSSL compiler options have been added to make it possible to disable SSLv3:

#ifndef OPENSSL_NO_SSL3
SSL_CTX *
SSL_CTX_v3_new()
     CODE:
     RETVAL = SSL_CTX_new (SSLv3_method());
     OUTPUT:
     RETVAL

#endif
[download]

In the following codeblock from IO::Socket::SSL you can see that the result is "SSL Version SSLv3 not supported" because Net::SSLeay cannot CTX_v3_new. I tried to find information about this method check in IO::Socket::SSL's documentation but could not find it:

    my $ctx_new_sub =  UNIVERSAL::can( 'Net::SSLeay',
    $ver eq 'SSLv2'   ? 'CTX_v2_new' :
    $ver eq 'SSLv3'   ? 'CTX_v3_new' :
    $ver eq 'TLSv1'   ? 'CTX_tlsv1_new' :
    $ver eq 'TLSv1_1' ? 'CTX_tlsv1_1_new' :
    $ver eq 'TLSv1_2' ? 'CTX_tlsv1_2_new' :
    'CTX_new'
    ) or return IO::Socket::SSL->_internal_error("SSL Version $ver not
+ supported",9);
[download]

I can not help you regards question 2 since I don't know much about that.

I'm sorry, but I don't understand why everyone is shouting SSCCE immediately. Also hippo's example doesn't show anything you already knew: That when you try to use SSLv3 the program fails.

The reason is this: I have never yet seen the error to which my anonymous brother alluded by "I get error that this version is not supported", presuming he means this version of SSL. Given that his code is incomplete and error message inexact, I cannot tell either by inspection nor by running it what the actual error message is nor what throws it. I've given a counterexample to show that I can quite happily run some code requiring SSLv3 without throwing an error resembling that hinted at in the OP.

Note additionally that my counterexample program doesn't fail. It correctly reports that the site tested forbids an SSLv3 connection (quite reasonably, I think we can all agree). It would be instructive to know what the OP sees when running that same code.

It's a good deduction on your part (++) that the OP's underlying openssl libs may not allow for SSLv3. Hopefully our anonymous poster will return and confirm it.

Ok, I can understand that also. And even though I deduced the problem surely my answer can also not be the correct one to this problem,

One thing that I noticed through your last reply when you said:

"It correctly reports that the site tested forbids an SSLv3 connection"

Are you sure that you have a build with SSLv3 enabled? It surprised me a little bit but when I ran your test I didn't get the 'not supported' message either and I know I don't have SSLv3 enabled.

So I turned on extra debugging (use IO::Socket::SSL qw(debug4);) and it is only then that I get to see the not supported message. So now I am wondering if in your case: Was it the site that rejected it or your client?

Without debugging

IO::Socket::SSL version 2.056
SSL connection with SSLv3 failed
SSL connection with TLSv1_2 set up
[download]

After turnig on debugging:

IO::Socket::SSL version 2.056
DEBUG: .../IO/Socket/SSL.pm:641: global error: SSL Version SSLv3 not s
+upported
SSL connection with SSLv3 failed
...
SSL connection with TLSv1_2 set up
(program exits normally)
[download]

edit: Result with debug looked like fatal exception (as hippo commented below). I added the last line now for clarification. See ... above

Traditionally both cert and key should be PEM formatted. Since version 1.988 it also supports DER and PKCS12. It will automatically detect the format but you must use the same format for both key and certificate. I have no idea what's wrong in your specific case and I have no way to reproduce it but it should work in general as I described and there is also the test t/cert_formats.t in the distribution to check the relevant combinations.