Relay Executive 전용: 키스토어 마이그레이션

해당 메뉴얼은 로컬 키스토어를 새로운 암호화 및 복호화 메커니즘으로 마이그레이션하는 절차를 설명합니다.

🔹 키스토어가 구성되어 있지 않은 경우, 해당 섹션을 건너뛸 수 있습니다.

릴레이어 클라이언트 버전에 따라 마이그레이션 절차가 다릅니다. 현재 클라이언트 버전을 확인하려면 다음 명령어를 실행합니다.

./bifrost-relayer --version

출력 예시:

bifrost-relayer 2.1.1-1b4f8ca012b

1. 릴레이어 클라이언트 버전 v2.1.1 미만

1.1. 바이너리 업데이트

키스토어를 마이그레이션 하려면 아래 단계에 따라 릴레이어 클라이언트를 최신 버전으로 업데이트합니다.

1단계:

진행하기 전에 이전 bifrost-relayer 바이너리 파일을 제거하거나 백업합니다.

rm <PATH_TO_BIFROST_RELAYER_BINARY>

2단계.

동일한 경로에 최신 버전의 bifrost-relayer를 설치하고 필요한 권한을 업데이트합니다. (참고: 경로가 변경된 경우, Systemd 설정 파일도 그에 맞게 업데이트해야 합니다)

wget "https://github.com/bifrost-platform/bifrost-relayer.rs/releases/latest/download/bifrost-relayer"
chmod +x bifrost-relayer

1.2. 설정 업데이트

1.2.1. 서명자(Signer) 설정

서명자를 지정하고 설정하는 방법이 변경되었습니다. 이전에는 다음과 같이 설정했습니다:

system:
  private_key: "0xxxx...xxx"

이제 설정이 변경되었습니다. system 섹션에서 개인 키가 제거되었습니다. 대신, signer_config를 명시적으로 지정해야 하며, 이는 다음 중 하나를 포함할 수 있습니다:

• 일반 텍스트 개인 키

• AWS KMS 키

업데이트된 설정 형식은 다음과 같습니다:

system:
  #----- ❌ 여기서 개인 키가 제거되었습니다

# 옵션 1. AWS KMS 서명자 사용 시
signer_config:
  kms_key_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 옵션 2. 일반 텍스트 개인 키로 로컬 서명자 사용 시
signer_config:
  private_key: "0xxxx...xxx"

1.2.2. 키스토어(Keystore) 설정

키스토어를 지정하고 설정하는 방법이 변경되었습니다. 이전에는 다음과 같이 설정했습니다:

system:
  keystore_path: "./example"
  keystore_password: "password"

이제 설정이 변경되었습니다. system 섹션에서 경로와 비밀번호가 제거되었습니다. 대신, 다음을 포함하는 keystore_config를 명시적으로 지정해야 합니다:

• 키스토어 경로

• 일반 텍스트 비밀번호 또는 AWS KMS 키

  • ⚠️ 중요: 이 단계에서는 마이그레이션을 진행하기 위해 이전에 사용했던 비밀번호를 입력해야 합니다.

업데이트된 설정 형식은 다음과 같습니다:

system:
  #-----> ❌ 여기서 경로와 비밀번호가 제거되었습니다

keystore_config:
  path: "./example"
  password: "password" # ---> ⚠️ 중요: 이전에 사용했던 비밀번호를 입력합니다

1.3. 마이그레이션 CLI 명령어 실행: migrate-keystore

마이그레이션을 진행하기 전에 실행 중인 릴레이어를 중지해야 합니다. 다음 명령어를 실행하여 중지합니다.

# 작동하지 않으면(예: 권한 거부) 처음에 sudo를 추가하여 재실행합니다
systemctl stop bifrost-relayer.service

1.3.1. 최신 BRP 라운드 가져오기

그런 다음 최신 BRP(Bitcoin Relay Protocol) 라운드를 가져와야 합니다. 다음 명령어를 실행하여 조회합니다.

메인넷(Mainnet)

curl --location 'https://public-01.mainnet.bifrostnetwork.com/rpc' --header 'Content-Type: application/json' --da

테스트넷(Testnet)

curl --location 'https://public-01.testnet.bifrostnetwork.com/rpc' --header 'Content-Type: application/json' --da

이제 키스토어 암호화를 마이그레이션하기 위한 두 가지 옵션이 있습니다:

1. 일반 텍스트 비밀번호로 암호화된 키스토어

2. AWS KMS로 암호화된 키스토어

보안 요구 사항에 가장 적합한 옵션을 선택하고 해당 단계를 따릅니다.

