FGLPROFILE Configuration

The Genero Web Services secured communication and the support of XML-Security is based on the OpenSSL engine. It allows a 4GL Web Services client, or a 4GL application using the com or xml API, to communicate with any secured server over HTTP or HTTPS, and to handle encrypted and/or signed XML document in 4GL coming from any other application. The configuration is defined from entries in the FGLPROFILE file.
Note: When using 4GL Web Services on server side, it is the Web Server that is in charge of the 4GL Web Services server security, not the 4GL server application itself. You must refer to your Web Server manual to secure the server part of the Web Services.

This is useful for deployment purposes, as no additional code modification is necessary, even if the location of the different servers changes, or if different cryptography keys or X509 certificates are necessary for a same application but intended to several customers with their own needs.

Configuration categories:

Security Configuration
HTTP basic or digest authentication
Proxy
Server
XML Cryptography
Examples

Security Configuration

The following table lists the FGLPROFILE entries specifying the security certificates and algorithms the Web Services client uses for HTTPS and password encryption. These entries specify how an application using the low-level com or xml APIs performs secured communications .

Entry	Description
security.global.script	Filename of a script executed each time a password of a private key is required by the client. The security script accepts one argument corresponding to the filename of the private key for which the password is required, and must return the correct password or the client stops. For script examples, see Windows Password Script Example or Unix Password Script Example. This entry cannot be used if security.global.agent is set.
security.global.agent	Port number where the fglpass agent is waiting for requests. It returns the password that grants access to a private key when needed by a 4GL application. The DVM and the fglpass agent perform authentication and exchange encrypted data over the local host network only. Refer to Using the password agent for details. This entry cannot be used if security.global.script is set.
security.global.protocol	The SSL protocol to use for secured communications. Valid values include: TLSv1 (Default) SSLv3 SSLv2 SSLv23
security.global.ca	Filename of the Certificate Authority list, with the concatenated PEM-encoded third party X.509 certificates considered as trusted, and in order of preference.
security.global.windowsca	If set to TRUE, build the Certificate Authority list from the Certificate Authorities stored in the Windows key store. This entry is only valid on Windows systems where security.global.ca is not set.
security.global.cipher	The list of encryption, digest, and key exchange algorithms the client is allowed to use during a secured communication. If this entry is omitted, all algorithms are supported. For more details about cipher, refer to www.openssl.org .
security.global.certificate	Filename of the PEM-encoded client X.509 certificate to be used for any secured connection if not redefined in a specific server configuration.
security.global.privatekey	Filename of the PEM-encoded private key associated to the above X509 certificate and to be used for any secured connection if not redefined in a specific server configuration.
security.global.keysubject	The subject string of a X.509 certificate and its associated private key registered in the Windows key store to be used for any secured connection if not redefined in a specific server configuration. This entry is valid only on Windows systems.
security.ident.certificate	Filename of the PEM-encoded client X.509 certificate.
security.ident.privatekey	Filename of the PEM-encoded private key associated to the above X509 certificate.
security.ident.keysubject	The subject string of a X.509 certificate and its associated private key registered in the Windows key store. This entry is valid only on Windows systems.

Notes:

The ident keyword must be replaced with your own identifier, and all necessary entries must be set. See FGLPROFILE setting.
If an entry is defined more that once, only the last occurrence is taken into account.

Back to the top

HTTP basic or digest Authentication

The following table lists the FGLPROFILE entries that specify the login and password to use in the case of HTTP authentication to a server or a proxy. The entries also specify the login and password to use in an application using the low-level com or xml API.

Entry	Description
authenticate.ident.login	The login identifying the client to a server during HTTP Authentication.
authenticate.ident.password	The password validating the login of a client to a server during HTTP Authentication. As passwords should never be in clear text, it is recommended that you encrypt them with the fglpass tool. For more information, see FGLPROFILE password encryption.
authenticate.ident.realm	The string identifying the server to the client during HTTP Authentication. If the string does not match the server's string, authentication fails. This parameter is optional, but it is recommended that you check the server identity, especially if the server's location is suspicious.
authenticate.ident.scheme	One of the following strings representing the different HTTP Authentication mechanisms. Anonymous (default value) - The client does not know anything about the server, and performs a first request to retrieve the server authentication mechanism. It then uses the login and password to authenticate to the server using the Basic or Digest mechanism, depending on the server returned value. Basic - The client authenticates itself to the server at first request, by sending the login and the password using the Basic authentication mechanism. Digest - The client performs a first request without any login and password, to retrieve the server information before authenticating itself to the server in a second request using the Digest mechanism.

Notes:

The ident keyword must be replaced with your own identifier and both entries must be set. See FGLPROFILE setting.
If an entry is defined more that once, only the last occurrence is taken into account.

Back to the top

Proxy Configuration

The following table lists the FGLPROFILE entries that specify how the Web Services client communicates with a proxy. The entries specify the way an application using the low-level com or xml API communicates with a proxy.

Entry	Description
proxy.http.location	Location of the HTTP proxy defined as host:port or ip:port. If the port is omitted, the port 80 is used.
proxy.http.list	The list of beginning host names, separated with semicolons, for which the Web Services client does not go via the HTTP proxy.
proxy.http.authenticate	The HTTP Authenticate identifier the Web Services client uses to authenticate itself to the HTTP proxy.
proxy.https.location	Location of the HTTPS proxy defined as host:port or ip:port. If the port is omitted, the port 443 is used
proxy.https.list	The list of beginning host names, separated with semicolons, for which the Web Services client does not go via this HTTPS proxy.
proxy.https.authenticate	The HTTP Authenticate identifier the Web Services client uses to authenticate itself to the HTTPS proxy.

