The tarantella security Command

Controls SGD security services and manages server certificates.

Syntax

tarantella security certinfo | certrequest | certuse | customca |
decryptkey | disable | enable | fingerprint | peerca | selfsign |
start | stop

Description

The following table shows the available subcommands for this command.

Subcommand Description More Information certinfo Displays information about an SSL certificate or Certificate Signing Request (CSR), and optionally checks whether a specified private key matches the public key contained in a particular SSL certificate. tarantella security certinfo certrequest Creates a CSR and a corresponding key pair, which you use to obtain an SSL certificate for use with SGD security services. tarantella security certrequest certuse Installs an SSL certificate, or specifies the location of an installed certificate, for use with SGD security services. tarantella security certuse customca Installs a root certificate for a custom CA for use with SGD security services. tarantella security customca decryptkey Decrypts an encrypted private key so that you can use it with SGD. tarantella security decryptkey disable If an SGD server has been secured using the tarantella security enable command, restores the security settings to their previous state. tarantella security disable enable Makes an SGD server secure. tarantella security enable fingerprint Displays the fingerprint of the CA certificate installed on the SGD server. tarantella security fingerprint peerca Shows, imports, or exports the primary server’s CA certificate used for secure intra-array communication. tarantella security peerca selfsign Generates and installs a self-signed server SSL certificate. tarantella security selfsign start Enables secure (SSL) connections. Users who require secure connections are given them. tarantella security start stop Disables secure (SSL) connections. Users configured for secure connections are given standard connections instead. tarantella security stop

Examples

The following example displays information about a CSR in /tmp/boston.csr.

# tarantella security certinfo --csrfile /tmp/boston.csr

The following example decrypts the key /opt/keys/key1, which is stored in Definite Encoding Rules (DER) format, placing the decrypted key in /opt/keys/key2.

# tarantella security decryptkey \
  --enckey /opt/keys/key1 \
  --deckey /opt/keys/key2 \
  --format DER

tarantella security certinfo

Displays information about an installed SSL certificate (--certfile) or a Certificate Signing Request (--csrfile).

Syntax

tarantella security certinfo
                           [ --certfile certfile [ --keyfile keyfile ] ]
                           [ --full ]

tarantella security certinfo --csrfile csrfile [ --full ]

Description

This command can also check whether a specified private key matches the public key in a particular SSL certificate. In other words, the public key can decrypt text encrypted with the private key.

Use the first form of this command without specifying a certfile and keyfile to check the key and SSL certificate installed using the tarantella security certuse command.

The following table shows the available options for this command.

Option Description --certfile Specifies the location of a file containing a server SSL certificate. The command displays information about this certificate, including the following: Information about the server and your organization. Alternative DNS names for the server. Credentials of the CA that validated the server SSL certificate. Dates for which the SSL certificate is valid. If you omit --certfile, the command displays information about the SSL certificate and key installed in the /opt/tarantella/var/tsp directory. You must specify the full path to the SSL certificate file. --keyfile Specifies the location of a private key. The command checks whether a private key matches the public key contained in the SSL certificate file. You must specify the full path to the key file. --csrfile Specifies the location of a file containing a CSR. The command displays information about this CSR, including the following: The DNS name, or chosen common name, of the server the CSR is for. Alternative DNS names for the server. Your organization’s name and location. You must specify the full path to the CSR file. --full Displays more detailed information about the specified SSL certificate or CSR, for example, the contents of the public keys they contain.

Examples

The following example displays detailed information about the SSL certificate in the /opt/certs/newyork.cert file.

# tarantella security certinfo \
--certfile /opt/certs/newyork.cert \
--full

The following example displays information about the SSL certificate in /opt/certs/boston.cert, and checks that the private key /opt/keys/boston.key matches the public key contained in that SSL certificate.

# tarantella security certinfo \
--certfile /opt/certs/boston.cert \
--keyfile /opt/keys/boston.key

The following example displays information about the CSR in /tmp/boston.csr.

# tarantella security certinfo \
--csrfile /tmp/boston.csr

tarantella security certrequest

Generates a CSR, and a public and private key pair.

Syntax

tarantella security certrequest --country country
                                --state state
                                --orgname org
                              [ --ouname ou ] 
                              [ --email email ] 
                              [ --locality locality ] 
                              [ --keylength length ]

