DB2 JCC Driver

Functional Specifications V12.1.0

Jun 2023

rocketsoftware.com [email protected] US: +1.855.577.4323 EMEA: +0.800.520.0439

APAC: 612.9412.5400
 766364188.docx

Document Control

SR Versio Specifications Owner(s) Date

No n

1 V 0.1 First Draft Shweta Naik Jun 14, 2023

Updated as per review Jul 6,2023

2 V 0.2 Shweta Naik
comments

Updated changes related to Mar 14, 2024

3 V 0.3 Shweta Naik
diversification

Added section Apr 03,2024

4 V 0.4 Shweta Naik
Documentation updates

5 V 1.0

Reviewers

SR Name Comments Date

No

Design flow diagram

1 Kollol K Misra Jul 6, 2023
changes to be done

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
1
 766364188.docx

Approvals

SR Name Comments Date

No

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
2
 766364188.docx

Table of Contents
1 Executive Summary..............................................................................................3
2 App Token Generation overview..........................................................................3
3 Requirement.........................................................................................................3
4 Solution:................................................................................................................4
5 List of JCC changes..............................................................................................5
6 App Token Registration........................................................................................6
7 SQL queries for Server set up..............................................................................6
8 Create Trusted Context........................................................................................8
7. Connectivity..........................................................................................................8
8. Test Scenarios covered........................................................................................8
9. Documentation updates.......................................................................................9

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
3
 766364188.docx

1 Executive Summary
This is the functional specification document for DB2 JCC driver for App Token
Generation. This document covers the details for SAP Audit Exception - Application
Token Generation feature in version 12.1.0.

2 App Token Generation overview

SAP requires to reduce the auditing by allowing exceptions to auditing for configured
trusted connections using a new definition of trust to establish a Trusted Context, in
which the application sends a token to the server and is validated by a customer
provided stored procedure. The application is required to create an application token
(APPTOKEN) and provide that as input during the database connection. To generate
the APPTOKEN, input from the server is required in the form of a NONCE. A NONCE is a
“number used once”, most often implemented as a random number. From a security
perspective, it used to prevent replay attacks as each connection has a unique
unguessable nonce. This requires though, that the generation of the apptoken is done
as part of the connect processing, it cannot take place before hand.

3 Requirement
The initial requirement is to support identifying a client application via an Application
Identification token, or apptoken for short.

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
4
 766364188.docx

4 Solution:
The solution consists of these three components.

 Allow application to specify or register an APPTOKEN.

 Allow a stored procedure to be a trust attribute for a trusted context.
 Allow exception to auditing for a trusted context.

Overview of changes

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
5
 766364188.docx

DRDA changes

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
6
 766364188.docx

5 List of JCC changes.

1. The AppTokenGen feature for audit exception will be available only with
security manager level 11 and above.
2. First check is to see if security Manager level is 11, only then the CONNONCE
value will be available.
3. JCC driver will parse the CONNONCE provided in DRDA packet 2226.
4. The CONNONCE is then diversified using the AES-CMAC crypto algorithm, which
is a block cipher encryption.
5. The diversified CONNONCE is then sent to the custom App Token Gen API to
generate the AppToken(APPTKN).
6. Only when the CONNONCE is available, APPTKN will be sent on the DRDA to the
Db2 server.
7. The APPTKN is validated by a customer provided stored procedure on the
server.

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
7
 766364188.docx

8. The implementation of how the APPTKN is generated is left to the client with
source server acting as transport for the value.
9. The APPTKN will be validated by a customer provided stored procedure to
determine if a Trusted Connection should be established. (Logic for validation is
out of scope for JCC driver.)
10. CONNONCE – random 128-bit number. The target server with Security Manager
level 11 will always send back a CONNONCE on ACCSECRD, regardless of
security mechanism used, so it does not need to be requested.
11. AES_CMAC algorithm which uses block cipher encryption is used to diversify
the CONNONCE before it is sent to the customer app token api for generating
the APPTKN.
12. The response from the customer APP Token API implementation will be the
APPTKN that is sent over the DRDA to the server.
13. Once the APPTKN is sent over the DRDA no specific response is expected.
14. The trusted connection is established only when the APPTKN sent over DRDA is
validated at the server via the Trust Procedure provided by the customer.

