1. PKI & Web Services
SPS Spotlight Series
January 2015

2. NOTE: This information was originally created for The SPS Spotlight Series project, which ran from November through November 2015.  Updates to the original content may be incorporated to ensure accuracy. If you have any questions about this information, please contact the SPS Help Desk at

3. Overview Enhancement Overview Definitions Logging in with PKI
Sybase/PD² Passwords
Updates to sql.ini files
PD² Client Information
Sybase Web Services Information
Java Keystore & Certificates
HTTP, HTTPS and Tectia
HTTPS Configuration – Server side & Client side

4. Enhancement Overview
Beginning with the release of PD² v4.2 Incr 2 SR15, the PD² client software is now Public Key-enabled (PKE) for authentication of users to the underlying Sybase Adaptive Server Enterprise (ASE) database server.
For sites deploying SR15, individual use of a Common Access Card (CAC) to uniquely identify an SPS user should be enforced through local policy and standard operating procedures.
Non-CAC users continue to use the traditional user name/password login functionality.

5. Definitions Sybase Web Services (aka ws)
New web services service name (ex: SPS_HD_ASE15_WS)
PD² Sybase Adaptive Service
PD² Sybase service name (ex: SPS_HD_ASE15)
Producer Port
Port used to communicate between a client (e.g., PD² application) and Web Services.
Consumer Port
Port used to communicate between the Web Services and the Sybase ASE server

6. Definitions continued
wsOwner
Sybase login name
Used in the pkidod.pbd file to communicate between client and Web Services
New Script-Aid script updates this user’s Password Expiration interval
PasswordGenerator.exe is used to update and encrypt this password in the pkidod.pbd file
saws
Used to start/stop Web Services
Encrypted password is stored in SPS_<DODAAC>_WS_setenv.bat file
First change password in ASE using sp_password
Then use sps_update_pwd.bat to encrypt password

7. CAC Login Functional Steps
Insert CAC into machine.
Launch PD² application.
Select Login with CAC button.
System detects certificates associated with CAC.
CAC certificate is checked for validity to ensure that it is an X certificate, is readable, and is active.
If this is the user’s first CAC login, user is prompted to enter PD² User ID/password.
System will perform the CAC self registration process.
Subsequent logins by the user will use CAC credentials and will not prompt for PD² User ID/password.

8. CAC Login Functional Steps (continued)
Once registered with CAC, PD² users will be no longer be able to use traditional PD² User ID/password.
If a user receives a new CAC, the PD² sysadmin will deregister the user and reset the user’s password so the user may re- register with the new CAC.
The new password will only be used once, to re-register the new CAC.
Users who will not use CAC based authentication for accessing PD² will continue to use their traditional User ID/password to log in to the PD² client application.

9. Traditional Login vs CAC Login Method
Username
password
PD² Client
Sybase Server
CAC
Credentials
Web Services
Server
Username
password
PD² Client
Sybase Server

10. PD² Logon Window
The logon window has changed in SR15. There are now 2 ways to login to PD.
The traditional User ID/password option.
Logging in with CAC

11. PKI Login – CAC Registration – Database Logon Window
For users who decided to use the CAC option, the first time the Logon with CAC button is clicked, the user will be prompted to register their CAC information.
The following window will appear, where the user will enter their PD² login credentials to register as a CAC user.
Again, this is only required for first CAC login or re-registering a CAC login.

12. PKI Login – Select a Certificate Window
The Select a Certificate window will appear each time the user logs into PD² using the CAC option.
These certificates are setup by the System Administrator.

13. System Administration User Task for non-CAC user

14. System Administration User Task for CAC user
Deregister User button replaces Change Password fields for CAC users.

15. Deregistration of a user
Once the Deregister User button is clicked the following window opens.
The SA will assign the user a temporary password, which they will use when they re-register their new CAC.
Deregistered users will not be able to log in using the traditional method and must re-register as a CAC user.
MOTTO: Once you go CAC you can’t go back!