Notes:

If an entry is defined more that once, only the last occurrence is taken into account.

Back to the top

Server Configuration

The following table lists the FGLPROFILE entries that specify the correct way a Web Services client connects to an end point (usually a server). Notice that the entries specify also the way an application using the low-level com or xml API connects to an end point.

Entry	Description
ws.ident.url	The endpoint URL of the server.
ws.ident.cipher	The list of encryption, digest and key exchange algorithms the client is allowed to use during a secured communication to that server. It overwrites the global definition.
ws.ident.verifyserver	If set to TRUE, the client performs a strict server identity validation. If not fulfilled, it stops the communication; otherwise no server identity verification is performed. The default value is TRUE. For example: ws.ident.verifyserver = "TRUE"
ws.ident.security	The security identifier the client uses to perform an HTTPS communication to the server.
ws.ident.authenticate	The HTTP authenticate identifier the client uses to authenticate itself to the server.

Notes:

The ident keyword must be replaced with your own identifier. All necessary entries, depending on the remote server's configuration, must be set. See FGLPROFILE sample.
You can use the unique identifier in the 4GL code instead of the server URL, with the alias:// prefix. For example, alias://ident.
If an entry is defined more that once, only the last occurrence is taken into account.

Back to the top

XML Cryptography configuration

The following table lists the FGLPROFILE entries that specify the correct way to map a cryptography key or certificate to be used with the xml cryptography API.

Entry	Description
xml.keystore.calist	The list of PEM-encoded third party X.509 certificates, separated with semicolons, of the Certificate Authority considered as trusted, in order of preference.
xml.keystore.x509list	The list of PEM-encoded third party X.509 certificates, separated with semicolons, to be used to find out the correct X.509 certificate when getting an incomplete one in a XML signature or an encrypted XML document.
xml.ident.key	The filename of a cryptography key. For instance RSA.pem, DSA.der or HMAC.bin.
xml.ident.x509	The filename of a cryptography x509 certificate. For instance Cert.crt.

Notes:

The ident keyword must be replaced with your own identifier. See FGLPROFILE sample 2.
You can use the unique identifier in the 4GL code instead of the filename.
If an entry is defined more that once, only the last occurrence is taken into account.

Back to the top

Examples

Windows Password Script Example

  @echo off
  REM -- Windows password script

  IF "%1" == "Cert/MyPrivateKeyA.pem" GOTO KeyA
  IF "%1" == "Cert/MyPrivateKeyB.pem" GOTO KeyB
  GOTO end
  :KeyA
  ECHO PasswordA
  GOTO end
  :KeyB
  ECHO PasswordB
  GOTO end
  :end
  GOTO :EOF

Unix Password Script Example

  # Unix password script
  
  if [ "$1" == "Cert/MyPrivateKeyA.pem" ]
   then
    echo PasswordA
  fi
  if [ "$1" == "Cert/MyPrivateKeyB.pem" ]
   then
    echo PasswordB
  fi

FGLPROFILE sample

The following is an FGLPROFILE sample, configured for a connection to a HTTPS server via a proxy, and with HTTP and Proxy Authentication.

  ############################
  ## Security configuration ##
  ############################
  security.global.script     =  "Cert/password.sh"
  security.global.ca         =  "Cert/CAList.pem"
  security.global.cipher     =  "HIGH" # Use only HIGH encryption ciphers
  security.mykey.certificate =  "Cert/MyCertificateA.crt"
  security.mykey.privatekey  =  "Cert/MyPrivateKeyA.pem"
  
  ###############################
  ## Proxy HTTP Authentication ##
  ###############################
  authenticate.proxyauth.login    =  "myapplication"
  authenticate.proxyauth.password =  "mypswd"
  authenticate.proxyauth.scheme   =  "Basic"
  
  ###############################
  ## HTTPS Proxy configuration ##
  ###############################
  proxy.https.location     =  "10.0.0.170"
  proxy.https.list         =  "www.mycompany.com;www.mycompany.com"
  proxy.https.authenticate =  "proxyauth"
  
  ################################
  ## Server HTTP Authentication ##
  ################################
  authenticate.serverauth.login    =  "mylogin"
  authenticate.serverauth.password =  "password"
  
  ##########################
  ## Server configuration ##
  ##########################
  ws.myserver.url          =  "https://www.MyMachine.com/cgi-bin/fglccgi.exe/ws/r/MyWebService"
  ws.myserver.authenticate =  "serverauth"
  ws.myserver.security     =  "mykey"

FGLPROFILE sample 2

The following is an FGLPROFILE sample, configured for XML cryptography and using the fglpass agent to get the private key passwords.

############################ ## Security configuration ## ############################ security.global.agent = "4444" ########################## ## Crypto configuration ## ########################## xml.keystore.calist = "RSARootCertificate.crt;DSARootCertificate.crt" xml.keystore.x509list = "RSA1024Certificate.crt;DSA1024Certificate.crt" xml.id1.x509 = "RSA1024Certificate.crt" xml.id2.x509 = "DSA1024Certificate.crt" xml.id3.key = "RSA1024Key.pem" xml.id4.key = "DSA1024Key.der" xml.id5.key = "HMAC.bin"

Back to the top