Skip Headers
Oracle® Key Manager 3 Administration Guide
Release 3.0
E41579-02
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

12 Command Line Utilities

This chapter describes command line utilities that allow users to launch backups, export keys, import keys, and list data units from the command line instead of from the OKM Manager GUI.

The following command line utilities are available:


Note:

The OKM Command Line utility supersedes the Backup Command Line utility. Oracle recommends you use the OKM Command Line utility whenever possible.

OKM Command Line Utility

The OKM Command Line utility allows you to:

  • Schedule automated backups

  • Back up OKM core security

  • Import and export keys

  • Destroy keys

  • List audit events

  • List data units

  • Create or modify multiple agents.

Unlike the Backup Command Line utility, this utility can use X.509 certificates to authenticate itself as a valid OKM user instead of a username and passphrase, so you are not required to enter a passphrase on the command line.

The following table details the roles that can perform these functions:

Table 12-1 OKM Command Line Utility - User Role Access

Action: Role:

Backup

Backup Operator

Back up OKM Core Security

Security Officer

Import/Export Keys

Operator

Destroy Keys

Operator

List Audit Events

All RolesFoot 1 

List Data Units

Operator/Compliance Officer

Create Agents

Operator

Set/Change Agent Default Key Group

Compliance Officer

Change Agent Properties

Operator

List Agents

Operator/Compliance Officer


Footnote 1 If you specify agent IDs, data unit IDs, or key IDs, you must have the Operator or Compliance Officer role.

This utility is installed with the OKM Manager GUI using the same installer.


Note:

If you want to enter link-local IPv6 addresses, invoke the OKM Command Line Utility and specify the link-local IPv6 address. Include the Zone ID (for example, ”%4”) at the end of the address. Refer to "IPv6 Addresses with Zone IDs" to see what steps you must follow for the initial setup.

If you are using Solaris, and wish to specify or display characters than cannot be represented in ASCII, then ensure that the appropriate Solaris locale has been installed on your Solaris system and then your environment has been configured to use this locale. Refer to the Solaris locale(1) and localeadm(1M) man pages for more information.


Solaris/Windows1 Syntax

okm -v | --version | --help | -h
okm backup [ [ [ --cacert=filename ] [ --usercert=filename ] ]
               [ --directory=dirname ] ] | --oper=username 
               [ --retries=retries ] [ --timeout=timeout ]
               [ --verbose=boolean ]
                 --kma=networkaddress 
                 --output=dirname 
okm backupcs [ [ [ --cacert=filename ] [ --usercert=filename ]]
                 [ --directory=dirname ] | --oper=username ]
                 [ --retries=retries ] [ --timeout=timeout ]
                 [ --verbose=boolean ]
                   --kma=networkaddress 
okm createagent[ [ [ --cacert=filename ] [ --usercert=filename ] ]
                   [ --directory=dirname ] | --oper=username ]
                   [ --retries=retries ] [ --timeout=timeout ]
                   [ --verbose=boolean ]
                   [ --description=description ] 
                   [ --site=siteid ]
                   [ --keygroup=defaultkeygroupid ]
                   [ --onetimepassphrase=boolean ]
                     --kma=networkaddress 
                     --agent=agentid 
                     --passphrase=agentpassphrase
okm currload [ [ [ --cacert=filename ] [ --usercert=filename ] ]
                 [ --directory=dirname ] ] | --oper=username
                 [ --retries=retries ] [ --timeout=timeout ]
               [ --verbose=boolean ]
                 --output=filename 
                 --kma=networkaddress
okm destroykeys [ [ [ --cacert=filename ] [ --usercert=filename ] ]
                    [ --directory=dirname ] | --oper=username ]
                    [ --retries=retries ] [ --timeout=timeout ]
                    [ --verbose=boolean ]
                      --kma=networkaddress 
                      --duids=filename | --all=true
                      --keystate=keystate 
                      --comment="text"
