Web Services changes
There are changes in support of web services in Genero 3.21.
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.
Get OpenSSL from third-party vendors for Windows
- Go to an official OpenSSL library vendor. OpenSSL recommends Shining Light Productions (external link) for OpenSSL libraries for Windows.
- Download the OpenSSL libraries from there.
- By default, GWS will look for the OpenSSL libraries in the $FGLDIR\bin
directory unless you have also specified OPENSSL_MODULES to look in another path. Copy the following
libraries into your $FGLDIR\bin directory.
- libcrypto-3-x64.dll
- libssl-3-x64.dll
- legacy.dll
- Verify that the installation has worked by running the command fglpass -Vssl; it should return the version of the OpenSSL libraries.
See GWS Security for more details about security and encryption with GWS.
New security.global.options entry in FGLPROFILE to allow legacy OpenSSL 1 options
Starting from FGLGWS 3.21.02, 4.01.06, and 5.00.00, it is now mandatory to use OpenSSL 3.0 LTS to get the latest security fixes. This change is due to OpenSSL 1.1.1 going EOL in September 2023 (external link).
To ease your migration from OpenSSL 1 to OpenSSL 3, the FGLPROFILE option
security.global.options can be used to set OpenSSL 1 options to connect to a legacy
server.
For details, go to Security Configuration FGLPROFILE entries.
New fglwsdl option -SSLOptions to support legacy OpenSSL 1 options
Starting from FGLGWS 3.21.02, 4.01.06, and 5.00.00, it is now mandatory to use OpenSSL 3.0 LTS to get the latest security fixes. This change is due to OpenSSL 1.1.1 going EOL in September 2023 (external link).
The fglwsdl tool supports the option (-SSLOptions) to set
OpenSSL 1 options when connecting to a legacy server.
For more details, go to fglwsdl.
New security.global.certificate.selfsigned.preload entry in FGLPROFILE
Starting from FGLGWS 3.21.02, 4.01.07, and 5.00.02, there is an option to preload the global
self-signed certificate and private key used for HTTPS connections. Typically, the certificate and
key is loaded at the first HTTPS request. If you find the GWS computation of the certificate and key
takes too long, you can speed things up by setting the
security.global.certificate.selfsigned.preload = TRUE to preload the certificate
and key at the start of the application instead of at the first HTTPS connection.
For more information on web service security configuration, go to Security Configuration FGLPROFILE entries.
Change to OAuthAPI.GetIDSubject returns
Starting from FGLGWS 3.21.02 and 4.01.06, the OAuthAPI.GetIDSubject function
returns the subject identifier of an ID token in a string instead of an integer.
If you have previously used the function, review your code and ensure that the variable that
affects the return value is of type STRING.
For details, go to OAuthAPI.GetIDSubject().
Changes to the OpenIDConnect service configuration
Starting from FGLGWS 3.21.02, 4.01.07, and 5.00.02, two parameters of the Genero OpenIDConnect service configuration ($FGLDIR\web_utilities\services\openid-connect\res\configuration) have changes:
- The
oidc.logout.id_token_hintparameter, used in the logout request sent to the provider, has been replaced byoidc.logout.identifier. The new parameter supports the values "id_token_hint", "client_id", or anempty(" ") value. The default value is "id_token_hint". - The
oidc.logout.post_redirectparameter, used to send the post redirect uri in the logout request, now needs a string value instead of the boolean value true/false on previous versions. The default value is now "post_logout_redirect_uri".
No action needs to be taken on your part, but if you have previously used a custom OpenIDConnect configuration file and you want to use it when upgrading FGLGWS version, ensure that you review your configuration for these parameters.
For more information on OpenID Connect Single sign-on, refer to the Single Sign-On User Guide.
Discontinued support for OCSP
We are discontinuing support for the Online Certificate Status Protocol (OCSP) due to the decision by several Certificate Authorities to phase out support for this protocol in web services. However, please note that the OCSP functionality will remain intact within our product, allowing you to continue using this feature as part of your secure communications.
For more information on OCSP, go to Enable OCSP.
Improved communication protocol between GAS and GWS
The communication protocol between the Genero Application Server (GAS)
and the Genero Web Service (GWS) processes has been updated to improve reliability, specifically to
ensure that no connections are lost when the GWS process needs extra time to stop or restart. Prior
to this update, if the GWS process needed time to stop, connections could be lost or requests could
be sent before the service was ready. The protocol was enhanced so that gwsproxy
now ensures fglrun is ready to receive the next request before proceeding.
To ensure you are using this improved communication protocol between the GAS and your GWS applications, ensure you are using the following version pairs (or greater):
-
FGLGWS 3.21.05 and GAS 3.21.05
External DTD of XML request and response bodies
Starting from FGLGWS 3.21.05, the web services engine no longer fetches the external document type definition (DTD), or any other external entity, of an XML request or response body that it parses.
This change improves security by preventing XML external entity
processing, which could cause the server to fetch from a network address or a file on the server.
This applies to SOAP and REST services and clients, and to the com methods that read
an XML body, such as com.HttpServiceRequest.readXmlRequest and com.HttpServiceRequest.beginXmlRequest.
The engine now ignores the external DTD and the external parameter entities of a body, without
raising an error. The attribute default values declared there no longer apply. If the body
references an entity that only the external DTD declares, the engine either replaces the reference
with an empty value or fails to parse the body. On macOS and iOS with a libxml2 version older than 2.13, the attribute default values
declared inside the body's <!DOCTYPE> no longer apply either.
After upgrading, review any service or client whose XML bodies rely on an external DTD.
For details, go to DomDocument Features and StaxReader Features.
load-external-dtd feature of the XML classes
Starting from FGLGWS 3.21.05, the xml.DomDocument and
xml.StaxReader classes have a load-external-dtd feature, which
defines whether a parse fetches the external DTD of a document.
The feature is TRUE by default, so existing
programs fetch external DTDs as before.
An xml.DomDocument that sets enable-html-compliancy to TRUE, then
back to FALSE before loading XML, now follows the load-external-dtd feature like any
other document. Previously, it fetched the external DTD without applying its attribute default
values.
After upgrading, review any program that parses XML from a source that you do not control, such as a
response from a third party or a file that a user uploads, and set load-external-dtd
to FALSE for those documents.
For details, go to DomDocument Features and StaxReader Features.
Changes to how GWS handles an invalid HTTP request
Starting from FGLGWS 3.21.05, when a Web Services server application receives a request that is not valid HTTP, the server responds to the client with an HTTP error status, and the application keeps running.
Where previously such a request put the server into an invalid
state, and every later call failed with the same error, the application now goes on processing
requests.
For such a request, com.WebServiceEngine.ProcessServices() and
com.WebServiceEngine.HandleRequest() return status -5
instead of -8.
com.WebServiceEngine.GetHTTPServiceRequest() still raises error -15565.
After upgrading, review any request loop that tests for -8, and handle -5 there.
For details, go to com.WebServiceEngine.ProcessServices.
Changes in earlier versions
Make sure to check the upgrade notes of earlier versions, to not miss changes introduced in maintenance releases. For more details, go to Web services changes in BDL 3.20.
- Support for validating filenames in WSAttachments. The high-level REST
WSAttachmentattribute has an option to verify filenames in received files using a regular expression pattern, also available in FGLGWS 4.01.00. - Changes to default IP version used by a GWS client. The default IP version is now IPv4, also available in FGLGWS 4.01.00.
- fglwsdl -xmlname option added to generate variables named with XMLName, also available in FGLGWS 4.01.00.
- Dynamic loading of zlib library for data compression, also available in FGLGWS 4.01.03.