CipherTrust Manager: REST APIよる鍵管理をためす

概要

CM (CipherTrust Manager) には、GUI、 CLI(ksctl)、REST APIと３つのインターフェースが存在し、これらのインターフェースを介して鍵管理等の処理が可能です

CMには"API playground "が提供されており、postman等のREST Clientや、プログラミングなしに、REST APIを試すことができます
"API playground"は、CMのREST APIのドキュメントも兼ねており、全APIの詳細をご確認いただけます

今回は、CMのREST APIの利用方法について解説します

目的

最短で、CMの"API playground"の利用方法を理解し、実際にREST APIを用いて鍵操作を試してみます

参照ドキュメント

• CipherTrust Manager 製品ドキュメント
  • REST Interface
  • Authenticating to the REST API
  • CM REST API Specification - Swagger file format

手順

CMのデプロイ

CMのデプロイがまだお済みでない場合、下記をご参照されCMのデプロイをおこなってください
（本記事の検証内容では、"Trial Evaluation"や正式ライセンス等、ライセンスのアクティベーションは必要ありません。）

API Playgruond へのアクセス

CMのGUI管理画面の"API & CLI Documentation"をクリックします

または、CM管理画面へログイン後、右上の"API"をクリックします

API Playgroundへのログイン

”API Playgruond"が表示されました

右上の"Authentication"をクリックし、CMの管理者アカウントの"username"と"password"を入力、"POST"をクリックします

ログインが成功すると、どの”Domain"にログインしたか（今回はDomainを用いていないため"root")、及び、今回の認証の有効期間の残り時間が表示されます

有効期間の残り時間がなくなると、REST APIの呼び出しに失敗します
再度、認証するためには"Re Authenticate"をクリックして下さい

CM 管理画面よりテスト用の鍵の作成

左メニューの"Keys"をクリックします
現在CMで管理している鍵が表示されます
"+ Add Key"をクリックします

"Key Name"（任意: 例"test_key"）を入力し"Add Key"をクリックします

今回の検証では、この鍵をExportするため"Exportable"を有効に設定します
(実際の運用では、Exportする必要がない場合は、セキュリティ上、無効のままの運用をお勧めします）

以上の操作にてテスト用の鍵が作成できました
（これらの操作は REST APIやCLIでも可能です)

API playground 上での REST API による鍵操作

左上の検索用のtext box にて、"key2"と入力します
下の検索結果から"Keys"を選択します
鍵操作"Keys"のAPIの説明が表示されます

"List"をクリックします
鍵の一覧取得のためのAPIの説明が確認できます

"?"マークをクリックすると、各パラメータの説明が表示されます
今回は、先程作成した鍵(例: "test_key")のみ確認するため、パラメータ"name"に鍵の名前を入力します

画面の下へスクロールし、"GET"をクリックして、REST APIを呼び出しします

呼び出しが成功すると、REST API呼び出しの応答が表示されます
鍵の名前"test_key"の情報表示されました
"id"の値をコピーします

"Export"をクリックします

"id"をクリックします

先ほどコピーしていた鍵("test_key")のidを入力（ペースト）します

"body"にPOSTするパラメータが確認できます
"schema"をクリックすると、全パラメータが確認できます
各パラメータをクリックすると、そのパラメータの説明が確認できます

今回はすべてのパラメータを削除しました

"POST"をクリックし、REST APIを呼び出しします

Exportが成功しました
"name"に鍵の名前(例: "test_key") が確認できます

画面下へスクロールすると、"material"にExportされた鍵の値を確認することができます

curl コマンド を用いての REST API による鍵操作

API playgroundの代わりに、curlコマンドを利用して、REST APIの呼び出しを行います

認証のためのcurlコマンドのサンプル取得

API Playground の"Authentication"をクリックすると、フォームの下に、APIの説明書きされています

What is this? Authenticating to the API is a POST to /v1/auth/tokens. Reference the Tokens API from the sidebar.