okm export [ [ [ --cacert=filename ] [ --usercert=filename ] ]
               [ --directory=dirname ] | --oper=username ]
               [ --retries=retries ] [ --timeout=timeout ]
               [ --listwait=waittime ] [ --verbose=boolean ]
                 --filter=filter | --duids=filename 
                 --kma=networkaddress 
                 --output=filename 
                 --partner=transferpartnerid 
okm import [ [ [ --cacert=filename ] [ --usercert=filename ] ]
               [ --directory=dirname ] ] | --oper=username 
               [ --retries=retries ] [ --timeout=timeout ]
               [ --verbose=boolean ]
               [ --overrideeuiconflict=boolean ]
                 --kma=networkaddress 
                 --input=filename 
                 --partner=transferpartnerid 
                 --keygroup=keygroupid 
okm listagentperformance [ [ [ --cacert=filename ] [ --usercert=filename ] ]
                             [ --directory=dirname ] | --oper=username ]
                             [ --filter=filter ]
                             [ --retries=retries ] [ --timeout=timeout ]
                             [ --listwait=waittime ] [ --verbose=boolean ]
                             [ --output=filename ]
                             [ --startdate=date ] [ --enddate=date ]
                             [ --localtimezone=boolean ]
                             [ --rateinterval=rateinterval ]
                               --kma=networkaddress   
okm listagents[ [ [ --cacert=filename ] [ --usercert=filename ] ]
                  [ --directory=dirname ] | --oper=username ]
                  [ --retries=retries ] [ --timeout=timeout ]
                  [ --listwait=waittime ] [ --verbose=boolean ]
                  [ --filter=filter ] [ --output=filename ]
                    --kma=networkaddress 
