path: root/QuickRef

(This quick reference list was contributed by anton@genua.de. Thanks, --Sampo)

Net::SSLeay - useful function prototypes


#----------------------------------
# Import frequently used functions
#----------------------------------

use Net::SSLeay qw(die_now die_if_ssl_error);

$errs = die_if_ssl_error($msg);
	Program dies with $msg if print_errs() was able to find and print 
	some errors.
	$errs is 0 if no error occurred.

die_now($msg);
	Program dies unconditionally! print_errs($msg) is used to print out 
	errors before dying.


#--------------------------
# Unsorted prototypes  
#--------------------------

$count = Net::SSLeay::print_errs($msg);
	Prints SSLeay-error stack with included $msg via 'warn'. Number of 
	printed	errors is returned (->$count).

void Net::SSLeay::randomize($seed_file,$seed_string);
void Net::SSLeay::randomize();
	Load random bytes from $seed_file and from string $seed_string.
	Also uses $Net::SSLeay::random_device and $Net::SSLeay::how_random 
	(Bits!) if used	without parameters.

void Net::SSLeay::RAND_seed($seed_string);
	Seeds randomgenerator with $seed_string.

$bytes_read = Net::SSLeay::RAND_load_file($file_name, $how_much);
	Loads $how_much bytes randomness from file $file_name.

$bytes_written = Net::SSLeay::RAND_write_file($file_name);
	Writes randomness to $file_name.

void Net::SSLeay::load_error_strings();
	Load SSL error messages to make error output more informative.

void Net::SSLeay::ERR_load_crypto_strings();
	Load crypto-API related error messages.
 
void Net::SSLeay::SSLeay_add_ssl_algorithms();
	Add support for supported ciphers.

void Net::SSLeay::ENGINE_load_builtin_engines
	Load any built-in SSL engines suported by the underlybing OpenSSL

void Net::SSLeay::ENGINE_register_all_complete
	Register any built-in SSL engines

$ctx = Net::SSLeay::CTX_new();
	Creates SSL-context. 

int Net::SSLeay::CTX_set_default_verify_paths($ctx);
	Load default location where to find certificates to verify
	remote certificates. This value is precompiled in SSLeay-Toolkit.

int Net::SSLeay::CTX_load_verify_locations($ctx, $cert_file, $cert_dir);
	Set verify location. File with certificates or hashed directory.

void Net::SSLeay::CTX_set_verify($ctx, $mode , \&verify_cb);
	Set mode and callback what to do with remote certificates.
	$mode:	
		&Net::SSLeay::VERIFY_NONE
		&Net::SSLeay::VERIFY_PEER
		&Net::SSLeay::VERIFY_FAIL_IF_NO_PEER_CERT
		&Net::SSLeay::VERIFY_CLIENT_ONCE
	\&verify_cb: 
		$ok = verify_cb($ok,$x509_store_ctx);
		Callback gets info if SSL-toolkit verified certificate ($ok) 
		and certificate store location.
	
void Net::SSLeay::CTX_set_default_passwd_cb($ctx,\&passwd_cb);
	If our RSA private key is passphrase protected and this callback is
	defined, then do not ask on the terminal but call the function.
	\&passwd_cb:
		$passwd = verify_cb($verify);
		If $verify is true, then the callback is supposed to make sure
		the returned password has been verified.

$bool = Net::SSLeay::CTX_use_certificate_file($ctx,$cert,$type);
$bool = Net::SSLeay::CTX_use_PrivateKey_file($ctx,$key,$type);
	Functions to load cert/key from filename ($cert/$key) with filetype 
	$type into SSL-context. 
	Filetypes are:
		&Net::SSLeay::FILETYPE_PEM

$ssl = Net::SSLeay::new($ctx)
	Creates a SSL-session in context $ctx. Returns 0 on failure.

$bool = Net::SSLeay::use_certificate_file($ssl,$cert,$type);
$bool = Net::SSLeay::use_RSAPrivateKey_file($ssl,$key,$type);
	Functions to load cert/key from filename ($cert/$key) with filetype 
	$type into SSL-session. 
	Filetypes are:
		&Net::SSLeay::FILETYPE_PEM

$bool = Net::SSLeay::set_fd($ssl, fileno(S));
	Connect SSL-Toolkit with TCP-connection.
	$ssl	SSL-Session
	S	open socket
	$bool	0-failure 1-success
	
$bool = Net::SSLeay::accept($ssl);
	Make SSL-handshake on hot connection. I am server!
	$ssl	SSL-session
	$bool	0-failure 1-success

$bool = Net::SSLeay::connect($ssl);
	Make SSL-handshake on hot connection. I am client!
	$ssl	SSL-session
	$bool	0-failure 1-success

$x509 = Net::SSLeay::get_peer_certificate($ssl);
	Get X509 certificate from SSL_session.

$x509 = Net::SSLeay::X509_STORE_CTX_get_current_cert($x509_store_ctx)
	Extract current certificate from cert-store. Cert-store is
	used in callbacks!

