Oracle Key Vault RESTfulサービスのスタート・ガイド

2 Oracle Key Vault RESTfulサービスのスタート・ガイド

RESTfulサービス・ユーティリティをダウンロードし、その構成ファイルをカスタマイズすると、Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドの使用を開始できます。

Oracle Key Vault RESTfulサービスの有効化/無効化
RESTfulサービスは、Oracle Key Vault管理コンソールから有効化または無効化します。
Oracle Key Vault RESTfulサービスの構成ファイルとロギング・ファイル
Oracle Key Vaultには、RESTfulサービス・ユーティリティ・コマンドの実行時に必須またはオプションの設定を指定するために使用できるokvrestcli.iniファイルとokvrestcli_logging.propertiesファイルが用意されています。
RESTfulサービス・ユーティリティ・コマンドのヘルプ情報の取得
コマンドライン(JSONでは使用できません)で、okv RESTfulサービス・ユーティリティ・コマンドの各コンポーネントの詳細なヘルプ情報を参照できます。
Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドの実行
Oracle Key Vaultには、RESTfulサービス・ユーティリティ・コマンドを実行するための様々な方法があります。
オブジェクトのネーミング・ガイドライン
このネーミング・ガイドラインは、ユーザー、ユーザー・グループ、エンドポイント、エンドポイント・グループおよび仮想ウォレットのOracle Key Vaultオブジェクトに影響します。
RESTfulサービス・ユーティリティ・コマンドでの日時の設定方法
サポートされている書式を使用して、日付またはタイムスタンプと、期間を指定します。
LDAPユーザーによるRESTfulサービスの使用
通常のOracle Key Vault管理者と適切に認可されたLDAPユーザーは、どちらもサーバーにログインしてOracle Key Vault RESTfulサービス・ユーティリティ・コマンドを実行できます。

2.1 Oracle Key Vault RESTfulサービスの有効化/無効化

RESTfulサービスは、Oracle Key Vault管理コンソールから有効化または無効化します。

RESTfulサービスの有効化
エンドポイント要件を確認して、ネットワーク・サービスを有効化した後で、RESTfulサービスの有効化とRESTfulソフトウェア・ユーティリティのダウンロードが可能になります。その後で、ユーティリティの構成ファイルをカスタマイズします。
RESTfulサービスの無効化
RESTfulサービスは、管理タスクの実行時に短時間有効にする必要があります。

親トピック: Oracle Key Vault RESTfulサービスのスタート・ガイド

2.1.1 RESTfulサービスの有効化

エンドポイント要件を確認して、ネットワーク・サービスを有効化した後で、RESTfulサービスの有効化とRESTfulソフトウェア・ユーティリティのダウンロードが可能になります。その後で、ユーティリティの構成ファイルをカスタマイズします。

ステップ1: エンドポイントのシステム要件の確認
RESTfulコマンドライン・インタフェースを使用してエンドポイントをプロビジョニングする前に、ネットワーク経由で安全にデータを転送するためのツールが必要です。
ステップ2: ネットワーク・サービスの有効化
Oracle Key Vaultサーバーにアクセスするには、IPアドレスによってRESTfulクライアント用のWebアクセスを構成する必要があります。
ステップ3: RESTfulサービスの有効化
ネットワーク・サービスを有効にした後、RESTfulサービスを有効にできます。
ステップ4: RESTful Servicesユーティリティのダウンロード
RESTfulサービス・ユーティリティは、okvrestclipackage.zipファイル内にあります。
ステップ5: RESTfulサービス・ユーティリティの構成
RESTfulサービス・ユーティリティのダウンロード後に、zipファイルに含まれている複数のファイルを変更する必要があります。

親トピック: Oracle Key Vault RESTfulサービスの有効化/無効化

2.1.1.1 ステップ1: エンドポイントのシステム要件の確認

RESTfulコマンドライン・インタフェースを使用してエンドポイントをプロビジョニングする前に、ネットワーク経由で安全にデータを転送するためのツールが必要です。

エンドポイント管理者としてエンドポイントのホストにログインします。
次のツールがあることを確認します。
- OpenSSL 1.0.1p以降
- JAVA 8以降。Oracle Databaseリリース12.2.0.1以上のデータベース・サーバーにRESTfulサービスをデプロイする場合は、$ORACLE_HOME/jdk/jreの埋込みJava Runtime Environment (JRE)を使用できます。
  Oracleリリース12.2.0.1以降のデータベース・インストール環境の場合は、JAVA_HOMEに$ORACLE_HOME/jdk/jreを設定し、JAVA_HOME/binをPATHに追加します。以前のデータベース・リリースの場合は、JAVA 8以降をダウンロードしてインストールし、JAVA_HOMEおよびPATHを適切に設定します。OpenJDKはサポートされていません。

親トピック: RESTfulサービスの有効化

2.1.1.2 ステップ2: ネットワーク・サービスの有効化

Oracle Key Vaultサーバーにアクセスするには、RESTfulクライアントのWebアクセスをそのIPアドレスごとに構成する必要があります。

すべてのIPアドレスを許可するか、このステップで指定するIPアドレスのサブセットへのアクセスを制限できます。このオプションによって、Oracle Key Vault管理コンソールへのアクセスも制限されることに注意してください。

システム管理者ロールを持っているユーザーとしてOracle Key Vault管理コンソールにログインします。
「System」を選択し、左側のサイドバーから「Settings」を選択します。
「Settings」ページが表示されます。「Network Details」セクションに移動します。
「Web Access」で、RESTfulクライアントに対して次のIPアドレス・オプションのいずれかを選択します。
- すべてのIPアドレスを許可する場合は、「All」。
- 一連のIPアドレスを指定する場合は、「IP address(es)」。このオプションを選択した場合は、隣のフィールドにIPアドレスを入力します(各IPアドレスは空白で区切ります)。
「Save」をクリックします。

親トピック: RESTfulサービスの有効化

2.1.1.3 ステップ3: RESTfulサービスの有効化

ネットワーク・サービスを有効にした後、RESTfulサービスを有効にできます。

マルチマスター・クラスタ環境では、あるノードでRESTfulサービスを有効にすることで、クラスタ全体でサービスが有効になります。

システム管理者ロールを持っているユーザーとしてOracle Key Vault管理コンソールにログインします。
「System」を選択し、左側のサイドバーから「Settings」を選択します。

「Settings」ページが表示されます。「System Configuration」セクションに移動してから、そこにある「RESTful Services」セクションに移動します。
「Enable」の右側のボックスを選択します。
「Save」をクリックします。

親トピック: RESTfulサービスの有効化

2.1.1.4 ステップ4: RESTfulサービス・ユーティリティのダウンロード

RESTfulサービス・ユーティリティは、okvrestclipackage.zipファイル内にあります。

Oracle Key Vault 21.1リリースで導入された新しいRESTfulサービス・ユーティリティに加えて、Oracle Key Vaultでは、従来のRESTfulサービス・ユーティリティの実装も引き続きサポートされています。これは、クラシックRESTfulサービス・ユーティリティとしてダウンロードできます。

次のいずれかの方法を使用して、Oracle Key Vault RESTfulサービス・ユーティリティのokvrestclipackage.zipファイルをダウンロードします。
- Oracle Key Vault管理コンソールのホーム・ページから、次の操作を実行します。
  1. システム管理者ロールを持つユーザーとしてログインします。
  2. 「System」タブを選択します。
  3. 左側のサイドバーで、「Settings」を選択します。
  4. 「System Configuration」から「RESTful Services」を選択します。
  5. 「RESTful Services」ダイアログ・ボックスで、「Download」を選択します。
    Oracle Key VaultのクラシックRESTfulサービス・ユーティリティをダウンロードするには、「Download Classic Utility」をクリックします。このバージョンの使用方法の詳細は、リリース18.6バージョンの『Oracle Key Vault管理者ガイド』を参照してください。
  6. 「Opening okvrestclipackage.zip」ダイアログ・ボックスで、「Save」を選択してokvrestclipackage.zipファイルをローカルに保存します。
- Oracle Key Vault管理コンソールの「Endpoint Enrollment」および「Software Download」から、次の操作を実行します。
  1. Oracle Key Vault管理コンソールに接続します。
    Oracle Key Vault管理コンソールへのログイン・ページが表示されます。ログインしないでください。
  2. ログイン・ページの右下隅にある「Login」で、「Endpoint Enrollment and Software Download」をクリックします。
  3. 「Download RESTful Service Utility」タブをクリックします。
  4. 「Download」ボタンをクリックします。
    クラシックRESTfulサービス・ユーティリティをダウンロードするには、「Download Classic Utility」をクリックします。
  5. 安全な場所にokvrestclipackage.zipをダウンロードします。