Description

You send the generated CSR to a supported CA to obtain an SSL certificate for use with SGD security services.

Note the following:

• If your CA lets you change the host name stored in the SSL certificate, make sure the SSL certificate contains a fully qualified DNS name. For example, boston.indigo-insurance.com, not boston.

• If the SGD server has multiple DNS names, for example, it is known by different names inside and outside a firewall, you can specify the additional DNS names as subject alternative names for the SSL certificate. This enables you to associate more than one DNS name with the SSL certificate.

• Make a copy of the private key and CSR generated by this command and keep them in a safe, secure location. Key information is stored in the /opt/tarantella/var/tsp directory. If your private key is lost or damaged, you will be unable to use any SSL certificate you obtain using the CSR.

• This command generates a new CSR and key pair each time you run it. If you generate a new CSR with this command, the previous CSR is overwritten and the new private key is stored in the file /opt/tarantella/var/tsp/key.pending.pem.

You can use the tarantella security certinfo command to display information about SSL certificates and CSRs.

If you do not specify --ouname, --email or --locality SGD omits that information from the CSR. There are no default values.

The options that can be used for this command are as follows.

Option Description --country Specifies the country where your organization is located. Use ISO 3166 country codes. For example, use US for the United States or DE for Germany. --state Specifies the state or province where your organization is located. Do not use abbreviations here. For example, use Massachusetts rather than Mass. or MA. --orgname Specifies the official, legal name of your organization. --ouname Specifies the name of a organizational unit (OU) within your organization, if required. If you do not need to specify an OU, you can use this setting to specify a less formal organization name. --email Specifies your business email address. This address is used for correspondence between you and the CA you send the CSR to. --locality Specifies the city or principality where your organization is located, if needed. --keylength Specifies the length of the key pair. The default is 1024.

Examples

The following example generates a CSR for Indigo Insurance, located in Massachusetts, with contact Bill Orange.

# tarantella security certrequest \
--country US \
--state MA \
--orgname "Indigo Insurance" \
--email "orange@indigo-insurance.com"

tarantella security certuse

Installs a server SSL certificate, or specifies the location of a previously installed SSL certificate, to be used by SGD security services.

Syntax

tarantella security certuse

tarantella security certuse --certfile cfile [ --keyfile kfile ]

Description

SSL certificates must be Base 64-encoded Privacy Enhanced Mail (PEM) format, with a header line including "BEGIN CERTIFICATE", as used by OpenSSL.

If no arguments are specified, this command reads the SSL certificate from standard input and installs it in /opt/tarantella/var/tsp.

After installing an SSL certificate, you must restart SGD using the tarantella restart command.

The following table shows the available options for this command.

Option Description --certfile Specifies the location of a file containing the SSL certificate. If no --keyfile argument is specified, SGD assumes that the tarantella security certrequest command was used to generate the private key. You can use this option as follows: To tell SGD about an SSL certificate you have already installed for use with another product, such as a web server. In this case, SGD makes symbolic links to, not copies of, the SSL certificate file and key file, if specified. To install an SSL certificate received from a CA after generating a CSR using tarantella security certrequest. In this case, SGD installs the SSL certificate in /opt/tarantella/var/tsp for use with SGD security services. You must specify the full path to the SSL certificate file. --keyfile Specifies the location of a file containing the private key for the SSL certificate specified by --certfile. Use this option to tell SGD about a private key you have already. If you used the tarantella security certrequest command to generate a CSR and obtain an SSL certificate, you do not need to use this option. You must specify the full path to the key file.

Examples

The following command installs an SSL certificate, which is saved in a temporary file /tmp/cert, and uses the private key generated when the tarantella security certrequest command was used to generate the CSR:

# tarantella security certuse < /tmp/cert

The following command installs an SSL certificate, which is stored in /opt/certs/cert, and a private key, which is stored in /opt/keys/key. The tarantella security certrequest command was not used to generate the CSR.

# tarantella security certuse \
--certfile /opt/certs/cert \
--keyfile /opt/keys/key

tarantella security customca

Installs or removes a root certificate for a custom CA for use with SGD security services.

Syntax

tarantella security customca

