This is the API Reference for Network Firewall. This guide is for developers who need detailed information about the Network Firewall API actions, data types, and errors.
The REST API requires you to handle connection details, such as calculating signatures, handling request retries, and error handling. For general information about using the Amazon Web Services REST APIs, see Amazon Web Services APIs.
To access Network Firewall using the REST API endpoint: https://network-firewall.<region>.amazonaws.com
Alternatively, you can use one of the Amazon Web Services SDKs to access an API that''s tailored to the programming language or platform that you''re using. For more information, see Amazon Web Services SDKs.
For descriptions of Network Firewall features, including and step-by-step instructions on how to use them through the Network Firewall console, see the Network Firewall Developer Guide.
Network Firewall is a stateful, managed, network firewall and intrusion detection and prevention service for Amazon Virtual Private Cloud (Amazon VPC). With Network Firewall, you can filter traffic at the perimeter of your VPC. This includes filtering traffic going to and coming from an internet gateway, NAT gateway, or over VPN or Direct Connect. Network Firewall uses rules that are compatible with Suricata, a free, open source network analysis and threat detection engine. Network Firewall supports Suricata version 6.0.9. For information about Suricata, see the Suricata website.
You can use Network Firewall to monitor and protect your VPC traffic in a number of ways. The following are just a few examples:
Allow domains or IP addresses for known Amazon Web Services service endpoints, such as Amazon S3, and block all other forms of traffic.
Use custom lists of known bad domains to limit the types of domain names that your applications can access.
Perform deep packet inspection on traffic entering or leaving your VPC.
Use stateful protocol detection to filter protocols like HTTPS, regardless of the port used.
To enable Network Firewall for your VPCs, you perform steps in both Amazon VPC and in Network Firewall. For information about using Amazon VPC, see Amazon VPC User Guide.
To start using Network Firewall, do the following:
(Optional) If you don''t already have a VPC that you want to protect, create it in Amazon VPC.
In Amazon VPC, in each Availability Zone where you want to have a firewall endpoint, create a subnet for the sole use of Network Firewall.
In Network Firewall, create stateless and stateful rule groups, to define the components of the network traffic filtering behavior that you want your firewall to have.
In Network Firewall, create a firewall policy that uses your rule groups and specifies additional default traffic filtering behavior.
In Network Firewall, create a firewall and specify your new firewall policy and VPC subnets. Network Firewall creates a firewall endpoint in each subnet that you specify, with the behavior that''s defined in the firewall policy.
In Amazon VPC, use ingress routing enhancements to route traffic through the new firewall endpoints.
TLSInspectionConfiguration, define the TLS inspection configuration. You can retrieve all objects for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration.
TagKey:
type: string
pattern: ^.*$
minLength: 1
maxLength: 128
ThrottlingException: {}
ProtocolNumbers:
type: array
items:
$ref: '#/components/schemas/ProtocolNumber'
ProtocolNumber:
type: integer
minimum: 0
maximum: 255
ResourceStatus:
type: string
enum:
- ACTIVE
- DELETING
PortRanges:
type: array
items:
$ref: '#/components/schemas/PortRange'
Certificates:
type: array
items:
$ref: '#/components/schemas/TlsCertificateData'
PortRange:
type: object
required:
- FromPort
- ToPort
properties:
FromPort:
allOf:
- $ref: '#/components/schemas/PortRangeBound'
- description: 'The lower limit of the port range. This must be less than or equal to the ToPort specification. '
ToPort:
allOf:
- $ref: '#/components/schemas/PortRangeBound'
- description: 'The upper limit of the port range. This must be greater than or equal to the FromPort specification. '
description: 'A single port range specification. This is used for source and destination port ranges in the stateless rule MatchAttributes, SourcePorts, and DestinationPorts settings. '
Description:
type: string
pattern: ^.*$
maxLength: 512
StatusReason:
type: string
pattern: ^[a-zA-Z0-9- ]+$
minLength: 1
maxLength: 256
InvalidRequestException: {}
ResourceId:
type: string
pattern: ^([0-9a-f]{8})-([0-9a-f]{4}-){3}([0-9a-f]{12})$
minLength: 36
maxLength: 36
CollectionMember_String:
type: string
LastUpdateTime:
type: string
format: date-time
InternalServerError: {}
EncryptionConfiguration:
type: object
required:
- Type
properties:
KeyId:
allOf:
- $ref: '#/components/schemas/KeyId'
- description: The ID of the Amazon Web Services Key Management Service (KMS) customer managed key. You can use any of the key identifiers that KMS supports, unless you're using a key that's managed by another account. If you're using a key managed by another account, then specify the key ARN. For more information, see Key ID in the Amazon Web Services KMS Developer Guide.
Type:
allOf:
- $ref: '#/components/schemas/EncryptionType'
- description: The type of Amazon Web Services KMS key to use for encryption of your Network Firewall resources.
description: A complex type that contains optional Amazon Web Services Key Management Service (KMS) encryption settings for your Network Firewall resources. Your data is encrypted by default with an Amazon Web Services owned key that Amazon Web Services owns and manages for you. You can use either the Amazon Web Services owned key, or provide your own customer managed key. To learn more about KMS encryption of your Network Firewall resources, see Encryption at rest with Amazon Web Services Key Managment Service in the Network Firewall Developer Guide.
PortRangeBound:
type: integer
minimum: 0
maximum: 65535
DescribeTLSInspectionConfigurationResponse:
type: object
required:
- UpdateToken
- TLSInspectionConfigurationResponse
properties:
UpdateToken:
allOf:
- $ref: '#/components/schemas/UpdateToken'
- description: A token used for optimistic locking. Network Firewall returns a token to your requests that access the TLS inspection configuration. The token marks the state of the TLS inspection configuration resource at the time of the request.
To make changes to the TLS inspection configuration, you provide the token in your request. Network Firewall uses the token to ensure that the TLS inspection configuration hasn't changed since you last retrieved it. If it has changed, the operation fails with an InvalidTokenException. If this happens, retrieve the TLS inspection configuration again to get a current copy of it with a current token. Reapply your changes as needed, then try the operation again using the new token.
The object that defines a TLS inspection configuration. This, along with TLSInspectionConfigurationResponse, define the TLS inspection configuration. You can retrieve all objects for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration.
Network Firewall uses a TLS inspection configuration to decrypt traffic. Network Firewall re-encrypts the traffic before sending it to its destination.
To use a TLS inspection configuration, you add it to a Network Firewall firewall policy, then you apply the firewall policy to a firewall. Network Firewall acts as a proxy service to decrypt and inspect inbound traffic. You can reference a TLS inspection configuration from more than one firewall policy, and you can use a firewall policy in more than one firewall. For more information about using TLS inspection configurations, see Decrypting SSL/TLS traffic with TLS inspection configurations in the Network Firewall Developer Guide.
TLSInspectionConfigurationResponse: allOf: - $ref: '#/components/schemas/TLSInspectionConfigurationResponse' - description: 'The high-level properties of a TLS inspection configuration. This, along with the TLSInspectionConfiguration, define the TLS inspection configuration. You can retrieve all objects for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration. ' Addresses: type: array items: $ref: '#/components/schemas/Address' KeyId: type: string pattern: .*\S.* minLength: 1 maxLength: 2048 EncryptionType: type: string enum: - CUSTOMER_KMS - AWS_OWNED_KMS_KEY ServerCertificateScope: type: object properties: Sources: allOf: - $ref: '#/components/schemas/Addresses' - description: The source IP addresses and address ranges to decrypt for inspection, in CIDR notation. If not specified, this matches with any source address. Destinations: allOf: - $ref: '#/components/schemas/Addresses' - description: The destination IP addresses and address ranges to decrypt for inspection, in CIDR notation. If not specified, this matches with any destination address. SourcePorts: allOf: - $ref: '#/components/schemas/PortRanges' - description:The source ports to decrypt for inspection, in Transmission Control Protocol (TCP) format. If not specified, this matches with any source port.
You can specify individual ports, for example 1994, and you can specify port ranges, such as 1990:1994.
The destination ports to decrypt for inspection, in Transmission Control Protocol (TCP) format. If not specified, this matches with any destination port.
You can specify individual ports, for example 1994, and you can specify port ranges, such as 1990:1994.
Configures the associated Certificate Manager Secure Sockets Layer/Transport Layer Security (SSL/TLS) server certificates and scope settings Network Firewall uses to decrypt traffic in a TLSInspectionConfiguration. For information about working with SSL/TLS certificates for TLS inspection, see Requirements for using SSL/TLS server certficiates with TLS inspection configurations in the Network Firewall Developer Guide.
If a server certificate that's associated with your TLSInspectionConfiguration is revoked, deleted, or expired it can result in client-side TLS errors.
The object that defines a TLS inspection configuration. This, along with TLSInspectionConfigurationResponse, define the TLS inspection configuration. You can retrieve all objects for a TLS inspection configuration by calling DescribeTLSInspectionConfiguration.
Network Firewall uses a TLS inspection configuration to decrypt traffic. Network Firewall re-encrypts the traffic before sending it to its destination.
To use a TLS inspection configuration, you add it to a Network Firewall firewall policy, then you apply the firewall policy to a firewall. Network Firewall acts as a proxy service to decrypt and inspect inbound traffic. You can reference a TLS inspection configuration from more than one firewall policy, and you can use a firewall policy in more than one firewall. For more information about using TLS inspection configurations, see Decrypting SSL/TLS traffic with TLS inspection configurations in the Network Firewall Developer Guide.
TagValue: type: string pattern: ^.*$ minLength: 0 maxLength: 256 AddressDefinition: type: string pattern: ^([a-fA-F\d:\.]+($|/\d{1,3}))$ minLength: 1 maxLength: 255 ServerCertificates: type: array items: $ref: '#/components/schemas/ServerCertificate' ServerCertificate: type: object properties: ResourceArn: allOf: - $ref: '#/components/schemas/ResourceArn' - description: The Amazon Resource Name (ARN) of the Certificate Manager SSL/TLS server certificate. description: Any Certificate Manager Secure Sockets Layer/Transport Layer Security (SSL/TLS) server certificate that's associated with a ServerCertificateConfiguration used in a TLSInspectionConfiguration. You must request or import a SSL/TLS certificate into ACM for each domain Network Firewall needs to decrypt and inspect. Network Firewall uses the SSL/TLS certificates to decrypt specified inbound SSL/TLS traffic going to your firewall. For information about working with certificates in Certificate Manager, see Request a public certificate or Importing certificates in the Certificate Manager User Guide. TagList: type: array items: $ref: '#/components/schemas/Tag' minItems: 1 maxItems: 200 Address: type: object required: - AddressDefinition properties: AddressDefinition: allOf: - $ref: '#/components/schemas/AddressDefinition' - description: 'Specify an IP address or a block of IP addresses in Classless Inter-Domain Routing (CIDR) notation. Network Firewall supports all address ranges for IPv4 and IPv6.
Examples:
To configure Network Firewall to inspect for the IP address 192.0.2.44, specify 192.0.2.44/32.
To configure Network Firewall to inspect for IP addresses from 192.0.2.0 to 192.0.2.255, specify 192.0.2.0/24.
To configure Network Firewall to inspect for the IP address 1111:0000:0000:0000:0000:0000:0000:0111, specify 1111:0000:0000:0000:0000:0000:0000:0111/128.
To configure Network Firewall to inspect for IP addresses from 1111:0000:0000:0000:0000:0000:0000:0000 to 1111:0000:0000:0000:ffff:ffff:ffff:ffff, specify 1111:0000:0000:0000:0000:0000:0000:0000/64.
For more information about CIDR notation, see the Wikipedia entry Classless Inter-Domain Routing.
' description: A single IP address specification. This is used in the MatchAttributes source and destination specifications. DescribeTLSInspectionConfigurationRequest: type: object title: DescribeTLSInspectionConfigurationRequest properties: TLSInspectionConfigurationArn: allOf: - $ref: '#/components/schemas/ResourceArn' - description:The Amazon Resource Name (ARN) of the TLS inspection configuration.
You must specify the ARN or the name, and you can specify both.
TLSInspectionConfigurationName: allOf: - $ref: '#/components/schemas/ResourceName' - description:The descriptive name of the TLS inspection configuration. You can't change the name of a TLS inspection configuration after you create it.
You must specify the ARN or the name, and you can specify both.
TlsCertificateData: type: object properties: CertificateArn: allOf: - $ref: '#/components/schemas/ResourceArn' - description: The Amazon Resource Name (ARN) of the certificate. CertificateSerial: allOf: - $ref: '#/components/schemas/CollectionMember_String' - description: The serial number of the certificate. Status: allOf: - $ref: '#/components/schemas/CollectionMember_String' - description: The status of the certificate. StatusMessage: allOf: - $ref: '#/components/schemas/StatusReason' - description: Contains details about the certificate status, including information about certificate errors. description: Contains metadata about an Certificate Manager certificate. parameters: X-Amz-Credential: name: X-Amz-Credential in: header schema: type: string required: false X-Amz-Date: name: X-Amz-Date in: header schema: type: string required: false X-Amz-Signature: name: X-Amz-Signature in: header schema: type: string required: false X-Amz-Algorithm: name: X-Amz-Algorithm in: header schema: type: string required: false X-Amz-Security-Token: name: X-Amz-Security-Token in: header schema: type: string required: false X-Amz-SignedHeaders: name: X-Amz-SignedHeaders in: header schema: type: string required: false X-Amz-Content-Sha256: name: X-Amz-Content-Sha256 in: header schema: type: string required: false securitySchemes: hmac: type: apiKey name: Authorization in: header description: Amazon Signature authorization v4 x-amazon-apigateway-authtype: awsSigv4 externalDocs: description: Amazon Web Services documentation url: https://docs.aws.amazon.com/network-firewall/ x-hasEquivalentPaths: true