KeyPair Management Guide

Language: English | 한국어

1. CB-Spider KeyPair 개요

• 사용자는 KeyPair를 생성하여 VM에 안전하게 접속할 수 있다.
• KeyPair는 공개키(Public Key)와 개인키(Private Key)로 구성되며, VM 생성 시 지정하여 SSH 접속에 사용한다.
• CB-Spider는 KeyPair 생성 시 개인키(Private Key)를 반환하며, 사용자는 이를 안전하게 보관해야 한다.
• KeyPair와 VM 간의 관계는 아래 그림과 같다.

┌─────────────────────────────────────────────────────────────┐
│                   CB-Spider KeyPair                         │
│                                                             │
│  KeyPair-1                                                  │
│  ├── Public Key: (Stored in CSP)                            │
│  ├── Private Key: (User keeps)                              │
│  └── Used by: VM-1, VM-2, VM-3                              │
│                                                             │
│  KeyPair-2                                                  │
│  ├── Public Key: (Stored in CSP)                            │
│  ├── Private Key: (User keeps)                              │
│  └── Used by: VM-4, VM-5                                    │
└─────────────────────────────────────────────────────────────┘

2. CB-Spider KeyPair API 및 제공 정보 규격

• 사용자는 다음과 같은 CB-Spider REST API를 이용하여 KeyPair 정보를 JSON 규격으로 제공받는다.

2.1 KeyPair 관리 API

# KeyPair 관리
POST   /spider/keypair                  - Create KeyPair
GET    /spider/keypair                  - List KeyPairs
GET    /spider/keypair/{Name}           - Get KeyPair
DELETE /spider/keypair/{Name}           - Delete KeyPair

# KeyPair 등록/해제 (기존 CSP KeyPair 연동)
POST   /spider/regkeypair               - Register KeyPair
DELETE /spider/regkeypair/{Name}        - Unregister KeyPair

# KeyPair 목록 조회 (전체)
GET    /spider/allkeypair               - List All KeyPairs (CB-Spider + CSP)
GET    /spider/allkeypairinfo           - List All KeyPairs Info

# KeyPair 통계
GET    /spider/countkeypair             - Count All KeyPairs
GET    /spider/countkeypair/{ConnectionName} - Count KeyPairs by Connection

# CSP KeyPair 직접 삭제
DELETE /spider/cspkeypair/{Id}          - Delete CSP KeyPair

2.2 제공 정보 규격

KeyPair 정보 (KeyPairInfo)

필드	설명	예시
IId	KeyPair의 식별자 정보 (NameId, SystemId)	● {Name: "keypair-01", SystemId: "key-1234abcd"}
Fingerprint	KeyPair의 지문 정보 (CSP에서 제공)	● "SHA256:abc123..."
PublicKey	공개키 정보 (PEM 형식)	● "ssh-rsa AAAAB3NzaC1..."
PrivateKey	개인키 정보 (PEM 형식, 생성 시에만 반환)	● "-----BEGIN RSA PRIVATE KEY-----\n..."
VMUserID	VM 접속 시 사용할 사용자 ID	● "cb-user" (CB-Spider 추상화된 사용자)
TagList	KeyPair에 할당된 태그 리스트	● [{Key: "Environment", Value: "Production"}]
KeyValueList	CSP가 제공하는 추가 정보를 Key/Value List 형태로 제공	● [{Key: "KeyPairId", Value: "key-1234"}]

주요 필드 설명:

• PrivateKey: KeyPair 생성 시에만 반환되며, 재조회 시에는 포함되지 않음
• PublicKey: CSP에 따라 제공되지 않을 수 있음
• VMUserID: CB-Spider에서는 항상 "cb-user" 추상화된 사용자 사용
• Fingerprint: KeyPair의 고유 지문으로 검증에 사용

3. CB-Spider KeyPair API 및 제공 정보 예시

3.1 KeyPair 생성 예시

• AWS에서 keypair-web KeyPair를 생성하는 API 호출 및 결과 예시가 다음과 같다.

curl -sX 'POST' 'http://localhost:1024/spider/keypair' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "keypair-web"
    }
  }' | jq

응답 예시:

{
  "IId": {
    "NameId": "keypair-web",
    "SystemId": "keypair-web"
  },
  "Fingerprint": "1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f",
  "PublicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...",
  "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAr3SDz29ld...\n-----END RSA PRIVATE KEY-----\n",
  "VMUserID": "cb-user",
  "KeyValueList": [
    {
      "Key": "KeyPairId",
      "Value": "key-0a1b2c3d4e5f67890"
    },
    {
      "Key": "KeyName",
      "Value": "keypair-web"
    }
  ]
}

중요: 반환된 PrivateKey는 반드시 안전한 위치에 저장해야 하며, 재조회가 불가능합니다!

3.2 KeyPair 조회 예시

• AWS keypair-web KeyPair 정보 호출 API 및 제공 정보 예시가 다음과 같다.

curl -sX 'GET' 'http://localhost:1024/spider/keypair/keypair-web?ConnectionName=aws-config01' | jq

응답 예시:

{
  "IId": {
    "NameId": "keypair-web",
    "SystemId": "keypair-web"
  },
  "Fingerprint": "1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f",
  "PublicKey": "Hidden for security.",
  "PrivateKey": "Hidden for security.",
  "VMUserID": "cb-user",
  "KeyValueList": [
    {
      "Key": "KeyPairId",
      "Value": "key-0a1b2c3d4e5f67890"
    }
  ]
}

참고: 조회 시에는 PrivateKey와 PublicKey가 보안을 위해 숨겨져 반환됩니다.

3.3 KeyPair 목록 조회 예시

curl -sX 'GET' 'http://localhost:1024/spider/keypair?ConnectionName=aws-config01' | jq

