Web Services changes

There are changes in support of web services in Genero 3.10.

Security note: OpenSSL 3.0 LTS support

Starting with FGLGWS 3.21.01, 4.01.05 and 5.00.00, OpenSSL 3.0 LTS is required for encryption and security.

Because OpenSSL 1.1.1 goes EOL in September 2023 (external link), it is now mandatory to use OpenSSL 3.0 LTS to get the latest security fixes.

When installing an FGLGWS package, OpenSSL 3.0 libs will be provided in FGLDIR, if no OpenSSL 3.0 exists on the system.

Starting with OpenSSL 3.0, the SHA-1 digest algorithm is no longer supported by default. The OpenSSL 3.0 libs provided in FGLDIR still have SHA-1 digest activated by default. If you want to enable SHA-1 with the system OpenSSL 3.0 libs, use a command such as update-crypto-policies --set DEFAULT:SHA1 in order to use SHA-1. However, the SHA-1 digest algorithm is no longer recommended, because it is increasingly vulnerable as computers become more and more powerful. If you are using SHA-1 with GWS crypto APIs, consider moving to SHA-256 or to a stronger secure hash algorithm.

See GWS Security for more details about security and encryption with GWS.

The XMLElementNillable, XMLOptional, and XMLNillable attributes

The management of XML serialization when serializing nillable has changed. These attributes define how a NULL value is interpreted in XML.

When using the XMLOptional attribute, the behavior of the XML serialization has changed; it no longer handles XML nillable.

The new XMLNillable attribute can be used to specify that the XML representation of a NULL value must be xsi:nil="true".

In order to get the same result as when using XMLOptional in prior versions, set both XMLOptional and XMLNillable.

Instead of specifying each element individually with XMLNillable, the XMLElementNillable attribute can be used with a BDL RECORD defined as TYPE or DEFINE to specify the XML representation for nillable in all elements in the record. This eases migration to the new XMLNillable behavior, because now you can get the same behavior as before defining database records by adding the XMLElementNillable attribute.

Important: If in versions prior to GWS 3.10 you had the following expected XML serialization behavior, you need to take action to avoid serializer errors:

A variable that was expected to serialize an xsi:nil value, you must set the XMLNillable attribute on that variable.
A record defined with LIKE for fields in a database table which may allow null values, you must set the XMLElementNillable attribute as in the example.
```
DEFINE var RECORD ATTRIBUTE(XMLElementNillable) LIKE customer.*
```

It is therefore recommended to do the following:

Recompile the Genero Web Service server to create a new WSDL that supports the XML nillable feature.
Regenerate all Genero Web Service client stubs from the newly-generated WSDL to get the support of XML nillable. Regenerate client stubs using the fglwsdl tool.

Better support for Web Services API on iOS/GMI

Most of the Web Services APIs are not available on iOS mobile devices.

There are still some exceptions, related to iOS restrictions. For details see Web Services on mobile devices.

Note: In versions before 3.10, the iOS app displayed a pop-up dialog to cancel a long running HTTP request. Starting with 3.10, the pop-up dialog is no longer used; only the activity indicator displays, and the app goes into background mode, if the HTTP request fails to complete after several minutes. The program gets a runtime error -15553 if the user taps the app icons, to bring the app back to foreground mode.

OpenID Single sign-on (SSO) protocol not supported

Support of the OpenID Single sign-on (SSO) protocol has been dropped. This service based on Genero REST is no longer delivered in the Genero Web Services package under $FGLDIR/web_utilities/services/openid.

If you have previously used OpenID to authenticate users launching applications, you must now use an alternate method, such as OpenID Connect. See the OpenID Connect SSO topics in Genero Application Server User Guide.

Define server configuration based on regular expressions

Starting with GWS 3.10.09, instead of using the ws.myident.url FGLPROFILE entry, you can now use a regular expression to identify several server URLs, by using the ws.ident.regex.url entry.

For more details, see Web Services FGLPROFILE: Server configuration.

fglwsdl option -fRPCNamespace to support namespaces in RPC parameters

Starting with GWS 3.10.09, the fglwsdl tool supports the new option -fRPCNamespace to produce BDL code supporting the namespace attribute for RPC parameters.

For more details, see fglwsdl.

fglpass option -gid to allow agent authentication through a UNIX user group

Starting with GWS 3.10.10, the fglpass tool can be used with the -gid to allow agent authentication for all users which belong to the group of the current user executing the fglpass command.

For more details, see fglpass, Use the password agent.

Changes to security.global.protocol in FGLPROFILE

Starting with FGLGWS 3.10.22 GWS secured communication is based on the OpenSSL 1.1 engine. This version of OpenSSL always selects the security protocol. It no longer allows you to specify a specific Transport Layer Security (TLS) or Secure Sockets Layer (SSL).

The security.global.protocol entry in the fglprofile file is therefore no longer supported.

For instance, if you have set security.global.protocol = "TLsv1.2" to configure OpenSSL to use TLSv1.2 for HTTPS for earlier versions, you may encounter the following error message in your Web service:

OpenSSL 1.1 doesn't support specific protocol anymore

It is therefore recommended to remove the security.global.protocol entry from your fglprofile file. For more information on Web service security configuration, see HTTPS and password encryption.

Changes to how GWS handles cookies

When upgrading your Web services, you need to be aware of the requirement for sameSite when setting HTTP cookies. Review the changes in how the Genero Web Services (GWS) handles cookies:

WSHelper.WSServerCookiesType has a new member (sameSite) added to the record to specify how cookies are sent to other sites. Three values are possibles for sending cookies: "Strict", "Lax", or "None". The default is "Lax". If NULL, the default "Lax" is used.
The com.HTTPServiceRequest.setResponseCookies method taking WSHelper.WSServerCookiesType as parameter may raise a runtime error if the sameSite attribute is not set correctly. For instance, you can not set it to "None" if secure is not set to TRUE. This raises the error SameSite None value requires Secure to be set.

If you use cookies on the server side, we recommend you make the changes necessary for sending cookies, and that you recompile your sources. For instance, make sure that cookies you use to secure your application are set with sameSite "Strict". Setting SameSite="Strict" on the secure cookie ensures that only the exact URL the cookie has been set with will return the cookie to the server. If not set, the GWS sets each cookie's sameSite attribute as "Lax".

To have SameSite available, you must recompile your sources with fglcomp 3.10.24 or greater.