doc update with SSL info for #989

Author: bimalkjha

APIDocumentation.md

@@ -109,14 +109,46 @@ connStr = "DATABASE=database;HOSTNAME=hostname;PORT=port;Security=SSL;SSLServerC
 ```
 > Note the two extra keywords **Security** and **SSLServerCertificate** used in connection string. `SSLServerCertificate` should point to the SSL Certificate from server or an CA signed certificate. Also, `PORT` must be `SSL` port and not the TCPI/IP port. Make sure Db2 server is configured to accept connection on SSL port else `ibm_db` will throw SQL30081N error.
 
+> `ibm_db` uses IBM ODBC/CLI Driver for connectivity and it do not support a certificate generated in `jks` format.
+ `ibm_db` do not work with a `keystore.jks` file or any certificate generated for Java application. `ibm_db` works
+ with a certificate generate for non-Java application that can get processed by GSKit tool. If you have a `*.jks` file,
+ please get a SSL Certificate meant for non-Java application. If you have downloaded `IBMCertTrustStore` from IBM site,
+ ibm_db will not work with it; you need to download `Secure Connection Certificates.zip` file that comes for IBM
+ DB2 Command line tool(CLP).
+
+> `ibm_db` supports only ODBC/CLI Driver keywords in connection string: https://www.ibm.com/docs/en/db2/11.5?topic=odbc-cliodbc-configuration-keywords
+
+> Do not use keyworkds like `sslConnection=true` in connection string as it is a JDBC connection keyword and ibm_db
+ ignores it. Corresponding ibm_db connection keyword for `sslConnection` is `Security` hence, use `Security=SSL;` in
+ connection string instead.
+
 To connect to dashDB in IBM Cloud, use below connection string:
 ```
 connStr = "DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=passwd;Security=SSL";
 ```
 > We just need to add **Security=SSL** in connection string to have a secure connection against Db2 server in IBM Cloud.
 
+To connect a Db2 Server using SSL Certificate file, you can use connection string like below:
+```
+connStr = "DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=passwd;" +
+          "Security=SSL;SSLServerCertificate=/home/user/myclientcert.arm;";
+```
+> Value of `SSLServerCertificate` keyword must be full path of a certificate generated for non-Java application on
+ Db2 Server. It normally has `*.arm` or `*.cert` or `*.pem` extension. `ibm_db` do not support `jks` format
+ certificate file.
+
 You can also create a KeyStore DB using GSKit command line tool and use it in connection string along with other keywords as documented in [DB2 Infocenter](http://www.ibm.com/support/knowledgecenter/en/SSEPGG_11.5.0/com.ibm.db2.luw.admin.sec.doc/doc/t0053518.html).
 
+If you have created a KeyStore DB using GSKit using password or you have got *.kdb file with *.sth file, use
+connection string in below format:
+```
+connStr = "DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=dbuser;PWD=db2pwd;" +
+          "Security=SSL;SslClientKeystoredb=C:/client.kdb;SSLClientKeystash=C:/client.sth;";
+OR,
+connStr = "DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=dbuser;PWD=db2pwd;" +
+          "Security=SSL;SslClientKeystoredb=C:/client.kdb;SSLClientKeystoreDBPassword=kdbpasswd;";
+```
+
 **Note:** You can also create keystoredb using GSKit and add certificate file to keystoredb to use as documented in [DB2 Infocenter](http://www.ibm.com/support/knowledgecenter/en/SSEPGG_11.5.0/com.ibm.db2.luw.admin.sec.doc/doc/t0053518.html).
 
 ### <a name="openSyncApi"></a> 2) .openSync(connectionString [,options])

README.md

@@ -11,6 +11,8 @@ Async APIs return promises if callback function is not used. Async APIs supports
 
 - **SQL1598N Error** - It is expected in absence of valid db2connect license. Please click [here](#sql1598n) and read instructions.
 
+- **GSKit Error** - Check instructions as documented [here](https://github.com/ibmdb/node-ibm_db/blob/master/APIDocumentation.md#SSLConnection).
+
 ## API Documentation
 
 - For complete list of ibm_db APIs and example, please check [APIDocumentation.md](https://github.com/ibmdb/node-ibm_db/blob/master/APIDocumentation.md)
@@ -32,6 +34,9 @@ Install a newer compiler or upgrade older one.
 
 - **For Docker Linux Container:** make sure you have installed **make, gcc, g++(gcc-c++), python3.9 and node** before installing `ibm_db`. For `root` user, use `npm install --unsafe-perm ibm_db` to install `ibm_db`.
 
+- While installing `ibm_db` under a container, if you get libcrypt error, add a line in your scrip to install `libcrypt` and `libcrypt-compat` as this library is not present in most of the container OS. f.e. add a line like below in docker script:
+  `RUN apt-get update && apt-get install gcc g++ libcrypt libcrypt-compat python3 make -y`
+
 - **For Windows Subsystem for Linux (WSL):** Install `build-essentials` package before installing `ibm_db`.
 
 - **For MacOS:** Install XCode from appstore before installing `ibm_db`. Also, gcc@8 and `make` is required.
@@ -373,6 +378,8 @@ To suppress this error, Db2 server must be activated with db2connectactivate uti
 
 - Client side db2connect license is a `db2con*.lic` file that must be copied under `clidriver\license` directory.
 
+- User running application must have write permission for `clidriver\cfgcache` and `clidriver\license` directories as clidriver need to create binary files to store licensing info in these directories at runtime. Lack of permission to create file too causes SQL1598N error.
+
 - If you have a `db2jcc_license_cisuz.jar` file, it will not work for ibm_db. `db2jcc_license_cisuz.jar` is a db2connect license file for Java Driver. For non-Java Driver, client side db2connect license comes as a file name `db2con*.lic`.
 
 - If environment variable `IBM_DB_HOME` or `IBM_DB_INSTALLER_URL` is not set, `ibm_db` automatically downloads [open source driver specific clidriver](https://public.dhe.ibm.com/ibmdl/export/pub/software/data/db2/drivers/odbc_cli/) from https://public.dhe.ibm.com/ibmdl/export/pub/software/data/db2/drivers/odbc_cli and save as `node_modules\ibm_db\installer\clidriver`. Ignores any other installation.