In this blog you will learn how to secure communication with network profiles when using the UHTTP component in your application. Security, in general, and securing the network protocols play a significant role within IT departments today, and this blog will help you secure the UHTTP communication by applying a simple network profile setting.
You can simply change the profile settings in the ASN file.
A net profile is a collection of settings which you can specify in the Uniface assignment file in the NET_SETTINGS section.
For instance, this may look like:
[NET_SETTINGS]
CertProfile = verify_server=yes, verify_url_name=yes, ca_certificate=certs\ss_certkey3.pem,verify_client=yes, client_certificate=certs\ss_cert2.pem, client_key=certs\key2.pem, cpr_lst=AES128-GCM-SHA256, min_tls_version=1.2
|
You may already be using this profile in the network settings of the TLS connection. Uniface now also supports a profile setting for the UHTTP component. The UHTTP component already has a SET_FLAGS operation to influence the way the connection is set up between server and client. However, the SET_FLAGS is limited and does not allow cipher lists or protocol definitions. Also changing the flags settings may require a change in the 4GL script code. For all these reasons, the ability to simply make a change to the net profile in the ASN file is a big benefit.
Using a profile in UHTTP
Important notice:
The SET_FLAGS method is ignored when a profile is set in the UHTTP component by calling the method
SET_PROFILE(<profile_name>)
Even when this profile contains a single setting and the SET_FLAGS contains the maximum of settings, the flags are ignored.
There are UHTTP specific settings in the net profile, such as "verify_url_name" and the "http_followlocation". The rest of the settings are comparable with the TLS settings and will be explained in detail in this blog.
Set Flags compared to profile settings
In the past, any time you’ve used the SET_FLAGS is now a great time to switch to the profile settings, hence in this chapter the profile settings are explained and compared with the SET_FLAGS option in the UHTTP.
The following settings in a net profile are read by the UHTTP driver and are compared with the SET_FLAGS option.
|
Flag
|
Profile setting
|
Purpose
|
Curl option
|
|
1
|
verify_url_name= no
"vfy_url_nm" short name
UHTTP specific
|
Does not perform host verification.
|
CURLOPT_SSL_VERIFYHOST
verifies the certificate's name against host
|
|
2
|
verify_server = no
|
Does not perform peer server verification.
|
CURLOPT_SSL_VERIFYPEER
|
|
4
|
verify_content_length = no
vfy_cnt_len short name
UHTTP specific
|
Does not calculate the content-length.
|
None
|
|
16
|
http_followlocation
UHTTP specific
|
Enables each HTTP request/response to be handled individually.
|
CURLOPT_FOLLOWLOCATION
|
As an example:
SET_FLAGS(2)
is the same as a profile with the following setting:
http_profile=verify_server=no
UHTTP profile settings
The following settings are read by the UHTTP driver when using a profile. Supplying the short name for the setting is supported. For example: cipher_list can also be cpr_lst. http_followlocation does not have a short notation and is specific to the UHTTP driver.
Some settings can be switched on by using the following values: Yes,Y,yes,y or 1 and switched off by using: No,N,no,n or 0. See the table below for details. The defaults are in bold and underlined.
|
Profile option
|
Values
|
Description or maps to
|
|
min_tls_version
|
1.1 | 1.2 (default) | 1.3
|
CURLOPT_SSLVERSION
Defines the minimal TLS version to be used in the communication
|
|
cipher_list
|
See Uniface documentation
|
CURLOPT_SSL_CIPHER_LIST
Defines the list of ciphers which can be used by the connection
|
|
verify_server
{yes| y | 1} | {no | n | 0}
|
See Uniface doc (no default, uses underlying curl defaults)
Verifies the authenticity of the peer's certificate by default
Default value is: Yes
|
CURLOPT_SSL_VERIFYPEER
This option determines whether curl verifies the authenticity of the peer's certificate.
By default, verifies the authenticity of the peer's certificate
|
|
verify_url_name
{yes| y | 1} | {no | n | 0}
|
For UHTTP a yes or y is enough when a check is needed, since the server name is part of the URL.
By default, verifies the certificate's name against host. Checks the server's claimed identity. The URL should have the same name as the server’s name in the certificate.
Default value is: Yes
|
CURLOPT_SSL_VERIFYHOST
Verifies the certificate's name against host. Checks the server's claimed identity. The URL should have the same name as the server’s name in the certificate.
|
|
verify_content_length
{yes| y | 1} | {no | n | 0}
|
Does not calculate the content-length of the payload itself for a POST method. |
|
|
ca_location
|
See Uniface doc
|
CURLOPT_CAPATH
directory holding CA certificates
|
|
ca_certificate
|
See Uniface doc. Does not work when verify_server=no
Default is "USYSDIR\ca-bundle.crt"
This is the path to Certificate Authority (CA) bundle
|
CURLOPT_CAINFO
path to Certificate Authority (CA) bundle
|
|
http_followlocation
{yes| y | 1} | {no | n | 0}
|
follow HTTP 3xx redirects
By default, Uniface is configured to follow any location; this means the header that the server sends is part of an HTTP header in a 3xx response. The Location: header can specify a relative or an absolute URL to follow.
Default value is: Yes
|
CURLOPT_FOLLOWLOCATION
follow HTTP 3xx redirects
|
TLS profile compared to UHTTP profile
Important differences between the TLS profile settings and the UHTTP profile settings.
- verify_url_name is comparable to the verify_server_name in the TLS profile, except that this one is only used in the UHTTP driver to validate the server name in the URL against the server certificate.
- http_followlocation Specific to the UHTTP component.
- verify_content_length Specific to the UHTTP component and overlaps with the flag=4. Calculates content length.
Code example
In the following code example the SET_FLAGS(2) is replaced by a profile setting. See the line with: vUHTTP->SET_PROFILE("http_profile"). In the profile setting the extra option min_tls_version is used to force a secure TLS connection.
trigger detail
variables
handle vUHTTP
numeric vStatus
string vURI, vHeaders, vContent, vResponse
endvariables
newinstance "UHTTP", vUHTTP
;Create list of headers
putitem/id vHeaders, "Content-Type", "application/xml; charset=UTF-8"
putitem/id vheaders, "Accept-Charset", "ISO-8859-1 ; q = 0.4, UTF-16BE; q=0.9"
vUHTTP->SET_PROFILE("http_profile")
vStatus = vUHTTP->SEND(vURI, "GET", "", "", vHeaders, vContent, vResponse)
putmess "vStatus=%%vStatus%%%"
putmess "vContent=%%vContent%%%"
putmess vResponse
end
|
ASN file setting used in the code example
In the assignment file we specify:
[NET_SETTINGS]
http_profile=verify_url_name=no, min_tls_version=1.2, verify_server=no, http_followlocation=yes
|
Changes in behavior concerning the profile settings
When the assignment file is read by Uniface, all settings are parsed. When parsing the profile settings Uniface will show an error in the transcript window when an unknown setting is used or a wrong assignment is made. It is a minimal check, hence path and URLs are not checked to avoid slow startups of the Uniface application. The checks are mainly: does this setting exist and if it is a simple "yes" | "no" or value, check its validity.
The process continues and defaults are used on an error.
As an example:
http_profile=verify_url_name=no, min_tls_version=1.2, verify_server=no, http_followlocation=yes, hello=world
Contains a wrong setting hello=world
Uniface will report the following during startup:
NET_SETTINGS Error:Profile name:HTTP_PROFILE. Contains an unknown identifier:hello found at position:89
Another example when assigning a wrong value for a setting
min_tls_version=1.5 is wrong since the highest possible value is 1.3.
http_profile=verify_url_name=no, min_tls_version=1.5, verify_server=no, http_followlocation=yes
NET_SETTINGS Error:Profile name:HTTP_PROFILE min_tls_version contains a wrong version. Expected was 1.0 | 1.1 | 1.2 | 1.3 but found
was: 1.5 Setting TLS version to 1.2 (default)
Even so for the yes/no options it shows an error when there is a mistake. In all cases the process continues.
In the following line we assign the wrong value to http_followlocation, namely "uniface".
http_profile=verify_url_name=no, min_tls_version=1.2, verify_server=no, http_followlocation=uniface
NET_SETTINGS Error:Profile name:HTTP_PROFILE. Contains an invalid option for "http_followlocation". Found: "uniface" this should have been: yes | y | 1 | no | n | 0. Set to default:no
Path settings and URL settings are not checked. All errors are also reported when there are multiple mistakes in one profile.
Appendix
Recognized keywords in a net profile. Long and short name. See documentation for meaning and usage. Other keywords in the profile setting will be flagged as unknown by the ASN reader.
allow_renegotiation
authentication
ca_certificate
ca_cert
ca_location
ca_loc
cipher_list
cpr_lst
client_certificate
clt_cert
client_key
clt_key
clt_key_pwd
client_key_password
http_followlocation
min_tls_version
server_certificate
srv_cert
server_key
srv_key
server_key_password
srv_key_pwd
shared_key
sh_key
verify_client
vfy_clt
verify_client_name
vfy_clt_nm
verify_content_length
vfy_cnt_len
verify_server
vfy_srv
verify_server_name
vfy_srv_nm
verify_url_name
vfy_url_nm