ssltool
NAME
ssltool– command line tool to explore SSL support in Java (JSSE)
SYNOPSIS
ssltool command (help | [command-options])
ssltool help
Displays all the commands available with ssltool.
ssltool command help
Displays all the command-options available with the command.
ssltool show –cs
Shows all the supported and enabled cipher suites.
ssltool server [server-options]
Runs ssltool as a server program.
ssltool client [client-options]
Runs ssltool as a client program.
ssltool proxy [proxy-options]
Runs ssltool as a proxy (tunnel) program.
DESCRIPTION
The tool ssltool is a utility program to explore SSL support in the Java platform. It does so by running as a server, a client or a proxy program and by querying the Java platform on supported SSL protocols versions and cipher suites.
While running as server, it serves requests as per the incoming protocol, as specified by the option -inproto. When the incoming protocol is either TCP or SSL then the server listens for incoming connections. Once a connection is accepted, it spawns a thread to service messages on that connection. Action taken on receiving data bytes depends on the value of the options -mode and -action. For example, in the echo mode the server writes back whatever it receives to the same connection. In the bench mode, it can discard the received data (read-only action), write back the received data (read-write action), or simply wait for the connection to get closed (accept-wait action). Other supported incoming protocols are HTTP, HTTPS, RMI and SRMI (RMI over SSL). With HTTP and HTTPS, it simply returns the document specified by the requested URL and the value of –action is ignored. With RMI and SRMI, it runs an in-process rmiregistry and an RMI server class.
The client role is complementary to the server role, with the outgoing protocols (option –outproto) the same as incoming protocols supported by the server. With TCP and SSL protocols and echo mode, the client prompts the user to type a message, terminated by a new line, and sends the message to the server over the connection established during client initialization. With RMI and SRMI protocols, the message supplied as a byte array argument to the method call. In bench mode, the client writes bufsize bytes (write-only action), writes and reads bufsize bytes (write-read action), or simply opens and closes connections (open-close action) in a loop with the loop count specified by the option –num.
A proxy between a client and server can be used to analyze the TCP messages being exchanged. ssltool-based proxy operates at TCP level, so it can work with any client and server program. It waits for TCP connections at the port specified by the option –inport and forwards the connection to the target address specified by options –host and –port. The databytes exchanged can be analyzed by specifying one or more supported protocol analyzers. Currently, only two analyzers are supported: dd (data display) and ssl. The former simply displays the data exchanged as Hex bytes and the later parses the data as per SSL message definitions. Protocol analyzers are specified by option –patype. More than one analyzer can be specified by supplying a comma separated list as in –patype "dd,ssl".
Essentially, ssltool enables you to:
Query the Java platform for supported protocols and cipher suites.
Establish SSL connection and exchange data between any two machines connected by a TCP/IP network with the specified authentication and trusted certificates.
Perform HTTPS communication.
Perform RMI over SSL.
Benchmark SSL performance and compare it with TCP performance.
Analyze SSL protocol messages between any pair of SSL client and server.
OPTIONS for ssltool server
OPTIONS for ssltool client
OPTIONS for ssltool proxy
| -inport portno | TCP port to accept incoming connection. Default: 8995. |
| -port portno | TCP port to make outgoing connection. Default: 9000. |
| -host hostname | Hostname or IP address of the target. Default: localhost. |
| -bufsize size | Size of the buffer (in bytes) to read data. Default: 8192 |
| -patype palist | Protocol Analyzer types to analyze traffic. Default: none.
Valid values (can also specify a comma separated list ): dd,ssl or ssl,dd |
| -nio | Flag to indicate use of NIO buffers and socket calls for TCP based communication. |
| -verbose | Display execution status. Helpful for debugging. |
EXAMPLES
ssltool server
Runs a server listening for TCP connections on port 9000. Displays information about accepted connections and received bytes. Writes back the received data to the connection. Enter Ctrl-C to terminate the program.
ssltool client
Runs a client program that establishes a TCP connection to the server running on the same machine and listening for the connection at port 9000. Prompts the user to enter a message. Reads the message, sends it to the server, reads the response, and prints it on the screen. Enter quit at the prompt to exit the client.
ssltool proxy –patype dd
Runs a proxy program that tunnels the connections targeted to port 8995 to the port 9000 on the same machine. Displays all the exchanged bytes in Hex. You should run the client by issuing command "ssltool client –port 8995" to connect to proxy in place of the server in the previous example. Enter Ctrl-C to terminate the program.
sslsetup ss-certs sslsetup server-env ssltool server –inproto ssl
This sequence of commands creates keystore and truststore files, server.ks, client.ks, server.ts and client.ts in the current directory, populated with self-signed certificates for both client and server; sets proper values to the environment variable JSTK_OPTS and runs the server program to accept SSL connections.
sslsetup client-env ssltool client –outproto ssl
Sets up the JSTK_OPTS environment variable for running the client ( assuming that the commands are executed on the same machine and from the same directory as the previous sequence of commands ) and runs the client to establish SSL connection with the server.
ssltool server –inproto ssl –mode bench –action accept-wait –csfile cs.txt
Runs the server for benchmarking SSL connection setup overhead using the cipher suite listed in file cs.txt. Assumes that the JSTK_OPTS is set properly to accept SSL connections.
ssltool client –outproto ssl –mode bench –action open-close –host venus –csfile
cs.txt -invalidate
Runs the client for benchmarking SSL connection setup overhead to the server running on host venus using the cipher suite listed in file cs.txt. Assumes that the JSTK_OPTS is set properly to accept SSL connections.