- コマンドラインHTTPクライアント(wgetやcurlなど)を使用します。プライマリ/スタンバイ構成の場合は、プライマリ・データベースのIPアドレスを入力します。たとえば:
```
wget --no-check-certificate https://ip_address:5695/okvrestclipackage.zip  
curl -k https://ip_address:5695/okvrestclipackage.zip -o okvrestclipackage.zip 
curl -O -k https://ip_address:5695/okvrestclipackage.zip 
```

親トピック: RESTfulサービスの有効化

2.1.1.5 ステップ5: RESTfulサービス・ユーティリティの構成

RESTfulサービス・ユーティリティのダウンロード後に、zipファイルに含まれている複数のファイルを変更する必要があります。

okvrestclipackage.zipファイルをエンドポイントのOracle Key Vaultホーム・ディレクトリ(OKV_HOME)に移動します。
このzipファイルは任意の安全な場所に移動できますが、エンドポイントのOracle Key Vaultホーム・ディレクトリに配置すると、Oracle Key VaultのRESTfulファイルを一元的管理する際に好都合です。このガイドでは、このzipファイルをエンドポイントにダウンロードしたことを前提としています。
okvrestclipackage.zipファイルを解凍します。
たとえば:
```
unzip okvrestclipackage.zip
```
次に示すディレクトリ構造が作成されます。
- okvrestclipackage.zipファイルを格納したディレクトリ(OKV_HOMEディレクトリなど)
  - bin
    - okv
    - okv.bat
  - lib
    - okvrestcli.jar
  - conf
    - okvrestcli.ini
    - okvrestcli_logging.properties
RESTfulサービス・コマンドライン・ユーティリティ・スクリプトで、OKV_RESTCLI_CONFIG変数を設定します。
OKV_RESTCLI_CONFIGでは、okvrestcli.ini構成ファイルの場所を設定します。LinuxプラットフォームのRESTfulサービス・コマンドライン・ユーティリティ・スクリプトはokvで、Microsoft Windowsのユーティリティ・スクリプトはokv.batです。
JAVA_HOME環境変数は、最小バージョン1.7.0.21のJava Runtime Environment (JRE)インストールに設定します。

次に、目的の環境に応じて構成ファイルのokvrestcli.iniとokvrestcli_logging.propertiesを変更します。

関連項目

Oracle Key Vault RESTfulサービスの構成フィルとロギング・ファイル

親トピック: RESTfulサービスの有効化

2.1.2 RESTfulサービスの無効化

RESTfulサービスは、管理タスクの実行時に短時間有効にする必要があります。

RESTfulサービスはデフォルトでは無効になっています。RESTfulサービスを使用した管理タスクの実行後に、RESTfulサービスを無効にする必要があります。

システム管理者ロールを持っているユーザーとしてOracle Key Vault管理コンソールにログインします。
「System」を選択し、左側のサイドバーから「Settings」を選択します。

「Settings」ページが表示されます。「System Configuration」セクションに移動してから、そこにある「RESTful Services」セクションに移動します。
「RESTful Services」セクションで、「Enable」の右側のボックスの選択を解除します。
「System Settings」ページで、「Save」をクリックします。

親トピック: Oracle Key Vault RESTfulサービスの有効化/無効化

2.2 Oracle Key Vault RESTfulサービスの構成フィルとロギング・ファイル

Oracle Key Vaultには、RESTfulサービス・ユーティリティ・コマンドの実行時に必須またはオプションの設定を指定するために使用できるokvrestcli.iniファイルとokvrestcli_logging.propertiesファイルが用意されています。

okvrestcli.ini構成ファイル
okvrestcli.iniファイルを使用すると、Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドに使用するグローバル設定を制御できます。
okvrestcli_logging.propertiesログ・ファイルのパラメータ設定
okvrestcli_logging.propertiesログ・ファイルでは、Oracle Key Vault RESTfulサービスのアクティビティについてのロギングの処理方法を決定します。

親トピック: Oracle Key Vault RESTfulサービスのスタート・ガイド

2.2.1 okvrestcli.ini構成ファイル

okvrestcli.iniファイルを使用すると、Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドに使用するグローバル設定を制御できます。

okvrestcli.ini構成ファイルについて
okvrestcli.iniファイルを使用すると、Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドの実行時に共通して使用される設定を構成できます。
okvrestcli.iniの構成パラメータ
okvrestcli.iniのパラメータは、ユーザーの名前とパスワード、okvclient.oraファイルの場所などの設定に対応しています。
okvrestcli.iniファイルの[DEFAULT]および名前付きプロファイル
okvrestcli.iniファイルの[DEFAULT]および名前付きプロファイル・セクションを使用すると、異なるコンテキストでコマンドを実行するときに適用できる構成パラメータ設定の各種セットを維持できます。
okvrestcli.iniのパラメータの優先順位
Oracle Key Vault RESTfulサービス・コマンドを実行するときに、構成パラメータの値は優先順位に基づいて決定されます。
代替構成ファイルの使用
okvrestcli.ini構成ファイルの代替パラメータ構成ファイルを使用できます。

親トピック: Oracle Key Vault RESTfulサービスの構成フィルとロギング・ファイル

2.2.1.1 okvrestcli.ini構成ファイルについて

okvrestcli.iniファイルを使用すると、Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドの実行時に共通して使用される設定を構成できます。

該当する設定には、ユーザーの名前やOracle Key VaultサーバーのIPアドレスなどがあります。RESTfulサービス・ユーティリティでは、このような種類のokvrestcli.iniファイル内のパラメータをコマンドの実行ごとに設定する必要があります。このファイルで設定した設定内容は、すべてのOracle Key Vault RESTfulサービス・ユーティリティ・コマンドに自動的に適用されるため、コマンドの実行ごとにコマンドラインで手動入力する必要がなくなります。

okvrestcli.iniの構成パラメータは、名前付きプロファイルという異なるセクションにグループ化されています。それぞれのセクションには、プロファイル名とプロファイルに関連付けるパラメータのリストが含まれています。コマンドの実行時に名前付きプロファイルを指定(--profile profile_nameパラメータを使用)すると、コマンドの実行に名前付きプロファイルの下にリストされている構成パラメータが適用されます。[DEFAULT]プロファイルの下にリストされている構成パラメータは、名前付きプロファイルが指定されていない場合や、名前付きプロファイルの下にパラメータがリストされていない場合に適用されるデフォルトのパラメータ設定を表します。

デフォルトでは、okvrestcli.iniの場所は、Oracle Key Vault RESTfulサービス・ユーティリティをダウンロードした場所と同じになります。これは、エンドポイントのOKV_HOME/confディレクトリ内にあります。

関連項目

代替構成ファイルの使用方法

親トピック: okvrestcli.ini構成ファイル

2.2.1.2 okvrestcli.iniの構成パラメータ

okvrestcli.iniのパラメータは、ユーザーの名前とパスワード、okvclient.oraファイルの場所などの設定に対応しています。

okvrestcli.iniのパラメータは次のとおりです。

server: 実行のためにコマンドが送信されるターゲットOracle Key Vaultサーバーを決定します。このサーバーのIPアドレスを入力します。サーバー情報は、okv_client_configパラメータの設定時に、okvclient.oraファイルから取得することもできます。

Oracle Key Vaultクラスタのマルチマスター・デプロイメントでは、Oracle Key Vaultは、エンドポイントのクラスタ・サブグループ設定と、クラスタ・トポロジまたはOracle Key Vaultクラスタ・ノードの状態についての変更に基づいて、エンドポイントの構成ファイルokvclient.oraのサーバー情報を動的に更新します。エンドポイントのokvclient.oraから得られるサーバー情報を使用すると、okvrestcli.iniのSERVERパラメータを頻繁に更新しなくても、Oracle Key Vaultで最適なOracle Key Vaultノードを自動的に選択してRESTコマンドを実行できるようになります。
okv_client_config: エンドポイントのokvclient.oraファイルのフルパスを指定します。デフォルトでは、このファイルは$OKV_HOME/confディレクトリにあります。このパラメータは管理対象オブジェクトのRESTfulサービス・ユーティリティ・コマンドを実行する場合に必須です。そのコマンドは、常にエンドポイントのIDを使用して実行する必要があります。Oracle Key Vault RESTfulサービス・ユーティリティでは、okvclient.oraファイルから得られる次の情報のみを使用します。
- サーバー情報: Oracle Key VaultサーバーのIPアドレスまたはホスト名
- SSL_WALLET_LOC: エンドポイントで使用されるウォレットの場所。
これは文字列値であり、必須です。
user: RESTfulサービス・コマンドを実行するOracle Key Vaultユーザーを指定します。ユーザーには、コマンドを実行するための適切な権限が必要です。

