Edge 관리 API를 사용하여 키 저장소 및 트러스트 저장소 만들기

Apigee Edge 문서입니다.
Go to the Apigee X 문서로 이동합니다. info

이 문서에서는 Cloud용 Edge 및 Private Cloud 버전 4.18.01 이상용 Edge의 키 저장소 및 트러스트 저장소를 만들고 수정하고 삭제하는 방법을 설명합니다.

소개

TLS와 같은 공개 키 인프라를 사용하는 기능을 구성하려면 필요한 키와 디지털 인증서를 제공하는 키 저장소와 트러스트 저장소를 만들어야 합니다.

키 저장소, 트러스트 저장소, 별칭에 대한 소개는 키 저장소 및 트러스트 저장소를 참조하세요.

키 저장소 만들기

키 저장소는 조직의 환경(예: 테스트 또는 프로덕션 환경)에 따라 다릅니다. 따라서 프로덕션 환경에 배포하기 전에 테스트 환경에서 키 저장소를 테스트하려면 두 환경 모두에서 키 저장소를 만들어야 합니다.

환경에서 키 저장소를 만들려면 다음 단계를 따르세요.

  1. 이 섹션의 API 호출을 사용하여 키 저장소를 만듭니다.
  2. 별칭을 만들고 인증서/키 쌍을 별칭에 업로드합니다. 인증서 및 키를 업로드하는 방법은 인증서/키 쌍의 형식을 기반으로 합니다. 다음 섹션에서는 각 인증서/키 쌍 유형을 업로드하는 방법을 설명합니다:

키 저장소를 만들려면 키 저장소 또는 트러스트 저장소 만들기 API에 키 저장소 이름을 지정합니다. 키 저장소 이름에는 영숫자 문자만 포함할 수 있습니다.

curl -X POST -u orgAdminEmail:password -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>'

샘플 응답:

{
  "certs" : [ ],
  "keys" : [ ],
  "name" : "myKeystore"
}

인증서 및 키를 JAR 파일로 업로드

먼저 비공개 키, 인증서, 매니페스트가 포함된 JAR 파일을 만들어야 합니다. JAR 파일에는 다음 파일과 디렉터리가 포함되어야 합니다.

/META-INF/descriptor.properties
myCert.pem
myKey.pem

키 저장소 JAR에는 이 세 파일만 포함될 수 있습니다. 인증서 체인이 있는 경우 체인의 모든 인증서 를 단일 PEM 파일에 추가해야 합니다. 여기서 마지막 인증서는 루트 CA에서 서명 해야 합니다. 인증서는 각 인증서 사이에 빈 줄이 있는 올바른 순서로 PEM 파일에 추가해야 합니다. 즉 다음과 같습니다.

cert -> intermediate cert(1) -> intermediate cert(2) -> … -> root

키 쌍과 인증서가 포함된 디렉터리에서 /META-INF라는 디렉터리를 만듭니다. 그런 다음 /META-INF에서 descriptor.properties라는 파일을 만들고 다음 콘텐츠를 추가합니다.

certFile={myCertificate}.pem
keyFile={myKey}.pem

키 쌍과 인증서가 포함된 JAR 파일을 생성합니다.

jar -cf myKeystore.jar myCert.pem myKey.pem

JAR 파일에 descriptor.properties을 추가합니다.

jar -uf myKeystore.jar META-INF/descriptor.properties

이제 JAR 또는 PKCS 파일에서 별칭 만들기 API를 사용하여 인증서와 비공개 키가 포함된 JAR 파일을 업로드할 수 있습니다.

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertjar"

여기서 -F 옵션은 JAR 파일의 경로를 지정합니다.

이 호출에서 다음을 지정합니다.

  • alias_name - 키 저장소에서 인증서와 키를 식별합니다. 가상 호스트를 만들 때 별칭 이름으로 인증서와 키를 참조합니다.
  • key_pword - 비공개 키의 비밀번호입니다. 비공개 키에 비밀번호가 없는 경우 이 매개변수를 생략합니다.

키 저장소가 올바르게 업로드되었는지 확인합니다.

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

샘플 응답:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

인증서 및 키를 PEM 파일로 업로드

