feat(client-network-firewall): Network Firewall now supports inspecti…

…on of outbound SSL/TLS traffic.
aws · Oct 26, 2023 · 3686e69 · 3686e69
1 parent fd8ca90
commit 3686e69
Show file tree

Hide file tree

Showing 39 changed files with 274 additions and 74 deletions.
diff --git a/clients/client-network-firewall/src/commands/AssociateFirewallPolicyCommand.ts b/clients/client-network-firewall/src/commands/AssociateFirewallPolicyCommand.ts
@@ -72,7 +72,7 @@ export interface AssociateFirewallPolicyCommandOutput extends AssociateFirewallP
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidOperationException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/AssociateSubnetsCommand.ts b/clients/client-network-firewall/src/commands/AssociateSubnetsCommand.ts
@@ -87,7 +87,7 @@ export interface AssociateSubnetsCommandOutput extends AssociateSubnetsResponse,
  *          request later. </p>
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidOperationException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/CreateFirewallCommand.ts b/clients/client-network-firewall/src/commands/CreateFirewallCommand.ts
@@ -151,7 +151,7 @@ export interface CreateFirewallCommandOutput extends CreateFirewallResponse, __M
  *          request later. </p>
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidOperationException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/CreateFirewallPolicyCommand.ts b/clients/client-network-firewall/src/commands/CreateFirewallPolicyCommand.ts
@@ -125,7 +125,7 @@ export interface CreateFirewallPolicyCommandOutput extends CreateFirewallPolicyR
  * //     FirewallPolicyArn: "STRING_VALUE", // required
  * //     FirewallPolicyId: "STRING_VALUE", // required
  * //     Description: "STRING_VALUE",
- * //     FirewallPolicyStatus: "ACTIVE" || "DELETING",
+ * //     FirewallPolicyStatus: "ACTIVE" || "DELETING" || "ERROR",
  * //     Tags: [ // TagList
  * //       { // Tag
  * //         Key: "STRING_VALUE", // required
@@ -156,7 +156,7 @@ export interface CreateFirewallPolicyCommandOutput extends CreateFirewallPolicyR
  *          request later. </p>
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/CreateRuleGroupCommand.ts b/clients/client-network-firewall/src/commands/CreateRuleGroupCommand.ts
@@ -204,7 +204,7 @@ export interface CreateRuleGroupCommandOutput extends CreateRuleGroupResponse, _
  * //     Description: "STRING_VALUE",
  * //     Type: "STATELESS" || "STATEFUL",
  * //     Capacity: Number("int"),
- * //     RuleGroupStatus: "ACTIVE" || "DELETING",
+ * //     RuleGroupStatus: "ACTIVE" || "DELETING" || "ERROR",
  * //     Tags: [ // TagList
  * //       { // Tag
  * //         Key: "STRING_VALUE", // required
