Common Security Content

Shared content amongst the Security library documentation.

Syntax

General Usage

In case of error, the method throws an exception and sets the status variable. Depending on the error, a human-readable description of the problem is available in the sqlca.sqlerrm register. See Error handling in GWS calls (status).

The int_flag variable is checked during GWS API call to handle program interruptions, for more details, see Interruption handling in GWS calls (int_flag)

This method may raise exception -15700 (operation failed) or -15701 (invalid parameter).

Certificates

This command creates a serial file with an initial HEX value 01. OpenSSL uses this file to track the serial numbers of certificates it creates. The serial file is typically given the same name as the CA with the extension .srl.

All keys or certificates in PEM or DER format were created with the OpenSSL tool. For information on how the OpenSSL tool works, refer to the OpenSSL documentation.

Note: About the CSR and its private key:

If you want an official Certificate Authority, you must send the CSR file to one of the self-established Certificate Authority companies on the Internet (instead of creating it with openssl. See Encryption and authentication).
The CSR file is also used to encrypt messages that only its corresponding private key can decrypt.

Follow the instructions to create the CSR. This command creates a pem file containing the private key of the CSR protected by a password. By default, openssl outputs the private key in the privkey.pem file. If you want to specify a different file name, or if your openssl version does not output the private key by default, add -keyout myprivkey.pem to the command.

$ openssl rsa -in privkey.pem -out MyServer.pem

You are prompted for the passphrase. The unprotected private key is output in MyServer.pem.

Distinguishing Name (DN)

Follow the instructions to create the CSR. This command creates a pem file containing the private key of the CSR. The key is encrypted, so you are prompted for a passphrase for it. You will be prompted to identify the subject or issuer of the certificate – to provide a Distinguishing Name (DN) for the certificate – in a series of prompts. These are examples of what the prompts will look like:

Country Name (2 letter code) [AU]:FR
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:.
Organization Name (eg, company) [Internet Widgits Pty Ltd]:.                               
Organizational Unit Name (eg, section) []:.
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:.

The most important field in the DN is the Common Name (CN), which should have the exact Fully Qualified Domain Name (FQDN) of the host that you intend to use the certificate with. For instance, if the URL of the server is https://www.MyServer.com/fastcgi/ws/r/MyWebService, the CN must be www.MyServer.com. In the other fields, you provide additional details about your organization, which may be needed if you are purchasing an SSL certificate from a certificate authority.

The private key file of a root certificate authority must be handled with care because it validates certificates it has signed and it is used in creating future certificates. As a result, it must not be accessible by other users.