♾️

dfx identityコマンド

2024/06/09に公開

はじめに

分散型クラウド環境『Internet Computer』のCanisterを開発する上で必須ともいえるdfxコマンドには、様々な機能が凝縮されています。

本記事では、そのサブコマンドの一つdfx identityについて解説します。

dfxコマンドにおける『identity』は一個の秘密鍵と考えると分かりやすいでしょう。
名前を付けて複数の秘密鍵を管理し、それらを切り替えて使用する仕組みが用意されています。

執筆時点の最新版v0.20.1を使っています。使用されている環境や今後のバージョンアップにより仕様が変わる可能性がございますのでご注意ください。

$ dfx --version
dfx 0.20.1

dfxコマンドの準備

dfxコマンドは、Canister Development Kit(CDK)の一部としてインストールされるCLIツールです。

Mac/Linux、WindowsのWSL2 (Ubuntu)環境から、以下のコマンドを実行してインストールすることができます。

$ sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"

※Apple siliconの場合はRosettaが必須

dfx identityコマンド

dfx identityの主要なサブサブコマンドを以下に記載します。

コマンド サブコマンド サブサブコマンド 概要
dfx identity export identityから秘密鍵をPEMフォーマットでエクスポートします
import PEMフォーマットの秘密鍵をインポートしてidentityを作成します
list 登録されているidentityの一覧を表示します
new 新しいidentityを作成します
get-principal identityに対応するPrincipalを表示します
remove identityを削除します
rename identityの名前を変更します
use 使用するidentityを指定します
whoami 現在使用しているidentityを表示します

上記以外のサブサブコマンドについてはdfx identity --helpで確認してください。

1. dfx identity export

指定したidentityの秘密鍵をPEMフォーマットで表示します。

$ dfx identity export <identity>
-----BEGIN EC PRIVATE KEY-----
︙
-----END EC PRIVATE KEY-----

ファイルに出力したい場合

ファイルに出力したい場合は、標準出力をリダイレクション(> ファイル名)するとよいでしょう。

$ dfx identity export <identity> > <出力ファイル名>

2. dfx identity import

PEMファイルをインポートしてidentityを登録します。

dfx identity exportで表示されたPEMフォーマットのファイルを指定してインポートします。

$ dfx identity import <identity> <PEMファイル>
Please enter a passphrase for your identity: <passphase>
Encryption complete.
Imported identity: "<identity>".

コマンドを実行すると、<passphrase>を訊いてきます。
任意の<passphrase>を設定しておくことにより、秘密鍵は暗号化された状態で保存されます。また、作成されたidentityを使ってdfxコマンドを実行する場合には<passphrase>の入力が必須となりますので、セキュリティが向上します。
設定した<passphrase>は忘れないようにしましょう。

passphraseを設定したくない場合

--storage-mode plaintextオプションを指定すると<passphrase>を使用しないようにもできます。この場合、秘密鍵は暗号化されない状態で管理されます。

$ dfx identity import --storage-mode plaintext <identity> <PEMファイル>

defaultのidentityはこの形式で登録されており<passphrase>は未使用

seed phraseからのインポート

dfx identity newコマンド実行時に表示された<seed phrase>を用いてidentityを復元することもできます。<seed phrase>を記載したファイルを用意して--seed-file <seed phraseファイル>オプションを指定します。

$ dfx identity import --seed-file <seed phraseファイル> <identity>
Please enter a passphrase for your identity: <passphase>
Encryption complete.
Imported identity: "<identity>".

openSSLで生成したPEMファイルを取り込む

opensslコマンドで作成したECDSA secp256k1秘密鍵をインポートすることもできます。

$ openssl ecparam -name secp256k1 -genkey -noout -out <PEMファイル名>
$ dfx identity import <identity> <PEMファイル名>
Please enter a passphrase for your identity: <passphase>
Encryption complete.
Imported identity: "<identity>".

3. dfx identity list

登録されているidentityの一覧を表示します。

