
Using AWS
*********


Setting up environment
======================


Using environment variables
---------------------------

After installing *AWS* you must set the build environment to point the
compiler to the right libraries. First let's say that *AWS* has been
installed in "awsroot" directory.

Following are the instructions to set the environment yourself. Note
that the preferred solution is to use project files. In this case
there is no manual configuration.

*spec files*

   The spec files are installed in "<awsroot>/include/aws". Add this
   path into *ADA_INCLUDE_PATH* or put it on the command line
   *-aI<awsroot>/include/aws*.

*components*

   *AWS* uses some components they are installed in
   "<awsroot>/include/aws/components". Add this path into
   ADA_INCLUDE_PATH or put it on the command line
   *-I<awsroot>/include/aws/components*.

*libraries*

   The GNAT library files (".ali") and the *AWS* libraries
   ("libaws.a") are installed into "<awsroot>/lib/aws/static". Add
   this path into *ADA_OBJECTS_PATH* or put it on the command line
   *-aO<awsroot>/lib/aws/static*. Furthermore for *gnatlink* to find
   the libraries you must add the following library path option on the
   *gnatmake* command line *-largs -L<awsroot>/lib/aws/static -laws*.

   Note that to build SSL applications you need to add *-lssl
   -lcrypto* on gnatmake's *-largs* section.

*external libraries*

   You must do the same thing (setting *ADA_INCLUDE_PATH* and
   *ADA_OBJECTS_PATH*) for all external libraries that you will be
   using.


Using GNAT Project Files
------------------------

The best solution is to use the installed GNAT Project File "aws.gpr".
This is supported only for *GNAT 5.01* or above. You must have
installed *XML/Ada* with project file support too.

If this is the case just set the *ADA_PROJECT_PATH* variable to point
to the *AWS* and *XML/Ada* install directories. From there you just
have to with the *AWS* project file in your GNAT Project file, nothing
else to set:

   with "aws";

   project Simple is

     for Main use ("prog.adb");

     for Source_Dirs use ("src");

     for Object_Dir use "obj";

   end Simple;

See the *GNAT User's Guide* for more information about GNAT Project
Files.


Basic notions
=============

*AWS* is not a Web Server like *IIS* or *Apache*, it is a component to
embedded HTTP protocol in an application. It means that it is possible
to build an application which can also answer to a standard browser
like *Internet Explorer* or *Netscape Navigator*. Since *AWS* provides
support client and server HTTP protocol, applications can communicate
through the HTTP channel. This give a way to build distributed
applications, see AWS.Client.

An application using *AWS* can open many *HTTP* channels. Each channel
will use a specific port. For example, it is possible to embedded many
*HTTP* and/or many *HTTPS* channels in the same application.


Building an AWS server
----------------------

To build a server you must:

* declare the HTTP Web Server:

     WS  : AWS.Server.HTTP;

* Start the server

  You need to start the server before using it. This is done by
  calling *AWS.Server.Start* (see AWS.Server):

     procedure Start
       (Web_Server                : in out HTTP;
        Name                      : in     String;
        Callback                  : in     Response.Callback;
        Max_Connection            : in     Positive     := Def_Max_Connect;
        Admin_URI                 : in     String       := Def_Admin_URI;
        Port                      : in     Positive     := Def_Port;
        Security                  : in     Boolean      := False;
        Session                   : in     Boolean      := False;
        Case_Sensitive_Parameters : in     Boolean      := True;
        Upload_Directory          : in     String       := Def_Upload_Dir);
     --  Start the Web server. It initialize the Max_Connection connections
     --  lines. Name is just a string used to identify the server. This is used
     --  for example in the administrative page. Admin_URI must be set to enable
     --  the administrative status page. Callback is the procedure to call for
     --  each resource requested. Port is the Web server port. If Security is
     --  set to True the server will use an HTTPS/SSL connection. If Session is
     --  set to True the server will be able to get a status for each client
     --  connected. A session ID is used for that, on the client side it is a
     --  cookie. Case_Sensitive_Parameters if set to False it means that the CGI
     --  parameters name will be handled without case sensitivity. Upload
     --  directory point to a directory where uploaded files will be stored.

The procedure *Start* takes many parameters:

**Web_Server**

   this is the Web server to start.

**Name**

   This is a string to identify the server. This name will be used for
   example in the administrative status page.

**Callback**

   This is the procedure to call for each requested resources. In this
   procedure you must handle all the possible URI that you want to
   support. (see below).

**Max_Connection**

   This is the maximum number of simultaneous connections. It means
   that Max_Connection client's browsers can gets answer at the same
   time. This parameter must be changed to match your needs. A medium
   Web server will certainly need something like 20 or 30 simultaneous
   connections.

**Admin_URI**

   This is a special URI recognized internally by the server. If this
   URI is requested the server will return the administrative page.
   This page is built using a specific template page (default is
   '**aws_status.thtml**'), see Status page.

   The administrative page returns many information about the server.
   It is possible to configure the server via two configuration files
   see Configuration options.

**Port**

   This is the port to use for the Web server. You can use any free
   port on your computer. Note that on some OS specific range could be
   reserved or needs specials privileges (port 80 on Linux for
   example).

**Security**

   If Security is set to True the server will use an HTTPS/SSL
   connection. This part uses the *OpenSSL* library.

**Session**

   If Session is set to true the server will keep a session ID for
   each client. The client will be able to save and get variables
   associated with this session ID.

**Case_Sensitive_Parameters**

   If set to True the CGI name parameters will be handled without
   using the case.

Note that there is other *Start* routines which support other
features. For example there is a *Start* routine which use a
dispatcher routine instead of the simple callback procedure, see
AWS.Server. And there is also the version using a *Config.Object*
which is the most generic one.

* provides a callback procedure

  The callback procedure has the following prototype:

     function Service (Request : in AWS.Status.Data) return AWS.Response.Data;

  This procedure receive the request status. It is possible to
  retrieve information about the request through the *AWS.Status* API
  (see AWS.Status.).

  For example, to know what URI has been asked:

     URI : constant String := AWS.Status.URI (Request);

     if URI = "/whatever" then
        ...
     end if;

  Then this function should return an answer using one of the
  constructors in *AWS.Response* (see AWS.Response.). For example, to
  return an *HTML* message:

     AWS.Response.Build (Content_Type => "text/html",
                         Message_Body => "<p>just a demo");

  It is also possible to return a file. For example, here is the way
  to return a PNG image:

     AWS.Response.File (Content_Type => "image/png",
                        Filename     => "adains.png");

Note that the main procedure should exit only when the server is
terminated. For this you can use the *AWS.Server.Wait* service.

A better solution is to use a template engine like Templates_Parser to
build the *HTML* Web Server answer. Templates_Parser module is
distributed with this version of AWS.


Callback procedure
------------------

The callback procedure is the user's code that will be called by the
AWS component to get the right answer for the requested resource. In
fact AWS just open the HTTP message, parsing the HTTP header and it
builds an object of type *AWS.Status.Data*. At this point it calls the
user's callback procedure, passing the object. The callback procedure
must returns the right response for the requested resources. Now AWS
will just build up the HTTP response message and send it back to
user's browser.

**But what is the resource ?**

Indeed in a standard Web development a resource is either a static
object - an *HTML* page, an *XML* or *XSL* document - or a *CGI*
script. With *AWS* a resource is *just a string* to identify the
resource, it does not represent the name of a static object or *CGI*
script.