1.3.2. 옵션 1: 비밀번호로 암호화된 키스토어

키스토어를 마이그레이션하려면 다음 옵션과 함께 명령어를 실행합니다:

• chain: config.yaml 파일의 경로를 지정합니다.

• round: 이전 단계에서 가져온 라운드 인덱스를 입력합니다.

• new-password: 키스토어 키를 암호화하고 복호화하기 위한 새로운 일반 텍스트 비밀번호를 설정합니다.

  • 🚨 보안 강화를 위해 새 비밀번호를 사용하는 것을 적극 권장합니다.

• version: 이 옵션은 해당 단계에서 1로 설정해야 합니다.

⚠️ 중요: 명령어를 실행하기 전에, 마이그레이션이 성공하려면 config.yaml 파일에 이전에 사용했던 비밀번호가 지정되어 있어야 합니다.

# 작동하지 않으면(예: 권한 거부) 처음에 sudo를 추가하여 재실행합니다
./bifrost-relayer migrate-keystore \
  --chain "<YOUR_CONFIG_YAML_FILE_PATH>" \
  --round <THE_POOL_ROUND_TO_MIGRATE> \
  --new-password "<YOUR_NEW_PASSWORD>" \
  --version 1

명령어가 성공적으로 작동하면, config.yaml 파일의 keystore_config.password를 새로 설정한 비밀번호로 교체합니다.

keystore_config:
  path: "./example"
  password: "new-password" # ---> 이 부분을 새 비밀번호로 교체합니다

이제 릴레이어를 재시작합니다.

# 작동하지 않으면(예: 권한 거부) 처음에 sudo를 추가하여 재실행합니다
systemctl restart bifrost-relayer.service

1.3.3. 옵션 2: AWS KMS로 암호화된 키스토어

키스토어를 마이그레이션하려면 다음 옵션과 함께 명령어를 실행합니다:

• chain: config.yaml 파일의 경로를 지정합니다.

• round: 이전 단계에서 가져온 라운드 인덱스를 입력합니다.

• new-kms-key-id: 키스토어 키를 암호화하고 복호화하기 위한 새 AWS KMS 키 ID를 설정합니다.

• version: 이 옵션은 해당 단계에서 1로 설정해야 합니다.

⚠️ 중요: 명령어를 실행하기 전에, 마이그레이션이 성공하려면 config.yaml 파일에 이전에 사용했던 비밀번호가 지정되어 있어야 합니다.

# 작동하지 않으면(예: 권한 거부) 처음에 sudo를 추가하여 재실행합니다
./bifrost-relayer migrate-keystore \
  --chain "<YOUR_CONFIG_YAML_FILE_PATH>" \
  --round <THE_POOL_ROUND_TO_MIGRATE> \
  --new-kms-key-id "<YOUR_NEW_KMS_KEY_ID>" \
  --version 1

명령어가 성공적으로 작동하면, keystore_config.password를 제거하고 keystore_config.kms_key_id를 추가한 후, config.yaml 파일에서 새로운 AWS KMS 키 ID로 설정합니다.

keystore_config:
  path: "./example"
  kms_key_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  # ---> 비밀번호를 제거하고 kms_key_id를 추가합니다

이제 릴레이어를 재시작합니다.

# 작동하지 않으면(예: 권한 거부) 처음에 sudo를 추가하여 재실행합니다
systemctl restart bifrost-relayer.service

2. 릴레이어 클라이언트 버전 v2.1.1 이상

2.1. 바이너리 업데이트

키스토어를 마이그레이션 하려면 아래 단계에 따라 릴레이어 클라이언트를 최신 버전으로 업데이트합니다.

1단계:

진행하기 전에 이전 bifrost-relayer 바이너리 파일을 제거하거나 백업합니다.

rm <PATH_TO_BIFROST_RELAYER_BINARY> 

2단계:

동일한 경로에 최신 버전의 bifrost-relayer를 설치하고 필요한 권한을 업데이트합니다. (참고: 경로가 변경된 경우, Systemd 설정 파일도 그에 맞게 업데이트해야 합니다)

wget "https://github.com/bifrost-platform/bifrost-relayer.rs/releases/latest/download/bifrost-relayer"
chmod +x bifrost-relayer

2.2. 마이그레이션 CLI 명령어 실행: migrate-keystore

마이그레이션을 진행하기 전에 실행 중인 릴레이어를 중지해야 합니다. 다음 명령어를 실행하여 중지합니다:

# 작동하지 않으면(예: 권한 거부) 처음에 sudo를 추가하여 재실행합니다
systemctl stop bifrost-relayer.service

