NAME

Net::mbedTLS::Connection - Abstract class representing a TLS connection

SYNOPSIS

(See Net::mbedTLS::Client for a sample creation of $tls.)

    my $sent = $tls->write('Hello');

    my $output = "\0" x 100;
    my $got = $tls->read($output);

… or, to abstract over TLS in general:

    my $fh = $tls->tied_fh();

    print {$fh} "hey there\n";

DESCRIPTION

This class implements methods common to both server & client TLS connections.

METHODS: General

$fh = OBJ->tied_fh()

Returns a Net::mbedTLS::Connection::Tied instance for OBJ. See that module for details.

METHODS: I/O

$sent = OBJ->read( $PRE_EXTENDED_STRING )

Tries to read from the peer.

$PRE_EXTENDED_STRING is a scalar that will receive the result of the read. (This is more efficient than creating a new string on each read.)

Note the following caveats regarding $PRE_EXTENDED_STRING:

• If it is undef or empty an exception is thrown.

• Depending on how Perl stores the string in memory, its character length may increase during the read. (This is an effect of how Perl stores strings in memory.)

  (Perl internals note: SvUTF8 is turned off after the read.)

Returns one of:

• A positive integer, to represent the number of bytes sent.

• 0, to indicate that there is nothing to read, and the TLS session is done.

• undef, to indicate a non-fatal error (e.g., ERR_SSL_WANT_READ). That error will be the result of OBJ’s error().

Fatal errors cause a Net::mbedTLS::X::Base instance to be thrown.

$sent = OBJ->write( $BYTE_STRING )

Tries to send all of $BYTE_STRING to the peer.

Returns the same possibilities as read() above, except that 0 is not returned.

$done = OBJ->shake_hands()

Performs a TLS handshake. Not strictly needed because read() and write() will automatically do the handshake “under the hood”, but if you want to know when the handshake is done this is still useful.

The return is a boolean that indicates completion. If it’s falsy then the handshake isn’t done, and you’ll need to call this again once the underlying socket is ready for whatever mbedTLS wants. That should only happen for non-blocking sockets.

Example non-blocking operation:

    my $done;

    until ($done = $tls->shake_hands()) {
        vec( my $bitmask, fileno($socket), 1 ) = 1;

        if ($tls->error() == Net::mbedTLS::ERR_SSL_WANT_READ) {
            select $bitmask, undef, undef, undef;
        }
        if ($tls->error() == Net::mbedTLS::ERR_SSL_WANT_WRITE) {
            select undef, $bitmask, undef, undef;
        }
        else { ... }
    }

$done = OBJ->close_notify()

Sends a TLS-level close notification. Should normally happen once you’re done using the connection.

The return is as for shake_hands().

METHODS: INTROSPECTION

$num = OBJ->error()

The last error code from mbedTLS.

$fh = OBJ->fh()

A convenience method that returns the Perl filehandle from which you created OBJ.

$num = OBJ->verification_result()

Returns a bitmask that represents the peer certificate verification result. Possible bitmask values are the various X509_BADCERT_* constants from Net::mbedTLS. (See mbedTLS’s mbedtls_ssl_get_verify_result().)

$str = OBJ->tls_version_name()

A string version of the negotiated TLS version (e.g., TLSv1.2).

$str = OBJ->ciphersuite()

A string that describes the TLS session’s negotiated cipher suite.

@certs = OBJ->peer_certificates()

The peer’s certificate chain, in DER (i.e., binary) format.

If you want PEM (Base64) you can use Crypt::Format, e.g.:

    my $pem = Crypt::Format::der2pem($der, 'CERTIFICATE');

This croaks if called outside list context.

$num = OBJ->max_out_record_payload()

The maximum outgoing record payload, in bytes.

cpanm Net::mbedTLS

perl -MCPAN -e shell
install Net::mbedTLS