키 별명 작성

IBM® Key Protect for IBM Cloud®을(를) 사용하여 Key Protect API로 키 별명을 작성할 수 있습니다.

IBM® Key Protect for IBM Cloud®을(를) 사용하여 Key Protect 콘솔로 키 별명을 작성할 수 있습니다.

키 별명은 사용자가 읽을 수 있는 고유한 이름으로 키를 참조하며, 표시 이름의 한계를 초과하여 식별하고 그룹화할 수 있습니다. 별명을 사용하면 Key Protect 서비스에서 제공하는 자동 생성 ID가 아니라 인식 가능한 사용자 정의 이름으로 서비스에서 키를 참조할 수 있습니다. 예를 들어 ID가 02fd6835-6001-4482-a892-13bd2085f75d인 키를 작성하고 US-South-Test-Key로 별명이 지정되어 있으면 Key Protect api를 호출하여 US-South-Test-Key키를 검색하거나 메타데이터를 검색할 때 별명을 사용하여 키를 참조할 수 있습니다. 별명을 사용하여 Key Protect 콘솔에서 키를 구성할 수도 있습니다.

콘솔을 사용하여 키 별명 작성 및 편집

키를 작성하거나 가져오는 프로세스 중에 키에 키 별명을 추가할 수 있습니다.

키 별칭을 편집하려면 ⋯를 클릭한 다음 ‘별칭 편집’을 선택하세요. 탭에서 키에 지정된 기존 별명을 보고(삭제 가능) 별명을 추가할 수 있습니다. 키의 별명은 최대 5개일 수 있습니다.

API를 사용하여 키 별명 작성하기

다음 엔드포인트에 대한 POST 호출을 작성하여 키 별명을 작성하십시오.

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/aliases/<alias>

  1. 인증 정보를 검색하여 서비스에서 키에 대한 작업을 수행하십시오.

    키 별명을 작성하려면 관리자 또는 작성자 서비스 액세스 역할이 지정되어 있어야 합니다. IAM 역할을 Key Protect 서비스 조치에 맵핑하는 방법을 알아보려면, 서비스 액세스 역할을 확인하십시오.

  2. 다음 curl 명령을 실행하여 키 별명을 작성하십시오.

    $ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/aliases/<key_alias>" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/vnd.ibm.kms.key+json" \
    -H "correlation-id: <correlation_ID>"

다음 표에 따라 예제 요청의 변수를 대체하십시오.

Key Protect API를 사용하여 키 별칭을 생성하는 데 필요한 변수들을 설명합니다.
가변 설명
지역 필수. Key Protect 인스턴스가 상주하는 지리적 영역을 표시하는 지역 약어(예: us-south 또는 eu-gb)입니다.
자세한 내용은 ‘지역별 서비스 엔드포인트’를 참조하십시오.
keyID_or_alias 필수. 별명과 연관시키려는 키의 ID 또는 별명입니다. 키 ID를 검색하려면 키 나열 API를 참조하십시오.
key_alias 필수. 키를 쉽게 식별할 수 있도록 해 주는 사용자가 읽을 수 있는 고유 이름입니다.

별칭은 영숫자로만 구성되어야 하며, 대소문자를 구분하고, 대시(-)나 밑줄(_) 이외의 공백이나 특수 문자를 포함할 수 없습니다. 별칭은 버전 4 UUID일 수 없으며, 다음 Key Protect 에 나열된 예약된 이름(allowed_ip, key, keys, metadata, policy, policies, registration, registrations, ring, rings, rotate, wrap, unwrap, rewrap, version, versions.Alias )을 사용해서는 안 됩니다. 길이는 2~90자(포함) 사이여야 합니다.

참고: Key Protect 인스턴스 내에서 중복된 별칭 이름을 사용할 수 없습니다.
IAM_token 필수. 사용자의 IBM Cloud 액세스 토큰입니다. curl 요청에 Bearer 값을 포함하여 IAM 토큰의 전체 컨텐츠를 포함하십시오.

자세한 내용은 ‘액세스 토큰 가져오기’를 참조하십시오.
instance_ID 필수. Key Protect 서비스 인스턴스에 지정된 고유 ID입니다.

자세한 내용은 “인스턴스 ID 가져오기”를 참조하십시오.
correlation_ID 선택사항. 트랜잭션을 추적하고 상관시키는 데 사용되는 고유 ID입니다.

개인 데이터의 기밀성을 보호하기 위해 키 별명 작성 시 이름 또는 위치와 같은 개인 식별 정보(PII)를 입력하지 마십시오. 개인 식별 정보(PII)에 대한 더 많은 예시는 NIST 특별 간행물 800-122의 2.2절을 참조하십시오.

