JPARSS Version 0.95 Oct. 2, 2001 PACKAGE NAME: JPARSS (Java Parallel Secure Socket (Stream)) COPYRIGHT: See the NOTICE file inside this package. PURPOSE: Provide a Java network package to handle user authentication, and secure/plain file transfer with parallel socket streams to achieve optimal TCP bandwidth in high speed Wide Area Networks (Grid). DESCRIPTION: The emergence of high speed wide area networks makes grid computing a reality. However grid applications that need reliable data transfer still have difficulties to achieve optimal TCP performance due to network tuning of TCP window size to improve bandwidth and to reduce latency on a high speed wide area network. A Java package called JPARSS (Java Parallel Secure Stream (Socket)) that divides data into partitions that are sent over several parallel Java streams simultaneously and allows Java or Web applications to achieve optimal TCP performance in a grid environment without the necessity of tuning TCP window size. This package enables single sign-on, certificate delegation and secure or plain-text data/file transfer using several security components based on X.509 certificate and SSL. A simple file server is implemented along with a command line utility to provide peer-to-peer and third party file transfers. REQUIREMENTS: To use security feature of this package, one has to download a Java security package (IAIK) from the following web site http://jcewww.iaik.tu-graz.ac.at/. This Java package is free to any education/research institution. Java virtual machine 1.2 and above. DISTRIBUTION: This package is distributed in a single tar file which contains the following components: bin/jaft csh wrapper to start either a peer-to-peer or a 3rd party file transfer. bin/jafserver csh wrapper to start a file transfer server. lib/ contains jni shared libraries for the file servers. docs Java documents for this package. jparss source code of this package. classes class files of this package. cacert CA certificate for HPC group of Jefferson Lab. INSTALLATION: 1) Untar this package in a directory. Modify jaft and jafserver so that a right Java virtual machine and correct paths for jar files of IAIK package are selected. 2) This step is optional for those who wish to run a file server on a host. In order to run a file transfer server on a host, one has to become a root user and creates a directory called /etc/dg ( C:\etc\dg) on the host. There are 4 files need to be in this directory: hostcert.pem -- X.509 certificate for this server. hostkey.pem -- private key of this server. cacert.pem -- Trusted X.509 CA certificates. dgmap -- Map file that converts a X.509 subject into a local user name. The dgmap file contains multiple lines which have a local username followed by the subject of a user X.509 certificate. For example the following line maps a X.509 subject into a local user name 'guest' guest EmailAddress=chen@jlab.org, CN=HPC GUEST, OU=Jefferson Lab, O=Guest, L=Newport News, ST=VA, C=US 3) In order to use this package, a user has to create a directory in his/her home directory called .dg. In the directory a user X.509 certificate in p12 format must exist with file name usercert.p12. In addition a file called cacert.pem that contains trusted CA certificates must exist in this directory. Note: for JLAB/MIT grid users, this file can be found at cacert/jlabhpccacert.pem. USAGE: 1) Once file servers are running in a grid environment, users can use the csh wrapper 'jaft' to transfer files. jaft -[rsv] -n streams -P port [sourceHost]:file[s] \ destinationHost:file[s] get (put) -r: recursive copy. -s: secure data transfer. (very slow.) -v: verbose mode. -n: number of parallel streams. (default is 8.) -P: remote port. (default is 7893.) -R: restart downloading an existing file. -O: overwrite an existing file when uploading/downloading a file. -h: print out the above. If the sourceHost is missing, a peer-to-peer file transfer will be carried out. Otherwise a 3rd party file transfer between sourceHost and destinationHost will be carried out. Either a file (files) or a directory may be specified. The get or put argument specifies the direction of a file transfer. A user may have to enter a passphrase to decrypt his/her private key for his/her X.509 certificate ($(HOME)/.dg/usercert.p12) to generate and to store a temporary X.509 certificate that is valid for 24 hours. A user will not be prompted for a passphrase again as long as the temporary certificate is valid. The temporary certificate is used to authenticate a user to the file servers. 2) A file server can be started using a csh wrapper 'jafserver'. jafserver -P port -l logfile -h -P: port server listens at this port (default is 7893). -l: an output file for server logging message (default is /var/log/jparss). If stdout the name of the logging file, messages are dumped on the terminal. -h: print out these messages. You may have to enter a passphrase to decrypt the private key of this server (/etc/dg/hostkey.pem). APPLICATIONS: 1) Use parallel socket (stream) in applications. There are example programs in the directory jparss/demo. The examples illustrate how to use this package to establish secure connection between a server and a client and how to access the associated parallel input/output streams. The parallel input/output streams are derived from java.io.InputStream/java.io.OutputStream. Therefore applications using this package can easily send message via parallel streams as if the parallel streams were conventional Java streams. 2) Use parallel file transfer client APIs. Applications that wish to communicate with the parallel file transfer servers can use the the parallel file transfer client APIs. There are only two classes involved here: one is FileClient and the other is RemoteTransfer. The FileClient class handles a peer-to-peer file transfer and the RemoteTransfer handles a 3rd party file transfer. Please consult documents inside the docs directory for detailed information. TODO: Web services based on parallel file transfer will be available soon. BUG REPORTS: Please send comments and bugs to chen@jlab.org.