2.2.1. 최신 BRP 라운드 가져오기

그런 다음 최신 BRP(Bitcoin Relay Protocol) 라운드를 가져와야 합니다. 다음 명령어를 실행하여 조회합니다:

메인넷(Mainnet)

curl --location 'https://public-01.mainnet.bifrostnetwork.com/rpc' --header 'Content-Type: application/json' --da

테스트넷(Testnet)

curl --location 'https://public-01.testnet.bifrostnetwork.com/rpc' --header 'Content-Type: application/json' --da

이제 키스토어 암호화를 마이그레이션하기 위한 두 가지 옵션이 있습니다:

1. 일반 텍스트 비밀번호로 암호화된 키스토어

2. AWS KMS로 암호화된 키스토어

보안 요구 사항에 가장 적합한 옵션을 선택하고 해당 단계를 따릅니다.

2.2.2. 옵션 1: 비밀번호로 암호화된 키스토어

키스토어를 마이그레이션 하려면 다음 옵션과 함께 명령어를 실행합니다:

• chain: config.yaml 파일의 경로를 지정합니다.

• round: 이전 단계에서 가져온 라운드 인덱스를 입력합니다.

• new-password: 키스토어 키를 암호화하고 복호화하기 위한 새로운 일반 텍스트 비밀번호를 설정합니다.

  • 🚨 보안 강화를 위해 새 비밀번호를 사용하는 것을 적극 권장합니다.

⚠️ 중요: 명령어를 실행하기 전에, 마이그레이션이 성공하려면 config.yaml 파일에 이전에 사용했던 비밀번호 또는 AWS KMS 키 ID가 지정되어 있어야 합니다.

# 작동하지 않으면(예: 권한 거부) 처음에 sudo를 추가하여 재실행합니다
./bifrost-relayer migrate-keystore \
  --chain "<YOUR_CONFIG_YAML_FILE_PATH>" \
  --round <THE_POOL_ROUND_TO_MIGRATE> \
  --new-password "<YOUR_NEW_PASSWORD>"

명령어가 성공적으로 작동하면 config.yaml 파일을 다음과 같이 업데이트합니다:

• 이전에 keystore_config.password가 있었다면, 새로 설정한 비밀번호로 교체합니다.

• 이전에 keystore_config.kms_key_id가 있었다면, 그것을 제거하고 keystore_config.password를 추가한 후 새 비밀번호로 설정합니다.

keystore_config:
  path: "./example"
  password: "new-password" # ---> 이 부분을 새 비밀번호로 추가 또는 교체합니다

이제 릴레이어를 재시작합니다.

# 작동하지 않으면(예: 권한 거부) 처음에 sudo를 추가하여 재실행합니다
systemctl restart bifrost-relayer.service

2.2.3. 옵션 2: AWS KMS로 암호화된 키스토어

키스토어를 마이그레이션 하려면 다음 옵션과 함께 명령어를 실행합니다:

• chain: config.yaml 파일의 경로를 지정합니다.

• round: 이전 단계에서 가져온 라운드 인덱스를 입력합니다.

• new-kms-key-id: 키스토어 키를 암호화하고 복호화하기 위한 새 AWS KMS 키 ID를 설정합니다.

⚠️ 중요: 명령어를 실행하기 전에, 마이그레이션이 성공하려면 config.yaml 파일에 이전에 사용했던 비밀번호 또는 AWS KMS 키 ID가 지정되어 있어야 합니다.

# 작동하지 않으면(예: 권한 거부) 처음에 sudo를 추가하여 재실행합니다
./bifrost-relayer migrate-keystore \
  --chain "<YOUR_CONFIG_YAML_FILE_PATH>" \
  --round <THE_POOL_ROUND_TO_MIGRATE> \
  --new-kms-key-id "<YOUR_NEW_KMS_KEY_ID>"

명령어가 성공적으로 작동하면 config.yaml 파일을 다음과 같이 업데이트합니다:

• 이전에 keystore_config.kms_key_id가 있었다면, 새로 설정한 AWS KMS 키 ID로 교체합니다.

• 이전에 keystore_config.password가 있었다면, 그것을 제거하고 keystore_config.kms_key_id를 추가한 후 새 AWS KMS 키 ID로 설정합니다.

keystore_config:
  path: "./example"
  kms_key_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  #----> 이 부분을 새 AWS KMS 키 ID로 추가 또는 교체합니다

이제 모든 준비가 되었습니다. 릴레이어를 재시작합니다.

# 작동하지 않으면(예: 권한 거부) 처음에 sudo를 추가하여 재실행합니다
systemctl restart bifrost-relayer.service