성공적인 POST api/v2/keys/<keyID_or_alias>/aliases/<key_alias> 응답에서는 다른 메타데이터와 함께 키에 대한 별명이 리턴됩니다. 별명은 키에 지정되는 고유 이름이며 연관된 키에 대한 자세한 정보를 검색하기 위해 사용할 수 있습니다.

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 1
    },
    "resources": [
        {
            "keyId": "02fd6835-6001-4482-a892-13bd2085f75d",
            "alias": "test-alias",
            "creationDate": "2020-03-12T03:37:32Z",
            "createdBy": "..."
        }
    ]
}

응답 매개변수에 대한 자세한 설명은 Key Protect REST API 참조 문서.

각각의 키에는 최대 5개의 별명이 존재할 수 있습니다. 인스턴스당 별명은 1,000개로 제한됩니다.

API를 사용하여 키 별명 삭제

다음 엔드포인트에 대한 DELETE 호출을 수행하여 키 별명을 삭제하십시오.

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/aliases/<alias>

  1. 인증 정보를 검색하여 서비스에서 키에 대한 작업을 수행하십시오.

  2. 다음 curl 명령을 실행하여 키 별명을 삭제하십시오.

    $ curl -X DELETE \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/aliases/<key_alias>" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/vnd.ibm.kms.key+json" \
    -H "correlation-id: <correlation_ID>"

다음 표에 따라 예제 요청의 변수를 대체하십시오.

Key Protect API를 사용하여 키 별칭을 삭제하는 데 필요한 변수들을 설명합니다.
가변 설명
지역 필수. us-south 또는 eu-gb 과 같은 지역 약어는 Key Protect 인스턴스가 위치한 지리적 영역을 나타냅니다.

자세한 내용은 ‘지역별 서비스 엔드포인트’를 참조하십시오.
keyID_or_alias 필수. 1단계에서 검색한 키의 ID 또는 별명입니다.
key_alias 필수. 키를 식별하는 사용자가 읽을 수 있는 고유 이름입니다.
IAM_token 필수. 사용자의 IBM Cloud 액세스 토큰입니다. curl 요청에 Bearer 값을 포함하여 IAM 토큰의 전체 컨텐츠를 포함하십시오.

자세한 내용은 ‘액세스 토큰 가져오기’를 참조하십시오.
instance_ID 필수. Key Protect 서비스 인스턴스에 지정된 고유 ID입니다.
자세한 내용은 “인스턴스 ID 가져오기”를 참조하십시오.
correlation_ID 선택사항. 트랜잭션을 추적하고 상관시키는 데 사용되는 고유 ID입니다.

성공적인 DELETE api/v2/keys/<keyID_or_alias>/aliases/<key_alias> 요청에서는 키와 연관된 별명이 삭제되었음을 나타내는 HTTP 204 No Content 응답이 리턴됩니다.

서비스에서 별명이 완전히 삭제되려면 최대 5분이 걸립니다.

키 별명 FAQ

다음은 주요 별칭에 대한 추가 정보입니다:

  • 별명은 키와 별개입니다. 별명은 고유한 리소스이며 별명에 대해 수행되는 조치는 연관된 키에 영향을 주지 않습니다. 예를 들어, 별명을 삭제해도 연관된 키는 삭제되지 않습니다.

  • 별명은 한 번에 하나의 키와만 연관될 수 있습니다. 별명은 동일한 인스턴스와 지역에 있는 하나의 키와만 연관될 수 있습니다. 별명이 연관되어 있는 키를 변경하려면 별명을 삭제하고 최대 5분 동안 기다린 후 별명을 다시 작성하고 필요한 키에 맵핑해야 합니다.

  • 다른 인스턴스 또는 지역에서 동일한 이름의 별명을 작성할 수 있습니다. 각 별명은 각 인스턴스 또는 지역의 다른 키와 연관됩니다. 그러면 서비스의 애플리케이션 코드를 다른 인스턴스 또는 지역에서 재사용할 수 있습니다. 예를 들어 다음과 같은 별칭이 있는 경우 Application Key 미국-남부와 미국-동부 지역 모두에서 각각 다른 키에 연결되어 있으며 다른 키에 연결됩니다.

키 별명을 사용하는 API

다음 표에는 키 별명을 작성하고 사용하는 데 사용할 수 있는 API가 나열되어 있습니다.

키 별칭을 사용하는 API인 변수들을 설명합니다.
API 키 별명 영향
루트 키 작성 루트 키를 작성하는 동안 최대 5개의 별명을 작성할 수 있습니다.
표준 키 작성 표준 키를 작성하는 동안 최대 5개의 별명을 작성할 수 있습니다.
키 검색 ID 또는 별명으로 키를 검색할 수 있습니다.
키 메타데이터 보기 ID 또는 별명으로 키의 메타데이터를 검색할 수 있습니다.