Recent changes to WebServiceProxyDriver

WebServiceProxyDriver modified by marsupilami79

marsupilami79 — Wed, 03 Dec 2025 13:27:49 -0000

--- v19
+++ v20
@@ -10,14 +10,45 @@
 * more to come, I am sure...
 ##Con's
 * is another layer that might break.
-* it uses SOAP and XML - so it suffers from data bloat by XML.
+* it uses SOAP and XML - so it suffers from "data bloat" by XML. -> This is remedied to to a big degree by the optional CBOR webservice implementation for queries.
 * not all metadata functions are implemented yet
 * currently no support for stored procedures, generators and events.
 * XML doesn't allow to encode control characters besides TAB, Line Feed and Carriage Return. So other characters cannot be transported in Strings and CLOBs.
 * more to come, I am sure...
 #The server
 ##About
-The current implementation is an http server that listens on port 8000. It uses the FPC http server units. Since the server is based on the web service toolkit, other server implementations can be used (indy, Synapse, apache module). This allows a wide variety of choices. The current implementation is designed for Lazarus 2.0.6 and FPC 3.0.4 only. There is no Delphi implementation.
+The current implementation is an http server that listens on port 8000. It uses the FPC http server units. Since the server is based on the web service toolkit, other server implementations can be used (indy, Synapse, apache module). This allows a wide variety of choices. The current implementation is designed for Lazarus with FPC 3.2.2 or newer. There is no Delphi implementation.
+## compilation
+### supported compiler versions
+Depending on your familiarity with the Lazarus ecosystem there are two choices regarding the development environment:
+
+  * use FPC 3.2.2. This allows easy download and installation of a current Lazarus package. Unfortunately FPC 3.2.2 only supports OpenSSL version 1.1 which is obsolete by now.
+  * use FPC from the 3.2-fixes branch. This allows to use modern OpenSSL 3 versions but is slightly more complex to setup. The easiest way is to use [fpcupdeluxe](https://github.com/LongDirtyAnimAlf/fpcupdeluxe).
+
+### other build dependencies
+For building the Zeos Proxy Server, other softweare, that doesn't come preinstalled with Lazarus is required:
+
+  * [Web Service Toolkit](https://wiki.freepascal.org/Web_Service_Toolkit): The Zeos Proxy Server uses the [Web Service Toolkit](https://wiki.freepascal.org/Web_Service_Toolkit) to implement SOAP. The original toolkit can be downloaded from [Lazarus-CCR](https://sourceforge.net/p/lazarus-ccr/svn/HEAD/tree/wst/). A slightly modified version with some improved error reporting capabilities can be downloaded from the iks-patches bramnch on [https://github.com/marsupilami79/wst](https://github.com/marsupilami79/wst).
+  * Synapse: If you want to authenticate against an LDAP server, you will need the [synapse library](https://github.com/geby/synapse)
+  * If you want the server to announce its availability via Multicast DNS service discovery you will need [mdns4delphi](https://github.com/marsupilami79/mdns4Delphi)
+
+### building
+The Web Service proxy source code is delivered with Zeos in the `src/webservice` folder. 
+There are two flavors to choose from:
+
+* Application: The server is run as a regular application. This is more suitable for testing purposes. It doesn't require changes to the system. The project files for the application are in the `src/webservice/server/application` folder.
+* Service: The server is run as an operating system service. This is more suitable for running the proxy server in a production environment. The project files for the service are in the `src/webservice/server/application` folder.
+
+After chosing your desired flavor, follow the following steps:
+
+1. modify the `dbcproxy.inc` file to your needs. 
+2. compile the `wst_core` and `wst_fcltransport` packages in Lazarus
+3. open the package file for your desired flavor of the Web Service Proxy.
+4. If you want to use synapse or mdns4delphi, make sure that the paths are correctly set in the project settings (Project -> Project Options -> Compiler Options -> Paths -> Other unit files)
+5. Build the project (Run -> Build)
+
+The executable file will be built in the folder where the project file resides.
+
 ##configuration
 Upon startup the server reads the `zeosproxy.ini` in its own directory (windows) or `/etc/zeosproxy.ini` (linux). The first section that is read is the `[general]` section. Here the values for `database prefix` and `security module prefix` are read.  Every section of this ini file starting with the `database prefix` is treated as a database configuration name, that a client can connect to. The following values can be set in the `[general]` section:

WebServiceProxyDriver modified by marsupilami79

marsupilami79 — Thu, 10 Apr 2025 16:17:32 -0000

--- v18
+++ v19
@@ -182,5 +182,5 @@
 * compile the ZeosProxyService.lpi that can be found in src\webservice\server\service
 * place the resulting ZeosProxyService.exe at any place you like
 * create a ZDbcProxy.ini in the same directory
-* run `ZeosProxyService.exe install` to register it as a service in Windows
+* run `ZeosProxyService.exe --install` to register it as a service in Windows
 * run `net start TZeosProxyDaemon`to start the service

WebServiceProxyDriver modified by marsupilami79

marsupilami79 — Sat, 24 Feb 2024 20:10:16 -0000

--- v17
+++ v18
@@ -62,7 +62,7 @@
 ldap|This security module allows to verify a users password against an LDAP server.

 ####The yubiotp security module
-This module allows to check one time passwords that are generated by the Yubikeys, which are myade by Yubico. The Yubikey password can be concatenated with a user password. In that case the module expects the Yibikey OTP to be at the end of the password. The Yubikey OTP will be used to authenticate the user and the remaining password (without the Yubikey OTP) will be returned to be used for server authentication or for the use of other security modules.
+This module allows to check one time passwords that are generated by the Yubikeys, which are myade by Yubico. The Yubikey password can be concatenated with a user password. In that case the module expects the Yubikey OTP to be at the end of the password. The Yubikey OTP will be used to authenticate the user and the remaining password (without the Yubikey OTP) will be returned to be used for server authentication or for the use of other security modules.
 The following parameters can be set in sections that configure a yubiotop security module:

 key|description
@@ -73,6 +73,10 @@
 Base URL|The base URL used for authentication. For Yubicos public servers this would be `https://api.yubico.com/wsapi/2.0/verify`, which also is the default value of this option.
 Client ID|The client ID to use when communication with the authentication server. This ID can be used to check the signature of the servers response.
 Secret Key|The secret key that gets used by Yubico to sign the response. The default value for this option is an empty string. If a value is provided, the module will verify the signature of the response and fail the authentication if the signature is invalid.
+Yubikey SQL|An SQL statment that the module can use to check if the supplied user name and yubikey can be used. The SQL **must** have two parameters where the first parameter gets filled with the public identity of the yubikey and the second parameter gets filled with the user name.
+DB User|The user name to use when checking the public identity against the database.
+DB Password|The password to use when checking the public identity against the database.
+Replacement User Column|If this column name gets set, the user name that gets used for the authentication against subsequent modules or the database will be replaced by the value in the supplied column upon succesful yubikey lookup.

 ####The TOTP security module
 This module allows to check time based one time passwords as described in  RFC 6238 and used by Google Authenticator and others. The OTP can be combined with a user password. In that case the module expects the user password to be first in the password string and the OTP to be the last six characters in the password.

WebServiceProxyDriver modified by marsupilami79

marsupilami79 — Sat, 18 Nov 2023 08:36:40 -0000

--- v16
+++ v17
@@ -28,6 +28,11 @@
 Listening Port|This key allows to set the port that the Proxy server listenes on. The default value is `8000`.
 IP Address|This key allows to set the IP address that the server binds to. The default value is `127.0.0.1`. A value of `0.0.0.0` allows to listen on all IP addresses of the host.
 Connection Idle Timeout|From time to time the server cleans up connections. Connections that have not been used for this time will be closed. The timeout is specified in seconds. The default value is `86400` which is one day.
+use ssl|If enabled, SSL is used.
+host name|If SSL is enabled, this sets the host name to use for SSL.
+Certificate File|Sets the certificate file to use for SSL.
+Key File|Specifies the key file to use for SSL.
+Key Password|if the key fiule is encrypted, the key password can be set here.

 ###Connections
 Sections whose name start with the database prefix will be read as describing a database that users can connect to. The following keys can be used inside these sections:

WebServiceProxyDriver modified by marsupilami79

marsupilami79 — Tue, 25 Apr 2023 18:56:55 -0000

--- v15
+++ v16
@@ -2,11 +2,11 @@
 The Zeos WebServiceProxy driver is a driver that doesn't connect to a specific database. It is an internal API proxy for Zeos. Using this driver you can build a bridge across the internet between your Zeos based application and any database that is supported by Zeos. It uses http and https as its transport protocols, so it should be able to get through most firewalls. Also it doesn't rely on a constant connection but rather uses session IDs. So a change of the client IP address or a connection loss don't close the session.
 ##Pro's
 * Can connect nearly any Zeos supported database to the internet
+* can connect any mobile device to your database without requiring a client library.
+* can add 2FA to the database access. 2FA is checked before a connection to the database is created.
 * Is a Pascal only implementation, so no client library is used
 * Can encrypt the connection by using TLS
 * Doesn't loose the connection even if the client is suspended, disconnected for a time or changes its IP address.
-* doesn't suffer from slow wire protocols of some databases.
-* once it is ported to Zeos 7.3 it can connect any mobile device to your database without requiring a client library.
 * more to come, I am sure...
 ##Con's
 * is another layer that might break.
@@ -52,7 +52,9 @@
 yubiotp|This module allows to check one time passwords that are generated by the Yubikeys, which are myade by Yubico.
 totp|This module allows to check time based one time passwords as described in  RFC 6238 and used by Google Authenticator and others.
 integrated|This module allows to check passwords that were generated using the MD5Crypt algorithm and are stored in the database that will be used.
-chained|This security module allows to combine several security modules into a chanin. A username / password combination must be authenticated by each one of these modules.
+chained|This security module allows to combine several security modules into a chain. A username / password combination must be authenticated by each one of these modules.
+alternate|This security module allows to authenticate a user either by one security module or another security module.
+ldap|This security module allows to verify a users password against an LDAP server.

 ####The yubiotp security module
 This module allows to check one time passwords that are generated by the Yubikeys, which are myade by Yubico. The Yubikey password can be concatenated with a user password. In that case the module expects the Yibikey OTP to be at the end of the password. The Yubikey OTP will be used to authenticate the user and the remaining password (without the Yubikey OTP) will be returned to be used for server authentication or for the use of other security modules.
@@ -107,6 +109,33 @@
 ---|-----------
 Module List|This key lists the security module configurations to use from the very same ini file. Names are to be used without the `security prefix`. The delimiter for this list is the komma (`,`).

+####The alternate security module
+This security module allows to have two modules as alternatives to each other.
+So if one of two modules authenticates a user this suffices for the login to be allowed. 
+Its configuration consists of only one parameter, which lists the ini file sections to read for the alternate security modules.
+
+key|description
+---|-----------
+Module List|This key lists the security module configurations to use from the very same ini file. Names are to be used without the `security prefix`. The delimiter for this list is the komma (`,`).
+
+####The LDAP security module
+This security module allows to contact an LDAP server for user authentication.
+The module checks wether the user can login to the LDAP server.
+If the login is successful, it can do a search with a filter to check wether the user is allowed to use the service.
+Currently it doesn't support SSL, which should be trivial to add since synapse already supports it.
+
+This module isn't compiled by default because it requires the [synapse framework](https://sourceforge.net/p/synalist/code/HEAD/tree/) to be available.
+It has to be enabled in the `dbcproxy.inc` file by enabling the `ENABLE_LDAP_SECURITY` define.
+
+key|description
+---|-----------
+Host Name|The name of the LDAP host to query.
+User Name Mask|This allows to add striungs to the user name. The default is `%s` which will just generate a string with the username. For extending a user name with the domain name, set it to `yourdomainname\:s`.
+User Lookup Expression|An expression that can be used to check a users membership in groups. The Server will run an LDAP search using this expression. If one or meore objects are returned, access is granted. Again `:s` gets replaced by the user name. This parameter defaults to `(sAMAccountName=%s)`.  If it is left empty, the check will not be performed an the user will be allowed to log in. A group membership can be tested with an expression like `(&(sAMAccountName=%s)(memberOf=CN=somegroup,CN=Users,DC=contonso,DC=com))`.
+Base DN|The base DN that gets used for the LDAP search. It should be set to something like `DC=contonso,DC=com`.
+Replacement User|If this value is set, the username that was supplied to the security module gets replaced by `Replacement User` if the authentication finishes successful. This allows to authenticate users but have all users conenct to the database with the same username and password. This is considered bad style.
+Replacement Password|If This parameter is set, this value will get used to replace the user supplied password before authenticating to the database.
+
 #The client (Web Service Proxy)
 ##About
 By default the driver is compiled to use a separate client library. This library is intended to separate all the web service stuff from the Zeos driver. This way we can compile a working driver without relying on web service support by the compiler. The client library contains the web service proxy and all the units that are needed to do the networking stuff. Once the data is transferred, it is delivered to the Zeos driver that does the rest of the work.

WebServiceProxyDriver modified by marsupilami79

marsupilami79 — Tue, 18 Apr 2023 08:04:24 -0000

WebServiceProxy Driver modified by marsupilami79

marsupilami79 — Mon, 20 Mar 2023 15:50:49 -0000

--- v13
+++ v14
@@ -98,7 +98,7 @@
 Replacement User|If this value is set, the username and password that were supplied to the security module get replaced by `Replacement User` and `Replacement password` if the authentication finishes successful. This allows to authenticate users but have all users conenct to the database with the same username and password. This is considered bad style.
 Replacement Password|If `Replacement User` is set, this value will get used to replace the user supplied password before authenticating to the database.
 Password SQL|This parameter specifies the SQL command to use for retrieving a users hashed password from the database. The username will be supplied as the one and only parameter. The parameter has to be supplied as a question mark. Example: `select password from users where lower(username) = lower(?)`
-Add Database To Username|PostgreSQL has the option to determine the correct username by appending the database name to the user name. When migrating passwords from such an instance, this option has to be set to true. If this option is set to true, user names will be a concatenation of the client user name, the `@` symbol and the database name as listed in the ini file when calculating the user name for PostgreSQL type password checks. If the user name already contains an `@` no concatenation will be done. If the user name ends with an `@`, the `@`will be removed for the password calculation.
+Add Database To Username|PostgreSQL has the option to determine the correct username by appending the database name to the user name (aka the db_user_namespace feature). When migrating passwords from such an instance, this option has to be set to true. If this option is set to true, user names will be a concatenation of the client user name, the `@` symbol and the database name as listed in the ini file when calculating the user name for PostgreSQL type password checks. If the user name already contains an `@` no concatenation will be done. If the user name ends with an `@`, the `@`will be removed for the password calculation. The user name that gets used for the database lookup will still be the user name without the appended database name. If the username contains an `@` before the concatenation, nothing will be done and the user name will be used as is for password calculation.

 ####The chained security module
 This security module allows to combine several security modules into a chanin. A username / password combination must be authenticated by each one of these security modules. Its configuration consists of only one parameter, which lists the ini file sections to read for the chained security modules.

WebServiceProxy Driver modified by marsupilami79

marsupilami79 — Mon, 20 Mar 2023 15:16:49 -0000

--- v12
+++ v13
@@ -9,7 +9,7 @@
 * once it is ported to Zeos 7.3 it can connect any mobile device to your database without requiring a client library.
 * more to come, I am sure...
 ##Con's
-* is anoter layer that might break.
+* is another layer that might break.
 * it uses SOAP and XML - so it suffers from data bloat by XML.
 * not all metadata functions are implemented yet
 * currently no support for stored procedures, generators and events.

WebServiceProxy Driver modified by marsupilami79

marsupilami79 — Mon, 20 Mar 2023 15:16:33 -0000

--- v11
+++ v12
@@ -98,7 +98,7 @@
 Replacement User|If this value is set, the username and password that were supplied to the security module get replaced by `Replacement User` and `Replacement password` if the authentication finishes successful. This allows to authenticate users but have all users conenct to the database with the same username and password. This is considered bad style.
 Replacement Password|If `Replacement User` is set, this value will get used to replace the user supplied password before authenticating to the database.
 Password SQL|This parameter specifies the SQL command to use for retrieving a users hashed password from the database. The username will be supplied as the one and only parameter. The parameter has to be supplied as a question mark. Example: `select password from users where lower(username) = lower(?)`
-Add Database To Username|PostgreSQL has the option to determine the correct username by appending the database name to the user name. When migrating passwords from such an instance, this option has to be set to true. If this option is set to true, user names will be a concatenation of the client user name, the `@` symbol and the database name as listed in the ini file when calculating the user name for PostgreSQL stype password checks.
+Add Database To Username|PostgreSQL has the option to determine the correct username by appending the database name to the user name. When migrating passwords from such an instance, this option has to be set to true. If this option is set to true, user names will be a concatenation of the client user name, the `@` symbol and the database name as listed in the ini file when calculating the user name for PostgreSQL type password checks. If the user name already contains an `@` no concatenation will be done. If the user name ends with an `@`, the `@`will be removed for the password calculation.

 ####The chained security module
 This security module allows to combine several security modules into a chanin. A username / password combination must be authenticated by each one of these security modules. Its configuration consists of only one parameter, which lists the ini file sections to read for the chained security modules.

WebServiceProxy Driver modified by marsupilami79

marsupilami79 — Mon, 20 Mar 2023 15:13:26 -0000

--- v10
+++ v11
@@ -61,8 +61,8 @@
 key|description
 ---|-----------
 Yubikeys File|The file that contains the assignments of yubikeys to users. Each line lists one username and one or many yubikeys that are assigned to these users. A colon is used as the delimiter between the username and the yubikeys.
-Add Database To Username|In some configurations it might be viable to not only differentiate users by their user name but also on the databs that they want to get access to. If this option is set to true, user names will be a concatenation of the client user name, the `Database Separator` (usually the `@` symbol) and the connection name as listed in the ini file.
-Database Separator|The separator that gets used, if the `Add Database To Username` option is set. The default vaklue is the `@` character.
+Add Database To Username|In some configurations it might be viable to not only differentiate users by their user name but also on the database that they want to get access to. If this option is set to true, user names will be a concatenation of the client user name, the `Database Separator` (usually the `@` symbol) and the connection name as listed in the ini file.
+Database Separator|The separator that gets used, if the `Add Database To Username` option is set. The default value is the `@` character.
 Base URL|The base URL used for authentication. For Yubicos public servers this would be `https://api.yubico.com/wsapi/2.0/verify`, which also is the default value of this option.
 Client ID|The client ID to use when communication with the authentication server. This ID can be used to check the signature of the servers response.
 Secret Key|The secret key that gets used by Yubico to sign the response. The default value for this option is an empty string. If a value is provided, the module will verify the signature of the response and fail the authentication if the signature is invalid.
@@ -74,20 +74,21 @@
 key|description
 ---|-----------
 Secrets File|This key has to be set to the name of the file containing the secrets for the users to be authenticated.  Each line contains the name of a user and a Base32 encoded secret delimited by a `:`. This secret will get used to check the TOTP.
-Add Database To Username|In some configurations it might be viable to not only differentiate users by their user name but also on the databs that they want to get access to. If this option is set to true, user names will be a concatenation of the client user name, the `Database Separator` (usually the `@` symbol) and the connection name as listed in the ini file.
-Database Separator|The separator that gets used, if the `Add Database To Username` option is set. The default vaklue is the `@` character.
+Add Database To Username|In some configurations it might be viable to not only differentiate users by their user name but also on the database that they want to get access to. If this option is set to true, user names will be a concatenation of the client user name, the `Database Separator` (usually the `@` symbol) and the connection name as listed in the ini file.
+Database Separator|The separator that gets used, if the `Add Database To Username` option is set. The default value is the `@` character.

 #####Notes about generating TOTP secrets and distributing them
 With TOTP security is dependent on how well protected the secret is. Anybody who gets to know the secret can generate the correct TOTPs.

-* Most probably these secrets should be generated with a [cryptographically secure pseudorandom number generator (CSPRNG)](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator). The only CSPRNG that I found for Pascal is the [AES-256 based Cryptographically Secure Pseudo-Random Number Generator (CSPRNG) by Synopse](https://blog.synopse.info/?post/AES-CSPRNG) which os part of [mORMot](https://blog.synopse.info/?category/Open-Source-Projects/mORMot-Framework).
+* Most probably these secrets should be generated with a [cryptographically secure pseudorandom number generator (CSPRNG)](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator). The only CSPRNG that I found for Pascal is the [AES-256 based Cryptographically Secure Pseudo-Random Number Generator (CSPRNG) by Synopse](https://blog.synopse.info/?post/AES-CSPRNG) which is part of [mORMot](https://blog.synopse.info/?category/Open-Source-Projects/mORMot-Framework).
 * When distributing these secrets it makes sense to uses [Googles Key Uri Format](https://github.com/google/google-authenticator/wiki/Key-Uri-Format) as described in their (archived) wiki on Github.
 * It makes sense to generate QR codes for these URIs. In Delphi and FPC this can be done using the [
 Zint Barcode Generator for Delphi ](https://github.com/landrix/Zint-Barcode-Generator-for-Delphi).
 * A sample implementation for generating secrets and URIs can be found at https://github.com/marsupilami79/TOTPSecretGenerator4Pascal

 ####The integrated security module
-This module allows to check passwords that were generated using the MD5Crypt algorithm and are stored in the database that will be used. The password will be extracted from the database using a custom set SQL query. This query is expected to return the users hashed password in the first column of the first returned row.
+This module allows to check passwords that are stored in the database that will be used. The password will be extracted from the database using a custom set SQL query. This query is expected to return the users hashed password in the first column of the first returned row. The pasword can be hashed using either the MD5Crypt algorithm or the PostgreSQL variant of hashing passwords with MD5.
+
 The following parameters can be set in sections that configure an integrated security module:

 key|description
@@ -97,6 +98,7 @@
 Replacement User|If this value is set, the username and password that were supplied to the security module get replaced by `Replacement User` and `Replacement password` if the authentication finishes successful. This allows to authenticate users but have all users conenct to the database with the same username and password. This is considered bad style.
 Replacement Password|If `Replacement User` is set, this value will get used to replace the user supplied password before authenticating to the database.
 Password SQL|This parameter specifies the SQL command to use for retrieving a users hashed password from the database. The username will be supplied as the one and only parameter. The parameter has to be supplied as a question mark. Example: `select password from users where lower(username) = lower(?)`
+Add Database To Username|PostgreSQL has the option to determine the correct username by appending the database name to the user name. When migrating passwords from such an instance, this option has to be set to true. If this option is set to true, user names will be a concatenation of the client user name, the `@` symbol and the database name as listed in the ini file when calculating the user name for PostgreSQL stype password checks.

 ####The chained security module
 This security module allows to combine several security modules into a chanin. A username / password combination must be authenticated by each one of these security modules. Its configuration consists of only one parameter, which lists the ini file sections to read for the chained security modules.