dfx identityコマンド
はじめに
分散型クラウド環境『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をインストールした直後は、default
とanonymous
の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
のファイル名で保存されています。
default
identityは暗号化されずに秘密鍵が保存されていますので、中身を見てみましょう。
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 deploy
やdfx 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
公式リファレンス
Discussion