|
|
|
|
|
HELIOS WebShare UB User manual |
||||
The WebShare WebObjects Server ("webshare.woa") is a Java program running on a server with an Internet connection. It can be installed on the same machine where the WebShare File Server is installed, in which case it is called a "single server solution". To increase the level of file system security, the WebShare WebObjects Server should be installed on a separate server, in a "two-tier server solution".
Ideally no other applications or services would be running on the WebShare WebObjects Server. This allows the blocking of all ports and services (by software and/or hardware firewalls), except for those required by WebShare.
Due to the fact that no data files are stored or cached on the WebShare WebObjects Server, a high level of WebShare File Server security is ensured. The WebShare WebObjects Server uses one dedicated TCP/IP port for all Web clients, by default 2009.
During the installation of HELIOS WebShare the packed file "websharewoa.tar" is installed in the directory "HELIOSDIR/etc/webshare". The "start-helios" command then extracts the file in the directory "HELIOSDIR/var/run" to the "webshare.woa" package.
The WebShare product includes two server components. The WebShare File Server which is licensed on a given HELIOS machine ID (machID) and a WebShare WebObjects Server which may run on a separate server machine. The WebShare WebObjects Server belongs to the WebShare server product and will not require a separate WebShare activation key.
The complete HELIOS software license terms must be accepted during the installation and can be found on the product CD-ROM.
Each "*.wo" directory contains the "*.html", "*.wod" and "*.woo" files for the corresponding Web page. They may be localized to the desired GUI (Graphical User Interface) language. 6.4 "Customization/Localization" describes how to localize/customize the WebShare GUI.
The script "sbin/start-websharewoa" starts the WebShare WebObjects Server daemon. Usually, it is started by the "srvutil start websharewoa" command during "start-helios". In case that there should occur some startup problems, it can be started manually to monitor the error messages in a terminal window via:
Additional logging is reported to the WebObjects log files. They are located in "HELIOSDIR/var/adm/" and are called "websharewoa.log", with the appendices ".0" (yesterday), to ".6" (seven days ago). All internal WebObjects messages are reported to "websharewoa.log". All HELIOS generated WebShare WebObjects Server messages are reported to the system messages file.
Note: This section is about customizing the "webshare.woa" package. If no customizing is done, then this section can be ignored.
In order to customize the WebShare WebObjects Server first copy the "webshare.woa" package from
"HELIOSDIR/var/run" to "HELIOSDIR/var/webshare".
Whenever WebShare is started it looks for "webshare.woa" in "HELIOSDIR/var/webshare". If it cannot be retrieved from there, it is taken from "HELIOSDIR/var/run".
The idea is that "webshare.woa" is replaced en bloque in "HELIOSDIR/var/run", e.g. in case of a software update. Being in "var/webshare", localizations and other adjustments are preserved, when "start-helios" extracts "websharewoa.tar" anew to "HELIOSDIR/var/run".
Note: Use Ctrl-Open (Show Package Contents) to show the contents of the "webshare.woa" package, and subsequently of the ".wo" files in the contained "Contents" > "Resources" folder, to make the ".wod", ".html" and ".woo" files visible.
Localize all "*.html" files, using UTF-8 characters. The WebObjects Builder application can do this by showing the correct layout. You may also use any other HTML tool. Before changes in "*.html" files become valid, the "websharewoa" service must be stopped and restarted.
Localize all "*.wod" files, using UTF-8 strings. You may localize the strings with any UTF-8 compatible text editor. Before changes in "*.wod" files become valid, the "websharewoa" service must be stopped and restarted.
The Color Label items can be localized directly in the "WebShare Color Label Preferences" window. After a new login, the color names will appear according to your changes.
The built-in action names None, Create Dir, Rename, Permissions and Mail Message can be localized in the file "Main.wod", using UTF-8 strings. After restarting "websharewoa", the action names will appear according to your changes.
Custom action scripts are localized by putting #Title=UTFname into the script within the first 5 lines. Refer to 7.4 "WebShare scripts" for details on creating or customizing WebShare custom scripts and action scripts.
This document outlines how to configure your SSL setup. HELIOS WebShare SSL support is built using the standard Java security SSL implementation. Java security allows implementations of the JVM flexibility in how security is implemented. Unfortunately, the flexibility means there is no definitive mechanism for configuring SSL security on all JVMs. In this document, we will describe how to use the standard JDK 1.4 tools to accomplish these tasks.
SSL (Secure Sockets Layer) is a protocol designed by Netscape Communications Corporation to provide encrypted communications on the Internet. SSL is layered beneath application protocols such as HTTP, SMTP, FTP, Telnet, Gopher, and NNTP and is layered above the connection protocol TCP/IP. It is used by the HTTPS access method. SSL works by using a private key to encrypt data that is transferred over the SSL connection. Both Netscape Navigator and Internet Explorer support SSL, and many Web sites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:.
A server SSL connection uses two sets of certificates to secure the connection. The first set is called a "keystore". The keystore contains the keys and certificates for the server. These security credentials are used to prove to clients that the server is legitimately operating on behalf of a particular domain. If your server will only need to act as one domain, you only need one key entry and certificate in the keystore. Keys are stored in the keystore under aliases. Each alias corresponds to a domain name, e.g.: webshare.yourserver.com.
Certificates attempt to guarantee that a particular party is who they claim to be. Certificates are trusted based on who signed the certificate. If you only require light security, are deploying for internal use on trusted networks, etc. you can use "self-signed" certificates. Self-signed certificates encrypt the communication channel between client and server. However the client must verify the legitimacy of the self-signed certificate through some other channel. The most common client reaction to a self-signed certificate is to ask the user whether to trust the certificate, or to silently trust the certificate is legitimate. Unfortunately, blindly accepting self-signed certificates opens up the system to "man-in-the-middle" attacks.
The advantage of a self-signed certificate is that you can create them for free which is great when yearly certificate signature cost is a major concern, or for testing and evaluation. In addition, you can safely use a self-signed certificate if you can verify that the certificate you are using is legitimate. So if a system administrator creates a self-signed certificate, then personally installs it on a client's truststore (so that the certificate is trusted) you can be assured that the SSL connection will only work between the client and the correct server.
For higher security deployments, you should get your certificate signed by a CA (Certificate Authority). Clients truststores will usually contain the certificates of the major CAs and can verify that a CA has signed a certificate. This chain of trust allows clients to trust certificate from servers they have never interacted with before. Certificate signing is similar to a public notary (with equivalent amounts of verification of identity, record keeping, and costs).
Quick Setup with the built-in "default" certificate
On the WebShare WebObjects Server it is required to configure the HTTPS/SSL port. A good port number is 443 (default for HTTPS). First, the WebShare WebObjects Server must be stopped and then started again to ensure that the latest version gets unpacked in "var/run/webshare.woa". The quick setup commands are:
Note: The preference SSLPort is described in 6.6 "Preference keys".
The WebShare WebObjects Server will now be available via standard HTTP as well as HTTPS. The HTTPS connections can be started via the following browser URL:
Note: If the default port for SSL is not 443 the URL must include the port number, e.g. for port 3009 the browser URL is : https://webshare.yourdomain.com:3009
The Sun JDK (version 1.4.x) ships with all the security tools you need to configure SSL with HELIOS WebShare WebObjects Server. The most important is the "keytool" located in the "JAVA_HOME/bin" directory of the Java runtime. Sun JVMs persist keystores and truststores on the file system as encrypted files. The "keytool" is used to create, read, update, and delete entries in these files. HELIOS WebShare WebObjects ships with a self-signed "dummy" certificate designed for initial evaluation testing.
2. Create a self-signed SSL server certificate for your server domain. Note: you may already have one if your HELIOS WebShare WebObjects server domain matches an existing web domain with SSL. If so, you can skip to step 4.
4. Import the server certificate into the keystore. Note: if you are going to use the self-signed certificate generated in step 2, the certificate is already imported and you can skip this step.
1 Decide on a server domain
The WebShare WebObjects Server domain should match the server host name, e.g. "webshare.yourdomain.com".
2 Create a self-signed server certificate
In order to create a self-signed server certificate go to the command line on the WebShare WebObjects Server. "HELIOSDIR" must be replaced with the HELIOS installation directory, e.g. "/usr/local/helios" for the default installation:
As a next step enter the keystore password in a configuration file, which will be used by the WebShare WebObjects Server, to allow access to the "adaptorssl.key" content.
To secure your keystore password the file permissions "adaptorssl.pass" can be changed that no user can access this file, only the WebShare WebObjects root user could have access, e.g.
If you do not plan a CA signed certificate the self made HTTPS certificates should work and the additional steps are not required. Continue with a server restart to complete it (go to 6.5.4 "Completion").
3 Obtain a CA signed certificate
If you decide to get a CA signed certificate, you must first export the certificate in the standard CSR format. You can do this with the "keytool":
# keytool -certreq -keystore adaptorssl.key -alias webshare.yourdomain.com -file cert.webshare.yourdomain.com
Substitute your server name for "webshare.yourdomain.com" and the name of the certificate file you wish to produce for "cert.yourdomain.yourdomain.com". Submit the generated CSR to the CA and follow their instructions to get it signed.
4 Import server certificates
If you had a CA sign your server certificate, or if you have an existing SSL certificate, you must import it using the Java "keytool":
keytool -import -keystore adaptorssl.key -alias
webshare.yourdomain.com -file signed_certificate_file
It is important that the alias has not already an associated key. Otherwise you will receive an error.
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBxzCCATACAQAwgYYxCzAJBgNVBAYTAkRFMRAwDgYDVQQIEwdHZXJtYW55MRAwDgYDVQQHEwdHYXJic2VuMR0wGwYDVQQKExRIRUxJT1MgU29mdHdhcmUgR21iSDEXMBUGA1UECxMOSEVMSU9TIFN1...
-----END NEW CERTIFICATE REQUEST-----
Usually this needs to be submitted including the "----BEGIN..." and "----END..." lines into your CA (Certificate Authority, e.g. verisign.com)
- Your server domain name URL does not match the certificate
- Your certificate has not been sign by a CA
- You certificate has expired
- Your browser does not know about your CA, e.g. VeriSign is installed in all major browsers.
Our experience is that Netscape browsers provide more detailed information on certificates than others. In a case of a problem Netscape can be used to show how the CA certificate response will look like.
-----BEGIN CERTIFICATE-----
MIIDRzCCAvGgAwIBAgIQX6oiydIYfaEABAZyXsUOlDANBgkqhkiG9w0BAQUFADCBqTEWMBQGA1UEChMNVmVyaVNpZ24sIEluYzFHMEUGA1UECxM+d3d3LnZlcmlzaWdu...
-----END CERTIFICATE-----
websharewoa: [2004-04-30 15:54:30 MEST] <main> Unable to establish an SSL connection to port 443 on this host
websharewoa: [2004-04-30 15:54:30 MEST] <main> com.webobjects.foundation.NSForwardException for com.webobjects.foundation.NSForwardException for java.security.NoSuchAlgorithmException: Algorithm SunX509 not available "Algorithm SunX509 not available"
indicates that the used JVM implementation does not offer SSL support. Check for an update to that JVM or install the Sun JVM.
The Microsoft Internet Explorer 6 cannot use a port other than 443 (default) for a "websharewoa" secure HTTPS connection.
This section lists all the preference keys that are pertinent to the WebShare WebObjects Server. Find a description of how to set, view, change or delete preferences, with the HELIOS "prefdump", "prefvalue", and "prefrestore" utility programs in the HELIOS Base manual, chapter 6, "HELIOS utility programs".
Important: Make sure that preference keys DO NOT start or end with a slash ("/") character, and note that they are case-sensitive! Also, if any preference key or preference value includes spaces, that key or value must be enclosed in quotes.
Specifies the host name or IP address of the WebShare WebObjects Server. This is useful on machines with multiple IP addresses/host names. If this preference is not set, the WebShare WebObjects Server can be reached via any IP address/host name on the machine.
Specifies the WebShare File Server default host name prompt for the login dialog. It corresponds to the WebShare File Server entry in the WebShare login menu.
List of WebShare File Server host names or IP addresses which are allowed to be used on the WebShare WebObjects Server. The string must be comma-separated if more than one "allowed" host name or IP address is specified. If not set, all host names are allowed.
Specifies the WebShare File Server port number. If more than one WebShare File Server is used, they all have to use the same port.
Important: The value of this preference needs to be identical with the WebShare File Server preference TcpPort (7.8 "Preference keys"). If there should be the need to change a value, then make sure that both preference keys are assigned the same value!
Specifies the WebShare color used for the alternating lines in a table listing, e.g. the "Sharepoint" window. The color is defined by the HTML hexadecimal values of red, green and blue, e.g. #FFFF00 is yellow, #FF0000 is red, #00FF00 is green. See Fig. 16 in 5.1 "WebShare File Server login".
Specifies the WebShare toolbar color. The color is defined by the HTML hexadecimal values of red, green and blue, e.g. #FFFF00 is yellow, #FF000 is red, #00FF00 is green. See Fig. 17 in 5.2 "Work in a sharepoint".
This preference allows specifying a password for a protected HTML page, which allows monitoring the WebShare WebObjects Server and the events it is processing. By default, the page is unavailable until a password is set. For security reasons, this preference should not be used unless you are an WebObjects deployment specialist and you know how the WebShare WebObjects Server and WebObjects work internally.
The default time-out value for uploads and downloads of the WebShare WebObjects Server is 24 h (=86400 s). If more time is needed, e.g. due to a slow Internet connection, this preference may be set to a higher value.
Specifies that, after a user has been idle for a time, i.e. no web activity has occurred, the session will automatically be closed after one hour (=3600 s).
Modern browsers, e.g. Safari, FireFox, Internet Explorer support "gzip" compressed HTML pages. If supported by the browser, the WebShare WebObjects Server generates "gzip" compressed HTML pages. For slow connections, e.g. via modem or ISDN lines this will increase the browsing performance by factor 2-5, depending on the content. In case of problems with compressed pages this feature can be turned off by setting this preference to FALSE.
Note: The initial WebShare 1.0 product had no support for compressed pages.
| © 2005 HELIOS Software GmbH |
|
|
|
|
|