Cisco Active Network Abstraction BQL User Guide Version 3.5.1
Encrypted SSL Sockets
Download this chapter
Encrypted SSL SocketsEncrypted SSL Sockets
Download the complete book
Cisco ANA 3.5.1 BQL User's Guide - PDF of Entire BookCisco ANA 3.5.1 BQL User's Guide - PDF of Entire Book (PDF - 870 KB)
give_us_feedback

Table Of Contents

Encrypted SSL Sockets

Architecture

Negotiation Process

BQL and SSL

BQL Server

Socket Factory Service

Perl Example


Encrypted SSL Sockets

Architecture

The Secure Sockets Layer (SSL) sits between the Transmission Control Protocol (TCP) and the application in the Internet protocol architecture.

Figure A-1 SSL Protocol Architecture

The SSL protocol architecture includes the following components:

•Record Layer—Provides framing and padding for the other SSL components, and for the application. In addition, it identifies the SSL component being used in the message. It is common to all SSL messages.

•Handshake—Responsible for the negotiations that start a SSL session.

•Change Cipher—Activates the negotiated security parameters for a session.

•Alert—Enables the parties to exchange error or warning information. In addition, it identifies problems with the protocol or potential security problems with the session.

•Application—Communicates with the Record Layer which coordinates the TCP socket interface.

Negotiation Process

All SSL sessions are established between a client (initiates the communication) and a server.

Figure A-2 SSL Negotiation

The client starts the exchange by sending a Client Hello message to the server to let the server know that the client wants to establish secure communications. It also proposes a list of security parameters (cipher suites) that the client would like to use.