6 App Token Registration

Java based clients must register the callback programmatically when creating the
trusted connection.

a. Using URL, set the property appTokenGenClassName

com.ibm.db2.jcc.DB2ConnectionPoolDataSource dataSource =

new com.ibm.db2.jcc.DB2ConnectionPoolDataSource();
Object[] objects = new Object[2];

java.util.Properties properties = new java.util.Properties();

//Please note that for property: appTokenGenClassName the value should be mentioned along
// with the package as set below.

properties.setProperty("appTokenGenClassName","apptokengen.CustomDb2AppTokenGen");

objects = dataSource.getDB2TrustedPooledConnection("userid", "password", properties);

appTokenGenClassName is the property key to be used for setting the classname

for the custom App Token API. The class name should have the complete package
and the class should be present in the buildPath of the project.

b. Using datasource

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
8
 766364188.docx

com.ibm.db2.jcc.DB2ConnectionPoolDataSource dataSource =
new com.ibm.db2.jcc.DB2ConnectionPoolDataSource();
Object[] objects = new Object[2];

com.ibm.db2.jcc.DB2AppTokenGen apptokengen = new CustomDb2AppTokenGen();

dataSource.setAppTokenGen(apptokengen);

objects = dataSource.getDB2TrustedPooledConnection("userid", "password", properties);

dataSource.setAppTokenGen(apptokengen) is the API for setting the custom App

Token Object in datasource.

7 SQL queries for Server set up

db2 GRANT CONNECT ON DATABASE TO USER NEWTON1;

db2 GRANT CONNECT ON DATABASE TO USER ZURBIE1;

db2 CREATE SCHEMA MYVARS AUTHORIZATION db2admin;

db2 CREATE OR REPLACE VARIABLE MYVARS.CUSTOM_APPTOKEN VARBINARY(32672);

db2 CREATE OR REPLACE VARIABLE MYVARS.CUSTOM_NONCE VARBINARY(1024);

db2 GRANT CREATEIN, ALTERIN, DROPIN ON SCHEMA MYVARS TO USER NEWTON1;

db2 GRANT CREATEIN, ALTERIN, DROPIN ON SCHEMA MYVARS TO USER ZURBIE1;

db2 GRANT ALL PRIVILEGES ON VARIABLE MYVARS.CUSTOM_APPTOKEN TO NEWTON1;

db2 GRANT ALL PRIVILEGES ON VARIABLE MYVARS.CUSTOM_APPTOKEN TO ZURBIE1;

db2 GRANT ALL PRIVILEGES ON VARIABLE MYVARS.CUSTOM_NONCE TO NEWTON1;

db2 GRANT ALL PRIVILEGES ON VARIABLE MYVARS.CUSTOM_NONCE TO ZURBIE1;

db2 CREATE OR REPLACE PROCEDURE TEST.PROC1()

LANGUAGE SQL BEGIN

DECLARE SQLSTATE CHAR(5) DEFAULT '00000';

DECLARE APPTOKEN_v VARBINARY(32672);

DECLARE APPNONCE_v VARBINARY(1024);

DECLARE TOKENSTR_v VARBINARY(9);

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
9
 766364188.docx

SET TOKENSTR_v = VARBINARY('APPTOKEN_');

VALUES SYSIBM.CLIENT_APPTOKEN INTO APPTOKEN_v;

VALUES SYSIBM.APPTOKEN_NONCE INTO APPNONCE_v;

SET MYVARS.CUSTOM_APPTOKEN = SYSIBM.CLIENT_APPTOKEN;

SET MYVARS.CUSTOM_NONCE = SYSIBM.APPTOKEN_NONCE;

IF APPTOKEN_v IS NOT NULL AND APPNONCE_v IS NOT NULL

AND LOCATE(TOKENSTR_v, APPTOKEN_v) AND LOCATE(APPNONCE_v, APPTOKEN_v)

