Back to Contents

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

The following table lists the FGLPROFILE entries specifying the security certificates and algorithms the Web Services client uses for HTTPS and password encryption. Notice that the entries specify also the way an application using the low-level com or xml API 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. Refer to Windows Password Script Example or Unix Password Script Example (below) for script examples.
Note: 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.
Note: The DVM and the fglpass agent perform authentication and exchange encrypted data over the local host network only. Refer to fglpass tool for details.
Note: Cannot be used if security.global.script is set.		 
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.
Note: This entry is valid only on Windows systems, and if 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.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.
Note: This entry is valid only on Windows systems.

Notes:

  1. The ident key-word must be replaced with your own identifier, and all necessary entries must be set. See FGLPROFILE setting (below) for an example.
  2. 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. Notice that the entries specify also 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.
Note: 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 that string doesn't match the server's string, authentication fails.
Note: 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 doesn't know anything about the server, and performs a first request to retrieve the server authentication mechanism. Then it 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:

  1. The ident key-word must be replaced with your own identifier and both entries must be set.  See FGLPROFILE setting (below) for an example.
  2. 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. Notice that the entries specify also 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

	Note: 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 doesn't 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

    Note: 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 doesn't 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: 


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


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.

  

  
    
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:


    
	
  1. The ident key-word must be replaced with your own identifier. All 
	necessary entries, depending on the remote server's configuration, must be 
	set. For more information, see FGLPROFILE sample (below).
    2. 
  
  2. You can use the unique identifier in the 4GL code instead of the server URL, with the alias:// prefix as for instance alias://ident.
    3. 
	
  3. If an entry is defined more that once, only the last occurrence is taken into account.
    
	
    4. 


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, and in order of preference.

  

  

    
xml.keystore.x509list

    The list of PEM-encoded third party X.509 certificates, separated with semicolons, that will 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, as for instance RSA.pem, DSA.der or HMAC.bin.
  

  

    
xml.ident.x509

    The filename of a cryptography x509 certificate, as for instance Cert.crt.
  






Notes:


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


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