API "/v1/auth/tokens"の説明を確認します
検索のtext boxへ"Tokens"を入力します
検索結果から、"Tokens" > "Create - post"をクリックすると、APIの説明が表示されます

"schema"をクリックすると各パラメータの説明が確認できます

今回は、CM管理者の"username"と"password"を利用するように、"body"の内容を変更します
"curl"をクリックすると、curlを利用したAPIのサンプルが表示されます
これを"Copy"をクリックしコピーします

curlを利用したAPIのサンプルを、実行してみます
ユーザ認証のためのAPI token "jwt"が正常に取得できました

$ curl -k 'https://192.168.10.33/api/v1/auth/tokens/' -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary '{"grant_type":"password","username":"admin","password":"Thales123!"}' --compressed | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1012  100   944  100    68  20085   1446 --:--:-- --:--:-- --:--:-- 21531
{
  "jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiIwMThjOTlhMC1kNDAwLTQ0Y2YtYmM5Ny1kNTQ3NDYzMzdiYmYiLCJzdWIiOiJsb2NhbHxiMDQ0Y2QzYy1kNTYyLTRjNzQtYTRhMS1hZTRkNjk0MzNlZGUiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfdHlwZSI6InVucmVnaXN0ZXJlZCIsImRvbWFpbl9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImdyb3VwcyI6WyJhZG1pbiJdLCJzaWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJ6b25lX2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIn0sImp3dGlkIjoiOThiYWFkYjEtZmFjMi00Mzg4LWJhNDAtOGVjMGYzYjlhMzllIiwiaWF0IjoxNzIxMjgyNDU5LCJleHAiOjE3MjEyODI3NTl9.21oy6W8VlxE0PWIW-vFpZzIoUftCybayAndUhj_mJo2AEZaA_Qt1k_w5JSmacWlAREAVXeqx3H6Ed12uCuDs3w",
  "duration": 300,
  "token_type": "Bearer",
  "client_id": "00000000-0000-0000-0000-000000000000",
  "refresh_token_id": "75fb31a9-2a60-4d8c-8304-bdcbef312131",
  "refresh_token": "HlOq6ejdcsmbX7iq5TPrJtSXjUFlZ7eRqPR2oAMFNY4lvnfQtCBF2DZ3e05zDNys"
}

curlコマンドによる鍵操作

curlコマンドを利用して一連の鍵操作を行ってみます

前準備

CMのURLを環境変数"KSCTL_URL"へ設定します

$ export KSCTL_URL=https://192.168.10.33

認証

CMの管理者権限で認証を行います
取得したAPI Tokenを環境変数"KSCTL_JWT"へ設定します

export KSCTL_JWT=$(curl -k $KSCTL_URL/api/v1/auth/tokens/ -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary '{"grant_type":"password","username":"admin","connection":"","password":"Thales123!"}' | jq -r '.jwt')

鍵操作

対象の鍵(例:"testLkey"）のidを環境変数"KSCTL_KEYID"へ設定します

$ export KSCTL_KEYID=$(curl -k "$KSCTL_URL/api/v1/vault/keys2/" -H "Authorization: Bearer $KSCTL_JWT" -H 'accept: application/json' | jq -r '.resources[] | select(.name == "test_key") | .id')
$ printenv KSCTL_KEYID
5e5347c90294404e8a3f917c5e4d5c0639e64ebc83574bac931f243371c1b44d

対象の鍵をExportし、鍵の値を確認することができました

$ curl -k "$KSCTL_URL/api/v1/vault/keys2/$KSCTL_KEYID/export" -H "Authorization: Bearer $KSCTL_JWT" -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary $'{"encoding": "hex"}' | jq -r
'.material'
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1322  100  1303  100    19  33410    487 --:--:-- --:--:-- --:--:-- 33897
0bba8f4e1e10f9a5eb12cea4d390324d3a6a828be562ac9f70ce798e0c938e57