Oracle Key Vaultでは、管理対象オブジェクトのカテゴリに対応するRESTfulサービス・ユーティリティ・コマンドの実行時に、userパラメータは使用されません。こうしたコマンドは、常に、okv_client_configパラメータで設定されたエンドポイントのIDを使用して実行されます。
client_wallet: ユーザー資格証明が格納されているウォレットへの絶対パスを指定します。このウォレットは、ユーザーのパスワードを手動で指定することなくOracle Key Vaultサーバーにログインするために使用できます。ユーザー情報は、userパラメータから取得されます。client_walletパラメータにより、無人モードで実行する必要がある自動化スクリプトの実装と使用が可能になります。

Oracle Key Vaultでは、管理対象オブジェクトのカテゴリに対応するRESTfulサービス・ユーティリティ・コマンドの実行時に、client_walletパラメータは使用されません。こうしたコマンドは、常に、okv_client_configパラメータで設定されたエンドポイントのIDを使用して実行されます。
password: RESTfulサービス・ユーティリティ・コマンドを実行するユーザーのパスワードを指定します。client_walletを指定したときに、passwordパラメータは不要です。client_walletパラメータとpasswordパラメータの両方を指定すると、client_walletよりもpasswordパラメータが優先されます。

Oracle Key Vaultでは、管理対象オブジェクトのカテゴリに対応するRESTfulサービス・ユーティリティ・コマンドの実行時に、passwordパラメータは使用されません。こうしたコマンドは、常に、okv_client_configパラメータで設定されたエンドポイントのIDを使用して実行されます。
log_property: Javaロギング・プロパティ・ファイルのフルパスを指定します。このパラメータが設定されていないときにRESTfulコマンドを実行すると、Oracle Key Vaultによって、log_propertyが構成されていないというメッセージとともに、現行ディレクトリにINFOレベルでデフォルト名のログ・ファイルが生成されます。デフォルトのログ・プロパティ・ファイルは、ダウンロードしたokvrestclipackage.zipファイルに含まれています。このファイルを使用すると、ログ・ファイルとその形式をカスタマイズできます。これは文字列値であり、オプションです。

親トピック: okvrestcli.ini構成ファイル

2.2.1.3 okvrestcli.iniファイルの[DEFAULT]および名前付きプロファイル

okvrestcli.iniファイルの[DEFAULT]および名前付きプロファイル・セクションを使用すると、異なるコンテキストでコマンドを実行するときに適用できる構成パラメータ設定の各種セットを維持できます。

okvrestcli.iniファイルは、1つ以上の名前付きプロファイルのセクションとして編成されています。名前付きプロファイルのセクションは、論理的にグループ化された構成パラメータ設定のコレクションを表します。名前付きプロファイルのセクションには次の項目が含まれます。

[profile_name]として示される名前付きプロファイル・セクション・ヘッダー
名前プロファイル・ヘッダーの下の構成パラメータのリスト

名前付きプロファイルの下にリストされている構成パラメータ設定は、パラメータ--profile profile_nameを使用して、コマンドラインでプロファイル名を指定することで適用します。

[DEFAULT]プロファイルには、okvrestcli.iniパラメータのデフォルト値をリストします。[DEFAULT]プロファイルの下のパラメータ設定は、コマンドの実行時に名前付きプロファイルが指定されていない場合や、パラメータが名前付きプロファイルの下にリストされていない場合に適用されます。また、コマンドラインでパラメータを指定しないことも想定しています。

次の例では、異なるエンドポイントのIDを使用したOracle Key Vaultへの接続に適したプロファイルの使用方法を示します。これは、同じホストに分離されたPDBエンドポイントを構成した環境で役立ちます。このokvrestcli.iniファイルには、PDBエンドポイントごとの名前付きプロファイルがあり、それぞれのokvclient.oraファイルを指し示しています。

[DEFAULT]
log_property=/usr/local/okv/logging.property
server = 192.0.2.191

[HR_PDB]
okv_client_config=/usr/local/okv/hr_ep/okvclient.ora

[FIN_PDB]
okv_client_config=/usr/local/okv/finance_ep/okvclient.ora

[SALES_PDB]
okv_client_config=/usr/local/okv/sales_ep/okvclient.ora

HR_DBエンドポイントを使用してキーを作成する場合は、[HR_DB]プロファイルを使用します。

okv managed-object key create --profile HR_DB --algorithm AES --length 256 --mask "ENCRYPT,DECRYPT" --wallet hr_wallet

このコマンドでは、[HR_DB]プロファイルから得られるokv_client_configパラメータを使用します。その他の構成パラメータ(log_propertyやserverなど)は、[DEFAULT]プロファイルから適用されます。

この例では、マルチマスター・クラスタ環境でプロファイルを使用するユースケースを示します。ここでは、それぞれのノードで固有の設定を使用するクラスタ内のノードごとにプロファイルを作成します。次の例には、クラスタ内の3つのノードに対応するプロファイルが含まれます。

[DEFAULT]
log_property=/usr/local/okv/logging.property
user=okvadmin
server=192.0.2.191

[NODE1]
server=192.0.2.191

[NODE2]
server=192.0.2.192

[NODE3]
server=192.0.2.193

NODE2に対するコマンドを実行する場合は、[NODE2]プロファイルを使用します。

okv server status get --profile NODE2

このコマンドでは、[NODE2]プロファイルから得られるサーバー・エントリを使用します。その他の構成パラメータ設定は、[DEFAULT]プロファイルから得られる設定が使用されます。

[DEFAULT]の設定とプロファイルを使用する前に、okvrestcli.iniのパラメータの優先順位を理解しておいてください。

関連項目

okvrestcli.iniのパラメータの優先順位

親トピック: okvrestcli.ini構成ファイル

2.2.1.4 okvrestcli.iniのパラメータの優先順位

Oracle Key Vault RESTfulサービス・コマンドを実行するときに、構成パラメータの値は優先順位に基づいて決定されます。

パラメータの優先順位

okvrestcli.ini構成ファイルのパラメータ(serverエントリ以外)の優先順位は次のとおりです。

ユーザーがコマンドラインで指定したパラメータ値。
プロファイル・セクションで指定されたパラメータ値。ユーザーは、コマンドラインに--profileパラメータを含めます。
[DEFAULT]プロファイルで指定されたパラメータ値。ユーザーはコマンドラインで何も参照しません。

パラメータの優先順位の動作例

この例では、次のokvrestcli.iniファイルでパラメータの優先順位がどのように動作するかを示します。このファイルには、[DEFAULT]と[HR]プロファイルに異なるuserパラメータの設定が含まれています。

[DEFAULT]
user= psmith

[HR]
user=jgreenberg

例1: デフォルト・ユーザーpsmithを指定する場合は、このユーザーに対する参照をコマンドラインに含めないようにします。
```
okv manage-access endpoint-group add-endpoint --endpoint-group epg_1 --endpoint ep_1
```
例2: デフォルト・ユーザーを上書きして、HRプロファイル内のユーザーjgreenbergを指定する場合は、コマンドラインでHRプロファイルを指定します。
```
okv manage-access endpoint-group add-endpoint --profile HR --endpoint-group epg_1 --endpoint ep_1
```
例3: okvrestcli.iniのすべてのuser設定を上書きする場合は、コマンドラインに--user設定を含めます。
```
okv manage-access endpoint-group add-endpoint --user kjones --endpoint-group epg_1 --endpoint ep_1
```

serverパラメータの優先順位

serverパラメータの優先順位動作は、その他のokvrestcli.iniのパラメータ設定とはわずかに異なります。この設定は、okvrestcli.iniファイルに加えて、okvclient.oraファイルからも得られるためです。okvclient.oraファイルの場所は、okvrestcli.iniのokv_client_configパラメータで指定します。直接指定したserverエントリは、okv_client_configパラメータのserverエントリよりも優先されます。

serverエントリの優先度は次のとおりです。

ユーザーがコマンドラインで指定したserverパラメータ値。
サーバー情報は、okvclient.oraファイルから取得されます。このファイルをユーザーが指定する場合は、コマンドラインにokv_client_configパラメータを含めます。
プロファイル・セクションで指定されたserverパラメータ値。ユーザーは、コマンドラインに--profileパラメータを含めます。
サーバー情報は、プロファイル・セクションのokv_client_configパラメータで設定したokvclient.oraファイルから取得されます。このプロファイルは、ユーザーがコマンドラインで--profileパラメータを使用して指定します。
[DEFAULT]プロファイルで指定されたserverパラメータ値。ユーザーはコマンドラインで何も参照しません。
サーバー情報は、[DEFAULT]セクションのokv_client_configパラメータで指定したokvclient.oraファイルから取得されます。ユーザーはコマンドラインで何も参照しません。

