Last update: 2005-04-08
The ccWAP Gateway makes it possible for mobile devices to access content that is located on the local computer, in an intranet or on the Internet. The gateway takes requests from WAP-capable devices and connects to other servers in order to fetch content such as WML documents and images. Then, responses are converted to a format that is suitable for the mobile device if necessary, and is finally returned to the device. In case of security related applications (e-commerce, m-commerce), the transmission can be encrypted and the gateway can be authenticated by the use of electronic certificates.
Because of its mostly platform independent design, the ccWAP Gateway is able to run run on a wide variety of systems if they are network enabled. The following platforms are supported:
libssl.so.0
and libcrypto.so.0)The gateway makes only use of (very) basic system libraries and does not depend on advanced functionality that may be available. The requirements for the rest of the system are also very modest: About 400 KByte of disk space is needed for the program itself and about 2 to 5 MByte of main memory are required to run the gateway. The processor of the server machine should be fast enough, because some components are rather computing-intensive, e.g. when WTLS is in use. The gateway is a pure single-thread application, so that the benefits that result from having multiple processors available cannot be used by the gateway.
The ccWAP Gateway consists of the following files and directories, where some of them are platform dependent and hence are described separately.
wapgwsrvmain by using /bin/kshmaingethostwapgwsrv.shIn case the shell /bin/ksh is not available on the target system or
when its use is not desired, the invocation of wapgwsrv can also be
performed as follows:
/PATH/TO/main -a /PATH/TO/wapgwsrv ...
Another possibility (when permitted by the license) is to combine the
two files main und wapgwsrv into one file and rename the result to
wapgwsrv, e.g. by:
cat main wapgwsrv > wapgwsrv.new chmod +x wapgwsrv.new mv wapgwsrv.new wapgwsrv rm main
All further command line options are described in section "Running the Gateway".
It is not recommended to run the gateway under the user-id of root.
In order to nevertheless allow the gateway to bind to privileged ports,
that is, to ports below 1024, the program main (or a combined
wapgwsrv) may be installed suid-root. This privilege is only used
to bind sockets to ports, all other activities are performed with
normal access permissions.
wapgwsrv.exegethost.exewapgwsrv.exe for MS-Windows CE).MS-Windows versions of the gateway currently do not support SSL/TLS. Support for WTLS is independent of the underlying system and is always available.
wapgwsrv.licwapgwsrv or wapgwsrv.exe is
locatedwapgwsrv.cfgwml-docs/cgi-bin/log/ccwap.wucwml-docs/checkcom.wcc and may be loaded into mobile
devices that support thisccwap.keycheckcom.pemIt is not possible to run the ccWAP Gateway without a valid license file. This license file together with the program files must be readable for the application.
The operation of the ccWAP Gateway can be controlled through a number of parameters. These parameters can be specified directly on the command line, or they can be stored in a configuration file and then passed to the program as an argument on the command line. Both ways of passing parameters can be mixed arbitrarly.
Components of paths to files and directories, as used by some
parameters, must always be separated by a /, independent of the
underlying platform. The use of \ may cause unexpected behavior. The
ubiquitous drive letters under MS-Windows (e.g. c:) must be specified
as the first component of a path, e.g. /c:/programs/wapgwsrv.
A parameter consists of a name and a value. Both parts are
separated by a =. In the following list, all available parameters are
presented and are given together with example values, but which do not
necessarily represent their respective default value:
host=localhost:9200Defines the base address under which the gateway should be
accessible. The first part (in front of the :) specifies the DNS
name of the server machine or its IP address, while the second
part determines the base port number. Four UDP ports are occupied
in total (BasePort+0, BasePort+1, BasePort+2 and BasePort+3).
Default: host=localhost:9200
bindhost=0.0.0.0Determines the IP address on which the gateway should exclusively
listen for incoming UDP packets. The sockets are bound to all IP
addresses when the value is missing or empty, or when
bindhost=0.0.0.0 is specified. A specification such as
bindhost=127.0.0.1 would only allow local connections.
proxy=proxy:8080In case the gateway has to use a proxy server in order to fetch
WML documents and graphics from other servers, then it can be
given here by specifying the DNS name of the proxy server or its
IP address together with its port number. An eventually required
authentication by the proxy server can be fulfilled by prepending
the prefix userid:password@ with appropriate values for
userid and password.
It is also possible to use SSL/TLS for connections with a proxy
server and is indicated by the additional prefix https://, e.g.:
proxy=https://sslproxy:8081
allowuas=allowuas.lstThis parameter defines the name of a file that contains the
prefixes of User-Agent: headers to which exclusive access to the
gateway should be granted. Other devices are denied with the error
message "502" (Bad Gateway). Each line of the specified file
defines the case-sensitive prefix of a permitted User-Agent:
header. Comments and empty lines are not recognized as such. In
case the parameter allowuas= is not specified or is empty, or
when the file is not readable or is empty, then no checking of
User-Agent: headers is performed and all devices are accepted.
wmldocs=~dat/wml-docs/Defines the path to a directory that contains WML documents and graphics which constitute the local homepage of the gateway. This site is accessible for clients of the gateway under the URL
http://local/
The WML homepage feature is deactivated in case the parameter
wmldocs= is missing or is empty.
indexlist=index.wml i.wmlDefines a space-separated list of files that should be used as
index in the directory that is specified by wmldocs= and its
subdirectories. A missing parameter establishes the default value
indexlist=index.wml i.wml, while an empty value disables this
feature.
cgidir=~dat/cgi-bin/Determines a directory that is expected to contain only CGI programs that should be executed. This directory appears for clients of the gateway under the URL
http://local/cgi-bin/
Missing the parameter cgidir= or providing an empty value
disables this feature.
error404=/error404.wmlThis parameter defines the URL of a document that should be
returned to a device in response to an error with status code
"404" (Not Found), instead of the built-in error page. This can
happen only for accesses to the local homepage of the gateway,
that is, for URLs that start with the prefix http://local/. The
URL that is specified by error404= is interpreted relative to
http://local/ and is also allowed to refer to an external
document, which is fetched in the usual way in this case.
Notes: An error document is always delivered using the original status code, that is, "404"! When the internal processing of an error document leads to another status code than "200" (OK), then the built-in error page is returned instead. Relative links in error documents should be avoided, because their context generally differs from that of the document.
logdir=log/Defines a directory into which the logfiles should be placed. The
name of a logfile has the format access_NNNN.log, where
NNNN denotes the number of that port for which the accesses
are logged to that file in extended common logfile format
(including Referer: and User-Agent: headers). No logging takes
place in case the parameter logdir= is missing or has an empty
value.
logopts=dnsThe option logopts=dns enables the resolution of client IP
addresses into DNS hostnames. This procedure can take a long time,
therefore a good nameserver is recommended. An empty or missing
parameter disables this feature and causes only the client IP
addresses to be logged.
udplogdir=udplogdir/Defines a directory in which for each port number a subdirectory
is created which in turn is used to record all incoming (.req)
and outgoing (.res) UDP packets on that port and to save their
contents in separate files that are named by a timestamp in
hexadecimal format. An empty or missing parameter disables this
feature.
wtls.cert=ccwap.wucDefines a space-separated list of files that contain WTLS certificates which should be used by the gateway in order to authenticate itself to WAP clients (WTLS Class 2). The first certificate of such a chain represents the actual server certificate, while the remaining certificates, if specified, can be used to complete the chain to the root certificate. Note that not all devices support such certificate chains.
A WTLS certificate can be used either directly as such or it can be supplied in DER-encoded ASN.1-format. Each of these binary formats may further be used either directly or in PEM-encoded form with the gateway. In the last case, multiple certificates (of a chain) can be stored in the same file, and finally, the private RSA key may also be included in that file.
The specified certificates are only loaded into the gateway if a
private RSA key is specified by the parameter wtls.key= and if
that key can be successfully loaded.
wtls.key=ccwap.key passwordDefines a file that contains the private RSA key that belongs to the actual WTLS server certificate. Optionally, a base64-encoded password can be additionally specified (after a single space) that was used to encrypt the private key.
The private RSA key can be supplied in a special format or in DER-encoded ASN.1-format. Both formats also allow the key data to be encrypted. Each of these binary formats may further be used directly or in PEM-encoded form. In the last case, it is possible to include the RSA key into the same file as the WTLS certificate. The name of the file must be specified nevertheless for this parameter. Only the first private RSA key of a file is ever used.
It is possible to provide a private RSA key without specifying a corresponding WTLS certificate. In this case, only anonymous connections can be made (WTLS Class 1). This case also applys when no private key is specified at all and also causes a built-in key to be used instead.
tls.cacerts=checkcom.pemDefines a file that contains one or more PEM-encoded SSL/TLS CA certificates which in turn should be used to authenticate other servers when SSL/TLS is used to secure connections to other servers.
admin.host=localhost:8920This parameter, when specified, starts an additional administration server on the given port. This server makes it possible to manage the WML documents and other files that constitute the local homepage of the gateway. Accessing the URL
http://localhost:8920/?frameset
returns a start page that is divided into two parts. On the left side, a document tree displays the structure of the homepage, while the right side is reserved for displaying and editing the documents.
admin.binding=0.0.0.0Allows the socket on which the administration server is listening
for incoming connections to be bound to a specific IP address. A
value of 0.0.0.0 represents all addresses, which is also used in
case admin.binding= is not specified or has an empty value. A
specification such as admin.binding=127.0.0.1 would only allow
local connections.
admin.realm=WML-DocsDefines the text that should be displayed by the web browser in the prompt for a user-id and a password when the administration server is accessed. Authentication is disabled in case this parameter is empty or is not specified!
admin.authinfo=admin:adminDefines a user-id and a password, separated by a colon (:), that
should be used for authentication when accessing the
administration server.
A configuration file is a regular text file that can be modified with
any text editor. Each line contains one parameter and may be terminated
either by LF, CRLF or CR. Empty lines or lines that start with # or
which do not contain a = are ignored by the gateway.
A configuration file that is usually named wapgwsrv.cfg and that
lists all known parameters, although some on them are commented out, is
given in the following example:
# wapgwsrv.cfg host=localhost:9200 #bindhost=127.0.0.1 #proxy=localhost:8080 #allowuas=allowuas.lst wmldocs=~dat/wml-docs/ indexlist=index.wml i.wml cgidir=~dat/cgi-bin/ #error404=/error404.wml logdir=log/ #logopts=dns #udplogdir=udplog/ wtls.cert=ccwap.wuc wtls.key=ccwap.key tls.cacerts=checkcom.pem admin.host=localhost:8920 #admin.binding=127.0.0.1 admin.realm=WML-Docs admin.authinfo=admin:admin
The general calling sequence of the ccWAP Gateway looks like this:
/PATH/TO/wapgwsrv [[-d] [-m5] --] { Parameter | @ConfigFile }
DL:\PATH\TO\wapgwsrv.exe [[-m5] --] { Parameter | @ConfigFile }
The gateway should always be invoked by using the full program name, otherwise the program may fail to find itself or other required parts. Under MS-Windows and/or other GUI systems, this presents usually no problem and can be accomplished by simply activating the associated program symbol or icon.
The gateway can be terminated in the usual way which is provided by the underlying system for such purposes.
Option -d instructs the gateway (only under UNIX/Linux) to put itself
as a daemon into the background and to drop its connection to the
controlling terminal. The stderror output should be redirected to
/dev/null or to a file in this case, e.g. by appending 2>/dev/null
to the command line.
Option -m5 determines the memory usage and reserves about 5 Mbytes of main memory, which is recommended for server applications. Otherwise, only about 2 Mbytes are reserved.
Option -- marks the following command line arguments as application specific.
Each of the following command line arguments defines either a parameter
(Parameter) or a file that contains multiple parameters
(ConfigFile), see also section "Configuration of the
Gateway". The same parameter may occur multiple times, but only the
last (right most) setting is taken. This way it is possible to override
settings from a configuration file with those given on the command
line. When specifying parameters on the command line, it is best to use
double quotes (") around every parameter in order to protect them
against misinterpretation by the shell. The name of a configuration
file is interpreted relative to the installation directory of the
gateway (with the symbolic name ~dat/) if its name is not given by
using an absolute path.
The ksh-script named wapgwsrv.sh can be used alternatively to start
and stop the ccWAP Gateway under UNIX/Linux:
wapgwsrv.sh start {Parameter}Starts the gateway. Parameters for the gateway are taken from the
configuration file wapgwsrv.cfg. Additional parameters can be
specified on the command line, e.g.
wapgwsrv.sh start "bindhost=192.168.1.50"
The script does not check whether the gateway is running afterwards or not.
wapgwsrv.sh stopStops the gateway if it is running, otherwise a message that states this fact will be produced.
wapgwsrv.sh statusLists all processes that are related to the gateway. No output will be produced if the gateway is not running.
The ccWAP Gateway supports all transmission protocols that are specified for WAP 1.x over UDP/IP, these are:
The ccWAP Gateway supports SAR (Segmentation and Reassembly) in conjunction with the connection-oriented protocols (WSTP, WSTPS), but currently only in direction to the WAP client, that is, in responses. The theoretical limit for such transactions is 358400 bytes (256*1400 bytes), but in practice, sizes of about 32 Kbytes per transaction should not be exceeded. Requests of WAP clients that make use of SAR but nevertheless consist of only one packet are accepted in any case. The maximum packet size is 1400 bytes.
Transmissions between the ccWAP Gateway and WAP clients can be secured by using WTLS, that is, they can be encrypted and the gateway can be authenticated using electronic certificates. The ccWAP Gateway supports WTLS Class 1 (anonymous without server authentication) and WTLS Class 2 (with server authentication). The gateway permits strong cryptography only: RSA with 1024 bits or more for key exchange, RC5 with 128 bits for bulk encryption and SHA-1 for hashing and the MAC.
In order to fetch documents from other servers, the ccWAP Gateway is able use a proxy server if necessary. Authentication by the proxy server is also supported.
Communications between the ccWAP Gateway and other servers (including proxy servers) can be secured using SSL/TLS, that is, the transmission can be encrypted and web servers can be authenticated using electronic certificates. The ccWAP Gateway supports SSL 3.0 and TLS 1.0, but it permits strong cryptography only. Certificates of other servers are currently not verified.
The ccWAP Gateway does not return content back to a WAP client for
which the client has not explicitly stated that it does accept these
types of documents in the Accept: header of the request. Otherwise
the client receives an error message.
During the conversion of WML into its binary form, the ccWAP Gateway performs various optimizations which make heavy use of the string-table that is defined for the binary format of WML. This does compress the output by an additional certain amount if some strings have a common prefix or suffix in a WML deck. All characters are always transcoded to UTF-8. Many other character encodings of WML source documents are also supported by the gateway, such as UTF-16, ISO-8859-*, Windows-125[0-8], KOI8-R, GB2312, BIG5, SHIFT_JIS, EUC-JP, KSC5601 and EUC-KR.
Furthermore, the ccWAP Gateway offers the ability to provide a local homepage. An advantage of this is a shorter response time, because no other web server has to be contacted to fulfill a request. The WML homepage can consist of WML documents, images, CGI programs and other components. If the administration server of the gateway has been started (see section "Configuration of the Gateway"), the WML homepage can be managed remotely (from other computers) by the help of an HTML interface. Additionally, the server offers the ability to create simple WML documents without in-depth knowledge of WML.
The ccWAP Gateway provides an additional special function: Files of the
WML homepage which have the extension .csv are treated
automagically like a database. First, a search template is presented
in which at most two search terms can be specified together with the
fields where to search in and for display. Then, a search can be
issued and the results are displayed, and the possibility to browse
within the list of hits is also provided. The display messages are
available in the languages english and german, and are selected
depending on the Accept-Language: header of a request. The .csv
file must have a first line that contains the column names, supported
column separators are TAB (tabulator character), comma (,) and
semi-colon (;), but columns cannot contain the chosen column
separator. LF, CRLF, and CR can serve as line terminators. .csv files
can be created and modified by the help of the administration server,
with MS-Excel or by using any text editor.
Copyright (C) 2001-2005 CheckCom Inc. <info@checkcom.com>