Secure Credential Registration Guide (How to use the credential APIs)

[seokho-son]

Secure Credential Registration Guide (How to use the credential APIs)

개요

이 가이드는 클라이언트가 하이브리드 암호화(AES + RSA)를 사용해 안전하게 CSP API 사용을 위한 credentials를 CB-Tumblebug 서버에 등록하는 방법을 설명한다.
클라이언트는 CB-Tumblebug API를 통해 발급받은 RSA 공개 키를 사용해 자체 생성한 AES 키로 credentials 데이터를 암호화한 후 API를 통해 서버에 안전하게 전송한다. 이 과정에서 RSA는 4096비트 키를 사용하며, AES는 256비트 키를 사용해 데이터를 암호화한다.

Credential 등록 관련 APIs

• GET /credential/publicKey
• POST /credential

sequenceDiagram
    participant Client
    participant CB-TB Server

    Note over Client: Start Credential Registration Process

    Client->>CB-TB Server: Request an RSA public key (GET: /credential/publicKey)
    CB-TB Server->>CB-TB Server: Generate RSA Key Pair (4096-bit, OAEP padding, SHA-256)
    CB-TB Server-->>Client: Return RSA Public Key and Token ID

    Note over Client: Generate AES-256 Key (32 bytes, One-Time Key)
    Client->>Client: Encrypt Credential Values with AES-256 (CBC Mode, PKCS7 Padding)

    Note over Client: Encrypt AES Key with RSA Public Key (OAEP padding, SHA-256)
    Client->>Client: Prepare Payload with Encrypted AES Key and Encrypted Credential Data

    Client->>CB-TB Server: Send Encrypted Credential Data and Encrypted AES Key (POST: /credential)

    Note over CB-TB Server: Decrypt AES Key with RSA Private Key
    CB-TB Server->>CB-TB Server: Use RSA Private Key to Decrypt AES Key (OAEP padding, SHA-256)
    CB-TB Server->>CB-TB Server: Use AES Key to Decrypt Credential Values (CBC Mode, PKCS7 Padding)
    
    CB-TB Server->>CB-TB Server: Register Credential Information

    Note over CB-TB Server: Expire All Keys (One-Time Use)
    CB-TB Server->>CB-TB Server: Delete RSA Key Pair, AES Key (One-Time Use)

    CB-TB Server-->>Client: Return Success Response with Registered Credential Information

    Client->>Client: Verify Server Response for Successful Registration

    Note over Client: Expire All Keys (One-Time Use)
    Client->>Client: Delete RSA Key Pair, AES Key (One-Time Use)

    Note over Client: Process Complete

Loading

단계별 가이드

1. RSA 공개 키 발급

먼저, 서버에서 RSA 공개 키를 발급받는다. 이 공개 키는 클라이언트에서 생성할 AES 키를 암호화하는 데 사용한다.
발급받은 RSA 공개 키는 1회성 키이며, Credential 등록 작업이 완료되면 RSA 키 페어는 서버 측에서 삭제된다.

• HTTP Method: GET
• Endpoint: /credential/publicKey

API 응답 예시

{
  "publicKeyTokenId": "cr5sidugsanc73arjjbg",
  "publicKey": "-----BEGIN RSA PUBLIC KEY-----\nMIICCgKCAgEAuBIImwTfVSjhDUW/NEnWf/9LTpSsSWhsnVOSKRp9AmJGg4fgbYnF\nDMdZ/puWn43x1f8PTk3j7CK2b7T/0L0orOF3JdRVtNdTeuuSDuuyiPAJsYn+nXTr\nQXS/7uEZ23KLrqaaz4DY2tInHmSVeemaGGI4iLVGr9jJpt9IUSWWZBLJ1SWCuxJQ\ntmKggM92SloXE0QDX/qC8rdmLlh2I5+mbAGsO84MtDjPulcKa32o8/F32WISmBqq\nRZ7/+eQLC+/vetDGzLitdZReb3wWq4H7PYJe3jJDjFaDOjJdmg83vOnLOVoPqYOG\nVmsoYYEYPqTyioAIt6XlwsWR6CNj/iRfPDgXlEbPI/GOvLEg2wHFjVd315fB6fid\nayV+owkQNH98qGU9ATOEMnwEz3nHsuEnO6AZALu7SVzNNgl5EZQ+rv2zem+6iHLd\nUuinrUkW5Mhg7it+TFo0GJVt5+DiEOe28evdwbNa2s1TAGxfi40xYU5BXoMPq3Bv\n7QXLLqcXqX8uM5WhYPIUZ79inWmZ+GsUvCh87Ry8s8ouiJ8uE7mv+iHQZ6szvMyL\nreQl87oTiRS2SFw6ZTCpEKSWr2YM0JmMotvKWhsjHXzzMTr5SfADvx3FC+aPjveA\nCm3qjVVcf5/O9G5Wwmyp19rIwUA3V92a2NJ5knnMowntLjxkMfOFjt0CAwEAAQ==\n-----END RSA PUBLIC KEY-----\n"
}

요청 코드 예시 (Python)

import requests