serverパラメータの優先順位の動作例

次の例は、このパラメータの様々な設定方法に基づいて、どのようにserverパラメータの優先順位が機能するかを示しています。

例1: okvrestcli.ini構成ファイルには、次に示す設定があると仮定します。
```
[DEFAULT]
server=192.0.2.190
```
このデフォルト設定を使用するには(IPアドレス192.0.2.190を使用するには)、このデフォルト設定への参照をコマンドラインに含めないようにします。
```
okv manage-access endpoint-group add-endpoint --endpoint-group epg_1 --endpoint ep_1
```
例2: okvrestcli.ini構成ファイルには、次に示す設定があると仮定します。
```
[DEFAULT]
okv_client_config=/usr/local/okv/okvclient/okvclient.ora
```
okv_client_configパラメータは、使用するserver設定が含まれているokvclient.oraファイルを指し示しています。okv_client_configは[DEFAULT]セクションにあるため、このokvclient.oraを使用するには、その参照がコマンドラインに含まれないようにします。
```
okv manage-access endpoint-group add-endpoint --endpoint-group epg_1 --endpoint ep_1
```
例3: okvrestcli.ini構成ファイルには、デフォルトおよび[NODE_1]というプロファイルがあり、次のように設定されていると仮定します。
```
[DEFAULT]
okv_client_config=/usr/local/okv/okvclient/okvclient.ora

[NODE_1]
server=192.0.2.191
```
okv_client_configのデフォルト・サーバー設定を192.0.2.191の[NODE_1]プロファイル設定で上書きするには、コマンドラインに--profileパラメータを含めます。
```
okv manage-access endpoint-group add-endpoint --profile node_1 --endpoint-group epg_1 --endpoint ep_1
```
例4: okvrestcli.ini構成ファイルには、次に示す設定があると仮定します。
```
[DEFAULT]
server = 192.0.2.191

[HR]
okv_client_config=/usr/local/okv/hr_ep/okvclient.ora
```
デフォルトを上書きして例3のようにokvclient.oraファイルのserver設定を使用するには、コマンドに--profileパラメータを含めます。
```
okv manage-access endpoint-group add-endpoint --profile hr --endpoint-group epg_1 --endpoint ep_1
```
例5: 次のokvrestcli.ini構成ファイルがあると仮定します。
```
[DEFAULT]
server = 192.0.2.191

[HR]
okv_client_config=/usr/local/okv/hr_ep/okvclient.ora
```
この設定のすべてを上書きするには、コマンドラインで適切なサーバーIPアドレス設定を直接指定します。
```
okv manage-access endpoint-group add-endpoint --server 192.0.2.192 --endpoint-group epg_1 --endpoint ep_1
```
これは、okv_client_configパラメータ設定についても機能します。
```
okv manage-access endpoint-group add-endpoint --okv_client_config /usr/local/okv/okvclient/okvclient.ora --endpoint-group epg_1 --endpoint ep_1
```
次の例では、名前付きプロファイル(HR)と--serverパラメータの両方を使用しています。この--serverパラメータは、[HR]プロファイルで指定されているokvclient.oraファイルのserver情報を上書きします。
```
okv managed-object key create --profile HR --server 192.0.2.192 --algorithm AES --length 256 --mask "ENCRYPT,DECRYPT" --wallet hr_wallet
```

親トピック: okvrestcli.ini構成ファイル

2.2.1.5 代替構成ファイルの使用方法

okvrestcli.ini構成ファイルの代替パラメータ構成ファイルを使用できます。

デフォルトでは、Oracle Key Vaultはokvrestcli.ini構成ファイルを使用して、Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドの共通に使用される設定を制御します。この構成ファイルの独自のバージョンを作成して、コマンドラインの実行で指定できます。

別の構成ファイルを使用するには、コマンドの実行時に--configパラメータを含めます。次のように、コマンド固有のパラメータの前に--configパラメータを追加します。
```
okv managed-object key create --config full_path_to_conf_file --algorithm AES --length 128 --mask "ENCRYPT,DECRYPT,EXPORT"
```
okvrestcli.iniファイルの場合と同じ優先順位のルールに従います。たとえば、新しい構成ファイルに、[HR]というプロファイルを使用するとします。次に示すように指定します。
```
okv managed-object key create --config full_path_to_conf_file --profile hr --algorithm AES --length 128 --mask "ENCRYPT,DECRYPT,EXPORT"
```

関連項目

親トピック: okvrestcli.ini構成ファイル

2.2.2 okvrestcli_logging.propertiesログ・ファイルのパラメータ設定

okvrestcli_logging.propertiesログ・ファイルでは、Oracle Key Vault RESTfulサービスのアクティビティについてのロギングの処理方法を決定します。

okvrestcli_logging.propertiesの変更はオプションです。これを構成しない場合、RESTfulサービス・ユーティリティ・コマンドを実行すると、Oracle Key Vaultによってデフォルトのロギング・ファイルが作成されて更新されます。

デフォルトでは、okvrestcli_logging.propertiesファイルの場所は、Oracle Key Vault RESTfulサービス・ユーティリティをダウンロードした場所になります。これは、エンドポイントのOKV_HOME/confディレクトリ内にあります。

okvrestcli_logging.propertiesのパラメータ設定は次のとおりです。

java.util.logging.FileHandler.patternでは、出力ファイル名を生成するための次のいずれかのパターンを指定します。デフォルトは%h/java%u.logです。
- /: ローカル・パス名のセパレータです。
- %h: user.homeシステム・プロパティの値です。
- %g: ローテーションされたログを区別するための世代番号です。
- %uは、競合を解決するための一意の番号です。
- %%: 単一のパーセント記号%に変換されます。
java.util.logging.FileHandler.limitでは、1つのファイルに書き込むおおよその最大量(バイト)を指定します。ゼロの場合は、無制限になります。デフォルトは200000です。
java.util.logging.FileHandler.countでは、循環させる出力ファイルの数を指定します。デフォルトは5です。
java.util.logging.FileHandler.formatterでは、使用するFormatterクラスの名前を指定します。デフォルトはjava.util.logging.XMLFormatterです。
java.util.logging.ConsoleHandler.levelでは、ハンドラのデフォルト・レベルを指定します。デフォルトはINFOです。
指定可能なロギング・レベルは、ALL、TRACE、FINEST、FINER、FINE、CONFIG、INFO、WARNING、SEVEREおよびOFFです。

INFO以上のロギングでは完全な詳細が示されます。ロギング・レベルをSEVEREに設定すると、一般に重大な問題に相当するSEVEREロギング・レベルのメッセージのみが表示されます。問題を診断するには、より多くの詳細が必要になることがあります。この情報は、重大な問題の発生によって得られるだけでなく、より多くの情報を生成するレベルによっても取得できます。

次に、この設定の例を示します。

handlers= java.util.logging.FileHandler

# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = /usr/local/okv/okvrest.log
java.util.logging.FileHandler.limit = 200000
java.util.logging.FileHandler.count = 1
#java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.FileHandler.formatter = com.oracle.okv.rest.log.OkvFormatter

# Limit the message that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = FINER
#java.util.logging.ConsoleHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.ConsoleHandler.formatter = com.oracle.okv.rest.log.OkvFormatter

親トピック: Oracle Key Vault RESTfulサービスの構成フィルとロギング・ファイル

2.3 RESTfulサービス・ユーティリティ・コマンドのヘルプ情報の取得

コマンドライン(JSONでは使用できません)で、okv RESTfulサービス・ユーティリティ・コマンドの各コンポーネントの詳細なヘルプ情報を参照できます。

okv categoryコンポーネントのヘルプ情報
okv -helpまたはokv --helpを入力すると、okvコマンドのcategoryコンポーネントのヘルプ情報が返されます。
okv resourceコンポーネントのヘルプ情報
okv category --helpを入力すると、指定したcategoryのresourceコンポーネントに関する詳細情報が返されます。
okv actionコンポーネントのヘルプ情報
okv category resource --helpを入力すると、categoryおよびresourceを指定したokvコマンドのactionコンポーネントに関する詳細情報が返されます。
okv optionコンポーネントのヘルプ情報
okv category resource action --helpを入力すると、category、resourceおよびactionを指定したokvコマンドのoptionコンポーネントに関する詳細情報が返されます。

親トピック: Oracle Key Vault RESTfulサービスのスタート・ガイド