CDKをインストールした直後は、defaultanonymousの2つのidentityが登録されています。anonymousは秘密鍵に紐づかない匿名のidentityです。

$ dfx identity list
anonymous
default *

4. dfx identity new

新しいidentityを作成するコマンドです。引数に作成するidentityの名前を指定します。

$ dfx identity new <identity>
Please enter a passphrase for your identity: <passphrase>
Encryption complete.
Your seed phrase for identity '<identity>': <seed phrase>

This can be used to reconstruct your key in case of emergency, so write it down in a safe place.
Created identity: "<identity>".

コマンドを実行すると、<passphrase>を訊いてきます。
任意の<passphrase>を設定しておくことにより、秘密鍵は暗号化された状態で保存されます。また、作成されたidentityを使ってdfxコマンドを実行する場合には<passphrase>の入力が必須となりますので、セキュリティが向上します。
設定したpassphraseは忘れないようにしましょう。

identityの生成とともに、画面には24個の英単語が並んだ<seed phrase>が表示されますので、万が一のために控えておくとよいでしょう。<seed phrase>から秘密鍵の復元ができます。厳重に管理してくれぐれも流出させないように気を付けてください。

passphraseを設定したくない場合

--storage-mode plaintextオプションを指定するとpassphraseを使用しないようにもできます。この場合、秘密鍵は暗号化されない状態で管理されます。

$ dfx identity new --storage-mode plaintext <identity>

秘密鍵の実体ファイル

dfxコマンドが管理する秘密鍵は~/.config/dfx/identity/<identity>/ディレクトリに、identity.pem.encryptedもしくはidentity.pemのファイル名で保存されています。

defaultidentityは暗号化されずに秘密鍵が保存されていますので、中身を見てみましょう。

opensslコマンドで確認してみると、ECDSAの楕円曲線パラメータsecp256k1が使用されていることが分かります。

$ openssl ec -in ~/.config/dfx/identity/default/identity.pem -text
read EC key
Private-Key: (256 bit)
priv:
    ︙
pub:
    ︙
ASN1 OID: secp256k1
writing EC key
-----BEGIN EC PRIVATE KEY-----
    ︙
-----END EC PRIVATE KEY-----

5. dfx identity get-principal

principalとは、Internet ComputerにおけるユーザーやCanister等の識別子です。ユーザーの場合は秘密鍵とペアの公開鍵から一意に導出されます。

$ dfx identity [--identity <identity>] get-principal

--identityオプションで、指定したidentityのprincipalを表示することもできます。匿名(anonymous)のprincipalはシステム固定(2vxsx-fae)です。

$ dfx identity --identity anonymous get-principal
2vxsx-fae

6. dfx identity remove

dfxコマンドで管理しているidentityを削除します。identityに紐づいた秘密鍵が削除されますので、必要であれば事前にdfx identity exportコマンドで退避するなどしておくとよいでしょう。

$ dfx identity remove <identity>
Removed identity "<identity>".

7. dfx identity rename

identityの名前を変更します。

$ dfx identity rename <旧identity> <新identity>
Renamed identity "<旧identity>" to "<新identity>".

8. dfx identity use

dfxコマンドのうち、dfx deploydfx canisterなどidentityを利用する場合には、--identity <identity>オプションを指定することでidentityを切り替えることができます。

毎回--identityを指定するのが手間であったり指定漏れを防ぎたい場合、dfx identity useコマンドを使うと--identityオプションを省略した場合のidentityを初期のdefaultから切り替えることができます。

切り替えは永続的でTerminalを再度起動してもリセットされませんのでご注意ください。

$ dfx identity use <identity>
Using identity: "<identity>".

設定は以下のファイルに保存されています。

~/.config/dfx/identity.json

{
  "default": "default"
}

9. dfx identity whoami

現在使用しているidentityを表示します。dfx identity useコマンドでidentityを切り替える運用を行っている場合、--identityオプションを省略した場合にどのidentityが使われているか注意してください。

$ dfx identity whoami

公式リファレンス

https://internetcomputer.org/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-parent

Discussion