@@ -239,7 +239,7 @@ export interface CreateRuleGroupCommandOutput extends CreateRuleGroupResponse, _
  *          request later. </p>
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/CreateTLSInspectionConfigurationCommand.ts b/clients/client-network-firewall/src/commands/CreateTLSInspectionConfigurationCommand.ts
@@ -42,13 +42,13 @@ export interface CreateTLSInspectionConfigurationCommandOutput
 
 /**
  * @public
- * <p>Creates an Network Firewall TLS inspection configuration. A TLS inspection configuration contains the Certificate Manager certificate references that Network Firewall uses to decrypt and re-encrypt inbound traffic.</p>
- *          <p>After you create a TLS inspection configuration, you associate it with a new firewall policy.</p>
+ * <p>Creates an Network Firewall TLS inspection configuration. A TLS inspection configuration contains the Certificate Manager certificate associations that Network Firewall uses to decrypt and re-encrypt traffic traveling through your firewall.</p>
+ *          <p>After you create a TLS inspection configuration, you can associate it with a new firewall policy.</p>
  *          <p>To update the settings for a TLS inspection configuration, use <a>UpdateTLSInspectionConfiguration</a>.</p>
  *          <p>To manage a TLS inspection configuration's tags, use the standard Amazon Web Services resource tagging operations, <a>ListTagsForResource</a>, <a>TagResource</a>, and <a>UntagResource</a>.</p>
  *          <p>To retrieve information about TLS inspection configurations, use <a>ListTLSInspectionConfigurations</a> and <a>DescribeTLSInspectionConfiguration</a>.</p>
  *          <p>
- *               For more information about TLS inspection configurations, see <a href="https://docs.aws.amazon.com/network-firewall/latest/developerguide/tls-inspection.html">Decrypting SSL/TLS traffic with TLS
+ *               For more information about TLS inspection configurations, see <a href="https://docs.aws.amazon.com/network-firewall/latest/developerguide/tls-inspection.html">Inspecting SSL/TLS traffic with TLS
  * inspection configurations</a> in the <i>Network Firewall Developer Guide</i>.
  *             </p>
  * @example
@@ -96,6 +96,11 @@ export interface CreateTLSInspectionConfigurationCommandOutput
  *             ],
  *           },
  *         ],
+ *         CertificateAuthorityArn: "STRING_VALUE",
+ *         CheckCertificateRevocationStatus: { // CheckCertificateRevocationStatusActions
+ *           RevokedStatusAction: "PASS" || "DROP" || "REJECT",
+ *           UnknownStatusAction: "PASS" || "DROP" || "REJECT",
+ *         },
  *       },
  *     ],
  *   },
@@ -119,7 +124,7 @@ export interface CreateTLSInspectionConfigurationCommandOutput
  * //     TLSInspectionConfigurationArn: "STRING_VALUE", // required
  * //     TLSInspectionConfigurationName: "STRING_VALUE", // required
  * //     TLSInspectionConfigurationId: "STRING_VALUE", // required
- * //     TLSInspectionConfigurationStatus: "ACTIVE" || "DELETING",
+ * //     TLSInspectionConfigurationStatus: "ACTIVE" || "DELETING" || "ERROR",
  * //     Description: "STRING_VALUE",
  * //     Tags: [ // TagList
  * //       { // Tag
@@ -141,6 +146,12 @@ export interface CreateTLSInspectionConfigurationCommandOutput
  * //         StatusMessage: "STRING_VALUE",
  * //       },
  * //     ],
+ * //     CertificateAuthority: {
+ * //       CertificateArn: "STRING_VALUE",
+ * //       CertificateSerial: "STRING_VALUE",
+ * //       Status: "STRING_VALUE",
+ * //       StatusMessage: "STRING_VALUE",
+ * //     },
  * //   },
  * // };
  *
@@ -157,7 +168,7 @@ export interface CreateTLSInspectionConfigurationCommandOutput
  *          request later. </p>
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DeleteFirewallCommand.ts b/clients/client-network-firewall/src/commands/DeleteFirewallCommand.ts
@@ -130,7 +130,7 @@ export interface DeleteFirewallCommandOutput extends DeleteFirewallResponse, __M
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidOperationException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DeleteFirewallPolicyCommand.ts b/clients/client-network-firewall/src/commands/DeleteFirewallPolicyCommand.ts
@@ -56,7 +56,7 @@ export interface DeleteFirewallPolicyCommandOutput extends DeleteFirewallPolicyR
  * //     FirewallPolicyArn: "STRING_VALUE", // required
  * //     FirewallPolicyId: "STRING_VALUE", // required
  * //     Description: "STRING_VALUE",
- * //     FirewallPolicyStatus: "ACTIVE" || "DELETING",
+ * //     FirewallPolicyStatus: "ACTIVE" || "DELETING" || "ERROR",
  * //     Tags: [ // TagList
  * //       { // Tag
  * //         Key: "STRING_VALUE", // required
@@ -83,7 +83,7 @@ export interface DeleteFirewallPolicyCommandOutput extends DeleteFirewallPolicyR
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidOperationException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DeleteResourcePolicyCommand.ts b/clients/client-network-firewall/src/commands/DeleteResourcePolicyCommand.ts
@@ -60,7 +60,7 @@ export interface DeleteResourcePolicyCommandOutput extends DeleteResourcePolicyR
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DeleteRuleGroupCommand.ts b/clients/client-network-firewall/src/commands/DeleteRuleGroupCommand.ts
@@ -59,7 +59,7 @@ export interface DeleteRuleGroupCommandOutput extends DeleteRuleGroupResponse, _
  * //     Description: "STRING_VALUE",
  * //     Type: "STATELESS" || "STATEFUL",
  * //     Capacity: Number("int"),
- * //     RuleGroupStatus: "ACTIVE" || "DELETING",
+ * //     RuleGroupStatus: "ACTIVE" || "DELETING" || "ERROR",
  * //     Tags: [ // TagList
  * //       { // Tag
  * //         Key: "STRING_VALUE", // required
@@ -90,7 +90,7 @@ export interface DeleteRuleGroupCommandOutput extends DeleteRuleGroupResponse, _
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidOperationException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DeleteTLSInspectionConfigurationCommand.ts b/clients/client-network-firewall/src/commands/DeleteTLSInspectionConfigurationCommand.ts
@@ -60,7 +60,7 @@ export interface DeleteTLSInspectionConfigurationCommandOutput
  * //     TLSInspectionConfigurationArn: "STRING_VALUE", // required
  * //     TLSInspectionConfigurationName: "STRING_VALUE", // required
  * //     TLSInspectionConfigurationId: "STRING_VALUE", // required
- * //     TLSInspectionConfigurationStatus: "ACTIVE" || "DELETING",
+ * //     TLSInspectionConfigurationStatus: "ACTIVE" || "DELETING" || "ERROR",
  * //     Description: "STRING_VALUE",
  * //     Tags: [ // TagList
  * //       { // Tag
@@ -82,6 +82,12 @@ export interface DeleteTLSInspectionConfigurationCommandOutput
  * //         StatusMessage: "STRING_VALUE",
  * //       },
  * //     ],
+ * //     CertificateAuthority: {
+ * //       CertificateArn: "STRING_VALUE",
+ * //       CertificateSerial: "STRING_VALUE",
+ * //       Status: "STRING_VALUE",
+ * //       StatusMessage: "STRING_VALUE",
+ * //     },
  * //   },
  * // };
  *
@@ -94,7 +100,7 @@ export interface DeleteTLSInspectionConfigurationCommandOutput
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidOperationException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DescribeFirewallCommand.ts b/clients/client-network-firewall/src/commands/DescribeFirewallCommand.ts
@@ -121,7 +121,7 @@ export interface DescribeFirewallCommandOutput extends DescribeFirewallResponse,
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DescribeFirewallPolicyCommand.ts b/clients/client-network-firewall/src/commands/DescribeFirewallPolicyCommand.ts
@@ -57,7 +57,7 @@ export interface DescribeFirewallPolicyCommandOutput extends DescribeFirewallPol
  * //     FirewallPolicyArn: "STRING_VALUE", // required
  * //     FirewallPolicyId: "STRING_VALUE", // required
  * //     Description: "STRING_VALUE",
- * //     FirewallPolicyStatus: "ACTIVE" || "DELETING",
+ * //     FirewallPolicyStatus: "ACTIVE" || "DELETING" || "ERROR",
  * //     Tags: [ // TagList
  * //       { // Tag
  * //         Key: "STRING_VALUE", // required
@@ -138,7 +138,7 @@ export interface DescribeFirewallPolicyCommandOutput extends DescribeFirewallPol
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DescribeLoggingConfigurationCommand.ts b/clients/client-network-firewall/src/commands/DescribeLoggingConfigurationCommand.ts
@@ -79,7 +79,7 @@ export interface DescribeLoggingConfigurationCommandOutput
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DescribeResourcePolicyCommand.ts b/clients/client-network-firewall/src/commands/DescribeResourcePolicyCommand.ts
@@ -62,7 +62,7 @@ export interface DescribeResourcePolicyCommandOutput extends DescribeResourcePol
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DescribeRuleGroupCommand.ts b/clients/client-network-firewall/src/commands/DescribeRuleGroupCommand.ts
@@ -184,7 +184,7 @@ export interface DescribeRuleGroupCommandOutput extends DescribeRuleGroupRespons
  * //     Description: "STRING_VALUE",
  * //     Type: "STATELESS" || "STATEFUL",
  * //     Capacity: Number("int"),
- * //     RuleGroupStatus: "ACTIVE" || "DELETING",
+ * //     RuleGroupStatus: "ACTIVE" || "DELETING" || "ERROR",
  * //     Tags: [ // TagList
  * //       { // Tag
  * //         Key: "STRING_VALUE", // required
@@ -215,7 +215,7 @@ export interface DescribeRuleGroupCommandOutput extends DescribeRuleGroupRespons
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DescribeRuleGroupMetadataCommand.ts b/clients/client-network-firewall/src/commands/DescribeRuleGroupMetadataCommand.ts
@@ -75,7 +75,7 @@ export interface DescribeRuleGroupMetadataCommandOutput extends DescribeRuleGrou
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DescribeTLSInspectionConfigurationCommand.ts b/clients/client-network-firewall/src/commands/DescribeTLSInspectionConfigurationCommand.ts
@@ -97,14 +97,19 @@ export interface DescribeTLSInspectionConfigurationCommandOutput
  * //             ],
  * //           },
  * //         ],
+ * //         CertificateAuthorityArn: "STRING_VALUE",
+ * //         CheckCertificateRevocationStatus: { // CheckCertificateRevocationStatusActions
+ * //           RevokedStatusAction: "PASS" || "DROP" || "REJECT",
+ * //           UnknownStatusAction: "PASS" || "DROP" || "REJECT",
+ * //         },
  * //       },
  * //     ],
  * //   },
  * //   TLSInspectionConfigurationResponse: { // TLSInspectionConfigurationResponse
  * //     TLSInspectionConfigurationArn: "STRING_VALUE", // required
  * //     TLSInspectionConfigurationName: "STRING_VALUE", // required
  * //     TLSInspectionConfigurationId: "STRING_VALUE", // required
- * //     TLSInspectionConfigurationStatus: "ACTIVE" || "DELETING",
+ * //     TLSInspectionConfigurationStatus: "ACTIVE" || "DELETING" || "ERROR",
  * //     Description: "STRING_VALUE",
  * //     Tags: [ // TagList
  * //       { // Tag
@@ -126,6 +131,12 @@ export interface DescribeTLSInspectionConfigurationCommandOutput
  * //         StatusMessage: "STRING_VALUE",
  * //       },
  * //     ],
+ * //     CertificateAuthority: {
+ * //       CertificateArn: "STRING_VALUE",
+ * //       CertificateSerial: "STRING_VALUE",
+ * //       Status: "STRING_VALUE",
+ * //       StatusMessage: "STRING_VALUE",
+ * //     },
  * //   },
  * // };
  *
@@ -138,7 +149,7 @@ export interface DescribeTLSInspectionConfigurationCommandOutput
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/DisassociateSubnetsCommand.ts b/clients/client-network-firewall/src/commands/DisassociateSubnetsCommand.ts
@@ -78,7 +78,7 @@ export interface DisassociateSubnetsCommandOutput extends DisassociateSubnetsRes
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidOperationException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/ListFirewallPoliciesCommand.ts b/clients/client-network-firewall/src/commands/ListFirewallPoliciesCommand.ts
@@ -71,7 +71,7 @@ export interface ListFirewallPoliciesCommandOutput extends ListFirewallPoliciesR
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)

diff --git a/clients/client-network-firewall/src/commands/ListFirewallsCommand.ts b/clients/client-network-firewall/src/commands/ListFirewallsCommand.ts
@@ -75,7 +75,7 @@ export interface ListFirewallsCommandOutput extends ListFirewallsResponse, __Met
  * @see {@link NetworkFirewallClientResolvedConfig | config} for NetworkFirewallClient's `config` shape.
  *
  * @throws {@link InternalServerError} (server fault)
- *  <p>Your request is valid, but Network Firewall couldn’t perform the operation because of a
+ *  <p>Your request is valid, but Network Firewall couldn't perform the operation because of a
  *          system problem. Retry your request. </p>
  *
  * @throws {@link InvalidRequestException} (client fault)