Cisco Active Network Abstraction Customization User Guide, 3.6.6
Encrypted SSL Sockets
Download this chapter
Encrypted SSL SocketsEncrypted SSL Sockets
Download the complete book
PDF of Cisco ANA 3.6.6 Customization User GuidePDF of Cisco ANA 3.6.6 Customization User Guide (PDF - 4 MB)
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 Socket Layer (SSL) sits between the TCP layer and the application in the Internet protocol architecture (see Figure 27-1).

Figure 27-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 an SSL session.

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

•Alert—Enables 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 and a server.

Figure 27-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 which carries the server's public key certificate.

The server then sends a Server Hello Done message to the client, telling 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 then sends a Change Cipher Spec message that tells the server to activate the negotiated cipher suite. From that point 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.

With SSL version 3.0, SSL keys are created at installation time. SSL keys can also be recreated (see Perl Example). All 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 27-3 System Components

In Figure 27-3, 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 inputs are client connection requests, and the outputs are secured or nonsecured connections. For more information, see BQL Server.

The socket factory service creates the SSL-secured and nonsecured sockets. The inputs are BQL server requests for SSL-secured sockets and nonsecured sockets; the outputs are SSL-secured sockets and nonsecured sockets. For more information, see Socket Factory Service.

There are two ways to access the BQL server:

•Negotiate with the server and get the public key during the negotiation.

•If the public key is not provided explicitly, negotiate with the server using the process described in Figure 27-2.

When the private or public key is created on a Sun machine, it is created in a certificate file that uses the .cer format. However, when it is accessed from the client machine that uses the Perl package, it needs 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). To create it, run the following command: 

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 .trustore 
-file sheer.cer -keypass $PASSWORD -storepass $PASSWORD

The client-cert.pem file is then created 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 that want to validate the server's public key should have this file locally and supply it in the handshake process.

The registry entry allowRemoteUnsecured allows remote access that is not secured for debugging purposes.

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 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; that is, 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 in one of the following ways:

•During negotiation

•At the command line

Note When executing a script, to specify the certificate (public key) in the script (where no negotiation is required), the --certificate entry uses a hard-coded filename 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:

•The BQL statement number while the parameters are in the format $<param name>$ and the device key is replaced with ---interface---.

•Parameters in the order in which they appear in the BQL statement.

Note The gateway IP is hard-coded within the script; see the gateway_ip parameter.

Note The gateway user and password are hard-coded within the script; see the login parameter. 

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}

	}

}