TUMBLEBUG_SERVER = "localhost:1323"
HEADERS = {'Authorization': 'Basic ...'}

public_key_response = requests.get(f"http://{TUMBLEBUG_SERVER}/tumblebug/credential/publicKey", headers=HEADERS)
public_key_data = public_key_response.json()

public_key = public_key_data['publicKey']
public_key_token_id = public_key_data['publicKeyTokenId']

2. AES 키 생성 및 민감 데이터 암호화

클라이언트는 AES-256 키를 생성해 민감한 credentials 데이터의 값(value) 만 암호화한다.
이 AES 키는 RSA 공개 키로 암호화되어 서버로 전송된다. AES 암호화는 CBC 모드를 사용하며, 패딩은 PKCS7로 처리해야 한다.

AES 기반 데이터 암호화 및 RSA 공개 키를 통한 AES 키 암호화 예시 코드 (Python 예시)

from Crypto.Cipher import AES, PKCS1_OAEP
from Crypto.PublicKey import RSA
from Crypto.Hash import SHA256
from Crypto.Random import get_random_bytes
import base64

def pad(data, block_size):
    padding = block_size - len(data) % block_size
    return data + bytes([padding] * padding)

def encrypt_credential_value_with_publickey(public_key_pem, credentials):
    public_key = RSA.import_key(public_key_pem)
    rsa_cipher = PKCS1_OAEP.new(public_key, hashAlgo=SHA256)
    aes_key = get_random_bytes(32)  # AES-256 키 생성

    encrypted_credentials = {}
    for k, v in credentials.items():
        aes_cipher = AES.new(aes_key, AES.MODE_CBC)
        iv = aes_cipher.iv
        ciphertext = aes_cipher.encrypt(pad(v.encode(), AES.block_size))
        encrypted_credentials[k] = base64.b64encode(iv + ciphertext).decode()

    encrypted_aes_key = base64.b64encode(rsa_cipher.encrypt(aes_key)).decode()
    del aes_key  # 메모리에서 AES 키 삭제

    return encrypted_credentials, encrypted_aes_key

3. Credential 등록

암호화된 AES 키와 암호화된 credentials의 값(value) 들을 서버에 전송해 credentials를 등록한다.
이때, AES 키는 RSA 공개 키로 암호화된 상태로 전송되며, 서버에서 해당 AES 키를 복호화한 후 데이터를 처리한다.

• HTTP Method: POST
• Endpoint: /credential

API 요청 Body

{
  "credentialHolder": "admin",
  "credentialKeyValueList": [
    {
      "key": "ClientId",
      "value": "dPw3+CnCsn0RJXeiZxXnHfW03mFx5RaSfbwtPYCq1h6wwv7XsiWzfFmr02..."
    },
    {
      "key": "ClientSecret",
      "value": "ZzXL27hbAUDT0ohglf2Gwr60sAqdPw3+CnCsn0RJXeiZxXnHfW03mFx5RaSfbwtPYCq1h6wwv7XsiWzfFmr02..."
    }
  ],
  "encryptedClientAesKeyByPublicKey": "ZzXL27hbAUDT0ohglf2Gwr60sAqdPw3+CnCsn0RJXeiZxXnHfW03mFx5RaSfbwtPYCq1h6wwv7XsiWzfFmr02...",
  "providerName": "aws",
  "publicKeyTokenId": "cr5sidugsanc73arjjbg"
}

예시 요청 (Python)

credentials = {
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret"
}
encrypted_credentials, encrypted_aes_key = encrypt_credential_value_with_publickey(public_key, credentials)

credential_payload = {
    "credentialHolder": "admin",
    "providerName": "aws",
    "publicKeyTokenId": public_key_token_id,
    "encryptedClientAesKeyByPublicKey": encrypted_aes_key,
    "credentialKeyValueList": [{"key": k, "value": v} for k, v in encrypted_credentials.items()]
}

response = requests.post(f"http://{TUMBLEBUG_SERVER}/tumblebug/credential", json=credential_payload, headers=HEADERS)
print(response.json())

Go 언어 예시

package main

import (
    "crypto/aes"
    "crypto/cipher"
    "crypto/rand"
    "crypto/rsa"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "io"
    "io/ioutil"
    "net/http"
    "bytes"
)

func main() {
    publicKey, publicKeyTokenId := getPublicKey()

    credentials := map[string]string{
        "ClientId":     "your-client-id",
        "ClientSecret": "your-client-secret",
    }

    encryptedCredentials, encryptedAesKey := encryptCredentialsWithPublicKey(publicKey, credentials)

    payload := map[string]interface{}{
       

 "credentialHolder":                "admin",
        "providerName":                    "aws",
        "publicKeyTokenId":                publicKeyTokenId,
        "encryptedClientAesKeyByPublicKey": encryptedAesKey,
        "credentialKeyValueList":          encryptedCredentials,
    }

    sendCredentials(payload)
}

func getPublicKey() (string, string) {
    resp, err := http.Get("http://localhost:1323/tumblebug/credential/publicKey")
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    // Parse the response to extract public key and token ID
    publicKey := extractPublicKeyFromResponse(body)
    publicKeyTokenId := extractPublicKeyTokenIdFromResponse(body)
    return publicKey, publicKeyTokenId
}