2.3.1 okv categoryコンポーネントのヘルプ情報

okv -helpまたはokv --helpを入力すると、okvコマンドのcategoryコンポーネントのヘルプ情報が返されます。

構文: okv --helpまたはokv -help

入力例: okv --helpまたはokv -help

出力例:

Oracle Key Vault REST CLI Version 21.5.0.0.0 Built 11/09/2022 17:44
Usage: okv <category> <resource> <action> [<rest-cli-parameters>] [<parameters>]

Command:
  <category> : 
    managed-object                -     Commands that endpoints can execute to manage security objects.       
    backup                        -     Administration commands to manage Oracle Key Vault appliance backup and restore.
    admin                         -     Administration commands to manage client wallets and endpoints.       
    manage-access                 -     Access management commands to manage wallets and endpoint groups.     
    server                        -     Monitoring commands to retrieve static or dynamic information about an Oracle Key Vault server.
    cluster                       -     Monitoring commands to retrieve static or dynamic information about a cluster or a cluster node.
    primary-standby               -     Monitoring commands to retrieve static or dynamic information about the Oracle Key Vault primary-standby configuration.
    crypto                        -     Commands to perform cryptographic operations.   
    metrics                       -     Commands to perform metrics operations.                      

<rest-cli-parameters>:
    --client_wallet <arg>       Client wallet.
    --config <arg>              OKV REST CLI configuration file
                                (okvrestcli.ini) location.
    --from-json <arg>           Input file in JSON.
    --generate-json-input       Generate JSON input template file.
    --help                      List available options.
    --okv_client_config <arg>   OKV Client configuration file
                                (okvclient.ora) location.
    --output_format <arg>        Command output format, 'text' or 'json
    --password <arg>            User password.
    --profile <arg>             Profile name in configuration file
                                (okvrestcli.ini).
    --server <arg>              OKV server IP address or hostname.
    --user <arg>                Username.
    --version <arg>             Version for backward compatibility.

rest-cli-parametersは、すべてのコマンドに適用されるパラメータのリストを示します。

親トピック: RESTfulサービス・ユーティリティ・コマンドのヘルプ情報の取得

2.3.2 okv resourceコンポーネントのヘルプ情報

okv category --helpを入力すると、指定したcategoryのresourceコンポーネントに関する詳細情報が返されます。

構文: okv category --help

入力例: okv admin --help

出力例:

Oracle Key Vault REST CLI Version 21.4.0.0.0 Built 12/13/2021 01:19
Usage: okv admin <resource> <action> [<rest-cli-parameters>] [<parameters>]
 
Command:
  <category> : admin
  <resource> :
    endpoint                      -     Commands to manage endpoints.                                        
    client-wallet                 -     Commands to manage client wallets.

親トピック: RESTfulサービス・ユーティリティ・コマンドのヘルプ情報の取得

2.3.3 okv actionコンポーネントのヘルプ情報

okv category resource --helpを入力すると、categoryおよびresourceを指定したokvコマンドのactionコンポーネントに関する詳細情報が返されます。

構文: okv category resource --help

入力例: okv admin endpoint --help

出力例:

Oracle Key Vault REST CLI Version 21.4.0.0.0 Built 12/13/2021 01:19
Usage: okv admin endpoint <action> [<rest-cli-parameters>] [<parameters>]

Command:
  <category> : admin
  <resource> : endpoint
  <action> :
    create                        -     Add a new endpoint to the Oracle Key Vault.                          
    delete                        -     Remove an endpoint from the Oracle Key Vault.                        
    update                        -     Update the settings of an endpoint.                                  
    check-status                  -     Display the current state of an endpoint. The state will be either ACTIVE or PENDING.
    get                           -     Retrieve information about an endpoint.                              
    list                          -     Display a list of endpoints.                                         
    download                      -     Download the endpoint software (okvclient.jar) to the specified directory.
    provision                     -     Download and install the endpoint software in the specified directory.
    re-enroll                     -     Re-enroll a previously enrolled endpoint.                             
    suspend                       -     Suspend an endpoint.                                                 
    resume                        -     Resume an endpoint.                                                  
    get-enrollment-token          -     Retrieve an enrollment token for a registered endpoint.              
    re-enroll-all                 -     Re-enroll all previously enrolled endpoints.

親トピック: RESTfulサービス・ユーティリティ・コマンドのヘルプ情報の取得

2.3.4 okv optionコンポーネントのヘルプ情報

okv category resource action --helpを入力すると、category、resourceおよびactionを指定したokvコマンドのoptionコンポーネントに関する詳細情報が返されます。

構文: okv category resource action --help

入力例: okv admin endpoint provision --help

出力例:

Oracle Key Vault REST CLI Version 21.4.0.0.0 Built 12/13/2021 01:19

Usage: okv admin endpoint provision [<rest-cli-parameters>] <parameters>

The okv admin endpoint provision command downloads and installs the endpoint software for an endpoint in the specified directory.

Command:
  <category> : admin
  <resource> : endpoint
  <action>   : provision
 
Required Parameters:
    --endpoint <arg>   Name of the endpoint.
    --location <arg>    Path to the location where to install the endpoint
                       software. For Transparent Data Encryption (TDE)
                       environments, specify WALLET_ROOT/okv as the
                       installation directory.

Optional Parameters:
    --auto-login <arg>   Enter on of the following values:
                         TRUE: to enable auto-login authentication
                         FALSE: (default) to store the endpoint
                         credentials that are used to connect to the
                         Oracle Key Vault server in a password-protected
                         wallet. When --auto-login is set to FALSE, then
                         you will be promoted to enter a password
                         interactively.

親トピック: RESTfulサービス・ユーティリティ・コマンドのヘルプ情報の取得

2.4 Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドの実行

Oracle Key Vaultには、RESTfulサービス・ユーティリティ・コマンドを実行するための様々な方法があります。

RESTfulサービス・ユーティリティ・コマンドの構文
RESTfulサービス・ユーティリティ・コマンドの構文は、okvコマンドを使用することで動作します。
RESTfulサービス・ユーティリティ・コマンドの実行方法
Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドは、コマンド固有のパラメータをコマンドラインで直接指定して実行することも、JSON構文を使用して実行することもできます。
エンドポイントとしてOracle Databasesを自動的にエンロールするスクリプトの作成
データベース管理者がOracle Key VaultにOracle Databaseエンドポイントを自動的にエンロールするために実行できるスクリプトを作成できます。

親トピック: Oracle Key Vault RESTfulサービスのスタート・ガイド

2.4.1 RESTfulサービス・ユーティリティ・コマンド構文

RESTfulサービス・ユーティリティ・コマンドの構文は、okvコマンドを使用することで動作します。

RESTfulサービス・ユーティリティ・コマンドに使用する構文は、次のとおりです。

okv category resource action rest-cli-configuration-parameters command-parameters

この指定内容についての説明は次のとおりです。

categoryは、実行するコマンドのタイプを表します。managed-object、admin、cluster、backupなどのコマンドのタイプがあります。
resourceは、コマンドを実行するリソースのタイプです。endpoint、wallet、certificateなどのリソースのタイプがあります。
actionは、リソースに対して実行する処理です。create、add、locate、deleteなどの処理があります。
rest-cli-configuration-parametersには、REST CLI構成ファイルで指定するパラメータを含めます。--userや--client_walletなどのパラメータがあります。これに該当するパラメータは、すべてのコマンドに適用されます。
command-parametersは、エンドポイントの作成時にコマンドに必要なパラメータです。--descriptionや--emailなどのパラメータがあります。

このガイドでは、コマンドはokvの後にcategory、resource、actionを使用することで識別します。コマンドで必要な場合は、rest-cli-configuration-parameters command-parametersも使用します。たとえば、エンドポイントを作成する場合は、okv admin endpoint createコマンドを使用します。このコマンドの完全な構文は次のとおりです。

okv admin endpoint create --endpoint endpoint_name --description "description" --email email_address --platform platform --type type --unique TRUE|FALSE

Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドの構文は、次のルールに従います。

コマンドの指定は、okv category resource action rest-cli-configuration-parameters command-parametersの順序にする必要があります。category、resourceおよびactionは、次に示す順序で指定する必要があります。REST CLI構成パラメータは、コマンド固有のパラメータよりも前に指定する必要があります。
構成ファイル(okvrestcli.ini)の識別は、OKV_RESTCLI_CONFIG環境変数を使用することで可能になります。この変数は、RESTfulサービス・コマンドライン・ユーティリティ・スクリプトokv自体で設定します。これにより、この構成ファイルをコマンドの実行ごとに指定する必要がなくなります。

