ttCreateCerts

The ttCreateCerts utility creates Oracle wallets and certificates that are used when configuring Transport Layer Security (TLS) in TimesTen client/server and replication environments. Oracle wallets and certificates are created manually using ttCreateCerts for client/server TLS communications when you have multiple databases and need different certificates for each, or when you require certificates for both client/server connections and replication.

TimesTen supports several types of certificates, including self-signed certificates. A self-signed certificate is a digital certificate that is created, issued, and digitally signed by itself, rather than by a publicly trusted third-party Certificate Authority (CA). A certificate is self-signed if the issuer's name (who signed it) and the subject's name (who it belongs to) are the same.

The ttCreateCerts utility creates a self-signed root, client, and server certificates and uses the root certificate to sign the server's certificate for both client/server and replication. TimesTen stores the server certificate and self-signed root certificate in a server wallet. In a TimesTen client/server environment, for a client to be able to trust the server certificate, a copy of the self-signed root certificate is needed by the client. The ttCreateCerts utility creates a client wallet and stores the self- signed root certificate in it. See Task 2A: Create Self-Signed Certificates in Oracle TimesTen In-Memory Database Security Guide.

The utility creates three Oracle Wallets: rootWallet, clientWallet, and serverWallet.

Note:

You must have Java JDK or JRE version 8 or higher on your system to use ttCreateCerts. The utility searches for the environment variables JRE_HOME, JAVA_HOME, and the PATH settings.

Required Privilege

This utility requires no privileges. However, depending on the specified options, it may write files to directories that require instance administrator privileges.

Syntax

% ttCreateCerts -h
usage: ttCreateCerts [-dir WALLETDIR] [options...]
       ttCreateCerts [-h | -help]
       ttCreateCerts [-V | -version]
       ttCreateCerts [-showWallet WALLETDIR] [-json]
       ttCreateCerts [-run "ORAPKICOMMAND"]
options:
  -f | -force
  -verbose
  -validity DAYS | -valid_from mm/dd/yyyy -valid_until mm/dd/yyyy
  -dryrun
  -fips140_mode
  -client | -noclient
  -sign_alg  sha256 | sha384 | sha512 | ecdsasha256 | ecdsasha384 | ecdsasha512 
  -asym_alg ECC -eccurve p256 | p384 | p521
  -eccurve p256 | p384 | p521
  -asym_alg RSA -keysize 2048 | 4096
  -keysize  2048 | 4096

Options

The following table shows the supported options for ttCreateCerts. The second column indicates if the option is supported for ECC or RSA keys or both.

Option ECC or RSA Support Description

-dir

Supported for both ECC and RSA

This is an optional parameter. If the -dir parameter is not specified, the wallets are created in the default timesten_home/conf directory.

If the -dir parameter is specified, the wallets are placed in the directory that already exist.

Use the -force option to overwrite, regardless of whether the optional -dir parameter is used.

-h

-help

Supported for both ECC and RSA

Shows help (showing the above syntax).

-v

-V

-version

Supported for both ECC and RSA

Displays the TimesTen release number.

-showWallet WALLETDIR [-json]

Supported for both ECC and RSA

Shows information about the certificate in the specified WALLETDIR directory. If the optional -json parameter is specified, ttCreateCerts displays the output in JSON format.

-run "ORAPKICOMMAND"

Supported for both ECC and RSA

 Runs Oracle's orapki utility with the commands supplied in the parameter to manage Public Key Infrastructure (PKI) elements.

-f

-force

Supported for both ECC and RSA
Overwrites any previous wallets in the specified directory.

Note:

The -force option is ignored when the-run option is used.

-verbose

Supported for both ECC and RSA

Shows additional output from execution of the utility.

-validity

Supported for both ECC and RSA

One of two ways to specify the lifetime of the wallets that are created, expressed as a number of days from creation.

The default is 365 days, which can be overridden by setting either -validity or -valid_from and -valid_until.

-valid_from

-valid_until

Supported for both ECC and RSA

The other way to specify the lifetime of the wallets that are created, expressed as a start and an end date in mm/dd/yyyy format.

-dryrun

Supported for both ECC and RSA

Echoes all the commands to be executed by ttCreateCerts to create the certificates as you specified, but without executing them.

For options you do not set, you can use this to confirm what the default values are.

-fips140_mode

Supported for both ECC and RSA

Instructs ttCreateCerts to use FIPS mode when generating certificates. By default, ttCreateCerts does not run in FIPS mode.