THEN SIGNAL SQLSTATE value '01H5B';

END IF;

END;

db2 GRANT EXECUTE ON PROCEDURE TEST.PROC1() TO USER NEWTON1;

db2 GRANT EXECUTE ON PROCEDURE TEST.PROC1() TO USER ZURBIE1;

db2 commit;

db2stop force

db2start

8 Create Trusted Context

CREATE TRUSTED CONNECTION name BASED UPON CONNECTION

USING SYSTEM AUTHID authid

ATTRIBUTES ( TRUST_PROC procname … existing trust attributes …) …

The trust_proc will be called for every connect. You cannot replace or drop the
trust_proc while it is in use by an activated database.

The trust_proc procedure will be called prior to connect_proc so that it cannot influence
in any way values that might be used by trust_proc.

For example:
CREATE TRUSTED CONTEXT " +ctname +" BASED UPON CONNECTION USING SYSTEM
AUTHID " +testuser +" ATTRIBUTES (ADDRESS '"+ip+"', TRUST PROCEDURE
TEST.PROC1) ENABLE WITH USE FOR PUBLIC WITH AUTHENTICATION

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
10
 766364188.docx

7. Connectivity
T4 LUW

8. Test Scenarios covered.

S Test Scenario Expected Result Actual Result Comments
l
#
1 Create a Trusted Trusted Connection Trusted connection
connection using URL and should be established successful
then switch user successfully
2 Create a Trusted Trusted Connection Trusted connection
connection using data should be established successful
source and then switch successfully
user
3 Create a Trusted Trusted Connection Trusted connection failed
connection with invalid should not be
APPTKN and then switch established
user successfully

9. Documentation updates.
https://www.ibm.com/docs/en/db2/11.5?topic=pdsdjs-common-data-server-driver-jdbc-
sqlj-properties-all-database-products

appTokenGen

The AppTokenGen feature for SAP audit exception will be available only with security
manager level 11 and above. (DB2 12.1 version onwards).

The DB2 server must have all the necessary set up done before making the trusted
connection call with the app token details as given in the below link.

https://www.ibm.com/docs/en/db2/11.5?topic=statements-create-trusted-context

https://www.ibm.com/docs/en/db2/11.5?topic=connections-trusted-contexts-trusted

https://www.ibm.com/docs/en/db2/11.5?topic=views-configuration-routines

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
11
 766364188.docx

Java based clients must register the callback programmatically when creating the
trusted connection.

a. Using URL, set the property appTokenGenClassName

com.ibm.db2.jcc.DB2ConnectionPoolDataSource dataSource =

new com.ibm.db2.jcc.DB2ConnectionPoolDataSource();
Object[] objects = new Object[2];

java.util.Properties properties = new java.util.Properties();

//Please note that for property: appTokenGenClassName the value should be mentioned along
// with the package as set below.

properties.setProperty("appTokenGenClassName","apptokengen.CustomDb2AppTokenGen");

objects = dataSource.getDB2TrustedPooledConnection("userid", "password", properties);

appTokenGenClassName is the property key to be used for setting the classname

for the custom App Token API. The class name should have the complete package
and the class should be present in the buildPath of the project.

b. Using datasource

com.ibm.db2.jcc.DB2ConnectionPoolDataSource dataSource =
new com.ibm.db2.jcc.DB2ConnectionPoolDataSource();
Object[] objects = new Object[2];

com.ibm.db2.jcc.DB2AppTokenGen apptokengen = new CustomDb2AppTokenGen();

dataSource.setAppTokenGen(apptokengen);

objects = dataSource.getDB2TrustedPooledConnection("userid", "password", properties);

dataSource.setAppTokenGen(apptokengen) is the API for setting the custom App

Token Object in datasource.

© Rocket Software, Inc. or its affiliates 1990–2022. All rights reserved. Rocket and the Rocket Software logos are
registered
trademarks of Rocket Software, Inc. Other product and service names might be trademarks of Rocket Software or
its affiliates.
12