KeyPair Management Guide - cloud-barista/cb-spider GitHub Wiki

KeyPair Management Guide

Language: English | 한국어

1. CB-Spider KeyPair Overview

  • Users can create KeyPairs to securely access VMs.
  • KeyPairs consist of a Public Key and a Private Key, which are specified when creating VMs for SSH access.
  • CB-Spider returns the Private Key when creating a KeyPair, and users must store it securely.
  • The relationship between KeyPairs and VMs is shown in the diagram below.
┌─────────────────────────────────────────────────────────────┐
│                   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 and Information Specification

  • Users can receive KeyPair information in JSON format using the following CB-Spider REST API.

2.1 KeyPair Management API

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

# KeyPair Registration/Unregistration (Integration with existing CSP KeyPair)
POST   /spider/regkeypair               - Register KeyPair
DELETE /spider/regkeypair/{Name}        - Unregister KeyPair

# KeyPair List Query (All)
GET    /spider/allkeypair               - List All KeyPairs (CB-Spider + CSP)
GET    /spider/allkeypairinfo           - List All KeyPairs Info

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

# Direct CSP KeyPair Deletion
DELETE /spider/cspkeypair/{Id}          - Delete CSP KeyPair

2.2 Information Specification

KeyPair Information (KeyPairInfo)

Field Description Examples
IId KeyPair identifier information (NameId, SystemId) ● {Name: "keypair-01", SystemId: "key-1234abcd"}
Fingerprint KeyPair fingerprint information (provided by CSP) ● "SHA256:abc123..."
PublicKey Public key information (PEM format) ● "ssh-rsa AAAAB3NzaC1..."
PrivateKey Private key information (PEM format, returned only at creation) ● "-----BEGIN RSA PRIVATE KEY-----\n..."
VMUserID User ID to use when accessing VM ● "cb-user" (CB-Spider abstracted user)
TagList List of tags assigned to KeyPair ● [{Key: "Environment", Value: "Production"}]
KeyValueList Additional information provided by CSP in Key/Value List format ● [{Key: "KeyPairId", Value: "key-1234"}]

Key Field Descriptions:

  • PrivateKey: Returned only when creating KeyPair, not included in subsequent queries
  • PublicKey: May not be provided depending on CSP
  • VMUserID: Always uses "cb-user" abstracted user in CB-Spider
  • Fingerprint: Unique fingerprint of KeyPair used for verification

3. CB-Spider KeyPair API and Information Examples

3.1 KeyPair Creation Example

  • API call and result example for creating a keypair-web KeyPair in AWS:
curl -sX 'POST' 'http://localhost:1024/spider/keypair' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01",
    "ReqInfo": {
      "Name": "keypair-web"
    }
  }' | jq

Response Example:

{
  "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"
    }
  ]
}

Important: The returned PrivateKey must be saved in a secure location and cannot be retrieved again!

3.2 KeyPair Query Example

  • API call and provided information example for AWS keypair-web KeyPair:
curl -sX 'GET' 'http://localhost:1024/spider/keypair/keypair-web?ConnectionName=aws-config01' | jq

Response Example:

{
  "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"
    }
  ]
}

Note: When querying, PrivateKey and PublicKey are hidden for security.

3.3 KeyPair List Query Example

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

Response Example:

{
  "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"
        }
      ]
    }
  ]
}

Note: When listing KeyPairs, PrivateKey and PublicKey are also hidden for security.

3.4 KeyPair Deletion Example

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

Response Example:

{
  "Result": "true"
}

3.5 Force Delete Example

  • Use the force=true option to forcefully delete a KeyPair connected to VMs.
curl -sX 'DELETE' 'http://localhost:1024/spider/keypair/keypair-web?force=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConnectionName": "aws-config01"
  }' | jq

3.6 Existing CSP KeyPair Registration Example

  • Example of registering a KeyPair that already exists in CSP to 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

Response Example:

{
  "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. Precautions and Limitations

5.1 Private Key Management

  • Provided only at creation: Private Key is returned only once when creating KeyPair
  • Cannot be reissued: Cannot retrieve or reissue if Private Key is lost
  • Secure storage required:
    • File permissions: chmod 600 keypair.pem
    • Use secure storage (encrypted volume, password manager, etc.)
    • Never include in version control systems (Git, etc.)
  • Response to loss: Create new KeyPair and re-register to VM

5.2 KeyPair Deletion

  • KeyPairs in use by VMs cannot be deleted (some CSPs)
  • Force delete (force=true) may make SSH access to connected VMs impossible (Caution!)
  • Recommend checking list of VMs using the KeyPair before deletion

6. SSH Access Guide

6.1 SSH Access from Linux/Mac

# Set Private Key permissions (once only)
chmod 600 ~/.ssh/keypair-web.pem

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

# SSH Config file setup (optional)
cat >> ~/.ssh/config << EOF
Host my-vm
    HostName <VM-Public-IP>
    User cb-user
    IdentityFile ~/.ssh/keypair-web.pem
EOF

# Simplified access
ssh my-vm

6.2 SSH Access from Windows

Using PowerShell/CMD:

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

6.3 SSH Access Troubleshooting

Permission Denied error:

# Check Private Key permissions
ls -la ~/.ssh/keypair-web.pem
# If permissions are too open
chmod 600 ~/.ssh/keypair-web.pem

Host Key Verification Failed:

# Remove host from known_hosts file
ssh-keygen -R <VM-Public-IP>

Connection Timeout:

  • Check if SSH(22) port is allowed in Security Group Inbound Rules
  • Verify VM Public IP is correct

7. References