tarantella security customca --rootfile carootfile | --remove

Description

CA certificates must be Base 64-encoded PEM-format, with a header line including "BEGIN CERTIFICATE", as used by OpenSSL.

If no arguments are specified, this command reads the root certificate from standard input.

The following table shows the available options for this command.

Option Description --rootfile Specifies the location of a file containing the CA’s root certificate. Details are copied to /opt/tarantella/var/tsp for use by SGD security services. You must specify the full path to the root certificate file. --remove Removes any custom CA’s root certificate currently installed for use with SGD security services.

This command also imports the CA certificate into the CA certificate truststore for the SGD server. This is the /opt/tarantella/bin/jre/lib/security/cacerts file.

Examples

The following example installs a CA’s root certificate from the file/tmp/rootcert, which you can then delete.

# tarantella security customca --rootfile /tmp/rootcert

tarantella security decryptkey

Decrypts an encrypted private key so that you can use it with SGD. This enables you to use an SSL certificate that you are already using with another product such as a web server, rather than obtaining a separate SSL certificate for use exclusively with SGD.

Syntax

tarantella security decryptkey --enckey enckeyfile
                               --deckey deckeyfile
                             [ --format PEM|DER ]

Description

The following table shows the available options for this command.

Option Description --enckey Specifies the location of the encrypted private key that you want to decrypt. Only keys encrypted by a product that uses SSLeay or OpenSSL certificate libraries can be decrypted. You must specify the full path to the encrypted private key file. --deckey Specifies a file where the decrypted key is stored. Note - For security reasons, it is very important to restrict access to private keys, especially when stored in an unencrypted form. Access to private keys by unauthorized users can result in a serious security breach. Store private keys accordingly. You must specify the full path to the decrypted key file. --format Specifies the format the encrypted key is stored in. Defaults to PEM.

See the tarantella security certuse command for information about how to share server SSL certificates in this way.

Examples

The following example decrypts the key /opt/keys/key1, which is stored in DER format, placing the decrypted key in /opt/keys/key2.

# tarantella security decryptkey \
--enckey /opt/keys/key1 \
--deckey /opt/keys/key2 \
--format DER

tarantella security disable

If an SGD server has been secured using the tarantella security enable command, this command restores the security settings to their previous state.

Syntax

tarantella security disable

Description

Use this command to disable security services for an SGD server.

The following limitations apply for this command:

• Automatic security configurations only. Only use this command if you used the tarantella security enable command to enable security automatically on the SGD host. See tarantella security enable for more details.

• Standalone servers only. The SGD server must not be joined with other SGD servers in an array. If the SGD server is a member of an array, detach the SGD server from the array before using this command.

The command restores the security settings of an SGD server to their previous non-secure state. Any server SSL certificates or CA certificates are not removed.

Examples

The following example disables security services for an SGD server.

# tarantella security disable

tarantella security enable

Makes an SGD server secure.

Syntax

tarantella security enable

tarantella security enable --certfile cfile
                         [ --keyfile kfile ]
                         [ --rootfile carootfile ]
                         [ --firewalltraversal on|off ]

Description

Use this command to secure an SGD server.

The following limitations apply for this command:

• New installations only. The SGD installation must be a fresh installation and there has been no attempt to configure SGD security services.

• Standalone servers only. The SGD server must not be joined with other SGD servers in an array. If the SGD server is a member of an array, detach the SGD server from the array before using this command.

Use the --certfile option to specify a server SSL certificate to install. Certificates must be Base 64-encoded PEM-format, with a header line including "BEGIN CERTIFICATE", as used by OpenSSL.

If you omit the --certfile option, this command generates and installs a self-signed server SSL certificate. Only use self-signed server SSL certificates for test purposes.

If you use the --certfile option and the --keyfile option together, SGD creates symbolic links to the specified SSL certificate and key files.

Use the --rootfile option to install the CA certificate if the SSL certificate is signed by an unsupported CA. This option also imports the CA certificate into the CA certificate truststore for the SGD server. This is the /opt/tarantella/bin/jre/lib/security/cacerts file.

Use the --firewalltraversal option to enable or disable the SGD server for firewall traversal. SGD servers configured for firewall traversal cannot be used with the SGD Gateway.