ノート:

下位互換性の確保のために、Oracle Key Vaultリリース21.1より前から存在していたRESTfulサービス・ユーティリティ・コマンドライン・インタフェースも引き続きサポートされています。そのインタフェースは、okvrestclipackage.zipをダウンロードすることで使用できます。

ほとんどのRESTfulサービス・ユーティリティ・コマンドは、JSON入力をサポートしています。このガイドでは、JSONをサポートするコマンドにはJSONの使用例を示します。

親トピック: Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドの実行

2.4.2 RESTfulサービス・ユーティリティ・コマンドの実行方法

Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドは、コマンド固有のパラメータをコマンドラインで直接指定して実行することも、JSON構文を使用して実行することもできます。

コマンドラインを使用したRESTfulサービス・ユーティリティ・コマンドの実行
コマンドラインからRESTfulサービス・ユーティリティ・コマンドを実行する場合は、コマンド固有のすべてのパラメータをコマンドラインで指定します。
JSON構文を使用したRESTfulサービス・ユーティリティ・コマンドの実行
RESTfulサービス・ユーティリティ・コマンドでは、JSON構文がサポートされています。JSON出力の生成後に、その出力をコマンドのコマンドライン実行と組み合せて使用できます。
RESTfulサービス・ユーティリティ・コマンドの出力形式の指定
REST CLIパラメータ--output_formatを使用すると、出力形式をJSONとテキストのどちらにするかを選択できます。
コマンドラインおよびJSONファイルで指定するパラメータのネーミング規則
コマンドラインで指定するコマンド・パラメータに使用されるネーミング規則は、JSON構文で使用されるネーミング規則とは異なります。

親トピック: Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドの実行

2.4.2.1 コマンドラインを使用したRESTfulサービス・ユーティリティ・コマンドの実行

コマンドラインからRESTfulサービス・ユーティリティ・コマンドを実行する場合は、コマンド固有のすべてのパラメータをコマンドラインで指定します。

たとえば、okv manage-access endpoint-group add-endpointには、endpoint-groupとendpointのパラメータがあります。

okv manage-access endpoint-group add-endpoint --endpoint-group endpoint_group_name --endpoint endpoint_member

コマンドラインでREST CLI構成パラメータを指定するときには、コマンド固有のパラメータの前にREST CLI構成パラメータを指定する必要があります。次の例では、--profile hrはrest_cli_configuration_parametersの1つです。その後に、okv managed-object key createコマンドのcommand_parametersが続きます。

okv managed-object key create --profile hr --algorithm AES --length 128 --mask "ENCRYPT,DECRYPT,EXPORT"

関連項目

コマンドラインおよびJSONファイルで指定するパラメータのネーミング規則

親トピック: RESTfulサービス・ユーティリティ・コマンドの実行方法

2.4.2.2 JSON構文を使用したRESTfulサービス・ユーティリティ・コマンドの実行

RESTfulサービス・ユーティリティ・コマンドでは、JSON構文がサポートされています。JSON出力の生成後に、その出力をコマンドのコマンドライン実行と組み合せて使用できます。

JSON入力を使用してRESTfulサービスのコマンドを実行するには、まずコマンド固有のパラメータ値を使用してJSON入力ファイルを準備しておく必要があります。その後で、パラメータ--from-json json-input-file.jsonを使用してコマンドを実行します。

JSON入力を使用してRESTfulサービス・ユーティリティ・コマンドを実行する際の推奨プロセスは、次のとおりです。

コマンド専用に設計されたJSON入力を生成します。この入力を生成するには、--generate-json-inputパラメータを指定してコマンドを実行します。たとえば:

okv managed-object key create --generate-json-input

このコマンドに応じて生成されるJSON入力は次のとおりです。

{
  "service": {
    "category": "managed-object",
    "resource": "key",
    "action": "create",
    "options": {
      "algorithm": "#3DES|AES",
      "length": "#112,168(3DES)|128,192,256(AES)",
      "mask": [ "#ENCRYPT", "#DECRYPT", "#WRAP_KEY", "#UNWRAP_KEY", "#EXPORT", 
         "#DERIVE_KEY", "#GENERATE_CRYPTOGRAM", "#VALIDATE_CRYPTOGRAM", 
         "#TRANSLATE_ENCRYPT", "#TRANSLATE_DECRYPT", "#TRANSLATE_WRAP",
         "#TRANSLATE_UNWRAP" ],
      "wallet": "#VALUE",
      "attributes": {
         "extractable" : "#TRUE|FALSE"
      }
    }
  }
}

生成された入力をファイルに保存して、タスクを実行できるように編集します。先頭が#の値は変更する必要があります。この例では、ファイルcreate_key.jsonをコールして、次の値を使用するように編集します。

{
  "service": {
    "category": "managed-object",
    "resource": "key",
    "action": "create",
    "options": {
      "algorithm": "AES",
      "length": "256",
      "mask": [
        "ENCRYPT",
        "DECRYPT"
      ],
      "wallet": "hr_wallet",
      "attributes": {
         "extractable" : "FALSE"
      }
    }
  }
}

処理を実行するには、okv managed-object key createコマンドの実行時に、前の手順で編集したJSON入力ファイルの名前を指定するための--from-jsonパラメータを指定します。
たとえば、デフォルトの構成設定を使用してokv managed-object key createコマンドを実行するには、次のようにします。
```
okv managed-object key create --from-json create_key.json
```
JSON入力を使用する場合は、コマンドラインでコマンドのパラメータを指定することもできます。コマンドラインで指定したコマンド・パラメータは、JSON入力ファイルで指定した同じパラメータよりも優先されます。
- 例1: JSONファイルcreate_key.jsonで指定した長さとは異なる長さのキーを作成するために、コマンドラインでlengthパラメータを指定します。
```
okv managed-object key create --from-json create_key.json --length 128
```
  コマンドラインでコマンド・パラメータを上書きすると、JSON入力ファイルを変更することなく、同じJSONファイルを使用して、同じコマンドを異なるパラメータで実行できます。
- 例2: 複数の管理対象オブジェクトに同じ属性値を適用するために、入力JSONファイルで属性の設定を指定して、コマンドラインでオブジェクトのUUIDを指定します。次に示すJSON入力ファイルadd_attributes.jsonについて考えてみます。
```
{
  "service" : {
    "category" : "managed-object",
    "resource" : "attribute",
    "action" : "add",
    "options" : {
      "uuid" : "2359E04F-DA61-4F7C-BF9F-913D3369A93A",
      "attributes" : {
        "contactInfo" : "psmith@example.com",
        "deactivationDate" : "2024-12-31 09:00:00",
        "name" : {
                   "value" : "prod-hrdb-mkey",
                   "type" : "text"
         },
        "protectStopDate" : "2024-09-30 09:00:00"
      }
    }
  }
}
```
  この属性をUUIDが2359E04F-DA61-4F7C-BF9F-913D3369A93Aのオブジェクトに適用するには、次を実行します。
```
okv managed-object attribute add --from-json add_attributes.json --uuid 2359E04F-DA61-4F7C-BF9F-913D3369A93A
```

関連項目

コマンドラインおよびJSONファイルで指定するパラメータのネーミング規則

親トピック: RESTfulサービス・ユーティリティ・コマンドの実行方法

2.4.2.3 RESTfulサービス・ユーティリティ・コマンドの出力形式の指定

REST CLIパラメータ--output_formatを使用すると、出力形式をJSONとテキストのどちらにするかを選択できます。

デフォルトでは、RESTfulサービス・ユーティリティ・コマンドの出力はJSON形式です。ただし、特定のコマンドでは、--output_format textを指定するとテキスト形式でコマンド出力を生成できます。

例: 次のコマンドでは、新しく作成されたキーのUUIDがテキスト出力として返されます:

okv managed-object key create --output_format text --algorithm AES --length 25609285F83-CC1F-4FAF-BF6C-E2262733F369

ノート:

--output_format textは、次のコマンドでのみサポートされています:

okv managed-object certificate get
okv managed-object certificate register
okv managed-object certificate-request get
okv managed-object certificate-request register
okv managed-object key create
okv managed-object key get
okv managed-object key register
okv managed-object object activate
okv managed-object object destroy
okv managed-object object locate
okv managed-object object revoke
okv managed-object opaque get
okv managed-object private-key register
okv managed-object public-key get
okv managed-object public-key register
okv managed-object secret get
okv managed-object secret register
okv managed-object wallet add-member
okv managed-object wallet delete-member
okv managed-object wallet list

親トピック: RESTfulサービス・ユーティリティ・コマンドの実行方法