okm listauditevents [ [ [ --cacert=filename ] 
                        [ --usercert=filename ] ]
                        [ --directory=dirname ] | 
                        [ --oper=username ]
                        [ --filter=filter ]
                        [ --localtimezone=boolean ] 
                        [ --maxcount=count ]
                        [ --retries=retries ] 
                        [ --timeout=timeout ]
                        [ --verbose=boolean ]
                        [ --output=filename ]
                        [ --agentids=agentids | 
                          --dataunitids=dataunitds | 
                          --keyids=keyids ]
                          --kma=networkaddress 
okm listdu [ [ [ --cacert=filename ] [ --usercert=filename ] ]
               [ --directory=dirname ] ] | --oper=username 
               [ --filter=filter ]
               [ --retries=retries ] [ --timeout=timeout ]
               [ --listwait=waittime ] [ --verbose=boolean ]
               [ --output=filename ]
                 --kma=networkaddress 
okm listdukeycount[ [ [ --cacert=filename ] [ --usercert=filename ] ]
                  [ --directory=dirname ] | --oper=username ]
                  [ --filter=filter ]
                  [ --retries=retries ] [ --timeout=timeout ]
                  [ --listwait=waittime ] [ --verbose=boolean ]
                  [ --output=filename ]
                    --kma=networkaddress 
                    --duids=filename | --all=true
okm listkeys [ [ [ --cacert=filename ] [ --usercert=filename ] ]
                 [ --directory=dirname ] | --oper=username ]
                 [ --filter=filter ]
                 [ --retries=retries ] [ --timeout=timeout ]
                 [ --listwait=waittime ] [ --verbose=boolean ]
                 [ --output=filename ]
                   --kma=networkaddress
okm listkmaperformance [ [ [ --cacert=filename ] [ --usercert=filename ] ]
                           [ --directory=dirname ] | --oper=username ]
                           [ --filter=filter ]
                           [ --retries=retries ] [ --timeout=timeout ]
                           [ --listwait=waittime ] [ --verbose=boolean ]
                           [ --output=filename ]
                           [ --startdate=date ] [ --enddate=date ]
                           [ --localtimezone=boolean ]
                           [ --rateinterval=rateinterval ]
                             --kma=networkaddress
okm modifyagent[ [ [ --cacert=filename ] [ --usercert=filename ] ]
                   [ --directory=dirname ] | --oper=username ]
                   [ --retries=retries ] [ --timeout=timeout ]
                   [ --verbose=boolean ]
                   [ --description=description ] | 
                   [ --site=siteid ] |
                   [ --keygroup=defaultkeygroupid ] | 
                   [ --passphrase=agentpassphrase ] |
                   [ --enabled=boolean ] |
                   [ --onetimepassphrase=boolean ]
                     --kma=networkaddress 
                     --agent=agentid 

Parameter Descriptions

The following are OKM Command Line Utility subcommands.

Subcommands

backup

The backup subcommand generates a backup of the OKM data and downloads this backup to a backup data file and a backup key file in the specified output directory.

backupcs

The backupcs subcommand generates a backup of the OKM core security and stores this backup in an output file.

createagent

The createagent subcommand creates a new agent.

destroykeys

The destroykeys subcommand destroys deactivated or compromised keys.

export

The export subcommand creates a secure key file for a Transfer Partner that has been established with the OKM. All keys associated with a list of data units are exported using this key file and are protected using an AES-256-bit key that signs the key file. This list of data units is the result of the given filter string or file name. This key file can then be used to import the keys into the Transfer Partner's OKM using the import subcommand. Up to 1,000 Data Units can be exported on a single invocation of the kms command.

import

The import subcommand reads a secure key file for a Transfer Partner that has been established with the OKM. Keys and their associated data units are imported using this key file. The key transfer private key of the importing OKM is used to validate the key file. This file must be one that was previously exported from another OKM using the export subcommand.

listagents

The listagents subcommand produces a list of agents and their properties. The list may be filtered to produce a specific report containing just a subset of the agents.

listauditevents

The listauditevents subcommand lists audit events.

listdu

The listdu subcommand lists data units and their properties. This subcommand can be invoked prior to executing the export subcommand to determine the data units that are exported using the specified filter (if any).

modifyagent

The modifyagent subcommand changes properties of an existing agent, including its default Key Group. At least one of the following options must also be specified:

  • --enabled

  • --site

  • --description

  • --keygroup

  • --passphrase

  • --onetimepassphrase

Options

The lists of options below show the long and short option name. A long option name is separated from its value by an equals sign (=); a short option name is separated from its value by a space.

The following options are used for user authentication.


Note:

Users must first export the Root CA and user X.509 certificates from the OKM Manager GUI before invoking this utility with the --cacert, --directory, and --usercert options.

--agent=agentid

Short name: -B

Specifies an agent ID to be created or modified. This agent ID must be between 1 and 64 characters in length, inclusive.

--cacert=filename

Short name: -a

Specifies a OKM Root CA X.509 certificate PEM file for this utility to use to authenticate itself with the OKM. If not specified, then the utility looks for a ca.crt file in the directory specified by the --directory option. This option is mutually exclusive with the --oper option.

--description=description

Short name: -R

Specifies a description of the agent being created or modified. The description must be between 1 and 64 characters in length, inclusive.

--directory=dirname

Short name: -d

Specifies a directory in which to search for a PEM file containing a OKM Root CA X.509 certificate and a PEM file containing a OKM user X.509 certificate. If not specified, then this utility looks for the certificate files in the current working directory. This option is mutually exclusive with the --oper option.

--enddate

Short name: -eSpecifies the end date and time of a performance query in the format: YYYY-MM-DD hh:mm:ss, representing a value in universal coordinated time (UTC) or local time if the localtimezone option is true. The default value is the present.

--localtimezone Short name: -LSpecifies a boolean value to determine whether input and output times are in the local time zone instead of in Universal Coordinated Time (UTC). This affects the interpretation of input values such as start and end dates and the display of audit event timestamps. The boolean value can be "true" or "false."

--oper=username

Short name: -b

Specifies the OKM User ID for this utility to use to authenticate itself with the OKM. If specified, it prompts for the user's passphrase since certificates are not being used. This option is mutually exclusive with the --cacert, --usercert, and --directory options.

--rateinterval Short name: -I Specifies the rate display interval. Request rates will be extrapolated over the selected rate display interval and displayed as the average number of requests per that selected interval (for example, extrapolated average number of Create Key requests per day). Possible values are "second," "minute," "hour," "day," "week," "month," "year," or "entire." Selecting "entire" causes the counts of each request type to be displayed instead of their rates. The default value is "entire."

--startdate Short name: -s Specifies the start date and time of a performance query in the format: YYYY-MM-DD hh:mm:ss, representing a value in universal coordinated time (UTC) or local time if the localtimezone option is true. The default value is the beginning of data collection.

--usercert=filename

Short name: -u

Specifies a OKM user's X.509 certificate PEM file for this utility to use to authenticate itself with the OKM. This certificate file must also contain the user's private key. If not specified, then the utility looks for a clientkey.pem file in the directory specified by the --directory option. This option is mutually exclusive with the --oper option.

The following list shows additional options.

--agentids=agentids

Short name: -A

Specifies a comma-separated list of agent IDs for associated audit events. Each agent ID must be between 1 and 64 characters in length. The OKM user must have the Operator or Compliance Officer role to be able to specify this option. This option is mutually exclusive with the --dataunitids and --keyids options.

--all=true

Short name: -l

Indicates that this utility destroys all deactivated or compromised keys, as indicated by the --keystate option, for all data units. This option is mutually exclusive with the --duids option.

--comment=”text

Short name: -C

Specifies a comment describing the key destruction. This comment must be between 1 and 64 characters in length.

--dataunitids=dataunitds

Short name: -D

Specifies a comma-separated list of data unit IDs for associated audit events. Each data unit ID must be 32 hexadecimal characters. The OKM user must have the Operator or Compliance Officer role to be able to specify this option. This option is mutually exclusive with the --agentids and --keyids options.

--duids=filename

Short name: -i

For key export or destruction, this option specifies a filename containing a set of data unit IDs, one per line, newline delimited. Each data unit ID must be 32 hexadecimal characters. On the destroykeys subcommand, if a particular data unit does not have any deactivated or compromised keys, then that data unit is ignored. If the specified file is empty, then the destroykeys subcommand destroys all deactivated or compromised keys for all data units (see the --all option). This option is mutually exclusive with the --filter and --all options.

--filter=filter

Short name: -f

Specifies a filter string that is processed to generate either a list of data unit IDs to display or export or a list of audit events to display. The string must be enclosed in quotes (double quotes on Windows) if it contains white space (see "Examples").

Exporting takes time proportional to the number of data units and keys, so typically you should specify a filter that reduces the set of data units.

On the export subcommand, this option is mutually exclusive with the --duids option.

On the export and listdu subcommands, the syntax of this filter string is:

DUState=state[, Exported=boolean ][, Imported=boolean]

[, DataUnitID=duid][, ExternalTag=tag]

[, ExternalUniqueID=euid]

DUState=state

Where state can be ”normal,” ”needs-rekey,” or ”normal+needs-rekey.” If the DUState filter is not specified, then the default is ”DUState=normal+needs-rekey.”

Exported=boolean

Where boolean can be ”true” or ”false.” If the Exported filter condition is not specified, then data unit selection does not consider the exported state, so both exported data units and data units that have not been exported yet are eligible for selection.

Imported=boolean

Where boolean can be ”true” or ”false.” If the Imported filter condition is not specified, then data unit selection does not consider the imported state, so both imported data units and data units that have not been imported yet are eligible for selection.

DataUnitID=duid

Where duid is a Data Unit ID.

ExternalTag=tag

Where tag is an External Tag (must be padded to 32 characters with spaces for Data Units created for LTO tape drives).

ExternalUniqueID=euid

Where euid is an External Unique ID.

On the listagentperformance subcommand, the syntax of this filter string is:

AgentID=agentid[, SiteID=siteid][, DefaultKeyGroupID=kgid]

AgentID=agentid

Where agentid is an agent name. The CLI uses the "starts with" operator (instead of equality) when matching on this field as some agents supply trailing blanks to the value for this field.

SiteID=siteid

Where siteid is a Site ID.

DefaultKeyGroupID=kgid

Where kgid is a Key Group ID.

On the listauditevents subcommand, the syntax of this filter string is:

StartDate=date[, EndDate=date ][, Severity=text]

[, Operation=text][, Condition=text] [, Class=text]

[, RetentionTerm=text] [, KMAName=kmaname]

[, EntityID=entityid][, EntityNetworkAddress=netaddress]

[, SortOrder=order][, ShowShortTerm=boolean]

StartDate=date

Where date has the format: YYYY-MM-DD hh:mm:ss and represents UTC time.

EndDate=date

Where date has the format: YYYY-MM-DD hh:mm:ss and represents UTC time.

Severity=text

Where text is an audit severity string (e.g., ”Error”).

Operation=text

Where text is an audit operation string (e.g., ”Retrieve Root CA Certificate”).

Condition=text

Where text is an audit condition string (e.g., ”Success”).

Class=text

Where text is an audit class string (e.g., ”Security Violation”).

RetentionTerm=text

Where text is an audit retention term string (e.g., ”MEDIUM TERM RETENTION”).

KMAName=kmaname

Where kmaname is a KMA name.

EntityID=entityid

Where entityid is an Entity ID.

EntityNetworkAddress=netaddress

Where netaddress is an IP address or host name.

SortOrder=order

Where order can be ”asc” or ”desc.” By default, audit events are displayed in descending order by Created Date.

ShowShortTerm=boolean

Where boolean can be ”true” or ”false.” By default, audit events that have a short term retention are not displayed.

On the listkeys subcommand, the syntax of this filter string is:

KeyState=state[, KeyID=keyid][, KeyGroupID=kgid] [, Exported=boolean][, Imported=boolean] [, Revoked=boolean]

KeyState=state Where state can be one of the following: gen, ready, pnp, proc, deact, comp, dest

KeyID=keyidWhere keyid is a Key ID.

KeyGroupID=kgid Where kgid is a Key Group ID.

Exported=boolean Where boolean can be "true" or "false".

Imported=boolean Where boolean can be "true" or "false".

Revoked=boolean Where boolean can be "true" or "false".

On the listkmaperformance subcommand, the syntax of this filter string is:

KMAName=kmaname[, SiteID=siteid]

KMAName=kmanameWhere kmaname is a KMA name.

SiteID=siteid Where siteid is a Site ID.

--help

Short name: -h

Displays help information.

--input=filename

Short name: -i

Specifies the file name from which data units and keys are to be imported. This file is also known as the key transfer file.

--keygroup=keygroupid

Short name: -g

Specifies the ID of a Key Group that is defined to the OKM.

--keyids=keyids

Short name: -K

Specifies a comma-separated list of key IDs for associated audit events. The OKM user must have the Operator or Compliance Officer role to be able to specify this option. This option is mutually exclusive with the --agentids and --dataunitids options.

--keystate=keystate

Short name: -s

Specifies the state of keys to be destroyed. The keystate value can be ”deact” for deactivated keys, ”comp” for compromised keys, or ”deact+comp” for deactivated or compromised keys.

--kma=networkaddress

Short name: -k

Specifies the network address of the KMA to issue the request. The network address can be a host name, an IPv4 address, or an IPv6 address.

--listwait=waittime

Short name: -w

Specifies the number of seconds between List Data Units requests issued by the export and listdu subcommands. The default value is 2.

--localtimezone=boolean

Short name: -L

Displays timestamps of audit events in the local time zone instead of in universal coordinated time (UTC). Also, the StartDate and EndDate filters are interpreted to be in local time.

--maxcount=count

Short name: -c

Specifies the maximum number of audit events to list. The default value is 20,000.

--onetimepassphrase=boolean

Short name: -O

Specifies a boolean value to determine whether the enrollment passphrase may be used only once for authentication. The boolean value can be "true" or "false".

--output=filename or dirname

Short name: -o

Specifies the file name where the results are stored. These results are the backup on backup and backupcs requests, the key transfer file on export requests, a listing of the data units and their properties on listdu requests, and a listing of audit events on listauditevents requests. On listdu and listauditevents requests, ”-” may be specified for stdout, which is also the default. On backup requests, this option specifies the directory where the backup data file and backup key file are downloaded.

--overrideeuiconflict=boolean

Short name: -O

Specifies a boolean value to determine whether to override a conflict where an existing data unit has the same external unique ID as a data unit being imported. If this value is "true," then the existing data unit is updated to clear its external unique ID and the importing data unit retains its external unique ID. Otherwise, the import request fails. The boolean value can be "true" or "false."

--partner=transferpartnerid

Short name: -p

Specifies the ID of the Transfer Partner that is defined to the OKM and that is eligible to send or receive exported keys.

--passphrase=passphrase

Short name: -P

Specifies a passphrase for the agent being created or modified. Passphrases can be from 8 to 64 characters in length, inclusive. Passphrases must follow OKM passphrase rules.

--rclientcert=filename

Short name: -C

Specifies an X.509 certificate PEM file that has been issued by a Certificate Authority for this KMA.

--rclientkey=filename

Short name: -K

Specifies a private key file that accompanies the client certificate file.

--rclientpassword=password

Short name: -P

Specifies a password (if any) that protects the private key.

--retries=retries

Short name: -r

Specifies the number of times that this utility tries to connect to the KMA, if the KMA is busy. The default value is 60.

--server=networkaddress

Short name: -S

Specify the network address (IP address or, if DNS is configured, host name) of the remote syslog system.

--site=siteid

Short name: -S

Specifies the site ID for the agent being created or modified. This site ID must be between 1 and 64 characters in length, inclusive.

--timeout=timeout

Short name: -t

Specifies the timeout value in seconds between these retries. The default value is 60.

--verbose=boolean

Short name: -n

Indicates that this utility generates verbose output, including progress status during the processing of the request. The boolean value can be ”true” or ”false.”

--version

Short name: -v

Displays command-line usage.

Examples

These examples show a single command line. In some cases, the command line appears on multiple lines for readability. In Solaris examples, backslashes denote the continuation of a command line.

The following examples generate a backup using certificates in the ca.crt and clientkey.pem files in the given directory for authentication.

Solaris:

okm backup --kma=mykma1 \
           --directory/export/home/Joe/.sunw/kms/BackupOperatorCertificates \
           --output=/export/home/KMSBackups

Windows:

okm backup --kma=mykma1
           --directory=D:\KMS\Joe\BackupOperatorCertificates
           --output=D:\KMS\KMSBackups

The following examples generate a backup using the user ID and passphrase of a OKM user for authentication.

Solaris:

okm backup -k mykma1 -o /export/home/KMSBackups -b Joe

Windows:

okm backup -k mykma1 -o D:\KMS\KMSBackups -b Joe

The following examples export keys using certificates in the ca.pem and op.pem files in the current working directory for authentication.

Solaris:

okm export -k 10.172.88.88 -d "." -a ca.pem -u op.pem \
           -f "DUState = normal+needs-rekey, Exported = false" \
           -o Partner.dat -p Partner

Windows:

okm export -k 10.172.88.88 -d "." -a ca.pem -u op.pem
           -f "DUState = normal+needs-rekey, Exported = false"
           -o Partner.dat -p Partner

The following examples export keys using the user ID and passphrase of a OKM user for authentication.

Solaris:

okm export --kma=mykma1 --oper=tpFreddy \
           --filter="Exported = false" --output=Partner.dat \ 
           --partner=Partner

Windows:

okm export --kma=mykma1 --oper=tpFreddy
           --filter="Exported = false" --output=Partner.dat 
           --partner=Partner

The following examples import keys using certificates in the ca.crt and clientkey.pem files in the current working directory for authentication.

Solaris:

okm import --kma=10.172.88.88 --directory="." \
           --input=DRKeys.dat --partner=Partner \
           --keygroup=OpenSysBackupKeyGroup

Windows:

okm import --kma=10.172.88.88 --directory="."
           --input=DRKeys.dat --partner=Partner
           --keygroup=OpenSysBackupKeyGroup

The following examples import keys using the user ID and passphrase of a OKM user for authentication.

Solaris:

okm import --kma=mykma1 --oper=Joe --input=DRKeys.dat \
           --partner=Partner --keygroup=OpenSysBackupKeyGroup

Windows:

okm import --kma=mykma1 --oper=Joe --input=DRKeys.dat
           --partner=Partner --keygroup=OpenSysBackupKeyGroup

The following examples list data units using certificates in the ca.crt and clientkey.pem files in the given directory for authentication.

Solaris:

okm listdu --kma=10.172.88.88 \
            --directory=/export/home/Joe/.sunw/kms/OperatorCertificates \
            --output=/export/home/KMSDataUnits

Windows:

okm listdu --kma=10.172.88.88
           --directory=D:\KMS\Joe\OperatorCertificates 
           --output=D:\KMS\KMSDataUnits

The following examples list data units using the user ID and passphrase of a OKM user for authentication.

Solaris:

okm listdu -k mykma1 -b Joe -f "Exported=false" \
           --output=/export/home/KMSDataUnits

Windows:

okm listdu -k mykma1 -b Joe -f "Exported=false"
           --output=D:\KMS\KMSDataUnits

The following examples list audit events using certificates in the ca.crt and clientkey.pem files in the given directory for authentication.

Solaris:

okm listauditevents --kma=10.172.88.88 \
                    --directory=/export/home/Joe/.sunw/kms/OperatorCertificates \
                    --filter=Severity=Error \
                    --output=/export/home/KMSAuditEvents

Windows:

okm listauditevents --kma=10.172.88.88
                    --directory=D:\KMS\Joe\OperatorCertificates
                    --filter=Severity=Error
                    --output=D:\KMS\KMSAuditEvents

The following examples list audit events using the user ID and passphrase of a OKM user for authentication.

Solaris:

okm listauditevents -k mykma1 -b Joe -f "Severity=Error" \
                    --output=/export/home/KMSAuditEvents

Windows:

okm listauditevents -k mykma1 -b Joe -f "Severity=Error"
                    --output=D:\KMS\KMSAuditEvents

The following examples destroy all compromised keys using certificates in the ca.crt and clientkey.pem files in the given directory for authentication.

Solaris:

okm destroykeys --kma=10.172.88.88 \
                --directory=/export/home/Joe/.sunw/kms/OperatorCertificates \
                --all=true --keystate=comp \
                --comment="Joe destroyed compromised keys"

Windows:

okm destroykeys --kma=10.172.88.88
                --directory=D:\KMS\Joe\OperatorCertificates
                --all=true --keystate=comp
                --comment="Joe destroyed compromised keys"

The following examples destroy deactivated keys associated with a list of data unit IDs using the user ID and passphrase of a OKM user for authentication.

Solaris:

okm destroykeys -k mykma1 -b Joe -i DeactivatedDUIDs.txt \
                -s deact -C "Joe destroyed deactivated keys"

Windows:

okm destroykeys -k mykma1 -b Joe -i DeactivatedDUIDs.txt
                -s deact -C "Joe destroyed deactivated keys"

The following examples back up core security using certificates in the ca.crt and clientkey.pem files in the given directory for authentication.

Solaris:

okm backupcs --kma=10.172.88.88 \
             --directory=/export/home/Joe/.sunw/kms/SecurityOfficerCertificates \
             --output=/export/home/KMSCoreSecurity.xml

Windows:

okm backupcs --kma=10.172.88.88
             --directory=D:\KMS\Joe\SecurityOfficerCertificates
             --output=D:\KMS\KMSCoreSecurity.xml

The following examples back up core security using the user ID and passphrase of a OKM user for authentication.

Solaris:

okm backupcs -k mykma1 -b Joe -o /export/home/KMSCoreSecurity.xml

Windows:

okm backupcs -k mykma1 -b Joe -o D:\KMS\KMSCoreSecurity.xml

Exit Values

The following exit values are returned:

 0    Successful completion
 >0   An error occurred

Sample Perl Scripts

The following are some basic perl scripts that can be customized and run on either Solaris or Windows. These examples all use certificate-based authentication and require that the Root CA certificate and user's certificate reside in the current working directory.


Note:

The perl scripts are not installed with the OKM Command Line utility. If you want to invoke the OKM Command Line utility from a perl script, use a text editor to create one that looks similar to one of the perl scripts shown here.

  • listdu.pl

    #!/opt/csw/bin/perl
    ## the kms CLI utility must be in your path
    $cmd="okm";
    $KMA="kma1.example.com";
    $FILTER="--filter=Exported=false";
    $DIRECTORY=".";
    $OUTPUT="listdu.txt";
    system("$cmd listdu --verbose=true --directory=$DIRECTORY --kma=$KMA $FILTER
           --output=$OUTPUT")
    
  • export.pl

    #!/opt/csw/bin/perl
    ## the kms CLI utility must be in your path
    $cmd="okm";
    $KMA="kma1.example.com";
    $TP="DestinationPartner";
    $FILTER="Exported=false";
    $OUTPUT="$TP.dat";
    system("$cmd export --verbose=true --kma=$KMA --directory=. --filter=$FILTER
           --partner=$TP --output=$OUTPUT");
    
  • import.pl

    #!/opt/csw/bin/perl
    ## the kms CLI utility must be in your path
    $cmd="okm";
    $KMA="kma1.example.com";
    $TP="SourceTransferPartner";
    $KEYGROUP="MyKeyGroup"; 
    $INPUT="../aberfeldy/KeyBundle.dat";
    system("$cmd import --verbose=true --kma=$KMA --directory=. --partner=$TP 
           --keygroup=$KEYGROUP --input=$INPUT");
    
  • backup.pl

    #!/opt/csw/bin/perl
    ## the following must be in your path
    $cmd="okm";
    $KMA="kma1.example.com";
    $DIRECTORY="."; 
    $OUTPUT=".";
    system("$cmd backup --verbose=true --directory=$DIRECTORY --kma=$KMA 
           --output=$OUTPUT")
    

Backup Command Line Utility

The Backup Command Line utility allows you to launch a backup from the command line instead of from the Backup List menu. You can also schedule automated backups.

This utility is installed with the OKM Manager GUI using the same installer.


Note:

If you want to enter link-local IPv6 addresses, invoke the Backup Utility and specify the link-local IPv6 address. Include the Zone ID (for example, ”%4”) at the end of the address.

Refer to "IPv6 Addresses with Zone IDs" to see what steps you must follow for the initial setup.


Solaris Syntax

OKM_Backup [-UserID userid] [-Passphrase passphrase]
           -KMAIPAddress IPaddress -BackupFilePath pathname 
           [-Retries retries] [-Timeout timeout]

Windows Syntax

OKMBackupUtility [-UserID userid] [-Passphrase passphrase]
                 -KMAIPAddress IPaddress -BackupFilePath pathname 
                 [-Retries retries] [-Timeout timeout]

Parameter Descriptions

userid

The Backup Operator user ID. This must be a Backup Operator.

passphrase

The passphrase for the user ID.

If the userid or passphrase value is not specified, the utility prompts you for these values.

IPaddress

The KMA Management Network Address on which to launch the backup.

pathname

The location where the Backup File and Backup Key File should be downloaded on your system.

retries

The number of times that this utility tries to connect to the KMA, if the KMA is busy. The default is 60.

timeout

The timeout value in seconds between these entries. The default is 60.

Example

The following example creates a Backup File (format: OKM-Backup-backupid-timestamp.dat) and a Backup Key File (format: OKM-BackupKey-backupid-timestamp.xml).

OKM_Backup -UserID MyBackupOperator \
           -KMAIPAddress 10.0.60.172 \
           -BackupFilePath /tmp/MyKMSDownloads
OKM Backup Utility  Version 3.0.0 (build2020)
Copyright (c) 2007, 2013, Oracle and/or its affiliates.  All Rights Reserved.
Enter Passphrase:

Note:

The passphrase can optionally be specified on the command line using the -Passphrase parameter.