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

# 概要

[CM (CipherTrust Manager)](https://qiita.com/shinyaarai/items/8267141fcdab8f789c9e) には、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](https://thalesdocs.com/ctp/cm/latest/admin/adp_ag/adp-interfaces/index.html#rest-interface)
    - [Authenticating to the REST API](https://thalesdocs.com/ctp/cm/latest/admin/cm_admin/authentication/rest-api/index.html)
    - [CM REST API Specification](https://thalesdocs.com/ctp/cm/latest/extern/definition-developer.json) - Swagger file format

# 手順

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

https://qiita.com/shinyaarai/items/4007d20851e7b1d6e0f1

## API Playgruond へのアクセス

CMのGUI管理画面の"API & CLI Documentation"をクリックします
![CM_REST-1-1a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/93246ac7-1d06-f532-ce06-dcf4376ca1d8.png)

または、CM管理画面へログイン後、右上の"API"をクリックします
![CM_REST-1-2a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/45bd25b9-97d9-0339-0172-4d9d580842a0.png)

## API Playgroundへのログイン
”API Playgruond"が表示されました
![CM_REST-2-1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/78c77525-ee4e-9d95-c546-6a3283c83afc.png)

右上の"Authentication"をクリックし、CMの管理者アカウントの"username"と"password"を入力、"POST"をクリックします
![CM_REST-2-3a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/9244ae8a-e247-5337-cf49-0641589ff9b3.png)

ログインが成功すると、どの”Domain"にログインしたか（今回はDomainを用いていないため"root")、及び、今回の認証の有効期間の残り時間が表示されます
![CM_REST-2-4a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/f03f7b6c-2b79-5450-4966-e2991a4ad26d.png)

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

![CM_REST-2-5a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/bdf8ea05-16ec-68e7-b6ea-5dfd194a8bad.png)

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

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

![CM_REST-3-1a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/fe5602cb-c692-521d-54a0-117038bdd4fc.png)

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

![CM_REST-3-3a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/7c1e7c32-da42-dd90-8e33-a4f1f6fe127f.png)

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

![CM_REST-3-5a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/ebea83da-27a3-d2d4-adf5-6c60704c6e56.png)

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

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

左上の検索用のtext box にて、"key2"と入力します
下の検索結果から"Keys"を選択します
鍵操作"Keys"のAPIの説明が表示されます
![CM_REST-4-1a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/a4b77553-5932-cfd1-c27a-2396eec757e1.png)

"List"をクリックします
鍵の一覧取得のためのAPIの説明が確認できます
![CM_REST-4-2a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/df6f37fe-0a3e-1f27-ef9e-f6c73a78465a.png)

"?"マークをクリックすると、各パラメータの説明が表示されます
今回は、先程作成した鍵(例: "test_key")のみ確認するため、パラメータ"name"に鍵の名前を入力します
![CM_REST-4-3a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/b4cd808a-be6d-8d81-237a-4d5f3eceb8cb.png)

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

![CM_REST-4-4a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/a7b346a0-3409-de19-fbe8-9ca9ab98db54.png)

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

![CM_REST-4-5a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/12409db4-626f-5963-1572-d11b2ff09542.png)

"Export"をクリックします
![CM_REST-5-1a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/8d0f2284-1448-8ea9-89a9-1f1441b7f6c0.png)

"id"をクリックします
![CM_REST-5-2a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/849bdc0e-175d-7466-958f-fc863ed1ac3a.png)

先ほどコピーしていた鍵("test_key")のidを入力（ペースト）します
![CM_REST-5-3a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/b2e31171-5ef1-6af9-3af7-f691621a4df8.png)


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

![CM_REST-5-4a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/1438b6eb-f257-c9ca-8c86-837221eed701.png)

今回はすべてのパラメータを削除しました
![CM_REST-5-5a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/d212989f-59f2-7dd4-9041-dc41b899399d.png)

"POST"をクリックし、REST APIを呼び出しします
![CM_REST-5-6a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/b803634c-edee-b24c-513d-ce7d3c33b8df.png)

Exportが成功しました
"name"に鍵の名前(例: "test_key") が確認できます
![CM_REST-5-7a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/65a8e67c-12dd-50dd-2787-d2e665d5f320.png)

画面下へスクロールすると、"material"にExportされた鍵の値を確認することができます
![CM_REST-5-8a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/fd887632-919c-68f2-9f5e-4aa25a0d389e.png)


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

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

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

API Playground の"Authentication"をクリックすると、フォームの下に、APIの説明書きされています
![CM_REST-6-1a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/ee3923d9-8c09-6451-4e5a-fd56c22f4640.png)


> 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の説明が表示されます

![CM_REST-6-2a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/2cbd3d7b-5598-81f7-d357-a1ebebea510a.png)

"schema"をクリックすると各パラメータの説明が確認できます
![CM_REST-6-3a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/7b89013e-0a5e-af22-d549-497cef75b4d0.png)

今回は、CM管理者の"username"と"password"を利用するように、"body"の内容を変更します
"curl"をクリックすると、curlを利用したAPIのサンプルが表示されます
これを"Copy"をクリックしコピーします
![CM_REST-6-5a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/613085/f6686b90-501d-579f-4f92-d72c75cd52d1.png)

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
```