func encryptCredentialsWithPublicKey(publicKeyPem string, credentials map[string]string) (map[string]string, string) {
    rsaPublicKey, err := rsa.DecryptOAEP(sha256.New(), rand.Reader, publicKey, nil, nil)
    if err != nil {
        panic(err)
    }

    aesKey := make([]byte, 32)
    if _, err := io.ReadFull(rand.Reader, aesKey); err != nil {
        panic(err)
    }

    encryptedCredentials := make(map[string]string)
    for k, v := range credentials {
        aesCipher, err := aes.NewCipher(aesKey)
        if err != nil {
            panic(err)
        }
        gcm, err := cipher.NewGCM(aesCipher)
        if err != nil {
            panic(err)
        }
        nonce := make([]byte, gcm.NonceSize())
        if, err := io.ReadFull(rand.Reader, nonce); err != nil {
            panic(err)
        }
        ciphertext := gcm.Seal(nonce, nonce, []byte(v), nil)
        encryptedCredentials[k] = base64.StdEncoding.EncodeToString(ciphertext)
    }

    encryptedAesKey, err := rsa.EncryptOAEP(sha256.New(), rand.Reader, rsaPublicKey, aesKey, nil)
    if err != nil {
        panic(err)
    }
    return encryptedCredentials, base64.StdEncoding.EncodeToString(encryptedAesKey)
}

func sendCredentials(payload map[string]interface{}) {
    client := &http.Client{}
    reqBody, _ := json.Marshal(payload)
    req, err := http.NewRequest("POST", "http://localhost:1323/tumblebug/credential", bytes.NewBuffer(reqBody))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Basic ...")

    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Node.js 예시

const axios = require('axios');
const crypto = require('crypto');

async function main() {
    const { publicKey, publicKeyTokenId } = await getPublicKey();

    const credentials = {
        ClientId: 'your-client-id',
        ClientSecret: 'your-client-secret',
    };

    const { encryptedCredentials, encryptedAesKey } = encryptCredentialsWithPublicKey(publicKey, credentials);

    const payload = {
        credentialHolder: 'admin',
        providerName: 'aws',
        publicKeyTokenId,
        encryptedClientAesKeyByPublicKey: encryptedAesKey,
        credentialKeyValueList: Object.entries(encryptedCredentials).map(([key, value]) => ({ key, value })),
    };

    await sendCredentials(payload);
}

async function getPublicKey() {
    const response = await axios.get('http://localhost:1323/tumblebug/credential/publicKey');
    const { publicKey, publicKeyTokenId } = response.data;
    return { publicKey, publicKeyTokenId };
}

function encryptCredentialsWithPublicKey(publicKeyPem, credentials) {
    const publicKey = crypto.createPublicKey(publicKeyPem);
    const aesKey = crypto.randomBytes(32);

    const encryptedCredentials = {};
    for (const [key, value] of Object.entries(credentials)) {
        const iv = crypto.randomBytes(16);
        const cipher = crypto.createCipheriv('aes-256-cbc', aesKey, iv);
        let encrypted = cipher.update(value, 'utf8', 'base64');
        encrypted += cipher.final('base64');
        encryptedCredentials[key] = Buffer.concat([iv, Buffer.from(encrypted, 'base64')]).toString('base64');
    }

    const encryptedAesKey = crypto.publicEncrypt(
        {
            key: publicKey,
            padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
            oaepHash: 'sha256',
        },
        aesKey
    ).toString('base64');

    return { encryptedCredentials, encryptedAesKey };
}

async function sendCredentials(payload) {
    const response = await axios.post('http://localhost:1323/tumblebug/credential', payload, {
        headers: {
            'Content-Type': 'application/json',
            Authorization: 'Basic ...',
        },
    });
    console.log(response.data);
}

main().catch(console.error);

예시 출력

성공적으로 요청이 완료되면 다음과 같은 형식의 JSON 응답이 반환된다:

{
    "credentialName": "admin-aws",
    "credentialHolder": "admin",
    "providerName": "aws",
    "keyValueInfoList": [
        {"key": "ClientId", "value": "************"},
        {"key": "ClientSecret", "value": "************"}
    ],
    "allConnections": {
        "connectionconfig": [
            {
                "configName": "admin-aws-us-west-1",
                "providerName": "aws",
                "regionZoneInfoName": "us-west-1",
                "regionZoneInfo": {
                    "assignedRegion": "us-west-1",
                    "assignedZone": "us-west-1a"
                },
                "regionRepresentative": true,
                "verified": true
            }
        ]
    }
}

이 가이드를 따라 클라이언트에서 안전하게 credentials를 등록할 수 있다.

[seokho-son]

@MZC-CSC POST /credential 를 웹에서 직접 호출하시는 시나리오를 고려하여, 크리덴셜 암호화 방식을 추가해두었습니다. (mc-iam과 별개로 추가적인 보안 체계)

일단 이해가 잘 되시는지, 내용 살펴봐주시면 감사하겠습니다.