A Server Hello message is sent by the server informing the client of the preferred cipher suite. In addition, it tells the client that the server is willing to proceed with the SSL negotiation. The server follows this immediately with a Certificate message (carries the server's public key certificate).

The server then sends a Server Hello Done message to the client, that tells the client that the server has finished its part of the initial negotiations.

The client generates random numbers to use as a shared session key. In a Client Key Exchange message the client encrypts the session key with the server's public key and sends the result to the server. The client depends on the server's ability to decipher the Client Key Exchange message to verify the server's identity.

The client now sends a Change Cipher Spec message that tells the server to activate the negotiated cipher suite. From now on, all messages from the client are encrypted using the algorithm from the Server Hello and the session key in the Client Key Exchange. The client sends an encrypted Finished message, which ensures that both parties use the same cryptographic algorithms and parameters. The negotiation is considered to be successful when the message that follows the client's Change Cipher Spec is successfully decrypted as a Finished message.

The server sends a Change Cipher Spec message that tells the client that all subsequent messages from the server will use the negotiated security. The server then sends its own Finished message, which enables the client to confirm that the negotiated security is in place.

BQL and SSL

The secured BQL interface uses a socket factory service that implements encrypted SSL sockets. The sockets are used to facilitate secure communication between the Gateway and BQL clients. The socket factory service creates a regular server socket on port 9002 for the BQL server for local access and a secured server socket on port 9003 for remote access. Port 9002 can also be configured to allow or not allow unsecured access for remote clients for debugging purposes (the default is to not allow unsecured access).

The Gateway allows unsecured and secured connections from the local host and only secured connections from other machines.

The SSL keys are created at installation time (SSL version 3.0). The keys can also be recreated, see the Perl Example section. All the secured connections use the same keys. The Gateway holds both the public and private keys while the BQL clients have only the public key. The keys are used only for encryption and not for authentication.

Figure A-3 System Components

In the diagram above the BQL Server allows BQL communication between the server and clients using encrypted communication (SSL) for remote connections and standard communication for local connections. The feature inputs are client connection requests and the feature outputs are secured or non secured connections. For more information see the BQL Server section.

The socket factory service creates the SSL secured and non secured sockets. The feature inputs are BQL Server requests for SSL secured sockets and non secured sockets and the feature outputs are SSL secured sockets and non secured sockets. For more information see the Socket Factory Service section.

There are two ways to access the BQL Server, namely:

•Negotiate with the Server and get the public key during the negotiation, or

•If the public key is not provided explicitly, negotiate with the Server using the process explained in Figure A-2.

When the private or public key is created on a Sun machine it is created in a file with a .cer extension. However, when it is accessed from the client machine that uses the Perl package it will need to use the .pem format. The .pem format is generated from the .cer format.

The sheer.pem or client-cert.pem file that is used by the client machine is created by running a utility called keytool on the Server (an automatic script for doing this is located on the Server itself). In order to create it the following command line is run: 

keytool -export -rfc -alias sheer -keystore .keystore -file client-cert.pem -storepass 
$PASSWORD

The command keytool generates the private key .keystore and the .trustore files from the sheer.cer file: 

keytool  -genkey -alias sheer -keyalg RSA -dname "$DNAME" -keypass $PASSWORD -keystore 
.keystore -storepass $PASSWORD keytool -export -alias sheer -keystore .keystore 

-file sheer.cer -storepass $PASSWORD keytool -import -alias sheer -keystore .truststore 
-file sheer.cer -keypass $PASSWORD -storepass $PASSWORD

The client-cert.pem file is then created. The creation is as follows: 

Sheer.cer

|         |

.keystore .trustore

|

client-cert.pem

The names of the files are provided in the command line itself (hard coded).

The .keystore and .trustore files are located in \main\resourcebundle\com\cisco\nm\cmp

BQL Server

The SSL certificate that is used by all sockets is managed by the Gateway and stored in a local file. Clients wishing to validate the server's public key should have this file locally and supply it in the handshake process.

The following registry entry is used to allow remote access that is not secured, for debugging purposes:

•allowRemoteUnsecured

Possible values :

•true—The BQL server allows remote clients to connect to the unsecured port (9002)

•false—The BQL server allows only local clients to connect to the unsecured port (9002)

The default value is false.

This can be changed every time that the Gateway is restarted.

Example 

<key name="mmvm/agents/adapters/ShellRawServer">

<entry name="port">9002</entry>

          <entry name="SSLport">9003</entry>

          <entry name="allowRemoteUnsecured">false</entry>

          <entry name="sessionID">702</entry>

        </key>

      </key>

The SSL key <key name="ShellRawServer"> is located in: 

<key name="mmvm/agents/adapters/ShellRawServer">

The script "createSSLKeys" (under main/scripts) is used when a new Gateway is installed. This script creates the keys necessary for encryption.

When there is a standard SSL connection the client starts to negotiate with the server. The client does not require any key on the client side, the client gets the public key from the Server during the initial negotiation.

The following entry is used to open the key files stored in the file "security.properties" located in "Main\resourcebundle\com\sheer\":

•SSLPassword

Socket Factory Service

The following registry entries are used to create SSL secured sockets:

•keystoreType—Format of the file holding the public and private keys (certificates)

•securityAlgorithm—Sun machine (SunX509) or IBM machine (IBMX509)

•securityProtocol—The security protocol, namely, TLS

Example 

<key name="socketfactory">

        <entry name="keystoreType">jceks</entry>

        <entry name="securityAlgorithm">SunX509</entry>

        <entry name="securityProtocol">TLS</entry>

      </key>

Perl Example

In this example, the client receives the server public key:

•during negotiation

or

•at the command line

Note When executing a script in order to specify the certificate (public key) in the script (where no negotiation is required) the --certificate entry uses a hard coded file name and relative path. It uses the 'Keys\\client-cert.pem' file to take the relevant SSL connection parameters. This file should be transferred manually from the Server (where it was created) to the specific client machine.

This script executes a Sheer-1 script on the Gateway. It receives the device key as it appears in the Cisco ANA system, and two files:

1. The bql statement # while the parameters are in a format: $<param name>$ and the device key is replaced with: ---interface---

2. Parameters in the order they appear in the bql statement

Note The Gateway IP is set hard coded within the script, see parameter: gateway_ip below.

Note The Gateway user and password are set hard coded within the script, see parameter login below. 

my ($gateway_ip, $user, $pass, $device_key, $params_input, $xml_input, $port, $ssl_mode, 
$certificate)=("localhost","", "", "","", "", 0, 0, 0);

my $bql_statement;



GetOptions(

	'ip=s'       => \$gateway_ip,

	'user=s'     => \$user, 

	'password=s' => \$pass, 

	'key=s'      => \$device_key,

	'params=s'   => \$params_input,

	'file=s'     => \$xml_input,

	'ssl'        => \$ssl_mode,

	'port=s'     => \$port,

	'certificate'=> \$certificate,

);


usage() if not $gateway_ip or not $user or not $pass;



#print_params();

read_params_file();

read_input_file();

open_socket($ssl_mode);


exit(0);

Functions Part 

sub usage

{

    print STDERR << "EOF";


    usage: $0 [-ip Gateway ip Address] [-user user] [-password password] [-key device key] 
[-params params input file]

           [-f xml input file] --ssl --certificate

     

     -ip          : Host Gateway ip address 

     -user        : User name

     -password    : Password

     -key         : device key

     -params      : params input file name

     -f           : XML Input file name

     -ssl         : ssl mode

     -certificate : in case we want to work in mode where the certificate is taken from a 
local pem format file located on the pc itself.


    example: $0 -ip 10.56.22.196 -user gw_user -password gw_password -key CRS-PE7 -params 
SP-VRF-INSTANCE.ini 

             -f SP-VRF-INSTANCE.txt --ssl --certificate


EOF

    exit;

}



# read parameters file


my @params_list;


sub read_params_file {

#	open (my $handle_params_input, "<", "$params_input") or die "cannot open parameters 
file $params_input\n";

	open (my $handle_params_input, "<", "$params_input") or return;

	while (my $row = <$handle_params_input>) {

		#print "row=$row";

  		push @params_list, $row;

	};


	close $handle_params_input;

}



# read xml input file

sub read_input_file {

	open (my $handle_xml_input, "<", "$xml_input") or die "cannot open xml input file 
$xml_input\n";


	while (<$handle_xml_input>) {

		my $row = $_;

		if (/\<value\>\{\[ManagedElement\(Key=\-\-\-interface\-\-\-\)\]\}\<\/value\>/) {

			$row =~ 
s/\<value\>\{\[ManagedElement\(Key=\-\-\-interface\-\-\-\)\]\}\<\/value\>/\<value\>\{\[Man
agedElement\(Key=$device_key\)\]\}\<\/value\>/g;

	}

	elsif (/\<value\>\$([a-zA-Z0-9_\-]*)\$\<\/value\>/) {

		my $param = shift @params_list;

		chomp $param;

		#	print "Param: $param\n";

		$row =~ s/\<value\>\$([a-zA-Z0-9_\-]*)\$\<\/value\>/\<value\>$param\<\/value\>/g;

	}

  		$bql_statement .= $row;

	}

	$bql_statement .= "\n.\n";


	print "BQL 
Statement:\n--------------------------\n$bql_statement\n--------------------------\n";


	close $handle_xml_input;

}

Open socket and login for prompt 

sub open_socket {

	my ($ssl) = @_;


	my $socket;

	if ($ssl) {

		eval {

			require IO::Socket::SSL;

		};

		die "Please install IO::Socket::SSL\n" if $@;

		print "\nWorking in SSL Mode\n";

		if ( $certificate) {

			print "SSL parameters will be taken from certificate and public key local 
files.\n";

		}

		else {

			print "SSL parameters will be taken from the server during handshake.\n";

		}

		$port ||= 9003;

	   	$socket = IO::Socket::SSL->new (PeerAddr         => $gateway_ip,

						PeerPort         => $port,

						Proto            => 'tcp',

						SSL_version      => 'SSLv3',

						SSL_verify_mode  => $certificate,

						SSL_ca_file      => 'Keys\\client-cert.pem',

					);

	} else {

		print "\nWorking in Regular tcp/ip Mode\n";

		$port ||= 9002;

       		$socket = IO::Socket::INET->new (PeerAddr => $gateway_ip,

					PeerPort => $port,

					Proto => 'tcp',

					);

	}

	print_params();

	die "Unable to open socket in port $port for server $gateway_ip. \nError: $!" unless 
$socket;


	my $login = "openconnection user=$user password=$pass\n.\n";

	print "login to the gateway....\n";

	print $socket "$login";

	sleep 3;


	while ($_=<$socket>) {

		print $_;

		if (/^\.\r/) {last}

	}


	sleep 3;


	print "--------------------------\n\nexecuting the bql....\n";

	print $socket "$bql_statement";

	my $inMessage=0;

	my $message="empty";

	while ($_=<$socket>) {

		print $_;

  		if (/<Message type="String">/) {

			$inMessage=1;

		}

	

		if (m{<Message type="String">(.*)</Message>}) {

			$message.=$1;

			$inMessage=0;

		}

		elsif ($inMessage and m{^(.*)</Message>}) {

		$message.=$1;

		$inMessage=0;

		} 

		elsif (/<Message type="String">(.*)/) {

			$message.=$1;

			$inMessage=1;

		}

		elsif ($inMessage) {

			$message.=$_;

		}

		

  		if ($message ne "empty" and !$inMessage) {

  			$message =~ s/^empty//g;

  			print "$message\n";

		  	$message="empty";

  }

	

	if (/^\.\r/) {last}

}


	sleep 3;

	print "--------------------------\n\nlogout from the gateway....\n";

	print $socket "exit\n.\n";

	while ($_=<$socket>) {

		print $_;

		if (/^\.\r/) {last}

	}

}