16. Deregistration of a user continued
Once a user gets the new temporary password, they still cannot login to PD² using the traditional method. Any attempt to use the standard User ID/Password process with the temporary password will result in the following error message:

17. Sybase/PD² Passwords
When a PD² user registers a CAC, the PD² user automatically gets a new random password and the Sybase login’s password is set to never expire.  The PD² application will change the password periodically based on the current expiration policy divided by 2. 
Example: the password expiration policy is 60 days, then the PD² app will change the password to another random password every 30 days. 
The CAC user won’t be able to change his/her own password because no one knows what the random password is, and the PD² application does not provide the change password function for CAC users.
A Sybase login with sso_role can change the CAC user’s password using sp_password function.  That will be OK as the new password is encrypted using the user’s public key and PKI would be able to pick that up.
The user will then be able to use that password for other utilities, until the PD² app changes the password again.  CAC logins are still subject to 3 failed login attempts before locked.

18. Sybase/PD² Passwords continued
Ideally, the PD² user should be registered with CAC if:
The PD² user is not shared (e.g., sysadmin).
The PD² user is only used within PD².  The PD² user should not be used for other non-PD² applications, such as external reporting tools, Integrity tools, or Script-Aid.  
Script-Aid only requires a Sybase login, not PD² login.
PKI does not affect non-PD² users, such as Doc Transfer, Archiving, Adapter, sa, MWS, etc.
For other Sybase logins that are not used for PKI (CAC associated PD² users), it’s business as usual.
General note: All PD² users are Sybase users but not all Sybase users are PD² users . PKI only affects PD² users.

19. Web Services Communication Information

20. Sybase Web Services Information
When the Web Services gets installed a new folder under the \Sybase15 directory gets created. This folder name will be WS-15_0.
Subfolders include:
Bin
SPS_<DODAAC>_ASE15_WS_setenv.bat file
sps_update_pwd.bat
Encrypts the Web Services password.
Logs
commons-daemon.<datetimestamp>.log
[ :25:48] [info] [ 1516] Service started in 1328 ms.
SPS_<DODAAC>_WS_https.log
SPS_<DODAAC>_WS_webservices.log
Props
SPS_<DODAAC>_ASE15_WS.properties
This message usually indicates that the Web Services has started successfully.