응답 예시:

{
  "keypair": [
    {
      "IId": {
        "NameId": "keypair-web",
        "SystemId": "keypair-web-d60mdhu1pc4mliscb9og"
      },
      "Fingerprint": "1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f",
      "PublicKey": "Hidden for security.",
      "PrivateKey": "Hidden for security.",
      "VMUserID": "cb-user",
      "TagList": [
        {
          "Key": "Name",
          "Value": "keypair-web-d60mdhu1pc4mliscb9og"
        }
      ],
      "KeyValueList": [
        {
          "Key": "KeyFingerprint",
          "Value": "1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca:9f:f5:f1:6f"
        },
        {
          "Key": "KeyName",
          "Value": "keypair-web-d60mdhu1pc4mliscb9og"
        },
        {
          "Key": "KeyPairId",
          "Value": "key-0a1b2c3d4e5f67890"
        }
      ]
    },
    {
      "IId": {
        "NameId": "keypair-admin",
        "SystemId": "keypair-admin-e71nehv2qd5nmbjtc0ap"
      },
      "Fingerprint": "2a:62:bf:39:ca:9a:fa:e9:2a:36:6e:48:3e:8e:c9:db:0a:a6:a2:7a",
      "PublicKey": "Hidden for security.",
      "PrivateKey": "Hidden for security.",
      "VMUserID": "cb-user",
      "TagList": [
        {
          "Key": "Name",
          "Value": "keypair-admin-e71nehv2qd5nmbjtc0ap"
        }
      ],
      "KeyValueList": [
        {
          "Key": "KeyFingerprint",
          "Value": "2a:62:bf:39:ca:9a:fa:e9:2a:36:6e:48:3e:8e:c9:db:0a:a6:a2:7a"
        },
        {
          "Key": "KeyName",
          "Value": "keypair-admin-e71nehv2qd5nmbjtc0ap"
        },
        {
          "Key": "KeyPairId",
          "Value": "key-1b2c3d4e5f6789012"
        }
      ]
    }
  ]
}

참고: 목록 조회 시에도 보안을 위해 PrivateKey와 PublicKey는 숨겨져 반환됩니다.

3.4 KeyPair 삭제 예시

curl -sX 'DELETE' 'http://localhost:1024/spider/keypair/keypair-web' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

응답 예시:

{
  "Result": "true"
}

3.5 강제 삭제 (force) 예시

• VM 등이 연결된 KeyPair를 강제 삭제할 경우 force=true 옵션을 사용한다.

curl -sX 'DELETE' 'http://localhost:1024/spider/keypair/keypair-web?force=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

3.6 기존 CSP KeyPair 등록 예시

• CSP에 이미 존재하는 KeyPair를 CB-Spider에 등록하는 예시가 다음과 같다.

curl -sX 'POST' 'http://localhost:1024/spider/regkeypair' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "existing-keypair",
      "CSPId": "keypair-existing-csp-id"
    }
  }' | jq

응답 예시:

{
  "IId": {
    "NameId": "existing-keypair",
    "SystemId": "keypair-existing-csp-id"
  },
  "Fingerprint": "3b:73:ca:4a:db:ab:ab:fa:3b:47:7f:59:4f:9f:da:ec:1b:b7:b3:8b",
  "VMUserID": "cb-user"
}

5. 주의사항 및 제약사항

5.1 Private Key 관리

• 생성 시에만 제공: Private Key는 KeyPair 생성 시 단 한 번만 반환됨
• 재발급 불가: Private Key 분실 시 재조회나 재발급 불가능
• 안전한 보관 필수:
  • 파일 권한: chmod 600 keypair.pem
  • 안전한 저장소 사용 (암호화된 볼륨, 비밀번호 관리자 등)
  • 버전 관리 시스템(Git 등)에 절대 포함 금지
• 분실 시 대응: 새로운 KeyPair 생성 후 VM에 재등록 필요

5.2 KeyPair 삭제

• VM이 사용 중인 KeyPair는 삭제 불가 (일부 CSP)
• 강제 삭제(force=true) 시 연결된 VM의 SSH 접속이 불가능해질 수 있음 (주의!)
• 삭제 전 해당 KeyPair를 사용하는 VM 목록 확인 권장

6. SSH 접속 가이드

6.1 Linux/Mac에서 SSH 접속

# Private Key 권한 설정 (최초 1회)
chmod 600 ~/.ssh/keypair-web.pem

# SSH 접속
ssh -i ~/.ssh/keypair-web.pem cb-user@<VM-Public-IP>

# SSH Config 파일 설정 (선택사항)
cat >> ~/.ssh/config << EOF
Host my-vm
    HostName <VM-Public-IP>
    User cb-user
    IdentityFile ~/.ssh/keypair-web.pem
EOF

# 간편 접속
ssh my-vm

6.2 Windows에서 SSH 접속

PowerShell/CMD 사용:

# SSH 접속
ssh -i C:\Users\YourName\.ssh\keypair-web.pem cb-user@<VM-Public-IP>

6.3 SSH 접속 문제 해결

Permission Denied 오류:

# Private Key 권한 확인
ls -la ~/.ssh/keypair-web.pem
# 권한이 너무 개방되어 있으면
chmod 600 ~/.ssh/keypair-web.pem

Host Key Verification Failed:

# known_hosts 파일에서 해당 호스트 제거
ssh-keygen -R <VM-Public-IP>

Connection Timeout:

• Security Group의 Inbound Rules에 SSH(22) 포트가 허용되어 있는지 확인
• VM의 Public IP가 올바른지 확인

7. 참고 자료

• CB-Spider 사용자 가이드
• CB-Spider REST API 문서
• CB-Spider AdminWeb 가이드