인증서 및 키 PEM 파일에서 별칭 만들기 API를 사용하여 인증서와 비공개 키가 포함된 PEM 파일을 업로드합니다.

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F keyFile="@server.key" -F certFile="@signed.crt" \
-F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertfile"

여기서 -F 옵션은 PEM 파일의 경로를 지정합니다.

이 호출에서 다음을 지정합니다.

  • alias_name - 키 저장소에서 인증서와 키를 식별합니다. 가상 호스트를 만들 때 별칭 이름으로 인증서와 키를 참조합니다.
  • key_pword - 비공개 키의 비밀번호입니다. 비공개 키에 비밀번호가 없는 경우 이 매개변수를 생략합니다.

키 저장소가 올바르게 업로드되었는지 확인합니다.

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

샘플 응답:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

인증서 및 키를 PKCS12/PFX 파일로 업로드

JAR 또는 PKCS 파일에서 별칭 만들기 API를 사용하여 인증서와 비공개 키가 포함된 PKCS12/PFX 파일을 업로드합니다.

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.p12" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=pkcs12"

여기서 -F 옵션은 P12 파일의 경로를 지정합니다.

이 호출에서 다음을 지정합니다.

  • alias_name - 키 저장소에서 인증서와 키를 식별합니다. 가상 호스트를 만들 때 별칭 이름으로 인증서와 키를 참조합니다.
  • key_pword - 비공개 키의 비밀번호입니다. 비공개 키에 비밀번호가 없는 경우 이 매개변수를 생략합니다.

키 저장소가 올바르게 업로드되었는지 확인합니다.

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

샘플 응답:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

자체 서명된 인증서 및 키 만들기 및 업로드

자체 서명된 인증서 생성 API로 별칭 만들기 API를 사용하여 자체 서명된 인증서 및 키를 만들고 별칭에 업로드할 수 있습니다. 다음 호출은 자체 서명된 인증서를 만드는 데 필요한 정보만 지정합니다. 이 호출을 수정하여 추가 정보를 추가할 수 있습니다.

curl -u orgAdminEmail:password -X POST --header "Content-Type: application/json"  \
-d "{
    "alias": "selfsigned",
    "subject": {
        "commonName": "mycert"
    }
}" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?format=selfsignedcert"

다음과 같은 응답이 표시됩니다.

{
  "alias": "selfsigned",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:FALSE",
        "expiryDate": 1491497204000,
        "isValid": "Yes",
        "issuer": "CN=mycert",
        "publicKey": "RSA Public Key, 2048 bits",
        "serialNumber": "00:d1:b4:78:e1",
        "sigAlgName": "SHA256withRSA",
        "subject": "CN=mycert",
        "subjectAlternativeNames": [],
        "validFrom": 1459961204000,
        "version": 3
      }
    ],
    "certName": "selfsigned-cert"
  },
  "keyName": "selfsigned"
}

트러스트 저장소 만들기

트러스트 저장소를 만드는 데 사용하는 API는 키 저장소를 만드는 데 사용하는 API와 동일합니다. 유일한 차이점은 인증서 파일만 PEM 파일로 트러스트 저장소에 업로드한다는 것입니다.

인증서가 체인의 일부인 경우 체인의 모든 인증서를 트러스트 저장소에 별도로 업로드하거나 모든 인증서가 포함된 단일 파일을 만들어야 합니다. 파일의 각 인증서 사이에 빈 줄을 삽입해야 합니다.

체인의 일부가 아닌 자체 서명된 인증서를 여러 개 업로드하려면 동일한 기법을 사용합니다. 신뢰할 인증서가 여러 개 있는 경우 단일 파일로 업로드합니다.

최종 인증서는 일반적으로 인증서 발급기관에서 서명합니다. 예를 들어 트러스트 저장소에서 클라이언트 인증서(client_cert_1)와 클라이언트 인증서 발급기관의 인증서(ca_cert)를 업로드합니다.

양방향 TLS 인증 중에 서버가 client_cert_1을 클라이언트에 전송하면 클라이언트 인증이 성공합니다.

또는 동일한 인증서(ca_cert)로 서명된 두 번째 인증서(client_cert_2)가 있습니다. 하지만 client_cert_2를 트러스트 저장소에 업로드하지는 않습니다. 트러스트 저장소에는 여전히 client_cert_1과 ca_cert가 포함되어 있습니다.