If you have attempted to configure security previously, the tarantella security enable command has no effect. The command exits with an error message, indicating that security settings have been modified previously.

Ensure that the SGD server is running before you use this command. You can use the tarantella status command to show the current status of an SGD server.

The following table shows the available options for this command.

Option Description --certfile Specifies the location of a file containing the SSL certificate. You must specify the full path to the SSL certificate file. --keyfile Specifies the location of a file containing the private key for the SSL certificate specified by --certfile. Use this option to tell SGD about a private key you have already. If you used the tarantella security certrequest command to generate a CSR and obtain an SSL certificate, you do not need to use this option. You must specify the full path to the key file. --rootfile Specifies the location of a file containing the CA’s root certificate. Details are copied to /opt/tarantella/var/tsp for use by SGD security services. You must specify the full path to the CA root certificate file. --firewalltraversal Configures the SGD server for firewall traversal. If you do not specify this option, firewall traversal is enabled by default.

If you use this command to secure an SGD server, the tarantella security disable command can be used to restore the security settings to their previous state.

Examples

The following example secures the SGD server, installs the specified SSL certificate, and uses the private key generated when the tarantella security certrequest command was used to generate a CSR:

# tarantella security enable \
--certfile /opt/certs/cert

The following example secures the SGD server, and installs the specified SSL certificate and private key. A CA root certificate is also installed. The tarantella security certrequest command was not used to generate a CSR.

# tarantella security enable \
--certfile /opt/certs/cert \
--keyfile /opt/keys/key \
--rootfile /tmp/rootcert

The following example secures the SGD server and installs a self-signed SSL certificate. Firewall traversal is not enabled for the SGD server.

# tarantella security enable \
--firewalltraversal off

tarantella security fingerprint

Displays the fingerprint of the CA certificate installed on the SGD server.

Syntax

tarantella security fingerprint

Description

This command displays the fingerprint of the CA certificate installed using the tarantella security customca command.

If the SSL certificate for an SGD server is signed by a supported CA, you do not need to install a CA certificate.

If a server SSL certificate is not installed on the SGD server, this command shows the fingerprint of the built-in SGD CA certificate

Examples

The following example displays the fingerprint of the CA certificate installed on the SGD server.

# tarantella security fingerprint

tarantella security peerca

Shows, imports or exports the primary server’s CA certificate used for secure intra-array communication.

Syntax

tarantella security peerca [ --show | --import hostname | --export ]

Description

The following table shows the available options for this command.

Option Description --show Displays the primary server’s CA certificate for the array. --import Import the CA certificate from the specified server. --export Export the CA certificate from this server.

Examples

The following example shows the primary server’s CA certificate for the array.

# tarantella security peerca --show

tarantella security selfsign

Generates and installs a self-signed server SSL certificate.

Syntax

tarantella security selfsign

Description

Generates and installs a self-signed server SSL certificate. You must run the tarantella security certrequest command before using this command.

Only use self-signed server SSL certificates in a test environment because self-signed SSL certificates are not truly secure. While a self-signed server SSL certificate can be used to give users secure connections, users have no guarantee that the server they are connecting to is genuine. Self-signed certificates are valid for 365 days.

Examples

The following example generates and installs a self-signed server SSL certificate.

# tarantella security selfsign

tarantella security start

Starts security services on the SGD server where the command is run. Secure (SSL-based) connections are given to those users configured to require them.

Syntax

tarantella security start

Description

To enable secure connections to a particular SGD server you must already have installed an SSL certificate for that server.

Secure connections are enabled for the SGD server where the command is run.

Ensure that the SGD server is running before you use this command. You can use the tarantella status command to show the current status of an SGD server.

Examples

The following example enables secure connections for the SGD server where the command is run.

# tarantella security start

tarantella security stop

Disables security services on the SGD server where the command is run. Users configured to require secure (SSL-based) connections are given standard connections instead, if available.

Syntax

tarantella security stop [ --keep ]

Description

The following table shows the available options for this command.

Option Description --keep Specifies that any existing secure connections are preserved. If omitted, all secure connections are closed.

If you run the command without any options, secure connections are disabled for the SGD server where the command is run.

Examples

The following example disables security services for the SGD server where the command is run, but preserves any existing secure connections.

# tarantella security stop --keep