2.4.2.4 コマンドラインおよびJSONファイルで指定するパラメータのネーミング規則

コマンドラインで指定するコマンド・パラメータに使用されるネーミング規則は、JSON構文で使用されるネーミング規則とは異なります。

JSON構文のパラメータには、camelCaseネーミング規則(walletUserやclientWalletなど)を使用します。コマンドラインで使用するパラメータのネーミング規則は、一般に次のルールに従います。

パラメータ名には先頭に2つのハイフンを付けます(たとえば、--user)
各単語はハイフンで区切ります(たとえば、--endpoint-group)
すべての単語は小文字にします(たとえば、--endpoint)

コマンドラインのパラメータ名walletUserとclientWalletに相当するJSON構文のパラメータは、それぞれ--wallet-userと--client-walletです。

親トピック: RESTfulサービス・ユーティリティ・コマンドの実行方法

2.4.3 エンドポイントとしてOracle Databasesを自動的にエンロールするスクリプトの作成

データベース管理者がOracle Key VaultにOracle Databaseエンドポイントを自動的にエンロールするために実行できるスクリプトを作成できます。

Oracle Key Vault管理者は、データベース管理者が後で共有の場所からダウンロードし、データベース・サーバー上で実行して、Oracle Key Vault管理者の介入なしにデータベースをOracle Key Vaultに自動的にオンボードできるスクリプトおよびファイルのセットを作成できます。Oracle Key Vault管理者は、次のものをパッケージ化します。

Oracle Key Vault RESTfulサービス・パッケージ
ewallet.p12およびcwallet.ssoウォレット・ファイル
run-me.shスクリプト

次の手順では、これらのコンポーネントを作成する方法を説明します。

RESTfulサービス・パッケージをダウンロードし、作業ディレクトリに格納します。ここでは、他のファイルも作成します。
```
curl -O -k https://Oracle_Key_Vault_IP_address:5695/okvrestclipackage.zip
```
ユーザーを作成して、そのユーザーにエンドポイント作成権限を付与します(この作業をまだ実行していない場合)。
Oracle Key Vault管理コンソールを使用して、このユーザーを作成します。このトピックの手順では、このユーザーにrestuser_ronという名前を付けて、エンドポイント作成権限を付与します。システム管理者ロールを持つユーザーがrestuser_ronアカウントを作成して、そのユーザーにエンドポイント作成権限を付与します。最後に、restuser_ronユーザーがログインして、ワンタイム・パスワードを永続パスワードに変更する必要があります。Oracle Key VaultクラスタをオンボードADB- on- ExaCCに対して準備している場合、キー管理者は restuser_Ronに「エンドポイント・グループの作成」権限を追加で付与する必要があります。
ダウンロードしたokvrestclipackage.zipファイルを、その他のファイルを作成するディレクトリに解凍します。
okvrestclipackage.zipファイルの解凍後に、treeコマンドを使用すると、解凍したディレクトリ構造のコンテンツを確認できます。
```
$ tree
bin
-- okv
-- okv.bat
lib
–- okvrestcli.jar
conf
-- okvrestcli.ini
-- okvrestcli_logging.properties
```

bin/okvファイルを編集します。

たとえば:

#!/bin/bash
export OKV_RESTCLI_DIR=$(dirname "${0}")/..
#export OKV_RESTCLI_CONFIG=$OKV_RESTCLI_DIR/conf/okvrestcli.ini
if [ -z "$JAVA_HOME" ]
then
  echo "JAVA_HOME environment variable is not set."
  exit 1
fi

if [ -z "$OKV_RESTCLI_CONFIG" ]
then
  echo "OKV_RESTCLI_CONFIG environment variable is not set."
  exit 1
fi

export OKV_RESTCLI_JAR=$OKV_RESTCLI_DIR/lib/okvrestcli.jar
$JAVA_HOME/bin/java -jar $OKV_RESTCLI_JAR "$@"

この指定内容についての説明は次のとおりです。

export OKV_RESTCLI_CONFIG=$OKV_RESTCLI_DIR/conf/okvrestcli.ini行のコメントを解除します。

conf/okvrestcli.iniファイルを編集します。
たとえば:
```
[Default]
log_property=/usr/local/okv/conf/okvrestcli_logging.properties
server=192.0.2.181
okv_client_config=/usr/local/okv/conf/okvclient.ora
user=restuser_ron
client_wallet=/home/oracle
```
この指定内容についての説明は次のとおりです。
- serverは、Oracle Key VaultサーバーのIPアドレスです(たとえば、192.0.2.181)。
- userは、ステップ2で作成したOracle Key Vaultユーザーのユーザー名です。
- client_walletは、restuser_ronユーザーの永続パスワードを格納するウォレットへの絶対パスです。userオプションを含めているため、このコマンドはウォレットからユーザーの資格証明を取得して、Oracle Key Vaultサーバーとの接続を確立します。
次のコマンドを実行して、ウォレットを作成し、restuser_ronユーザーのパスワードを挿入します。
```
okv admin client-wallet add --client-wallet /home/oracle --wallet-user restuser_ron
Password: restuser_ron_password
```
このコマンドでは、/home/oracleディレクトリにパスワード保護されたウォレットewallet.p12と自動ログイン・ウォレットcwallet.ssoを作成します。
データベース管理者がダウンロードすることを目的として、Oracle Key Vault管理者が作成するパッケージに含まれているrun-me.shスクリプトと同様のスクリプトを作成します。
run-me.shでは、仮想ウォレットとそれに関連付けるエンドポイントの一意の名前が含まれたシェル・スクリプトokv-ep.shを作成します。サイトでウォレットおよびその他のコンポーネントの名前に通常使用される命名規則を使用します。
```
$ more run-me.sh
#!/bin/bash
export EP_NAME=${ORACLE_SID^^}_on_${HOSTNAME/.*}
export WALLET_NAME=${ORACLE_SID^^}
curl -Ok https://192.0.2.181:5695/okvrestclipackage.zip
unzip -Vj okvrestclipackage.zip lib/okvrestcli.jar -d ./lib
cat > /home/oracle/okv-ep.sh  << EOF
#!/bin/bash
mkdir -pv ${ORACLE_BASE}/product/okv
okv manage-access wallet create --wallet ${WALLET_NAME} --unique FALSE
okv admin endpoint create --endpoint ${EP_NAME} --description "$HOSTNAME, $(hostname -i)" --type ORACLE_DB --platform
 LINUX64 --subgroup "USE CREATOR SUBGROUP" --unique FALSE 
okv admin endpoint update --endpoint ${EP_NAME} --strict-ip-check TRUE
okv manage-access wallet set-default --wallet ${WALLET_NAME} --endpoint ${EP_NAME}
expect << _EOF
    set timeout 120
    spawn okv admin endpoint provision --endpoint ${EP_NAME} --location ${ORACLE_BASE}/product/okv --auto-login FALSE
    expect "Enter Oracle Key Vault endpoint password: "
    send "change-on-install\r"
    expect eof
_EOF
EOF
chmod +x okv-ep.sh
more ./okv-ep.sh
```
この指定内容についての説明は次のとおりです。
1. export ...はuppercase(ORACLE_SID)_on_short_hostnameからエンドポイント名を作成し、大文字の(ORACLE_SID)からWALLET_NAMEを作成します。Oracle Real Application Clusters (Oracle RAC)環境で、ORACLE_SIDを大文字の(ORACLE_UNQNAME)に置き換えます。
2. curl ...では、データベース管理者がrun-meスクリプトを実行したときに、適切な現行バージョンのOracle Key Vault RESTfulサービス・パッケージをダウンロードします。
3. unzip ...は、okvrestcli.jarファイルのみを抽出し、それを./libディレクトリに配置します。
4. mkdir -pv ${ORACLE_BASE}/product/okvでは、Oracle Key Vaultクライアント・ソフトウェアのインストール・ディレクトリを作成します。Oracle Databaseリリース18c以降の場合、これはWALLET_ROOT/okvと同じです(/product/okvはディレクトリの例です)。
5. okv manage-access wallet createでは、Oracle Key Vaultに(共有)仮想ウォレットを作成します。ここでは、ウォレット名はuppercase($ORACLE_SID)と同じです。
6. okv admin endpoint createでは、ステップaのexportコマンドで作成したエンドポイントに関連した名前が付けられたエンドポイントを、type=ORACLE_DB, platform=LINUX64とフリー・テキストfully_qualified_hostname, IP addressで作成します。--subgroupオプションは、データベース・エンドポイントが最初に接続する優先Oracle Key Vault読取り/書込みペアを決定します。ここでは、それはエンドポイントがエンロールされるOracle Key Vaultサブグループです。
7. okv manage-access wallet set-defaultでは、デフォルト・ウォレットを設定します。つまり、ステップfで作成したエンドポイントをステップeで作成した共有ウォレットに関連付けます。
8. expectでは、okv admin endpoint provisionコマンドを実行して、プロンプトが表示されときに自動的にパスワードを挿入します。expectを使用する利点は、psコマンドを使用してもパスワードを取得できないことです。
run-me.shスクリプトを複製して、様々な状況で使用するプライマリ・スクリプトとセカンダリ・スクリプトを作成します。
プライマリ・スクリプトは、単一インスタンス・データベースおよび最初のOracle RACインスタンスに使用されます。セカンダリ・スクリプトは、プライマリ・データベースの残りのOracle RACノードおよび対応するスタンバイOracle RACデータベースのすべてのノードに使用されます。このセカンダリ・スクリプトは、最初のインスタンスで作成された共有ウォレットにエンドポイントを関連付けます。
1. run-me.shスクリプトの名前をprimary-run-me.shに変更します。
2. primary-run-me.shをsecondary-run-me.shという名前の新しいファイルにコピーします。
3. secondary-run-me.shを開き、次の行を削除します。
```
okv manage-access wallet create --wallet ${ORACLE_SID^^} --unique FALSE
```