서버가 TLS 핸드셰이크의 일부로 client_cert_2를 전달하면 요청이 성공합니다. 이는 Edge에서 client_cert_2가 트러스트 저장소에 없지만 트러스트 저장소에 있는 인증서로 서명된 경우 TLS 검증이 성공하도록 허용하기 때문입니다. 트러스트 저장소에서 CA 인증서(ca_cert)를 삭제하면 TLS 검증이 실패합니다.

키 저장소를 만드는 데 사용하는 것과 동일한 API인 키 저장소 또는 트러스트 저장소 만들기를 사용하여 환경에서 빈 트러스트 저장소를 만듭니다.

curl -u orgAdminEmail:password -X POST -H "Content-Type: text/xml" \
-d '<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

트러스트 저장소를 만든 후 인증서 PEM 파일에서 별칭 만들기 API를 사용하여 인증서를 PEM 파일로 트러스트 저장소에 업로드합니다.

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F certFile="@cert.pem" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myTruststore/aliases?alias=myTruststore&format=keycertfile"

여기서 -F 옵션은 PEM 파일의 경로를 지정합니다.

기존 키 저장소 또는 트러스트 저장소에 대한 세부정보 가져오기

키 저장소 및 트러스트 저장소 나열 API를 사용하여 환경에 기존 키 저장소가 있는지 확인합니다.

curl -u orgAdminEmail:password -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

클라우드 고객의 경우 테스트 및 프로덕션 환경 모두에서 체험판 조직에 기본 키 저장소가 무료로 제공됩니다. 두 환경 모두에서 이 호출에 대해 다음과 같은 결과가 표시됩니다. 

[ "freetrial" ]

이 기본 키 저장소를 사용하여 API를 테스트하고 API를 프로덕션에 푸시할 수 있지만 일반적으로 프로덕션에 배포하기 전에 자체 인증서 및 키가 포함된 자체 키 저장소를 만듭니다.

Private Cloud 고객의 경우 첫 번째 키 저장소를 만들 때까지 반환된 배열이 비어 있습니다.

키 저장소 또는 트러스트 저장소 가져오기 API를 사용하여 키 저장소의 콘텐츠를 확인합니다. 클라우드 고객의 경우 Apigee Edge에서 체험판 계정에 무료로 제공하는 기본 인증서인 단일 서버 TLS 인증서가 표시됩니다.

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/freetrial

다음과 같은 응답이 표시됩니다.

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

별칭에 대한 세부정보 가져오기

별칭 나열 API를 사용하여 키 저장소의 모든 별칭 목록을 가져옵니다.

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases"

다음과 같은 응답이 표시됩니다.

[
  "alias1",
  "alias2",
  "alias3",
]

만료일 및 발급기관과 같은 별칭에 대한 모든 정보를 가져오려면 별칭 가져오기 API를 사용하고 별칭 이름을 지정합니다.

curl  -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}"

다음과 같은 응답이 표시됩니다.

{
  "alias": "alias1",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:TRUE",
        "expiryDate": 1459371335000,
        "isValid": "No",
        "issuer": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "publicKey": "RSA Public Key, 1024 bits",
        "serialNumber": "00:86:a0:9b:5b:91:a9:fe:92",
        "sigAlgName": "SHA256withRSA",
        "subject": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "subjectAlternativeNames": [],
        "validFrom": 1456779335000,
        "version": 3
      }
    ],
    "certName": "new\-cert"
  },
  "keyName": "newssl20"
}

별칭의 인증서를 다운로드하려면 별칭의 인증서 내보내기 API를 사용합니다.

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/e/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/certificate"

다음과 같은 응답이 표시됩니다.

-----BEGIN CERTIFICATE-----
MIIDojCCAwugAwIBAgIJAIagm1uRqf6SMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYD
...
RBUkaTe/570sLHY0tvkIm5tEX36ESw==
-----END CERTIFICATE-----

만료된 인증서가 있고 갱신하려는 경우 인증서 서명 요청 (CSR)을 다운로드할 수 있습니다. 그런 다음 CSR을 CA로 전송하여 새 인증서를 가져옵니다. 별칭의 CSR을 생성하려면 별칭의 CSR 생성 API를 사용합니다.

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/csr"

