Contents: - introduction - how eGCB works - download and install - configuration and running - programming with eGCB - extensions and bug report 1. Introduction 2. How eGCB works eGCB is a new system that provides multiple connection methods and enables communication into/out of private and firewalled networks. Available mechanisms are GCB, DPF, and retrictive DPF. Each section that follows explain how each mechanism works and what network settings are best supported by each mechanism. 2.1 How GCB works 2.2 How DPF works 2.3 How rDPF works 3. Download and Install 4. Configuration and Running 4.1 Setting up CA 4.2 Getting Certificate 5. Programming with eGCB --------------------------------------------------------------------------------- 1. Setting up CA 1.1 Directory structure /scratch/sschang/eGCB_CA - certs: certificates this CA generates will be stored here in addition to being sent to requesters - private: CA's private key is stored here - serial: echo '01' > serial - index.txt: touch index.txt 1.2 Configuration file We will be using 'req' to generate root CA and 'ca' command to generate certificates. These commands require very long list of arguments. We can make our life easier by putting these arguments into a configuration file and let openssl use the file. Create a file something like the one shown below and name it as "/scratch/sschang/eGCB_CA/config" --------------- example configuration file ------------------------ ------------ end of example configuration file ---------------------- Now we need to let openssl use the config file by setting the environment var OPENSSL_CONF. With csh, do the following: $setenv OPENSSL_CONF /scratch/sschang/eGCB_CA/config 1.3 Generate root certificate Now that we have environment setup correctly, we can generate our root CA that will be used to sign certificates we will generate. - generate CA's private key - generate CA's self-signed certificate these two can be done by the following single command: "openssl req -x509 -newkey rsa -days 365 -out CA_cert.pem -outform PEM" To see if everything went well, check if you have private/CA_key.pem and run: "openssl x509 -in CA_cert.pem -text -noout" 1.4 Generate certificates The person or organization that wants to get a certificate should send a certificate request to CA. If you want to get a certificate, then see instructructions in section 2. Given that you have a certificate request sent from a requestor, a certificate can be simply generated by doing: "openssl ca -in dewey_req.pem" A new certificate will be created as /scratch/sschang/eGCB_CA/certs/02.pem something like that. Change this file to an appropriate name such as 'dewey_cert.pem' and send it the requester. 2. Get certificates The certificate is your public key signed by the CA, and the public key must be paired with your private key. Hence you must generate a (private, public) key pair using some public key mechanism--at the moment we only support RSA public key mechanism, and then a certificate request that contains the public key. All of these operation can be done by a single command in openssl. Note that if your are the same person who sets up CA in section 2, then you have to unsetenv and use the default openssl config file since the config file in section 1 is only for CA operation. "openssl req -newkey rsa:1024 -keyout dewey_private_key.pem -keyform PEM -out dewey_req.pem" The command will ask you several questions such as country name, host name, email address. Since eGCB is a connection service that uses IP address and needs to extract IP address from your certificate, you need to have your IP address in your certificate. At the moment, we don't know what the best place in X.509 certificate to store IP address is. Therefore, we decided to use the place for host name. Please enter your IP address instead of hostname when you are asked about the host name. The command will generate dewey_private_key.pem and dewey_req.pem files. The first file is RSA private key and the second one is the certificate request file. You need to send this request file to CA. To see if the correct request gets generated, run the following command: "openssl req -in dewey_req.pem -text -noout" If you want to keep the private key not protected by a password, then run the following command: "openssl rsa -in dewey_private_key.pem -out dewey_private_key.plain.pem" The new private key will be stored in dewey_private_key.plain.pem not protected by a password If everything is fine, the CA will send you a certificate after a while. Let's assume that the certificate is named as 'dewey_cert.pem'. A PEM file can contain both a private and the corresponding certificate. Having the private key and its certificate in a single file is a good idea because this will make much easier to maintain correct (private, certificate) pair. To make our life simple, we currently support only this option. So, do the following: "cat dewey_cert.pem dewey_private_key.plain.pem > dewey.pem" Since your certificate and private key are stored in a single file, you must keep this file very secret. Protect the file with your password or store it in a very safe place. 3. CAs you trust You can have trusted CAs in a flat PEM file or in multiple PEM files in a directory. When CAs are stored in multiple files, each file can contain a single certificate. Before going further, I have to note that openssl maintains a system-wide CA list that applications in the machine must trust by default. Hence if you want to have your own CA list in addition to those default CAs, then you have to keep reading this section. Otherwise, you can proceed to the next section. The procedure is very simple. - collect certificates of CAs you want to trust but not in the default CA list. - concatenate those certificate into a single PEM file, if you like the single file option. Or put those files into the directory. Note that adding or deleting certificate to/from the trust list may greatly affect the security of your application. So you must keep the list absolutely write-protected. 3. Environment Setting - eGCB_DEBUG_PATH: the name of the file to which log and debug msgs go - eGCB_DEBUG_LEVEL: debug level. "basic", "network", or "fulldebug" - eGCB_LOG_MAXSIZE - eGCB_MY_CERT: the full pathname of your certificate. Remember that this file must contain both your private key and certificate - eGCB_CA_FILE: the full pathname of the file that contains CAs you trust - eGCB_CA_DIR - eGCB_TRUST_DEFAULT_CA: yes or no - eGCB_MY_IP - eGCB_INAGENT_LOC - eGCB_INAGENT_PUB - eGCB_OUTAGENT_LOC - eGCB_OUTAGENT_PUB - eGCB_ROUTE The format of routing table: # File format of eGCB routing table: # - each line contains one routing rule # - each routing rule has the following fields: # + peer: ip/mask, where ip is a dotted notation and mask is the number # of bits to be matched # + inagent: ip:port of peer's inagent. If direct communication is required, # then this field is "none" # + outbound: "allowed" or "controlled". If "allowed", then outagent must be # contacted to get the permission to connect the peer # If a line starts with '#' or white space, it is treated as a comment # 128.105.144.68/32 128.105.144.68:65432 allowed 128.105.144.79/32 none allowed 128.105.144.79/32 none controlled 3. Install 4. Running 4.1 Inagent usage: inagent -S service -C certificate [-T trust_default_CA] [-F CA_file] [-D CA_dir] -P public_addr -L local_addr [-B on_boundary] [-E can_talk] -f debug_file [-g debug_level] [-x max_of_debug_file] service: 'GCB', 'DPF', or 'rDPF' certificate: the full pathname of the file containing your certificate and private key trust_default_CA: 'yes' if you want to trust default CAs. Default is 'no' CA_file: the full path name of the file that contains CAs you trust. If you do not want to trust default CAs, then you must provide your own list of CAs you trust through this or the next arg CA_dir: the full path name of the dir that contains CAs you trust public_addr: the address that clients in the public network must contact to get through the firewall managed by this agent. Must be ip:port. E.g., "128.105.175.121:65432" local_addr: the address that servers behind the firewall that this agent manages must contact to get registered to this agent. Must be ip:port. E.g., "192.168.100.1:65431" on_boundary: 'yes' if the agent is on the boundary of the private network that it manages. Default is 'no' can_talk: 'yes' if the agent is able to directly talk with machines behind the firewall it manages. Default is 'no' debug_file: the full path name of the file that log and debug messages go debug_level: 'fulldebug', 'network', or 'basic'. 'fulldebug' means extensive logging and 'basic' means minimum logging. Default is 'basic' max_of_debug_file: maximum size of the debug file. When the file reaches the size, the log is moved to *.old file and new log file will be created. Default is 64000 4.2 Outagent 4.3 Client