Certificates and Keys for 4GL Language Features¶

Certificates and Keys for 4GL Language Features

Socket Handle and Server Socket Handle SSL Connections¶

This section contains information about utilization of secure socket layer connections. FWD expands on the 4GL use of -ssl to include a full range of options. Namely:

Handle string parameter	SSLContext
-ssl	SSL
-sslv2	SSLv2
-sslv3	SSLv3
-tls	TLS
-tlsv1	TLSv1
-tlsv1.1	TLSv1.1
-tlsv1.2	TLSv1.2

To secure the connection, an SSL layer may be added. This requires adding the appropriate connection string parameter, such as -ssl or -tls, to ENABLE-CONNECTIONS. If needed, there are options to specify:

the public[/private] key and digital certificate to use within the keystore (-keyalias). If not specified, the default value for this is default_server;
and the password for opening it (-keyaliaspasswd). For security reasons, this key is expected to be encrypted. The default password is ... password which encrypted looks like: 20333c34252a2137. Use the 4GL built-in function ENCRYPT() to obtain the value to pass to this option.

The 4GL offers for tests a set of 3 server side keys (test_server_SHA and test_server_SHA384 beside the default default_server). They are stored in .pem format and can be found in <OE-root>\keys\ folder.

Creation and Migration of Certificates and Keys¶

Server Side Store

The SSL socket implementation of FWD is based on JKS (https://docs.oracle.com/cd/E19509-01/820-3503/ggfen/index.html). To create a similar default_server store to be used with FWD SSL sockets the following command can be used:

$ keytool -genkey -keyalg RSA -alias default_server -keystore default_server.store -storepass <server-keystore-password> -validity 48 -keysize 1024

This .store container must be located in working directory of the FWD-client which acts as SSL-server for FWD to load it. More than that, if an access password was specified, it must be configured by adding to ssl-socket:keystore:password=<server-keystore-password> the client's command line. This should be a different password than any of the certificates stored in the file and the command-line option with no encryption.

Client Side Key

After generating the server-side key, we need to export the public certificate and make it available to SSL-client for use. We do this using the following commands:

$ keytool -exportcert -keystore default_server.store -alias default_server > default_server.cer
$ keytool -importcert -alias default_server -file default_server.cer -keystore trusted-cert.store

trusted-cert.store must exist in the working directory of the 'remote' client so that the public key to be available for the SSL-client endpoint. Similar to SSL-server's endpoint, if a password was set for access to trusted-cert store, it must be passed in the client's command line using: ssl-socket:truststore:password=<client-truststore-password>.

Store and Key Locations

	deploy_server		deploy_client
	Server	Client	Server	Client
Resource file (in working directory)	none	`default_server.store`	none	`trusted-cert.store`
Command-line Parameter	none	`ssl-socket:keystore:password`	none	`ssl-socket:truststore:password`

4GL Socket Sample¶

Server Socket Handle

In 4GL, creating a server socket is quite easy. There are 3 steps to do it:

CREATE a SERVER-SOCKET and store it to a HANDLE variable;
call SET-CONNECT-PROCEDURE to configure the callback to be invoked when a client connects;
open the socket using ENABLE-CONNECTIONS method.

Here is a small example which respond the simplest possible HTML pages to all clients connecting to dedicated port:

PROCEDURE handle-connection:
   DEFINE INPUT PARAMETER hSock AS HANDLE.
   DEFINE VARIABLE mBuffer AS MEMPTR NO-UNDO.
   DEFINE VARIABLE cInputStr AS CHARACTER INIT "~74html /~76".

   MESSAGE "Incoming connection".

   SET-SIZE(mBuffer) = 1001.
   hSock:READ(mBuffer, 1, 1000, READ-AVAILABLE).
   MESSAGE GET-STRING(mBuffer, 1, 1000).

   SET-SIZE(mBuffer) = LENGTH(cInputStr) + 1.
   PUT-STRING(mBuffer, 1) = cInputStr.
   hSock:WRITE(mBuffer, 1, LENGTH(cInputStr)).
   SET-SIZE(mBuffer) = 0.
END.

DEFINE VARIABLE hSocket AS HANDLE.
CREATE SERVER-SOCKET hSocket.  // #1
hSocket:SET-CONNECT-PROCEDURE("handle-connection"). // #2
hSocket:ENABLE-CONNECTIONS("-S 9123 -ssl -keyaliaspasswd 20333c34252a2137 -sessiontimeout 60"). // #3
MESSAGE "SSL server started on port 9123.".

Each time a client will connect to this socket, the handle-connection callback procedure will be invoked. It is the one which implements the specific protocol and handles the actual communication with the client.

Client Socket Handle

To create a socket in 4GL, first CREATE SOCKET and store it in a handle variable. Then invoke CONNECT method, using the -H and -S parameters to specify the server endpoint. Here is a short example in which a web page is requested, similar to a web-client:

DEFINE VARIABLE hSocket AS HANDLE.
DEFINE VARIABLE lError AS LOGICAL.
DEFINE VARIABLE mBuffer AS MEMPTR NO-UNDO.
DEFINE VARIABLE cInputStr AS CHARACTER INIT "GET index.html HTTP/1.1".
DEFINE VARIABLE readLen AS INTEGER.

CREATE SOCKET hSocket.   // #1

lError = hSocket:CONNECT("-H localhost -S 9123 -ssl -nosessionreuse -nohostverify"). // #2
IF (hSocket:CONNECTED()) THEN DO:
    SET-SIZE(mBuffer) = LENGTH(cInputStr) + 1.
    PUT-STRING(mBuffer, 1) = cInputStr.
    hSocket:WRITE(mBuffer, 1, LENGTH(cInputStr)).
    SET-SIZE(mBuffer) = 0.

    SET-SIZE(mBuffer) = 1001.
    hSocket:READ(mBuffer, 1, 1000, READ-AVAILABLE).
    MESSAGE GET-STRING(mBuffer, 1, 1000).

    hSocket:DISCONNECT().
END.

DELETE OBJECT hSocket.

If -ssl option is specified, the connection is encrypted using SSL protocol. If -tls is specified, the connection is encrypted using TLS protocol. Additional options: -nosessionreuse and -nohostverify allow to specify whether to ignore old SSL session ID, and to turn off the host verification, respectively.

Web Service SSL Connections¶

TBD

Appserver SSL Connections¶

The legacy 4GL approach for adding SSL to appserver connections is to add -ssl to the options string passed to CONNECT(). This is not used in FWD.

Instead, all appserver usage in FWD uses the built-in "distributed application protocol" which is always based on the secure sockets implementation that is already configured for every server and client. This is true for using the hand-coded Java appserver access (the FWD equivalent to the Java Open Client) or for the converted 4GL code calling a SERVER handle.

See the following for details:

Bootstrap Configuration
Certificate Authority
Certificate Configuration in the Directory
Key-Stores and Trust-Stores
Cryptography Setup Helper
Legacy Appserver Agents
Establishing a Session with the FWD Server

Project

General

Profile

FWD

Wiki