21. Sybase Web Services Information continued
A test can be performed to verify if the Web Services is fully started. By opening a web browser and entering in the following information.
webpage
(ex:
If the page is able to be displayed, web services is fully started.
Notice that we are using the Producer Port.

22. Updates to sql.ini files
On the Sybase Server, in the \Sybase15\ini directory, the sql.ini file needs to be updated to include the new Web Services information.
[SPS_HD_ASE15_WS]
master=NLWNSCK, ,8173
query=NLWNSCK, ,8173
On the PD² Client side, in the \Program Files (x86)\Sybase\ini directory, the sql.ini file needs to be updated to include the new Web Services information.
[SYB_SERVER]
query=TCP, ,5970
master=TCP, ,5970
webservice=http, ,8171
Note the port values are different: Consumer on Sybase server; Producer on Client.

23. PD² Client Information
pkidod.pbd file
\Program Files (x86)\PD²\BIN
Must exist on all client machines
Must be up-to-date with the correct web services password for the wsOwner login.
See KB ID: for error messages if not up-to-date
One-to-one connection
One pkidod.pbd file to one Sybase server. If users are logging into multiple servers, the file must be switched accordingly

24. PD² Client Information continued
Web Services Connection User Password Change Utility
If the wsOwner’s password ever has to be updated in Sybase Central, the PasswordGenerator.exe will need to be run.
Updates & encrypts the wsOwner’s password value in the pkidod.pbd file
Creates a back-up copy of the pkidod.pbd file each time it is run
New pkidod.pbd file must then be transferred to every client machine, failure to do so will cause issues when trying to login with CAC.

25. Java Keystore & Certificates
The Sybase Web Services uses the Java Key Store (JKS) technology to access the server certificate for HTTPS. The server certificate is an X.509 certificate and has public and private key pair stored in the JKS-based keystore. The server certificate and the JKS-based keystore generation processes are dependent on the certificate tools employed by the site.
The keystore must meet the following criteria:
Compatible with Java 7
The keystore has a keystore password (storepass). This password is required when configuring the Sybase Web Services to access the keystore.
The keystore has a password for the server key (keypass). This password is required when configuring the Sybase Web Services to access the private key of the server certificate in the keystore.
The server key entry is stored in the keystore under the “ws” alias (without quotes; both letters are in lower-case).
The CA certificates (root and intermediate) in the certificate chain of the server certificate are stored as trusted certificates in the keystore.

26. Java Keystore Knowledge Base articles
KB ID: JKS-based Keystore for Sybase Web Services FAQs
KB ID: What is a keystore for Sybase Web Services?
KB ID: What is the process of generating the JKS-based keystore?
KB ID: Is there an example for generating the JKS-based keystore on a Windows- based system?
KB ID: Is there an example for generating the JKS-based keystore on a UNIX system?
KB ID: Generating the JKS-based keystore on a Windows-based system.
KB ID: Generating the JKS-based keystore on a UNIX system
KB ID: 15211
Error #1: Error 7: Unresolvable external u_dod_pki_vars when linking reference at line 21 in function uf_ztrieve_pwd of object u_dsk_pki_authentication.
Error #2: Error 2: Unable to establish communications with web services error message.

27. HTTP, HTTPS and Tectia
HTTP is simpler to configure, but it does not encrypt communication between the Sybase Web Services and PD² client. Encryption may be done by other tools, such as SSH Tectia.
HTTPS is more secure, encrypting communication between the Sybase Web Services and PD² client. However, additional preparations are required on both database server and PD² client machines.
Is SSH Tectia enabled on the database server and client machines?
Does network traffic between the database server and client machine pass through a proxy server?
Communication between the Sybase Web Services and PD² client in HTTP and HTTPS No
HTTP: in clear HTTPS: encrypted
Yes
HTTP: encrypted HTTPS: encrypted

28. Traditional Login vs CAC Login Method with HTTPS
Username
password
PD² Client
Sybase Server
HTTPS
CAC
Credentials
Web Services
Server
Username
password
PD² Client
Sybase Server

29. HTTPS Configuration – Server side
Details are in Section 6 of the Sybase ASE 15.7 SP102 Web Services Configuration Guide.
The keystore file is named <WSNAME>.keystore, where <WSNAME> is the Web Services name. Ex: SPS_DODAAC_ASE15_WS.keystore.
The keystore file is located \Sybase15\WS-15_0\props.
The Sybase Web Services is configured to use a server certificate that is properly stored on the Sybase server.
\Sybase15\Shared\JavaKeyStore
Ex: _wi2hddb01x64.caci.com
The Sybase Web Services HTTPS Configuration Utility is needed to configure the Sybase Web Services for HTTPS support. This utility updates the Web Services properties file with HTTPS information.
SPS_<DODAAC>_ASE15_WS.properties file gets updated with keystore information at the bottom of the file.

30. HTTPS Configuration – Client side
Section 6.3 Configure Client Machine Certificate Store in the guide.
The client machine where the PD² Client is installed has the proper Certificate Authority (CA) certificate imported in order to validate the server certificate.
When the PD² Client initiates the communication with the Sybase Web Services using the HTTPS protocol, the server certificate must be validated. If the server certificate cannot be validated, the “Certificate Error” error occurs when using the PKI functionality in PD². To ensure the success of the validation process, the client machine must import the root CA certificate that is included in the certificate chain of the server certificate.
In the sql.ini file, the protocol needs to be changed from http to https and the port number must be updated to the HTTPS port if it is different from the original HTTP port.
From: webservice=http, ,8171
To: webservice=https, ,443