$asn1_utctime = Net::SSLeay::X509_get_notBefore($x509);
$asn1_utctime = Net::SSLeay::X509_get_notAfter($x509);
$x509_name = Net::SSLeay::X509_get_subject_name($x509);
$x509_name = Net::SSLeay::X509_get_issuer_name($x509);
($type1, $subject1, $type2, $subject2, ...) = Net::SSLeay::X509_get_subjectAltNames($x509)
	 subjectAltName types as per x509v3.h GEN_* for example:
	 GEN_DNS == 2
	 GEN_IPADD == 7
	Return information from a certificate.

$string = Net::SSLeay::P_ASN1_UTCTIME_put2string($asn1_utctime);
	Convert a asn1_utctime structure to a printable string.

$string = Net::SSLeay::X509_NAME_oneline($x509_name);
	Convert a x509_name structure to a printable string.	

$string = Net::SSLeay::get_cipher($ssl)
	Return the active cipher from SSL-session $ssl.

$string = Net::SSLeay::dump_peer_certificate($ssl)
	Return Subject/Issuer from peer-certificate in printable string.

$string = Net::SSLeay::PEM_get_string_X509($x509);
	Returns a printable string containing the X509 certificate PEM encoded
	from $x509.

$mode = Net::SSLeay::CTX_get_verify_mode($ctx)
	Return verify-mode previously set with CTX_set_verify in SSL-context.
	
$mode = Net::SSLeay::get_verify_mode($ssl)
	Return verify-mode in SSL-session.

$written_bytes = Net::SSLeay::ssl_write_all($ssl,$string);
	Write $string to SSL-session. This call returns undef if write failed.
	The whole string gets written!

$written_bytes = $Net::SSLeay::write($ssl,$string);
	Write $string to SSL-session. This call returns immediately. SSL maybe
	wrote the string not completely - check yourself or use ssl_write_all!

$string = Net::SSLeay::ssl_read_all($ssl,$how_much);
	Read everything available from the SSL-session and return it. Read a 
	maximum	of $how_much Bytes (default: 2000000000).

$string = Net::SSLeay::read($ssl);
	Read one bunch of data from the SSL-session and return.

void Net::SSLeay::free ($ssl);
	Free ressources from the SSL-session.

void Net::SSLeay::CTX_free ($ctx);
	Free ressources from the SSL-context.


#----------------------
# Hash functions
#----------------------

# Several cryptographic digests (hash functions) are supported, possibly
# including MD2, MD4, MD5, and RIPEMD160.

$hash = Net::SSLeay:MD5($data);
	Computes md5 hash over $data. $hash is a binary string! Convert it to
	a printable with $string = unpack("H32",Net::SSLeay::MD5($data));

$hash = Net::SSLeay:RIPEMD160($data);
       Computes RIPEMD160 hash over $data. $hash is a binary string! Convert it to
       a printable with $string = unpack("H40",Net::SSLeay::RIPEMD160($data));
 
Note that some digests may not be available, depending on the version
of OpenSSL used.
 

#----------------------
# TCP-Connection hints
#----------------------

# Make socket unbuffered after connect succeeded.
#
select(S); $| = 1; select(STDOUT);

# Close connection by half... from client to server. This signals EOF to
# server. (Clear some buffers, too...??)
# Use this if finished with sending data to remote side.
shutdown S, 1;

# Finally close connection. Do this after reading everything availlable!
#
close S;


#------------------
# TCP Client
#------------------

# #!/usr/bin/perl -w
use strict;
use Socket;
my ($remote,$port, $iaddr, $paddr, $proto, $line);

$remote  = shift || 'localhost';
$port    = shift || 3000;  # random port
if ($port =~ /\D/) { $port = getservbyname($port, 'tcp') }
die "No port" unless $port;
$iaddr   = inet_aton($remote)               || die "no host: $remote";
$paddr   = sockaddr_in($port, $iaddr);

$proto   = getprotobyname('tcp');
socket(SOCK, PF_INET, SOCK_STREAM, $proto)  || die "socket: $!";
connect(SOCK, $paddr)    || die "connect: $!";
while (defined($line = <SOCK>)) {
    print $line;
}

close (SOCK)            || die "close: $!";
exit;


#--------------------
# TCP Server
#--------------------

# #!/usr/bin/perl -Tw
use strict;
BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
use Socket;
use Carp;

sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }

my $EOL = "\015\012";

my $port = shift || 3000;
my $proto = getprotobyname('tcp');
$port = $1 if $port =~ /(\d+)/; # untaint port number

socket(Server, PF_INET, SOCK_STREAM, $proto)        || die "socket: $!";
setsockopt(Server, SOL_SOCKET, SO_REUSEADDR,
                                    pack("l", 1))   || die "setsockopt: $!";

bind(Server, sockaddr_in($port, INADDR_ANY))        || die "bind: $!";
listen(Server,SOMAXCONN)                            || die "listen: $!";

logmsg "server started on port $port";

my $paddr;

for ( ; $paddr = accept(Client,Server); close Client) {
    my($port,$iaddr) = sockaddr_in($paddr);
    my $name = gethostbyaddr($iaddr,AF_INET);

    logmsg "connection from $name [",
            inet_ntoa($iaddr), "]
            at port $port";

    print Client "Hello there, $name, it's now ",
                    scalar localtime, $EOL;
}