다음과 같은 응답이 표시됩니다.

-----BEGIN CERTIFICATE REQUEST-----
MIIB1DCCAT0CAQAwgZMxCzAJBgNVBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRl
...
RF5RMytbkxkvPxIE17mDKJH0d8aekv/iEOItZ+BtQg+EibMUkkjTzQ==
-----END CERTIFICATE REQUEST-----

양방향 TLS의 트러스트 저장소에 인증서 추가

인바운드 연결(Edge로의 API 요청)에 양방향 TLS를 사용하는 경우 트러스트 저장소에는 Edge에 요청을 보낼 수 있는 각 클라이언트의 인증서 또는 CA 체인이 포함됩니다.

트러스트 저장소를 처음 구성할 때 알려진 클라이언트의 모든 인증서를 추가할 수 있습니다. 하지만 시간이 지남에 따라 새 클라이언트를 추가할 때 트러스트 저장소에 인증서를 추가할 수 있습니다.

양방향 TLS에 사용되는 트러스트 저장소에 새 인증서를 추가하려면 다음 단계를 따르세요.

  1. 가상 호스트에서 트러스트 저장소에 대한 참조를 사용하고 있는지 확인합니다.
  2. 위의 트러스트 저장소 만들기에 설명된 대로 새 인증서를 트러스트 저장소에 업로드합니다.

  3. 트러스트 저장소 참조를 업데이트하여 동일한 값으로 설정합니다. 이 업데이트로 인해 Edge에서 트러스트 저장소와 새 인증서가 다시 로드됩니다.

    자세한 내용은 참조 수정을 참조하세요.

키 저장소/트러스트 저장소 또는 별칭 삭제

키 저장소/트러스트 저장소 또는 별칭을 삭제할 때는 주의해야 합니다. 가상 호스트, 대상 엔드포인트 또는 대상 서버에서 사용 중인 키 저장소, 트러스트 저장소 또는 별칭을 삭제하면 가상 호스트 또는 대상 엔드포인트/대상 서버를 통한 모든 API 호출이 실패합니다.

일반적으로 키 저장소/트러스트 저장소 또는 별칭을 삭제하는 데 사용하는 프로세스는 다음과 같습니다.

  1. 위에 설명된 대로 새 키 저장소/트러스트 저장소 또는 별칭을 만듭니다.
  2. 인바운드 연결(Edge로의 API 요청)의 경우 가상 호스트 구성을 업데이트하여 새 키 저장소 및 키 별칭을 참조합니다.
  3. 아웃바운드 연결(Apigee에서 백엔드 서버로)의 경우 다음 단계를 따르세요.
    1. 이전 키 저장소 및 키 별칭을 참조한 API 프록시의 TargetEndpoint 구성을 업데이트하여 새 키 저장소 및 키 별칭을 참조합니다. TargetEndpoint 가 TargetServer를 참조하는 경우 TargetServer 정의를 업데이트하여 새 키 저장소 및 키 별칭을 참조합니다.
    2. 키 저장소 및 트러스트 저장소가 TargetEndpoint 정의에서 직접 참조되는 경우 프록시를 다시 배포해야 합니다. TargetEndpoint가 TargetServer 정의를 참조하고 TargetServer 정의가 키 저장소 및 트러스트 저장소를 참조하는 경우 프록시를 다시 배포할 필요가 없습니다.
    3. API 프록시가 올바르게 작동하는지 확인합니다.
    4. 키 저장소/트러스트 저장소 또는 별칭을 삭제합니다.

자세한 내용은 별칭의 인증서 업데이트를 참조하세요.

키 저장소 또는 트러스트 저장소 삭제

키 저장소 또는 트러스트 저장소 삭제 API를 사용하여 키 저장소 또는 트러스트 저장소를 삭제할 수 있습니다.

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName

가상 호스트에서 사용 중인 키 저장소 또는 트러스트 저장소를 삭제하고 다시 만드는 경우 API 프록시를 다시 배포해야 합니다.

별칭 삭제

별칭 삭제 API를 사용하여 키 저장소 또는 트러스트 저장소에서 별칭을 삭제할 수 있습니다.

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName/aliases/{alias_name}