So this string is just an internal representation for the resource.
The callback procedure must be implemented to handle each internal
resource and return the right response.

Let's have a small example. For example we want to build a Web server
that will answer 'Hello World' if we ask for the internal resource
**/hello**, and must answer 'Hum...' otherwise:

   with AWS.Response;
   with AWS.Server;
   with AWS.Status;

   procedure Hello_World is

     WS : AWS.Server.HTTP;

     function HW_CB (Request : in AWS.Status.Data)
       return AWS.Response.Data
     is
        URI : constant String := AWS.Status.URI (Request);
     begin
        if URI = "/hello" then
           return AWS.Response.Build ("text/html", "<p>Hello world !");
        else
           return AWS.Response.Build ("text/html", "<p>Hum...");
        end if;
     end HW_CB;

   begin
      AWS.Server.Start
        (WS, "Hello World", Callback => HW_CB'Unrestricted_Access);
      delay 30.0;
   end Hello_World;

Now of course the resource internal name can represent a file on disk.
It is not mandatory but it is possible. For example it is perfectly
possible to build with *AWS* a simple page server.

As an example, let's build a simple page server. This server will
returns files in the current directory. Resources internal name
represent an *HTML* page or a *GIF* or *PNG* image for example. This
server will return a 404 message (Web Page Not Found) if the file does
not exist. Here is the callback procedure that implements such simple
page server:

   function Get (Request : in AWS.Status.Data) return AWS.Response.Data is
      URI      : constant String := AWS.Status.URI (Request);
      Filename : constant String := URI (2 .. URI'Last);
   begin
      if Utils.Is_Regular_File (Filename) then
         return AWS.Response.File
                  (Content_Type => AWS.MIME.Content_Type (Filename),
                   Filename     => Filename);

      else
         return AWS.Response.Acknowledge
           (Messages.S404,
            "<p>Page '" & URI & "' Not found.");
      end if;
   end Get;

Form parameters
---------------

Form parameters are stored into a table of key/value pair. The key is
the form input tag name and the value is the content of the input
field as filled by the user:

   Enter your name

"
   <INPUT TYPE=TEXT NAME=name VALUE="<default>" size=15>

Note that as explained above Callback procedure, the resource
described in *ACTION* is just an internal string representation for
the resource.

In this example there is two form parameters:

*name*
   The value is the content of this text field as filled by the
   client.

*go*
   The value is "Ok".

There is many functions (in *AWS.Parameters*) to retrieve the tag name
or value and the number of parameters. Here are some examples:

   function Service (Request : in AWS.Status.Data) return AWS.Response.Data is
      P : constant AWS.Parameters.List := AWS.Status.Parameters (Request);
   ...

*AWS.Parameters.Get (P, "name")*

   Returns the value for parameter named **name**

*AWS.Parameters.Get_Name (P, 1)*

   Returns the string "name".

*AWS.Parameters.Get (P, 1)*

   Returns the value for parameter named **name**

*AWS.Parameters.Get (P, "go")*

   Returns the string "Ok".

*AWS.Parameters.Get_Name (P, 2)*

   Returns the string "go".

*AWS.Parameters.Get (P, 2)*

   Returns the string "Ok".

*Request* is the *AWS* current connection status passed to the
callback procedure. And *P* is the parameters list retrieved from the
connection status data. For a discussion about the callback procedure
see Building an AWS server.

Distribution of an AWS server
-----------------------------

The directory containing the server program must contain the following
files if you plan to use a status page see Status page.

**aws_status.thtml**

   The template *HTML* file for the *AWS* status page.

**aws_logo.png**

   The *AWS* logo displayed on the status page.

**aws_up.png**

   The *AWS* hotplug table up arrow.

**aws_down.png**

   The *AWS* hotplug table down arrow.

Note that these filenames are the current *AWS* default. But it is
possible to change those defaults using the configuration files see
Configuration options.

Building answers
================

We have already seen, in simple examples, how to build basic answers
using *AWS.Response* API. In this section we present all ways to build
answers from basic support to the more advanced support like the
compressed memory stream response.

Redirection
-----------

A redirection is a way to redirect the client's browser to another
URL. Client's won't notice that a redirection has occurs. As soon as
the browser has received the response from the server it will retrieve
the page as pointed by the redirection:

   return Response.URL (Location => "/use-this-one");

New location for a page
-----------------------

User will receive a Web page saying that this page has moved and
eventually pointing to the new location:

   return Response.Moved
     (Location => "/use-this-one";
      Message  => "This page has moved, please update your reference");

Authentication required
-----------------------

For protected pages you need to ask user to enter a password. See
Authentication.

Sending back an error message
-----------------------------

*Acknowledge* can be used to send back error messages. There is many
kind of status code, see *Message.Status_Code* definition. Together
with the status code it is possible to pass textual error message in
*Message_Body* parameter:

   return Response.Acknowledge
     (Status_Code  => Messages.S503,
      Message_Body => "Can't connect to the database, please retry later.",
      Content_Type => MIME.Text_Plain);

Response from a string
----------------------

This is the simplest way to build a response object. There is two
constructors in *AWS.Response*, one based on a standard string and one
for Unbounded_String:

   return Response.Build (MIME.Text_HTML, "My answer");

The Build routine takes also a status code parameter to handle errors.
By default this code is *Messages.S200* which is the standard HTTP
status (no error encountered). The other parameter can be used to
control caches. See AWS.Response.

Response from a Stream_Element_Array
------------------------------------

This is exactly as above but the Build routine takes a
*Stream_Element_Array* instead of a string.

Response from a file
--------------------

To build a *File* response there is a single constructor named *File*.
This routine is very similar to the one above except that we specify a
filename as the response:

   return Response.File (MIME.Text_HTML, "index.html");

Again there parameters to control the status code and cache. No check
on the filename is done at this point, so if "index.html" does not
exit no exception is raised. The server is responsible to check for
the file and to properly send back the 404 message if necessary.

Note that this routine takes an optional parameter named *Once* that
is to be used for temporary files created on the server side for the
client. With *Once* set to *True* the file will be deleted by the
server after sending it (this includes the case where the download is
suspended).

Response from a stream
----------------------

Sometimes it is not possible (or convenient) to build the response in
memory as a string object for example. Streams can be used to
workaround this. The constructor for such response is again very
similar to the ones above except that instead of the data we pass an
handle to a *Resources.Streams.Stream_Type* object.

The first step is to build the stream object. This is done by deriving
a new type from *Resources.Streams.Stream_Type* and implementing three
abstract procedures.

*Read*

   Must return the next chunk of data from the stream. Note that
   initialization if needed are to be done there during the first call
   to read.

*End_Of_File*

   Must return True when there is no more data on the stream.

*Close*

   Must close the stream and for example release all memory used by
   the implementation.

The second step is to build the response object:

   type SQL_Stream is new Resources.Streams.Stream_Type;

   Stream_Object : SQL_Stream;

   procedure Read (...) is ...
   function End_Of_File (...) return Boolean is ...
   procedure Close (...) is

   ...

   return Response.Stream (MIME.Text_HTML, Stream_Object);

Note that in some cases it is needed to create a file containing the
data for the client (for example a tar.gz or a zip archive). But there
is no way to properly remove this file from the file system as we
really don't know when the upload is terminated when using the
*AWS.Response.File* constructor. To solve this problem it is possible
to use a stream as the procedure *Close* is called by the server when
all data have been read. In this procedure it is trivial to do the
necessary clean-up.

Response from a on-disk stream
------------------------------

An ready-to-use implementation of the stream API described above where
the stream content is read from an on-disk file.

Response from a on-disk once stream
-----------------------------------

An ready-to-use implementation of the stream API described above where
the stream content is read from an on-disk file. When the transfer is
completed the file is removed from the file system.

Response from a memory stream
-----------------------------

This is an implementation of the standard stream support described
above. In this case the stream is in memory and built by adding data
to it.

To create a memory stream just declare an object of type
*AWS.Resources.Streams.Memory.Stream_Type*. When created, this memory
stream is empty, using the *Streams.Memory.Append* routines it is
possible to add chunk of data to it. It is of course possible to call
*Append* as many times as needed. When done just return this object to
the server:

   Data : AWS.Resources.Streams.Memory.Stream_Type;

   Append (Data, Translator.To_Stream_Element_Array ("First chunk"));
   Append (Data, Translator.To_Stream_Element_Array ("Second chunk..."));

   ...

   return Response.Stream (MIME.Text_HTML, Data);

Note that you do not have to take care of releasing the allocated
memory, the default *Close* routine will do just that.

Response from a compressed memory stream
----------------------------------------

This is a slight variant of the standard memory stream described
above. In this case the stream object must be declared as a
*AWS.Resources.Streams.Memory.ZLib.Stream_Type*.

The ZLib stream object must be initialized to enable the compression
and select the right parameters. This is done using the
*AWS.Resources.Streams.Memory.ZLib.Deflate_Initialize* routine which
takes many parameters to select the right options for the compression
algorithm, all of them have good default values. When initialized the
compressed stream object is used exactly as a standard stream:

   Data : AWS.Resources.Streams.Memory.ZLib.Stream_Type;

   Deflate_Initialize (Data);

   Append (Data, Translator.To_Stream_Element_Array ("First chunk"));
   Append (Data, Translator.To_Stream_Element_Array ("Second chunk..."));

   ...

   return Response.Stream (MIME.Text_HTML, Data);

Note that there is the reverse implementation to decompress a stream.
See AWS.Resources.Streams.Memory.ZLib. It's usage is identical.

Split page
----------

*AWS* has a specific high level service to split a large response into
a set of pages. For more information see Split pages.

Response a from pipe stream
---------------------------

The response sent to the server is read from the output of an external
application. This kind of stream can be used to avoid writing a
temporary file into the hard disk. For example it is possible to
return an archive created with the *tar* tool without writing the
intermediate tar achive on the disk.

Configuration options
=====================

To configure an *AWS* server it is possible to use a configuration
object. This object can be set using the *AWS.Config.Set* API or
initialized using a configuration file.

Configuration files are a way to configure the server without
recompiling it. Each application can be configured using two
configurations files:

*aws.ini*

   This file is parsed first and corresponds to the configuration for
   all AWS server runs in the same directory.

*<program_name>.ini*

   This file is parsed after "aws.ini". It is possible with this
   initialization file to have specific settings for some servers.
   "program_name.ini" is looked first in the application's directory
   and then in the current working directory. This is only supported
   on platforms where *Ada.Command_Line* is implemented. So, on
   **VxWorks** only "aws.ini" is parsed.

Furthermore, it is possible to read a specific configuration file
using the *AWS.Config.Ini.Read* routine. See AWS.Config.Ini.

Current supported options are:

*Accept_Queue_Size (positive)*

   This is the size of the queue for the incoming requests. Higher
   this value will be and less "*connection refused*" will be reported
   to the client. The default value is **64**.

*Admin_Password (string)*

   This is the password used to call the administrative page. The
   password can be generated with "aws_password" (the module name must
   be *admin*):

      $ aws_password admin <password>

*Admin_URI (string)*

   This is the URI to call the administrative page. This can be used
   when calling *AWS.Server.Start*. The default is **<not-defined>**.

*Case_Sensitive_Parameters (boolean)*

   If set to *True* the *HTTP* parameters are case sensitive. The
   default value **TRUE**.

*Certificate (string)*

   Set the certificate file to be used with the secure servers. The
   default is **cert.pem**. A single certificate or a certificate
   chain is supported. The certificates must be in *PEM* format and
   the chain must be sorted starting with the subject's certificate,
   followed by intermediate CA certificates if applicable and ending
   at the highest level (root) CA certificate. If the file contains
   only a single certificate, it can be followed by a private key. In
   this case the Key parameter (see below) must empty.

*Check_URL_Validity (boolean)*

   Server have to check URI for validity. For example it checks that
   an URL does not reference a resource above the Web root. The
   default is **TRUE**.

*cipher_priorities*

   Values are dependent on the actual secure layer (OpenSSL or
   GNUTLS). It is used to specify the session’s handshake algorithms
   and options.

*Cleaner_Wait_For_Client_Timeout (duration)*

   Number of seconds to timeout on waiting for a client request. This
   is a timeout for regular cleaning task. The default is **80.0**
   seconds.

*Cleaner_Client_Header_Timeout (duration)*

   Number of seconds to timeout on waiting for client header. This is
   a timeout for regular cleaning task. The default is **7.0**
   seconds.

*Cleaner_Client_Data_Timeout (duration)*

   Number of seconds to timeout on waiting for client message body.
   This is a timeout for regular cleaning task. The default is
   **28800.0** seconds.

*Cleaner_Server_Response_Timeout (duration)*

   Number of seconds to timeout on waiting for client to accept
   answer. This is a timeout for regular cleaning task. The default is
   **28800.0** seconds.

*CRL_File (string)*

   This configuration option must point to a filename containing a CRL
   (Certificate Revocation List). This will make it possible to
   control client connecting to the server. The default values is
   **<not-defined>**.

*Directory_Browser_Page (string)*

   Specify the filename for the directory browser template page. The
   default value is **aws_directory.thtml**.

*Down_Image (string)*

   The name of the down arrow image to use in the status page. The
   default is **aws_down.png**.

*Error_Log_Filename_Prefix (string)*

   This is to set the filename prefix for the log file. By default the
   log filename prefix is the program name (without extension)
   followed by "_error".

*Error_Log_Split_Mode [None/Each_Run/Daily/Monthly]*

   It indicates how to split the error logs. Each_Run means that a new
   log file is used each time the process is started. Daily and
   Monthly will use a new log file each day or month. The default is
   **NONE**.

*Exchange_Certificate (boolean)*

   If set to True it means that the client will be asked to send its
   certificate to the server. The default value is **FALSE**.

*Certificate_Required (boolean)*

   If set to True the server will reject all SSL connections if the
   client did not provide a certificate (be it valid or not). The
   *Exchange_Certificate* option must be set in this case. The default
   value is **FALSE**.

*Force_Wait_For_Client_Timeout (duration)*

   Number of seconds to timeout on waiting for a client request. This
   is a timeout for urgent request when resources are missing. The
   default is **2.0** seconds.

*Force_Client_Header_Timeout (duration)*

   Number of seconds to timeout on waiting for client header. This is
   a timeout for urgent request when resources are missing. The
   default is **2.0** seconds.

*Force_Client_Data_Timeout (duration)*

   Number of seconds to timeout on waiting for client message body.
   This is a timeout for urgent request when resources are missing.
   The default is **10800.0** seconds.

*Force_Server_Response_Timeout (duration)*

   Number of seconds to timeout on waiting for client to accept
   answer. This is a timeout for urgent request when resources are
   missing. The default is **10800.0** seconds.

*Free_Slots_Keep_Alive_Limit (positive)*

   This is the minimum number of remaining free slots to enable keep-
   alive HTTP connections. For heavy-loaded HTTP servers, the
   Max_Connection parameter should be big enough, and
   Free_Slots_Keep_Alive_Limit should be about 1-10% of the
   Max_Connection parameter depending on the duration of the average
   server response. Longer is the average time to send back a response
   bigger Free_Slots_Keep_Alive_Limit should be. The default is **1**.

*Hotplug_Port (positive)*

   This is the hotplug communication port needed to register and un-
   register an hotplug module. The default value is **8888**.

*Key (string)*

   Set the RSA key file to be used with the secure servers. The
   default file is **<not-defined>**.

*Line_Stack_Size (positive)*

   The HTTP lines stack size. The stack size must be adjusted for each
   applications depending on the use of the stack done by the callback
   procedures. The default is **1376256**.

*Log_Extended_Fields (string list)*

   Comma separated list of the extended log field names. If this
   parameter is empty, the HTTP log would be in the apache compartible
   format, otherwise log file would be in Extended format. For more
   information see Server Log.

*Log_File_Directory (string)*

   This is to set the directory where log file must be written. This
   parameter will be used automatically by *AWS.Log* if logging
   facility is enabled. By default log files are written in the
   current directory. The default is **./**.

*Log_Filename_Prefix (string)*

   This is to set the filename prefix for the log file. By default the
   log filename prefix is the program name (without extension).

*Log_Split_Mode [None/Each_Run/Daily/Monthly]*

   It indicates how to split the logs. Each_Run means that a new log
   file is used each time the process is started. Daily and Monthly
   will use a new log file each day or month. The default is **NONE**.

*Logo_Image (string).*

   The name of the logo image to use in the status page. The default
   is **aws_logo.png**.

*Max_Concurrent_Download (positive)*

   Control the maximum number of parallel downloads accepted by the
   download manager. The default value is **25**.

*Max_Connection (positive)*

   This is the maximum number of simultaneous connections for the
   server. This can be used when calling the *AWS.Server.Start*. The
   default is **5**.

   Note that the total number of threads used by a server is:

      N = <main server thread> + <max connections> [+ <session>]

   Note: [...] means optional value Add 1 only if the session feature
   is activated. This is due to the session cleaner task.

*Max_POST_Parameters (positive)*

   The maximum number of POST parameters supported by AWS. The default
   value is **100**.

*Max_WebSocket_Handler (positive)*

   The maximum number of message to handle simultaenously. The default
   value is **2**.

*MIME_Types (string)*

   The name of the file containing the MIME types associations. The
   default file name is **aws.mime**.

*Receive_Timeout (duration)*

   Number of seconds to timeout when receiving chunk of data. The
   default is **30.0** seconds.

*Reuse_Address (boolean)*

   Set the socket reuse address policy. If set to True the server will
   be able to bind to a socket that has just been released without the
   need of waiting. Enabling this feature may introduce security risks
   on some platforms. The default is **FALSE**.

*Security_Mode (string)*

   Set the security mode to use for the secure connections. The
   default mode is **SSLv23**. See AWS.Net.SSL.

*Send_Buffer_Size (positive)*

   This is the socket internal buffer used for sending data to the
   clients. The default is **0**.

*Send_Timeout (duration)*

   Number of seconds to timeout when sending chunk of data. The
   default is **40.0** seconds.

*Server_Host (string)*

   The name of the host machine. This can be used if a computer has
   more than one IP address, it is possible to have two servers at the
   same port on the same machine, both being binded on different IP
   addresses.

*Server_Name (string)*

   The name of the server. This can be used when calling
   *AWS.Server.Start*. The default is **AWS Module**.

*Server_Priority (natural)*

   Priority of the task handling the HTTP protocol. The default is
   Default_Priority.

*Server_Port (integer)*

   The port where server will wait for incoming connections requests.
   This can be used when calling *AWS.Server.Start*. The default is
   **8080**.

*Service_Priority (natural)*

   Priority of the tasks used by optional services like SMTP Server,
   Server Push, Jabber and the Transient Page cleaner. The default is
   **Default_Priority**.

*Session (boolean)*

   Whether the session support must be activated or not. The default
   is **FALSE**.

*Session_Name (string)*

   The name of the cookie session. This can be used to support
   sessions for multiple servers embedded into the same executable.
   The default is **AWS**.

*Session_Id_Length (positive)*

   The length of the session id in characters. The default is **11**
   characters.

*Session_Lifetime (duration)*

   Number of seconds to keep session information. After this period a
   session is obsoleted and will be removed at next cleanup. The
   default is **600.0** seconds.

*Session_Cleanup_Interval (duration)*

   Number of seconds between each run of the session cleanup task.
   This task will remove all session data that have been obsoleted.
   The default is **300.0** seconds.

*Session_Cleaner_Priority (natural)*

   Priority of the task cleaning the session data. The default is
   **Default_Priority**.

*Status_Page (string)*

   The name of the status page to used. The default is
   **aws_status.thtml**.

*Transient_Cleanup_Interval (positive)*

   Specify the number of seconds between each run of the cleaner task
   to remove transient pages. The default value is **180.0** seconds.

*Transient_Lifetime (duration)*

   Specify the number of seconds to keep a transient page. After this
   period the transient page is obsoleted and will be removed during
   next cleanup. The default value is **300.0** seconds.

*Trusted_CA (string)*

   This must point to the file containing the list of trusted
   Certificate Authorities. The CA in this file will be used to verify
   the client certificate validity. The default values is **<not-
   defined>**.

*Up_Image (string)*

   The name of the up arrow image to use in the status page. The
   default is **aws_up.png**.

*Upload_Directory (string)*

   This is to set the directory where upload files must be stored. By
   default uploaded files are written in the current directory. The
   default is **<not-defined>**.

*WebSocket_Message_Queue_Size (positive)*

   This is the size of the queue containing incoming messages waiting
   to be handled by one of the task, see Max_WebSocket_Handler above.
   The default value is **10**.

*WebSocket_Origin (string)*

   This is a regular expression which can be used to handle WebSockets
   originating from a specific domain. By default AWS handles
   WebSockets from any origins.

*WebSocket_Priority (natural)*

   Priority of the task handling the WebSockets. The default is
   **Default_Priority**.

*WWW_Root (string)*

   This option sets the Web Server root directory. All Web resources
   are referenced from this root directory. The default value is
   **./**.

Each option value can be retrieved using the *AWS.Config* unit or set
using *AWS.Config.Set*.

For example to build a server where the *port* and the maximum number
of *connection* can be changed via a configuration file (either
"aws.ini" or "<program_name>.ini"):

   WS   : AWS.Server.HTTP;

   Conf : constant AWS.Config.Object := AWS.Config.Get_Current;

   Server.Start (WS, Service'Access, Conf);


Session handling
================

*AWS* provides a way to keep session data while users are browsing. It
works by creating transparently a session ID where it is possible to
insert, delete and retrieve session data using a standard Ada API (see
AWS.Session.). Session data are key/value pair each of them being
strings. These sessions data are kept on the server, for client side
state management see HTTP state management.

* First you declare and start an HTTP channel with session enabled:

     WS : AWS.Server.HTTP;

     Server.Start (WS,
                   Port     => 1234,
                   Callback => Service'Access,
                   Session  => True);

  Here we have built an HTTP channel with a maximum of 3 simultaneous
  connections using the port 1234. A session ID will be created and
  sent inside a cookie to the client's browser at the first request.
  This session ID will be sent back to the server each time the client
  will ask for a resource to the server.

* Next, in the Service callback procedure that you have provided you
  must retrieve the Session ID. As we have seen, the callback
  procedure has the following prototype:

     function Service (Request : in AWS.Status.Data) return AWS.Response.Data;

  The Session ID is kept in the Request object and can be retrieved
  using:

     Session_ID  : constant AWS.Session.ID := AWS.Status.Session (Request);

* From there it is quite easy to get or set some session data using
  the provided API. For example:

     declare
        C : Integer;
     begin
        C := AWS.Session.Get (Session_ID, "counter");
        C := C + 1;
        AWS.Session.Set (Session_ID, "counter", C);
     end;

  This example first get the value (as an Integer) for session data
  whose key is "*counter*", increment this counter and then set it
  back to the new value.

It is also possible to save and restore all session data. It means
that the server can be shutdown and launched some time after and all
client data are restored as they were at shutdown time. Client will
just see nothing. With this feature it is possible to shutdown a
server to update its look or because a bug has been fixed for example.
It is then possible to restart it keeping the complete Web server
context.


HTTP state management
=====================

*AWS* provides a full implementation of RFC 2109 via the *AWS.Cookie*
package. Using this package you set, get and expire client-side HTTP
cookies.

First we set a cookie:

   declare
      Content : AWS.Response.Data;
   begin
      AWS.Cookie.Set (Content,
                      Key      => "hello",
                      Value    => "world",
                      Max_Age  => 86400.0);
   end;

Here we set the cookie *hello* with the value *world*, and we tell the
client to expire the cookie 86400 seconds into the future.

Getting the cookie value back is equally simple:

   declare
      Request : AWS.Status.Data
      --  Assume that this object contain an actual HTTP request.
   begin
      Put_Line (AWS.Cookie.Get (Request, "hello"));
      --  Output 'world'
   end;

Had the cookie *hello* not existed, an empty *String* would've been
returned.

In some cases it might be of value to know if a given cookie exists,
and for that we have the *Exists* function available:

   declare
      Request : AWS.Status.Data
      --  Assume that this object contain an actual HTTP request
   begin
      if AWS.Cookie.Exists ("hello") then
         Put_Line ("The 'hello' cookie exists!");
      end if;
   end;

Note that *Exists* doesn't care if the cookie contains an actual value
or not. If a cookie with no value exists, *Exists* will return *True*.

And finally we might wish to tell the client to expire a cookie:

   declare
      Content : AWS.Response.Data;
   begin
      AWS.Cookie.Expire (Content,
                         Key  => "hello");
   end;

The Cookie package provide *Get* functions and *Set* procedures for
*String*, *Integer*, *Float* and *Boolean* types, but since cookies
are inherently strings, it's important to understand what happens when
the cookie *String* value can't be converted properly to either
*Integer*, *Float* or *Boolean*.

So if either conversion fails or the cookie simply doesn't exist, the
following happens:

* For *Integer*, the value 0 is returned

* For *Float*, the value 0.0 is returned.

* For *Boolean*, the value *False* is returned. Note that only the
  string 'True' is *True*. Everything else is *False*.

For more information see AWS.Cookie.


Authentication
==============

*AWS* supports **Basic** and **Digest** authentication. The
authentication request can be sent at any time from the callback
procedure. For this the *AWS.Response.Authenticate* message must be
returned.

The authentication process is as follow:

* Send authentication request

  From the callback routine return an authentication request when
  needed:

     function Service (Request : in Status.Data) return Response.Data is
        URI  : constant String := Status.URI (Request);
        User : constant String := Status.Authorization_Name (Request);
     begin
        --  URI starting with "/prot/" are protected
        if URI (URI'First .. URI'First + 5) = "/prot/"
          and then User = ""
        then
           return Response.Authenticate ("AWS", Response.Basic);

  The first parameter is the **Realm**, it is just a string that will
  be displayed (on the authentication dialog box) by the browser to
  indicate for which resource the authentication is needed.

* Check authentication

  When an authentication as been done the callback's request data
  contain the user and password. Checks the values against an ACL for
  each protected resources:

     function Protected_Service
       (Request : in AWS.Status.Data) return AWS.Response.Data
     is
        User : constant String := Status.Authorization_Name (Request);
        Pwd  : constant String := Status.Authorization_Password (Request);
     begin
        if User = "xyz" and then Pwd = "azerty" then
           return ...;

Note that the **Basic** authentication is not secure at all. The
password is sent unencoded by the browser to the server. If security
is an issue it is better to use the **Digest** authentication and/or
an **SSL** server.

File upload
===========

File upload is the way to send a file from the client to the server.
To enable file upload on the client side the Web page must contain a
**FORM** with an **INPUT** tag of type **FILE**. The **FORM** must
also contain the **enctype** attribute set to *multipart/form-data*:

     File to process: 

On the server side, *AWS* will retrieve the file and put it into the
upload directory. *AWS* add a prefix to the file to ensure that the
filename will be unique on the server side. The upload directory can
be changed using the configuration options. See Configuration options.

The uploaded files are removed after the user's callback. This is done
for security reasons, if files were not removed it would be possible
to fill the server hard disk by uploading large files to the server.
This means that uploaded files must be specifically handled by the
users by either copying or renaming them.

*AWS* will also setup the form parameters as usual. In the above
example there is two parameters (see Form parameters).

*filename*

   This variable contains two values, one with the client side name
   and one with the server side name.

*First value : Parameters.Get (P, "filename")*

   The value is the full pathname of the file on the server. (i.e. the
   upload directory catenated with the prefix and filename).

*Second value : Parameters.Get (P, "filename", 2)*

   The value is the simple filename (no path information) of the file
   on the client side.

*go*

   The value is "Send File"

Communication
=============

This API is used to do communication between programs using the HTTP
GET protocol. It is a very simple API not to be compared with *GLADE*
or *SOAP*. This communication facility is to be used for simple
request or when a light communication support is needed. For more
complex communications or to achieve inter-operability with other
modules it is certainly a good idea to have a look at the *AWS/SOAP*
support, see SOAP.

In a communication there is a Client and a Server. Here is what is to
be done on both sides to have programs talking together.

Communication - client side
---------------------------

On the client side it is quite simple. You just have to send a message
using *AWS.Communication.Client.Send_Message*:

   function Send_Message
     (Server     : in String;
      Port       : in Positive;
      Name       : in String;
      Parameters : in Parameter_Set := Null_Parameter_Set)
      return Response.Data;

The message is sent to the specified server using the given port. A
message is composed of a name which is a string and a set of
parameters. There is a parameter set constructor in
*AWS.Communication*. This function return a response as for any
callback procedure.

Communication - server side
---------------------------

On the server side things are a bit more complex but not that
difficult. You must instantiate the *AWS.Communication.Server* generic
package by providing a callback procedure. This callback procedure
will must handle all kind of message that a client will send.

During instantiation you must also pass a context for the
communication server. This context will be passed back to the callback
procedure:

   generic

      type T (<>) is limited private;
      type T_Access is access T;

      with function Callback
        (Server     : in String;
         Name       : in String;
         Context    : in T_Access;
         Parameters : in Parameter_Set := Null_Parameter_Set)
         return Response.Data;

   package AWS.Communication.Server is
      ...

A complete example can be found in the demos directory. Look for
"com_1.adb" and "com_2.adb".

Note that this communication API is used by the Hotplug module
facility, see Hotplug module.


Hotplug module
==============

An **Hotplug module** is a module that can by dynamically binded to a
running server. It is a Web server and the development process is very
similar to what we have seen until now Building an AWS server. The
Hotplug module will register itself into a Web server by sending a
message using the communication API. The Hotplug module send to the
server a regular expression and an URL. The main server will redirect
all URL matching the regular expression to the Hotplug module.

Note that the main server will redirect the URL to the first matching
regular expression.


Hotplug module - server activation
----------------------------------

The first step is to properly create the main server hotplug module
registration file. This file must list all hotplug modules that can
register into the main server. Each line have the following format:

   hotplug_module_name:password:server:port

*hotplug_module_name*

   The name of the hotplug module. You can choose any name you want.
   This name will be use during the registration process and to
   generate the password.

*password*

   The MD5 password, see below.

*server*

   The name of the server where the redirection will be made. This is
   for security reasons, main server will not permit to redirect
   requests to any other server.

*port*

   The port to use for the redirection on *server*.

You must create a password for each hotplug modules. The generated
password depends on the hotplug module name. A tool named
*aws_password* is provided with *AWS* to generate such password. Usage
is simple:

   $ aws_password <hotplug_module_name> <password>

Then, after starting the main server you must activate the Hotplug
feature:

   AWS.Server.Hotplug.Activate (WS'Unchecked_Access, 2222, "hotplug_conf.ini");

"hotplug_conf.ini" is the hotplug module registration file described
above.


Hotplug module - creation
-------------------------

Here is how to create an Hotplug module:

* First you create a standard Web server, see Building an AWS
  server:

     WS : AWS.Server.HTTP (3, 1235, False, Hotplug_CB.Hotplug'Access, False);

  Here we have a server listening to the port 1235. This server can be
  used alone if needed as any Server developed with AWS.

* Then you register the Hotplug module to the main server, see
  AWS.Client.Hotplug:

     Response := AWS.Client.Hotplug.Register
                   (Name     => "Hotplug_Module_Demo",
                    Password => "my_password",
                    Server   => "http://dieppe:2222",
                    Regexp   => ".*AWS.*",
                    URL      => "http://omsk:1235/");

  The hotplug module *Hotplug_Module_Demo* must have been declared on
  the main server, the password and redirection must have been
  properly recorded too for security reasons, see Hotplug module -
  server activation. This command register *Hotplug_Module_Demo* into
  the server running on the machine *dieppe* and ask it to redirect
  all *URL* containing *AWS* to the server running on machine *omsk*
  on port *1235*.

* When the Hotplug module is stopped, you must unregister it:

     Response := AWS.Client.Hotplug.Unregister
                   (Name     => "Hotplug_Module_Demo",
                    Password => "my_password",
                    Server   => "http://dieppe:2222",
                    Regexp   => ".*AWS.*");

  Here we ask to unregister *Hotplug_Module_Demo* from server
  *dieppe*. As for the registration process a proper password must be
  specified, see Hotplug module - server activation.

A complete example can be found in the demos directory. Look for
"main.adb" and "hotplug.adb".


Server Push
===========

This protocol is obsolescent, it is hightly recommended to use the
WebSockets now. See WebSockets.

Server Push is a feature that let the Web Server send continuously
data to client's  Web Browser or client applications. The client does
not have to reload at periodic time (which is what is called client
pull) to have the data updated, each time the server send a piece of
data it gets displayed on the client.

To build a push server you need to build an instance of the
*AWS.Server.Push* package. This package takes a set of formal
parameters. Here are the step-by-step instructions to build a Push
Server:

* The data to be sent

  First you must create a type that will contains the data to be sent
  to client's browser except if it is a standard Ada type. See
  *Client_Output_Type* formal parameter.

* The data that will be streamed

  This is the representation of the data that will be sent to client's
  browser. This will be either a *String* for Web pages or
  *Stream_Element_Array* for binary data like pictures. See
  *Stream_Output_Type* formal parameter.

* The context

  It is often nice to be able to configure each client with different
  parameters if needed. This can be achieved with the Context data
  type that will be passed as parameter of the conversion function
  described below. See *Client_Environment* formal parameter.

* Provides a function to convert from the data type to be sent to
  the data that will be streamed.

  This is a function that will transform the data described on point 1
  above to the form described on point 2 above. See *To_Stream_Output*
  formal parameter.

* Build the Push Server

  To do so you just need to instantiate *AWS.Server.Push* with the
  above declarations.

* Registering new clients

  In the standard *AWS* procedure callback it is possible to register
  a client if requested. This is done by calling
  *AWS.Server.Push.Register*. It is possible to unregister a client
  using *AWS.Server.Push.Unregister*. Each client must be identified
  with a unique client ID. After registering a new client from the
  callback procedure you must return the *AWS.Response.Socket_Taken*
  message. This is very important, it tells the server to not close
  this socket.

* Sending the data

  At this point it is possible to send data to clients. To do so two
  routines are available.

*AWS.Server.Push.Send_To*

   To send a piece of data to a specific client identified by its
   client ID.

*AWS.Server.Push.Send*

   To send a piece of data to all clients registered on this server.

Very large Internet applications should use this feature carefully. A
push server keeps a socket reserved for each registered clients and
the number of available sockets per process is limited by the OS.


Working with Server sockets
===========================

With *AWS* is is possible to take out a socket from the server and
give it back later. This feature must be used carefully but it gives a
lot of flexibility. As the socket is taken away, the connection line
(or slot) is released, *AWS* can then use it to handle other requests.

This can be used to better support heavy loaded servers when some
requests need a long time to complete. Long time here means longer
than most of the other requests which should be mostly interractives
for a Web server. Of course in such a case a keep-alive connection is
kept open.

The usage in such a case is to take out the socket and put it in a
waiting line. This releases the connection for the server. When the
data to prepare the answer is ready you give back the socket to the
server.

* Take a socket from the server

  This first step is done form the callback function. A user instead
  of replying immediatly decides to take away the socket from the
  server. The first step is to record the connection socket socket by
  calling *AWS.Status.Socket*. The second step is to tell the server
  to not release this socket by returning *AWS.Response.Socket_Taken*
  from the callback function. At this point the server will continue
  to serve other clients.

  Note that this feature is used by the server push implementation,
  see Server Push.

* Give back the socket to the server

  Calling *AWS.Sever.Give_Back_Socket* will register the socket for
  reuse. This socket will be placed into a spool, next time the server
  will check for incoming requests it will be picked up.


Server Log
==========

It is possible to have the server activity logged into the file
"<progname>-Y-M-D.log". To activate the logging you must call the
*AWS.Server.Log.Start*, and it is possible to stop logging by calling
*AWS.Server.Log.Stop*. Note that *AWS.Server.Log.Start* have a
parameter named *Auto_Flush* to control output buffering. This
parameter is False by default. If set to True, the log file will be
automatically flushed after each data. If the server logging is not
buffered, i.e. Auto_Flush is False, the log can still be flushed by
calling the *AWS.Server.Log.Flush* routine. See AWS.Log for more
information especially about the way rotating logs can be setup. Using
this feature it is possible to have automatic split of the log file
each day, each month or at every run. See *AWS.Log* spec. This is very
useful to avoid having very big log files.

The log format depend on Log_Extended_Fields configuration parameter.
If this parameter is empty, the HTTP log would have fixed apache
compartible format:

   <client IP> - <auth name> - [<date and time>] "<request>" <status code> <size>

For example:

   100.99.12.1 -  - [22/Nov/2000:11:44:14] "GET /whatever HTTP/1.1" 200 1789

If the extended fields list is not empty, the log file format would
have user defined fields set:

   #Version: 1.0
   #Date: 2006-01-09 00:00:01
   #Fields: date time c-ip cs-method cs-uri cs-version sc-status sc-bytes
   2006-01-09 00:34:23 100.99.12.1 GET /foo/bar.html HTTP/1.1 200 30

Fields in the comma separated Log_Extended_Fields list could be:

*date*
   Date at which transaction completed

*time*
   Time at which transaction completed

*time-taken*
   Time taken for transaction to complete in seconds

*c-ip*
   Client side connected IP address

*c-port*
   Client side connected port

*s-ip*
   Server side connected IP address

*s-port*
   Server side connected port

*cs-method*
   HTTP request method

*cs-username*
   Client authentication username

*cs-version*
   Client supported HTTP version

*cs-uri*
   Request URI

*cs-uri-stem*
   Stem portion alone of URI (omitting query)

*cs-uri-query*
   Query portion alone of URI

*sc-status*
   Responce status code

*sc-bytes*
   Length of response message body

*cs(<header>)*
   Any header field name sent from client to server

*sc(<header>)*
   Any header field name sent from server to client

*x-<appfield>*
   Any application defined field name

*AWS* also support error log files. If activated every internal error
detected by *AWS* will gets logged into this special file. Log file
for errors would be in simple apache compartible format. See
*AWS.Server.Log.Start_Error* and *AWS.Server.Log.Stop_Error*.

For the full set of routines supporting the log facility see
AWS.Server.Log .


Secure server
=============

It is not much difficult to use a secure server (*HTTPS*) than a
standard one. Here we describe only what is specific to an HTTPS
server.

Before going further you must check that *AWS* has been configured
with *SSL* support. See Building. You must also have installed the
*OpenSSL* library on your system. If this is done, you can continue
reading this section.


Initialization
--------------

A server is configured as using the HTTPS protocol at the time it is
started. The only thing to do is to set the Start's Security parameter
to True. This will start a server and activate the *SSL* layer by
default. A secure server must use a valid certificate, the default one
is **cert.pem**. This certificate has been created by the *OpenSSL*
tool and is valid until year 2008. Yet, this certificate has not been
signed. To build a secure server user's can rely on, you must have a
valid certificate signed by one of the **Certificate Authorities**.

The certificate to be used must be specified before starting the
secure server with *AWS.Server.Set_Security*:

With a key and certificate files:

   AWS.Server.Set_Security
     (WS,
      Key_Filename         => "server.key",
      Certificate_Filename => "server.crt");

Or with a self-contained certificate:

   AWS.Server.Set_Security (WS, Certificate_Filename => "aws.pem");

Or using the *certificate* configuration parameter, see Configuration
options.


Verify callback
---------------

First note that it is not necessary to use such callback to verify the
certificate validity, see Using a Certificate Authority.

This callback will receive the client certificate as sent during SSL
handshake between the server and the client. The certificate
information can be checked for logging purpose or to impose some
restriction. Generally this callback should return the value from
*AWS.Net.SSL.Certificate.Verified*, see AWS.Net.SSL.Certificate.

The Verified status of the certificate is the one that has been issued
by the SSL implementation during certificate verification and can
generally be trusted.


Self-signed certificate
-----------------------


Creating a server certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The goal here is not to replace the *OpenSSL* documentation but just
to present one way to create a self signed certificate for an *HTTPS*
test server.

*Generate a RSA key*:

   $ openssl genrsa -rand <filename> -out aws-server.key

Filename must point to any file, this is used to initialized the
random seed.

*Generate the certificate*:

   $ openssl req -new -x509 -days 730 -key aws-server.key -out aws-server.cert

*Create a single self contained file (optional)*:

   $ cat aws-server.key aws-server.cert > aws.pem

A this point you can use "aws.pem" with your server or the separate
"server.key" and "server.crt" files.


Creating a client certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A certificate can also be used on a Web browser and passed to the
server to have a strong client authentication. A client certificate
must be *PKCS12*. The steps to generate such certificate are:

*Generate a RSA key*:

   $ openssl genrsa -des3 -out aws-client.key

Filename must point to any file, this is used to initialized the
random seed.

*Generate the certificate*:

   $ openssl req -new -x509 -days 730 -key aws-client.key -out aws-client.cert

*Create the corresponding PKCS12 certificate*:

   $ openssl pkcs12 -export -clcerts -in aws-client.cert -inkey aws-client.key -out client.p12


Using a Certificate Authority
-----------------------------

In this section we will use a Certificate Authority to signed the
server certificates and the client certificates. Using this method is
required if the server must ensure that only clients with a valid
certificate will be able to connect to the server. The server will
verify that the client certificate received has been signed by a known
Certificate Authority.

Note that these checks are happening during the SSL handshake, so
before the user's callback.

For this to work the following configuration options must be used:

*Exchange_Certificate*
   To request that the client certificate be sent.

*Trusted_CA*
   The file containing the certificate of the Certificate Authority we
   trust. The CA which has signed the client's certificate.

*Certificate_Required*
   If no certificate has been received from the client the server will
   reject the connection. If this is not set, we can still validate
   the client's certificate in the verify callback, see Verify
   callback and for example log the connecting users.


Initializing the Certificate Authority
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

First the Certificate Authority must be initialized on the computer.
This is heavily dependent on the actual Operating System used,
describing this part is out of scope of this document.

On GNU/Debian the default setup (see default_ca in
"/etc/ssl/openssl.cnf") can be used to create a **demo** Certificate
Authority locally to test this feature:

   $ mkdir demoCA
   $ mkdir demoCA/newcerts
   $ touch demoCA/index.txt
   $ echo ABCC > demoCA/serial
   $ echo 01 > demoCA/crlnumber


Creating the Certificate Authority
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Generate a RSA key*:

   $ openssl genrsa -out private-ca.key 1024

*Generate the certificate signing request*:

   $ openssl req -new -key private-ca.key -out private-ca.csr

During this step you'll be asked for information about the CA
(Country, State or Province, Organization Name...).

*Create the CA certificate*:

   $ openssl x509 -req -days 365 -in private-ca.csr -signkey private-ca.key -out private-ca.crt

This certificate will be used by AWS as the trusted CA, see
Configuration options.


Creating a CA signed server certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Generate a RSA key*:

   $ openssl genrsa -out aws-server.key 1024

*Generate the certificate signing request*:

   $ openssl req -new -key aws-server.key -out aws-server.csr

During this step you'll be asked for information about the server
(Country, State or Province, Common Name...). Note that the
Organization Name here must match the one from the CA and the Common
Name should be the server fully qualified domain name.

*Create the server certificate, signed it with our CA*:

   $ openssl ca -in aws-server.csr -cert private-ca.crt -keyfile private-ca.key -out aws-server.crt

*Create a single self contained file (optional)*:

   $ cat aws-server.key aws-server.cert > aws.pem


Creating a CA signed client certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Generate a RSA key*:

   $ openssl genrsa -des3 -out aws-client.key 1024

*Generate the certificate signing request*:

   $ openssl req -new -key aws-client.key -out aws-client.csr

During this step you'll be asked for information about the client
(Country, State or Province, Common Name...). Note that the
Organization Name here must match the one from the CA and the Common
Name should be the client's one.

*Create the client certificate, signed it with our CA*:

   $ openssl ca -in aws-client.csr -cert private-ca.crt -keyfile private-ca.key -out aws-client.crt

*Create the corresponding PKCS12 certificate*:

   $ openssl pkcs12 -export -clcerts -in aws-client.crt -inkey aws-client.key -out aws-client.p12


Creating a Certificate Revocation List (CRL)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A Certificate Revocation List is used to revoke some client's
certificates. Those clients won't be able to connect to the secure
server anymore. Using the CA created above the following commands can
be used to create a CRL.

*Revoke the certificate*:

   $ openssl ca -cert private-ca.crt -keyfile private-ca.key -revoke aws-client.crt

*Generate the CRL*:

   $ openssl ca -cert private-ca.crt -keyfile private-ca.key -gencrl -out crl.pem -crldays 30

The file "crl.pem" is the one to install on the server using the
CRL_File configuration option, see Configuration options. This file
contains the list of all revoked certificates for the corresponding
CA.


Security level
--------------

This table summarize the security level achieved with different
settings of the security oriented configuration parameters.

+--------------------------------------+-------+---------------+---------------+--------------+
| Security                             | SSL   | Exchange      | Certificate   | Trusted CA   |
|                                      |       | Certificate   | required      |              |
+======================================+=======+===============+===============+==============+
| Data between the client and the      | Yes   | No            | No            | No           |
| server are encrypted.                |       |               |               |              |
+--------------------------------------+-------+---------------+---------------+--------------+
| Client can be identified, it is      | Yes   | Yes           | No            | No           |
| still possible to access the server  |       |               |               |              |
| without having a certificate.        |       |               |               |              |
+--------------------------------------+-------+---------------+---------------+--------------+
| Client are identified, a certificate | Yes   | Yes           | Yes           | No           |
| is required. The verification of the |       |               |               |              |
| validity is up to the application    |       |               |               |              |
| using the verify callback.           |       |               |               |              |
+--------------------------------------+-------+---------------+---------------+--------------+
| Client are identified and verified,  | Yes   | Yes           | Yes           | Yes          |
| the certificate must have been       |       |               |               |              |
| signed by a Certificate Authority.   |       |               |               |              |
| It is not possible to access the     |       |               |               |              |
| server without a valid certificate.  |       |               |               |              |
+--------------------------------------+-------+---------------+---------------+--------------+


Protocol
--------

There are different security options, either *SSLv2*, *SSLv3* or
*TLSv1*. *SSLv2* and *SSLv3* are supported by most if not all Web
browsers. These are the default protocol used by *AWS*.

*TLSv1* is not supported at this point.


Unexpected exception handler
============================

When *AWS* detects an internal problem, it calls a specific handler.
This handler can be used to log the error, send an alert message or
build the answer to be sent back to the client's browser.

Here is the spec for this handler:

   type Unexpected_Exception_Handler is access
     procedure (E      : in     Ada.Exceptions.Exception_Occurrence;
                Log    : in out AWS.Log.Object;
                Error  : in     Data;
                Answer : in out Response.Data);

The handler can be called in two modes:

*Non fatal error (Error.Fatal is False)*

   In this case *AWS* will continue working without problem. A bug has
   been detected but it was not fatal to the thread (slot in *AWS*'s
   terminology) handling. In this case it is possible to send back an
   application level message to the client's browser. For that you
   just have to fill the unexpected handler's *Answer* parameter with
   the right response message. The *Error* parameter receive
   information about the problem, see AWS.Exceptions.

*Fatal error (Error.Fatal is True)*

   In this case *AWS* will continue working but a thread (slot number
   *Error.Slot* in *AWS*'s terminology) will be killed. It means that
   *AWS* will have lost one the simultaneous connection handler. The
   server will continue working unless it was the last slot handler
   available. Note that a Fatal error means an *AWS* internal bug and
   it should be reported if possible. In this mode there is no way to
   send back an answer to the client's browser and *Error* value must
   be ignored.

The default handler for unexpected exceptions send a message to
standard error for fatal errors. For non fatal errors it log a message
(if the error log is activated for the server) and send back a message
back to the client. The message is either a built-in one or, if
present in the server's directory, the content of the "500.tmplt"
file. This templates can used the following tags:

*AUTH_MODE*

   The authorization mode (Either NONE, BASIC or DIGEST).

*EXCEPTION*

   Exception information with traceback if activated.

*HTTP_VERSION*

   Either HTTP/1.0 or HTTP/1.1

*METHOD*

   The request method (Either GET, HEAD, POST or PUT)

*PAYLOAD*

   The full *XML* payload for *SOAP* request.

*PEERNAME*

   The IP address of the client

*SOAP_ACTION*

   Either True or False. Set to True for a *SOAP* request.

*URI*

   The complete URI

For more information see AWS.Server and AWS.Exceptions.


Socket log
==========

To ease *AWS* applications debugging it is possible to log all data
sent/received to/from the sockets. For this you need to call the
*AWS.Net.Log.Start* routine by passing a write procedure callback. You
have to create such procedure or use one read-to-use provided in
*AWS.Net.Log.Callbacks* package.

For more information see AWS.Net.Log and AWS.Net.Log.Callbacks.


Client side
===========

*AWS* is not only a server it also implement the HTTP and HTTPS
protocol from the client side. For example with *AWS* it is possible
to get a Web page content using the *AWS.Client* API, see AWS.Client.

It also support client **Keep-Alive** connections. It is then possible
to request many URI from the same server using the same connection
(i.e. the same sockets).

*AWS* client API also support proxy, proxy authentication and Web
server authentication. Only basic (and not digest) authentication is
supported at this time.

Let's say that you want to retrieve the *contrib.html* Web page from
Pascal Obry's homepage which is http://perso.wanadoo.fr/pascal.obry.
The code to do so is:

   Data := Client.Get
             (URL => "http://perso.wanadoo.fr/pascal.obry/contrib.html");

From there you can ask for the result's content type:

   if Response.Content_Type (Data) = "text/html" then
      ...
   end if;

Or using the MIME types defined in *AWS.MIME* unit:

   if Response.Content_Type (Data) = MIME.Text_HTML then
      ...
   end if;

And display the content if it is some kind of text data:

   Text_IO.Put_Line (Response.Message_Body (Data));

If the content is some kind of binary data (executable, PNG image, Zip
archive...), then it is possible to write the result to a file for
example. Look at the *agent* program in the *demos* directory.

If the Web page is protected and you must pass the request through an
authenticating proxy, the call will becomes:

   Data := Client.Get
             (URL        => "http://www.mydomain.net/protected/index.html"
              User       => "me",
              Pwd        => "mypwd",
              Proxy      => "192.168.67.1",
              Proxy_User => "puser",
              Proxy_Pwd  => "ppwd");

The client upload protocol is implemented. Using *AWS.Client.Upload*
it is possible to send a file to a server which support the file
upload protocol.