スクリプトを実行可能にします。

$ chmod +x primary-run-me.sh
$ chmod +x secondary-run-me.sh

各スクリプトをテストして、okv-ep.shファイルを作成できることを確認します。
```
$ ./primary-run-me.sh
$ ./secondary-run-me.sh
```
次のコマンドを実行して、仮想ウォレットおよびエンドポイントの名前が命名規則に従っていることを確認します。
```
$ more okv-ep.sh
```
各スクリプトに対して2つの.zipファイル・パッケージを作成します。
各パッケージには次のコンテンツが必要です。
- primary.zipには、primary-run-me.sh、ewallet.p12、cwallet.sso、binおよびconfディレクトリが含まれます。./libディレクトリは含めないでください。./libライブラリは、primary-run-me.shスクリプトの実行時にオンデマンドで作成および移入されます。
- secondary.zipには、secondary-run-me.sh、ewallet.p12、cwallet.sso、./binおよび./confディレクトリが含まれます。./libディレクトリは含めないでください。./libライブラリは、secondary-run-me.shスクリプトの実行時にオンデマンドで作成および移入されます。
これらの2つの.zipファイルを、データベース管理者が共有ファイル・サーバーからダウンロードできるようにします。
スクリプトをダウンロードして実行する場所をデータベース管理者に指示します。
- 単一インスタンス・データベースまたは最初のOracle RACインスタンスで、primary-run-me.shスクリプトを実行します。Oracle Data Guard環境の場合は、プライマリOracle RACデータベースのリード・ノードでスクリプトを実行します。
- プライマリ・データベースの残りのすべてのOracle RACノードおよび対応するスタンバイOracle RACデータベースのすべてのノードで、secondary-run-me.shスクリプトを実行します。

関連項目

ステップ4: RESTfulサービス・ユーティリティのダウンロード

親トピック: Oracle Key Vault RESTfulサービス・ユーティリティ・コマンドの実行

2.5 オブジェクトのネーミング・ガイドライン

このネーミング・ガイドラインは、ユーザー、ユーザー・グループ、エンドポイント、エンドポイント・グループおよび仮想ウォレットのOracle Key Vaultオブジェクトに影響します。

該当するオブジェクトのネーミング規則は次のとおりです。

エンドポイント、エンドポイント・グループ、ユーザー・グループおよび仮想ウォレットの名前に使用できる文字は、文字(a–z、A–Z)、数字(0-9)、アンダースコア(_)、ピリオド(.)およびハイフン(-)です。
ユーザー名に使用できる文字は、文字(a–z、A–Z)、数字(0-9)およびアンダースコア(_)です。
ほとんどの環境で、許容されている名前の長さの最大バイト数は120バイトです。バージョン18.4以前のOracle Key Vaultクラスタがある場合、オブジェクト名の最大長は24バイトです。
ユーザー、ユーザー・グループ、エンドポイントおよびエンドポイント・グループの名前は、大/小文字が区別されません。たとえば、psmithとPSMITHは、Oracle Key Vaultでは同じユーザーとみなされます。
仮想ウォレットの名前は、大文字と小文字が区別されます。たとえば、wallet_hrとWALLET_HRは、Oracle Key Vaultでは異なる2つのウォレットと見なされます。

親トピック: Oracle Key Vault RESTfulサービスのスタート・ガイド

2.6 RESTfulサービス・ユーティリティ・コマンドでの日時の設定方法

サポートされている書式を使用して、日付またはタイムスタンプと、期間を指定します。

期間書式

duration書式は、期間または時間間隔を指定します。この書式は、ISO-8601標準のサブセットに基づいています。構文は次のとおりです。

PnYnMnDTnHnMnS

または

PnW

この指定内容についての説明は次のとおりです。

Pは、期間表現の先頭に配置する期間指定子です。
nは数値です。
Pnの後に続く大文字は、日付値または時間値です。日付値は次のとおりです:
- Yは、カレンダ年数を示します。
- Mは、カレンダ月数を示します。
- Dは、カレンダ日数を示します。
- Wは、週数を示します。このオプションは、時間値を含む他のオプションとともに指定できません。
Tは、次のように残りの値が時間値を表していることを示します。
- nHは、n時間を意味します。
- nMは、n分を意味します。
- nSは、n秒を意味します。

例:

10分: PT10M
2時間30分: PT2H30M
5時間: PT5H
3日: P3D
45秒: PT45S
5時間、10分: PT5H10M
4週: P4W

日時書式

RESTfulサービス・ユーティリティで使用される日時書式はUTCです。日時を設定する4つの方法は次のとおりです。

timestamp。この書式は、ISO 8601と互換性があります。この例は、「2024年12月31日の午前9時にアクティブ化日を開始する」となります。
```
"activationDate" : "2024-12-31 09:00:00",
```
NOW。次の例では、コマンドの実行時にアクティブ化日を現在の時刻に設定します。
```
"activationDate" : "NOW",
```
timestamp+duration。この例は、「2024年12月31日の午後1時にアクティブ化日を開始する」となります。
```
"activationDate" : "2024-12-31 09:00:00+PT4H",
```
NOW+duration。次の例は、「アクティブ化日を現在から10分後に設定する」となります。
```
"activationDate" : "NOW+PT10M",
```

ノート:

セキュリティ・オブジェクトの日時属性(ActivationDate、DeactivationDate、ProcessStartDate、ProtectStopDateなど)をエポック時間に設定することは、その属性を設定しないのと同じ効果があります。たとえば、セキュリティ・オブジェクトのActivationDate属性を1970-01-01 00:00:00に設定してオブジェクトをただちにアクティブ化すると、そのオブジェクトは「Pre-Active」状態のままになります。これは、Oracle Key Vaultでその属性のエポック値が、その属性が設定されていないかのように処理されるためです。オブジェクトの属性をリストする際は、エポック時間値に設定された日時属性は含まれません。

親トピック: Oracle Key Vault RESTfulサービスのスタート・ガイド

2.7 LDAPユーザーによるRESTfulサービスの使用方法

通常のOracle Key Vault管理者と適切に認可されたLDAPユーザーは、どちらもサーバーにログインしてOracle Key Vault RESTfulサービス・ユーティリティ・コマンドを実行できます。

LDAPユーザーがOracle Key Vault RESTfulサービス・ユーティリティ・コマンドを実行するときには、コマンドの実行前にOracle Key Vaultによってユーザーが認証されます。セッションに対して有効なユーザーの認可は、認証プロセス中に判断されます。

RESTfulサービス・コマンドの実行時には、次の方法を使用して、--userパラメータでユーザーのユーザー名とドメイン名を指定します。
- サポートされているいずれかの形式(次を参照)のLDAPユーザー名と、縦線(|)で区切られたドメイン名。
  - sAMAccountName|LDAP_domain_name
    例: psmith|hr.example.com
  - NetBiosDomainName\\sAMAccountName|LDAP_domain_name.
    例: hr\\psmith|hr.example.com
    
    二重バックスラッシュ(\\)は、hr\\psmithがhr\psmithとして解釈されます。
  - userPrincipalName|LDAP_domain_name
    例: psmith@hr.example.com|hr.example.com
- LDAPユーザーのユーザー・プリンシパル名。
  例: psmith@hr.example.com

関連項目

RESTfulサービスの使用に必要な権限

親トピック: Oracle Key Vault RESTfulサービスのスタート・ガイド