-client | -noclient

Supported for both ECC and RSA
Indicates if ttCreateCerts adds a client certificate to the client wallet.

  • If -client is specified, ttCreateCerts adds a client certificate to the client wallet.

  • If -noclient is specified, ttCreateCerts does not add a client certificate to the client wallet.

The default is -client.

-sign_alg sha256 |sha384 | sha512 |ecdsasha256 | ecdsasha384 | ecdsasha512

Supported for both ECC and RSA

Specifies the signature algorithm used to sign a certificate.

Valid values are as follows:
  • For ECC keys, you must use one of the following elliptic curve signing algorithms:

    • ecdsasha256

    • ecdsasha384

    • ecdsasha512 (default for ECC keys)
  • For RSA keys, you must use one of the following RSA signing algorithms:

    • sha256

    • sha384
    • sha512 (default for RSA keys)

-asym_alg ECC | RSA

Supported for ECC or RSA

This is an optional parameter. If not specified, the default is ECC. The -asym_alg option indicates the asymmetric cryptographic algorithm to use when generating a key pair. Valid values are ECC (default) and RSA. Ensure you use uppercase (for example, ECC or RSA).

The valid -eccurve and -keysize options depend on whether you are using ECC or RSA.

See the Usage Rules section for more information about using the -asym_alg option.

-eccurve p256 | p384 | p521

Supported for ECC
-eccurve option is specific to ECC:

  • Refers to the Elliptic Curve Digital Signature Algorithm (ECDSA), which is a public-key asymmetric cryptographic algorithm that uses math from elliptic curves to create strong digital signatures.

  • If ECC keys and the ECC asymmetric cryptographic algorithm are used to generate certificates, then the -eccurve option is valid. The -eccurve option specifies the curve on which an ECC key is generated.

  • Valid values for -eccurve are p256 or p384 or p521 (default).

-keysize 2048 | 4096

Supported for RSA
keysize option is specific to RSA:

  • RSA refers to a pair of cryptographic keys, a public key and a private key that are used for public-key encryption and digital signatures.

  • If RSA keys and the RSA asymmetric cryptographic algorithm are used to generate certificates, then the -keysize option is valid. The -keysize option sets the key size (expressed in bits) for the RSA key. Supported key sizes are 2048 or 4096 (default).

Usage Rules for ECC and RSA keys

Note the following usage rules:
  • The -asym_alg option specifies which asymmetric cryptographic algorithm to use when generating a key pair.

    • If the algorithm is RSA, you can specify -keysize to set the size of the RSA key to be generated.

    • If the algorithm is ECC (default), you can specify -eccurve to set the ECC curve on which the key is generated.

  • If you do not specify -asym_alg, the following rules apply:

    • If you specify -eccurve and -keysize, the ttCreateCerts utility returns an error.

    • If you only specify -eccurve, ttCreateCerts uses the ECC algorithm.

    • If you only specify -keysize, ttCreateCerts uses the RSA algorithm.

    • If you do not specify -eccurve or -keysize, ttCreateCerts uses the ECC algorithm.

  • If you do not specify -sign_alg, the following rules apply:

    • If the algorithm is ECC (default), the sign_alg defaults to ecdsasha512.

    • If the algorithm is RSA, the sign_alg defaults to sha512.

The ttCreateCerts utility also has a -run option that allows you to run commands of the Oracle orapki utility to manage Public Key Infrastructure (PKI) elements. Place the orapki command in quotes, such as in this example: 

% ttCreateCerts -run "wallet create -wallet serverWallet -auto_login_only"

For more information on the discussion of using certificates signed by a certificate authority, see Task 2B: Create CA-Signed Certificates in Oracle TimesTen In-Memory Database Security Guide.

In addition to using ttCreateCerts manually, you can configure a TimesTen instance for TLS. When you do this, TimesTen runs ttCreateCerts to create Oracle Wallets and certificates for use at the instance level. See ttInstanceCreate.

Examples Illustrating the Use of ECC and RSA

Example 1:

Use the ttCreateCerts utility to create Oracle Wallets and certificates using the RSA asymmetric cryptographic algorithm with a key size of 2048 and a signing algorithm of sha384. This example assumes you have previously created the wallets/rsa subdirectory from a directory of your choice.
$ ttCreateCerts -dir wallets/rsa -asym_alg RSA -keysize 2048 -sign_alg sha384
ttCreateCerts : certificates created in wallets/rsa
Review the directory.
$ ls wallets/rsa
client1.cert  clientWallet  root.cert  rootWallet  server1.cert  serverWallet
Show Oracle Wallet information.
$ ttCreateCerts -showWallet wallets/rsa/rootWallet
NAME                                                        HOLDER          EXPIRATION
wallets/rsa/rootWallet/cwallet.sso                          CN=ecRoot,C=US  Sun Dec 09 12:27:23 UTC 2035
$ ttCreateCerts -showWallet wallets/rsa/serverWallet
NAME                                                          HOLDER           EXPIRATION
wallets/rsa/serverWallet/cwallet.sso                          CN=server1,C=US  Sun Dec 09 12:27:32 UTC 2035
$ ttCreateCerts -showWallet wallets/rsa/clientWallet
NAME                                                          HOLDER           EXPIRATION
wallets/rsa/clientWallet/cwallet.sso                          CN=client1,C=US  Sun Dec 09 12:27:40 UTC 2035

Additional Examples

This section provides ttCreateCerts examples that place the wallets in a wallets subdirectory under timesten_home/conf, where timesten_home is the full path to the TimesTen instance home directory.

The following example includes verbose output. (Without the -verbose option, only the last line is shown.) 

% ttCreateCerts -verbose -dir timesten_home/conf/wallets
Requested Certificates:
User Certificates:
Subject:        CN=server1,C=US
Trusted Certificates:
Subject:        CN=ecRoot,C=US
Requested Certificates:
User Certificates:
Subject:        CN=client1,C=US
Trusted Certificates:
Subject:        CN=ecRoot,C=US
ttCreateCerts : certificates created in timesten_home/conf/wallets

Here are the results. The contents of clientWallet and serverWallet are used. 

% ls timesten_home/conf/wallets
client1.cert  clientWallet  cwallet.sso root.cert  rootWallet  server1.cert  serverWallet
% ls timesten_home/conf/wallets/clientWallet
cwallet.sso
% ls timesten_home/conf/wallets/serverWallet
cwallet.sso

The next example is a dry run. No certificates are created (despite the last line). This shows only the default values:

% ttCreateCerts -dir timesten_home/conf/wallets -dryrun
...
+ /usr/dev_infra/platform/bin/java -d64 -Djava.security.egd=file:///dev/./urandom -cp 
/scratch/myinstance/install/lib/cryptoj.jar:/scratch/myinstance/install/lib/oraclepki.jar oracle.security.pki.textui.OraclePKITextUI 
wallet create -wallet rootWallet -auto_login_only -nologo
/scratch/myinstance/install/lib/cryptoj.jar:/scratch/myinstance/install/lib/oraclepki.jar oracle.security.pki.textui.OraclePKITextUI 
wallet add -wallet rootWallet -dn CN=ecRoot,C=US -sign_alg ecdsasha512 -self_signed -asym_alg ECC -eccurve p521 -jsafe -validity 365 -auto_login_only -nologo
/scratch/myinstance/install/lib/cryptoj.jar:/scratch/myinstance/install/lib/oraclepki.jar oracle.security.pki.textui.OraclePKITextUI 
wallet export -wallet rootWallet -dn CN=ecRoot,C=US -cert root.cert -jsafe -nologo
...
ttCreateCerts : certificates created in timesten_home/conf/wallets

The default settings are -sign_alg ecdsasha512, -asym_alg ECC, -eccurve p521, and -validity 365 (days).

Here is another example that sets signing algorithm ECC and the size of the elliptical curve:

% ttCreateCerts -dir timesten_home/conf/wallets -sign_alg ecdsasha256 
-eccurve p256
ttCreateCerts : certificates created in timesten_home/conf/wallets

This example specifies that the certificates will expire one year from when they were created:

% ttCreateCerts -dir timesten_home/conf/wallets -validity 365
ttCreateCerts : certificates created in timesten_home/conf/wallets

Or, equivalently:

% ttCreateCerts -dir timesten_home/conf/wallets -valid_from 01/28/2025 
-valid_until 01/28/2026
ttCreateCerts : certificates created in timesten_home/conf/wallets

This example tries to create wallets in a location where wallets already exist:

% ttCreateCerts -dir timesten_home/conf/wallets
ttCreateCerts: wallets is not empty, use -force to overwrite

This example shows how to try again using the -force option: 

% ttCreateCerts -dir timesten_home/conf/wallets -f
ttCreateCerts : certificates created in timesten_home/conf/wallets