# API Gateway의 REST API 보안 정책
보안 정책은 API Gateway가 제공하는 최소 TLS 버전과 암호 제품군의 사전 정의된 조합입니다.** 클라이언트가 API 또는 사용자 맞춤형 도메인 이름에 대해 TLS 핸드셰이크를 설정할 때, 보안 정책은 API Gateway가 허용하는 TLS 버전 및 암호 제품군을 강제 적용합니다. 보안 정책은 API 및 사용자 지정 도메인 이름을 클라이언트와 서버 간의 변조 및 도청과 같은 네트워크 보안 문제로부터 보호합니다.
API Gateway는 레거시 보안 정책과 향상된 보안 정책을 지원합니다. `TLS_1_0` 및 `TLS_1_2`는 레거시 보안 정책입니다. 이전 버전과의 호환성을 위해 이러한 보안 정책을 사용합니다. `SecurityPolicy_`로 시작하는 모든 정책은 향상된 보안 정책입니다. 규제 워크로드, 고급 거버넌스 또는 양자 내성 암호를 사용하려면 이러한 정책을 사용합니다. 향상된 보안 정책을 사용하는 경우 추가 거버넌스를 위해 엔드포인트 액세스 모드도 설정해야 합니다. 자세한 내용은 [엔드포인트 액세스 모드](#apigateway-security-policies-endpoint-access-mode) 섹션을 참조하세요.
## API Gateway가 보안 정책을 적용하는 방법
다음 예제에서는 API Gateway가 보안 정책을 예로 사용하여 `SecurityPolicy_TLS13_1_3_2025_09` 보안 정책을 적용하는 방법을 보여 줍니다.
이 `SecurityPolicy_TLS13_1_3_2025_09` 보안 정책은 TLS 1.3 트래픽을 허용하고 TLS 1.2 및 TLS 1.0 트래픽은 거부합니다. TLS 1.3 트래픽의 경우 보안 정책은 다음 암호 그룹을 허용합니다.
+ `TLS_AES_128_GCM_SHA256`
+ `TLS_AES_256_GCM_SHA384`
+ `TLS_CHACHA20_POLY1305_SHA256`
API Gateway는 다른 암호 그룹을 허용하지 않습니다. 예를 들어 보안 정책은 암호 제품군을 사용하는 모든 TLS `AES128-SHA` 1.3 트래픽을 거부합니다. 지원되는 TLS 버전 및 암호에 대한 자세한 내용은 [지원되는 보안 정책](apigateway-security-policies-list.md) 섹션을 참조하세요.
API Gateway에 액세스하는 데 사용되는 TLS 프로토콜 및 암호 클라이언트를 모니터링하려면 액세스 로그에서 `$context.tlsVersion` 및 `$context.cipherSuite` 컨텍스트 변수를 사용할 수 있습니다. 자세한 내용은 [API Gateway에서 REST API 모니터링](rest-api-monitor.md) 섹션을 참조하세요.
## 엔드포인트 액세스 모드
엔드포인트 액세스 모드는 `SecurityPolicy_`로 시작하는 향상된 보안 정책을 사용하는 모든 REST API 또는 사용자 지정 도메인 이름에 대해 지정해야 하는 추가 파라미터입니다. 리소스를 생성하거나 보안 정책을 레거시 정책에서 향상된 정책으로 변경할 때 이 작업을 수행합니다.
엔드포인트 액세스 모드가 `STRICT`로 설정된 경우 REST API 또는 사용자 지정 도메인 이름에 대한 모든 요청은 다음 검사를 통과해야 합니다.
+ 요청은 리소스와 동일한 API Gateway 엔드포인트 유형에서 시작되어야 합니다. 이는 리전, 엣지 최적화 또는 프라이빗 엔드포인트에서 발생할 수 있습니다.
+ 리전 또는 프라이빗 엔드포인트를 사용하는 경우 API Gateway는 SNI 호스트 일치를 사용합니다. 엣지 최적화 엔드포인트를 사용하는 경우 API Gateway는 CloudFront의 도메인 프런트닝 보호를 준수합니다. 자세한 내용은 [도메인 프론팅](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/CNAMEs.html#alternate-domain-names-restrictions)을 참조하세요.
이러한 조건 중 하나가 충족되지 않으면 API Gateway는 요청을 거부합니다. 가능하면 `STRICT` 엔드포인트 액세스 모드를 사용하는 것이 좋습니다.
엄격한 엔드포인트 액세스 모드를 사용하도록 기존 API 또는 도메인 이름을 마이그레이션하려면 먼저 보안 정책을 향상된 보안 정책으로 업데이트하고 엔드포인트 액세스 모드를 `BASIC`으로 설정한 상태로 유지합니다. 트래픽 및 액세스 로그를 검증한 후 엔드포인트 액세스 모드를 `STRICT`로 설정합니다. 엔드포인트 액세스 모드를 `STRICT`에서 `BASIC`으로 마이그레이션하면 변경 사항이 전파됨에 따라 약 15분 동안 엔드포인트를 사용할 수 없습니다.
특정 애플리케이션 아키텍처에 대해 엔드포인트 액세스 모드를 `STRICT`로 설정해서는 안 되며, 대신 엔드포인트 액세스 모드를 `BASIC`으로 설정해야 합니다. 다음 표에는 REST API 또는 사용자 지정 도메인 이름이 `STRICT` 엔드포인트 액세스 모드를 사용할 수 있도록 몇 가지 애플리케이션 아키텍처와 권장 사항이 나와 있습니다.
| 아키텍처 | 권장되는 마이그레이션 |
| --- | --- |
| VPC 엔드포인트를 사용하여 퍼블릭 사용자 지정 도메인 이름에 액세스합니다. | 이 아키텍처는 교차 엔드포인트 유형 트래픽을 사용합니다. [API Gateway의 프라이빗 API에 대한 사용자 지정 도메인 이름](apigateway-private-custom-domains.md)으로 마이그레이션하는 것을 권장합니다. |
| 메서드를 사용하여 사용자 지정 도메인 이름 또는 프라이빗 DNS 이름을 사용하지 않는 프라이빗 API를 간접적으로 호출합니다. | 이 아키텍처는 호스트 헤더와 TLS 핸드셰이크에 사용되는 SNI 간에 불일치를 생성하고 CloudFront의 도메인 프런트닝 제한을 통과하지 않습니다. 프라이빗 DNS를 사용하도록 VPC를 마이그레이션하는 것이 좋습니다. |
| 도메인 샤딩을 사용하여 여러 도메인 또는 하위 도메인에 콘텐츠를 배포합니다. | 이 아키텍처는 호스트 헤더와 TLS 핸드셰이크에 사용되는 SNI 간에 불일치를 생성하고 CloudFront의 도메인 프런트닝 제한을 통과하지 않습니다. 이러한 안티 패턴을 사용하지 않고 `HTTP/2`를 사용할 것을 권장합니다. |
엔드포인트 액세스 모드 사용에 대한 고려 사항은 다음과 같습니다.
+ API 또는 도메인 이름의 엔드포인트 액세스 모드가 `STRICT`인 경우 엔드포인트 유형을 변경할 수 없습니다. 엔드포인트 유형을 변경하려면 먼저 엔드포인트 액세스 모드를 `BASIC`으로 변경합니다.
+ 엔드포인트 액세스 모드를 `BASIC`에서 `STRICT`로 변경하면 API Gateway가 엄격한 엔드포인트 액세스 모드를 적용하는 데 15분의 지연이 발생합니다.
+ `SecurityPolicy_`로 시작하는 정책에서 레거시 정책으로 보안 정책을 변경하는 경우 엔드포인트 액세스 모드를 `""`로 설정 해제해야 합니다.
## 고려 사항
API Gateway의 REST API에 대한 보안 정책에 대한 고려 사항은 다음과 같습니다.
+ OpenAPI 정의 파일에서 보안 정책을 가져올 수 있습니다. 자세한 내용은 [x-amazon-apigateway-endpoint-access-modex-amazon-apigateway-security-policy](openapi-extensions-security-policy.md) 섹션을 참조하세요.
+ API는 API와 보안 정책이 다른 사용자 지정 도메인 이름에 매핑할 수 있습니다. 해당 사용자 지정 도메인 이름을 간접적으로 호출하면 API Gateway는 API의 보안 정책을 사용하여 TLS 핸드셰이크를 협상합니다. 기본 API 엔드포인트를 비활성화하면 직접 호출자가 API를 간접적으로 호출하는 방법에 영향을 미칠 수 있습니다.
+ 보안 정책을 변경하는 경우 업데이트가 완료되는 데 약 15분이 걸립니다. API의 `apiStatus`를 모니터링할 수 있습니다. API가 업데이트되면 `apiStatus`는 `UPDATING`이고 완료되면 `AVAILABLE`이 됩니다. API 상태가 `UPDATING`인 경우에도 API를 간접적으로 호출할 수 있습니다.
+ API Gateway는 모든 API에서 보안 정책을 지원합니다. 하지만 REST API에 대해서만 보안 정책을 선택할 수 있습니다. API Gateway는 HTTP 또는 WebSocket API에 대한 `TLS_1_2` 보안 정책만 지원합니다.
+ API에 대한 보안 정책은 `TLS_1_0`에서 `TLS_1_2`로 업데이트할 수 없습니다.
+ 일부 보안 정책은 ECDSA 및 RSA 암호 제품군을 모두 지원합니다. 사용자 지정 도메인 이름과 함께 이 유형의 정책을 사용하는 경우 암호 그룹은 고객이 제공한 인증서 키 유형인 RSA 또는 ECDSA와 일치합니다. REST API에서 이 유형의 정책을 사용하는 경우 암호 제품군은 RSA 인증서 유형과 호환되는 암호 제품군과 일치합니다.
# 지원되는 보안 정책
다음 표에서는 각 REST API 엔드포인트 유형과 사용자 지정 도메인 이름 유형에 대해 지정할 수 있는 [보안 정책](apigateway-security-policies.md)을 설명합니다. 이러한 정책을 통해 수신 연결을 제어할 수 있습니다. API Gateway는 송신 시 TLS 1.2만 지원합니다. 언제든지 API 또는 사용자 지정 도메인 이름에 대한 보안 정책을 업데이트할 수 있습니다.
제목에 `FIPS`가 포함된 정책은 민감한 정보를 보호하는 암호화 모듈에 대한 보안 요구 사항을 지정하는 미국 및 캐나다 정부 표준인 연방 정보 처리 표준(FIPS)과 호환됩니다. 자세한 내용은 *AWS 클라우드 보안 규정 준수* 페이지의 [Federal Information Processing Standard(FIPS) 140](https://aws.amazon.com/compliance/fips/)을 참조하세요.
모든 FIPS 정책은 AWS-LC FIPS 검증 암호화 모듈을 활용합니다. 자세한 내용은 *NIST 암호화 모듈 검증 프로그램* 사이트의 [AWS-LC 암호화 모듈](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4631) 페이지를 참조하세요.
제목에 `PQ`가 포함된 정책은 [양자 내성 암호(PQC)](https://aws.amazon.com/security/post-quantum-cryptography/)를 사용하여 TLS에 대한 하이브리드 키 교환 알고리즘을 구현하여 향후 양자 컴퓨팅 위협에 대한 트래픽 기밀성을 보장합니다.
제목에 `PFS`가 포함된 정책은 [Perfect Forward Secrecy(PFS)](https://en.wikipedia.org/wiki/Forward_secrecy)를 사용하여 세션 키가 손상되지 않도록 합니다.
제목에 `FIPS` 및 `PQ`가 모두 포함된 정책은 이러한 기능을 모두 지원합니다.
## 기본 보안 정책
새 REST API 또는 사용자 지정 도메인을 생성하면 리소스에 기본 보안 정책이 할당됩니다. 다음 표에는 이러한 리소스에 대한 기본 보안 정책이 나와 있습니다.
| **리소스** | **기본 보안 정책 이름** |
| --- | --- |
| 리전 API | TLS\$11\$10 |
| 엣지 최적화 API | TLS\$11\$10 |
| 프라이빗 API | TLS\$11\$12 |
| 지역 도메인 | TLS\$11\$12 |
| 엣지 최적화 도메인 | TLS\$11\$12 |
| 프라이빗 도메인 | TLS\$11\$12 |
## 리전 및 프라이빗 API와 사용자 지정 도메인 이름에 지원되는 보안 정책
다음 표에서는 지역 및 프라이빗 API와 사용자 지정 도메인 이름에 대해 지정할 수 있는 보안 정책을 설명합니다.
| **보안 정책** | **지원되는 TLS 버전** | **지원되는 암호** |
| --- | --- | --- |
| SecurityPolicy\$1TLS13\$11\$13\$12025\$109 | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1TLS13\$11\$13\$1FIPS\$12025\$109 | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1TLS13\$11\$12\$1PFS\$1PQ\$12025\$109 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1TLS13\$11\$12\$1PQ\$12025\$109 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$12 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$10 | TLS1.3 TLS1.2 TLS1.1 TLS1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
## 엣지 최적화 API 및 사용자 지정 도메인 이름에 지원되는 보안 정책
다음 표에서는 엣지 최적화 API와 엣지 최적화 사용자 지정 도메인 이름에 대해 지정할 수 있는 보안 정책을 설명합니다.
| **보안 정책 이름** | **지원되는 TLS 버전** | **지원되는 암호** |
| --- | --- | --- |
| SecurityPolicy\$1TLS13\$12025\$1EDGE | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1TLS12\$1PFS\$12025\$1EDGE | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1TLS12\$12018\$1EDGE | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$10 | TLS1.3 TLS1.2 TLS1.1 TLS1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
## OpenSSL 및 RFC 암호 이름
OpenSSL 및 IETF RFC 5246은 동일한 암호에 대해 서로 다른 이름을 사용합니다. 다음 표에는 각 암호의 RFC 이름에 OpenSSL 이름이 매핑되어 있습니다. 자세한 내용은 OpenSSL 설명서의 [ciphers](https://docs.openssl.org/1.1.1/man1/ciphers/)를 참조하세요.
| **OpenSSL 암호 이름** | **RFC 암호 이름** |
| --- | --- |
| TLS\$1AES\$1128\$1GCM\$1SHA256 | TLS\$1AES\$1128\$1GCM\$1SHA256 |
| TLS\$1AES\$1256\$1GCM\$1SHA384 | TLS\$1AES\$1256\$1GCM\$1SHA384 |
| TLS\$1CHACHA20\$1POLY1305\$1SHA256 | TLS\$1CHACHA20\$1POLY1305\$1SHA256 |
| ECDHE-RSA-AES128-GCM-SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 |
| ECDHE-RSA-AES128-SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 |
| ECDHE-RSA-AES128-SHA | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA |
| ECDHE-RSA-AES256-GCM-SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 |
| ECDHE-RSA-AES256-SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 |
| ECDHE-RSA-AES256-SHA | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA |
| AES128-GCM-SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 |
| AES256-GCM-SHA384 | TLS\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 |
| AES128-SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 |
| AES256-SHA | TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA |
| AES128-SHA | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA |
| DES-CBC3-SHA | TLS\$1RSA\$1WITH\$13DES\$1EDE\$1CBC\$1SHA |
# 보안 정책을 변경하는 방법
API의 보안 정책을 변경할 수 있습니다. 사용자 지정 도메인 이름을 통해 API로 트래픽을 전송하는 경우 API와 사용자 지정 도메인 이름은 동일한 보안 정책을 가질 필요가 없습니다. 해당 사용자 지정 도메인 이름을 간접적으로 호출하면 API Gateway는 API의 보안 정책을 사용하여 TLS 핸드셰이크를 협상합니다. 그러나 일관성을 위해 사용자 지정 도메인 이름 및 API에 동일한 보안 정책을 사용하는 것이 좋습니다.
보안 정책을 변경하는 경우 업데이트가 완료되는 데 약 15분이 걸립니다. API의 `apiStatus`를 모니터링할 수 있습니다. API가 업데이트되면 `apiStatus`는 `UPDATING`이고 완료되면 `AVAILABLE`이 됩니다. API를 업데이트할 때도 API를 간접적으로 호출할 수 있습니다.
------
#### [ AWS Management Console ]
**API의 보안 정책 변경**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. **API 설정**을 선택한 다음 **편집**을 선택합니다.
1. **보안 정책**에서 `SecurityPolicy_`로 시작하는 새 정책을 선택합니다.
1. **엔드포인트 액세스 모드**에서 **엄격**을 선택합니다.
1. **변경 사항 저장**을 선택합니다.
변경 사항을 적용하려면 API를 재배포합니다. 엔드포인트 액세스 모드를 엄격으로 변경했으므로 변경 사항이 완전히 전파되는 데 약 15분이 걸립니다.
------
#### [ AWS CLI ]
다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령은 `SecurityPolicy_TLS13_1_3_2025_09` 보안 정책을 사용하도록 API를 업데이트합니다.
```
aws apigateway update-rest-api \
--rest-api-id abcd1234 \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "SecurityPolicy_TLS13_1_3_2025_09"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": "STRICT"
}
]'
```
출력은 다음과 같습니다.
```
{
"id": "abcd1234",
"name": "MyAPI",
"description": "My API with a new security policy",
"createdDate": "2025-02-04T11:47:06-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"tags": {},
"disableExecuteApiEndpoint": false,
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "STRICT"
"rootResourceId": "efg456"
}
```
다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령은 보안 정책을 사용하기 위해 향상된 보안 `TLS_1_0` 정책을 사용하는 API를 업데이트합니다.
```
aws apigateway update-rest-api \
--rest-api-id abcd1234 \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "TLS_1_0"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": ""
}
]'
```
출력은 다음과 같습니다.
```
{
"id": "abcd1234",
"name": "MyAPI",
"description": "My API with a new security policy",
"createdDate": "2025-02-04T11:47:06-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"tags": {},
"disableExecuteApiEndpoint": false,
"securityPolicy": "TLS_1_0",
"rootResourceId": "efg456"
}
```
------