/******************************************************************************* * Copyright 2012-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. * Licensed under the Apache License, Version 2.0 (the "License"). You may not use * this file except in compliance with the License. A copy of the License is located at * * http://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. * This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR * CONDITIONS OF ANY KIND, either express or implied. See the License for the * specific language governing permissions and limitations under the License. * ***************************************************************************** * * AWS Tools for Windows (TM) PowerShell (TM) * */ using System; using System.Collections.Generic; using System.Linq; using System.Management.Automation; using System.Text; using Amazon.PowerShell.Common; using Amazon.Runtime; using Amazon.KeyManagementService; using Amazon.KeyManagementService.Model; namespace Amazon.PowerShell.Cmdlets.KMS { /// /// Creates a custom /// key store backed by a key store that you own and manage. When you use a KMS key /// in a custom key store for a cryptographic operation, the cryptographic operation is /// actually performed in your key store using your keys. KMS supports CloudHSM /// key stores backed by an CloudHSM /// cluster and external /// key stores backed by an external key store proxy and external key manager outside /// of Amazon Web Services. /// /// /// /// This operation is part of the custom /// key stores feature in KMS, which combines the convenience and extensive integration /// of KMS with the isolation and control of a key store that you own and manage. /// /// Before you create the custom key store, the required elements must be in place and /// operational. We recommend that you use the test tools that KMS provides to verify /// the configuration your external key store proxy. For details about the required elements /// and verification tests, see Assemble /// the prerequisites (for CloudHSM key stores) or Assemble /// the prerequisites (for external key stores) in the Key Management Service Developer /// Guide. /// /// To create a custom key store, use the following parameters. /// /// For external key stores: /// /// Some external key managers provide a simpler method for creating an external key store. /// For details, see your external key manager documentation. /// /// When creating an external key store in the KMS console, you can upload a JSON-based /// proxy configuration file with the desired values. You cannot use a proxy configuration /// with the CreateCustomKeyStore operation. However, you can use the values /// in the file to help you determine the correct values for the CreateCustomKeyStore /// parameters. /// /// When the operation completes successfully, it returns the ID of the new custom key /// store. Before you can use your new custom key store, you need to use the ConnectCustomKeyStore /// operation to connect a new CloudHSM key store to its CloudHSM cluster, or to connect /// a new external key store to the external key store proxy for your external key manager. /// Even if you are not going to use your custom key store immediately, you might want /// to connect it to verify that all settings are correct and then disconnect it until /// you are ready to use it. /// /// For help with failures, see Troubleshooting /// a custom key store in the Key Management Service Developer Guide. /// Cross-account use: No. You cannot perform this operation on a custom key store /// in a different Amazon Web Services account. /// Required permissions: kms:CreateCustomKeyStore /// (IAM policy). /// Related operations: /// [Cmdlet("New", "KMSCustomKeyStore", SupportsShouldProcess = true, ConfirmImpact = ConfirmImpact.Medium)] [OutputType("System.String")] [AWSCmdlet("Calls the AWS Key Management Service CreateCustomKeyStore API operation.", Operation = new[] {"CreateCustomKeyStore"}, SelectReturnType = typeof(Amazon.KeyManagementService.Model.CreateCustomKeyStoreResponse))] [AWSCmdletOutput("System.String or Amazon.KeyManagementService.Model.CreateCustomKeyStoreResponse", "This cmdlet returns a System.String object.", "The service call response (type Amazon.KeyManagementService.Model.CreateCustomKeyStoreResponse) can also be referenced from properties attached to the cmdlet entry in the $AWSHistory stack." )] public partial class NewKMSCustomKeyStoreCmdlet : AmazonKeyManagementServiceClientCmdlet, IExecutor { protected override bool IsSensitiveRequest { get; set; } = true; #region Parameter XksProxyAuthenticationCredential_AccessKeyId /// /// /// A unique identifier for the raw secret access key. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String XksProxyAuthenticationCredential_AccessKeyId { get; set; } #endregion #region Parameter CloudHsmClusterId /// /// /// Identifies the CloudHSM cluster for an CloudHSM key store. This parameter is required /// for custom key stores with CustomKeyStoreType of AWS_CLOUDHSM.Enter the cluster ID of any active CloudHSM cluster that is not already associated /// with a custom key store. To find the cluster ID, use the DescribeClusters /// operation. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String CloudHsmClusterId { get; set; } #endregion #region Parameter CustomKeyStoreName /// /// /// Specifies a friendly name for the custom key store. The name must be unique in your /// Amazon Web Services account and Region. This parameter is required for all custom /// key stores.Do not include confidential or sensitive information in this field. This field may /// be displayed in plaintext in CloudTrail logs and other output. /// /// #if !MODULAR [System.Management.Automation.Parameter(Position = 0, ValueFromPipelineByPropertyName = true, ValueFromPipeline = true)] #else [System.Management.Automation.Parameter(Position = 0, ValueFromPipelineByPropertyName = true, ValueFromPipeline = true, Mandatory = true)] [System.Management.Automation.AllowEmptyString] [System.Management.Automation.AllowNull] #endif [Amazon.PowerShell.Common.AWSRequiredParameter] public System.String CustomKeyStoreName { get; set; } #endregion #region Parameter CustomKeyStoreType /// /// /// Specifies the type of custom key store. The default value is AWS_CLOUDHSM.For a custom key store backed by an CloudHSM cluster, omit the parameter or enter /// AWS_CLOUDHSM. For a custom key store backed by an external key manager /// outside of Amazon Web Services, enter EXTERNAL_KEY_STORE. You cannot /// change this property after the key store is created. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] [AWSConstantClassSource("Amazon.KeyManagementService.CustomKeyStoreType")] public Amazon.KeyManagementService.CustomKeyStoreType CustomKeyStoreType { get; set; } #endregion #region Parameter KeyStorePassword /// /// /// Specifies the kmsuser password for an CloudHSM key store. This parameter /// is required for custom key stores with a CustomKeyStoreType of AWS_CLOUDHSM.Enter the password of the kmsuser crypto user (CU) account in the specified CloudHSM cluster. /// KMS logs into the cluster as this user to manage key material on your behalf.The password must be a string of 7 to 32 characters. Its value is case sensitive.This parameter tells KMS the kmsuser account password; it does not change /// the password in the CloudHSM cluster. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String KeyStorePassword { get; set; } #endregion #region Parameter XksProxyAuthenticationCredential_RawSecretAccessKey /// /// /// A secret string of 43-64 characters. Valid characters are a-z, A-Z, 0-9, /, +, and /// =. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String XksProxyAuthenticationCredential_RawSecretAccessKey { get; set; } #endregion #region Parameter TrustAnchorCertificate /// /// /// Specifies the certificate for an CloudHSM key store. This parameter is required for /// custom key stores with a CustomKeyStoreType of AWS_CLOUDHSM.Enter the content of the trust anchor certificate for the CloudHSM cluster. This is /// the content of the customerCA.crt file that you created when you initialized /// the cluster. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String TrustAnchorCertificate { get; set; } #endregion #region Parameter XksProxyConnectivity /// /// /// Indicates how KMS communicates with the external key store proxy. This parameter is /// required for custom key stores with a CustomKeyStoreType of EXTERNAL_KEY_STORE.If the external key store proxy uses a public endpoint, specify PUBLIC_ENDPOINT. /// If the external key store proxy uses a Amazon VPC endpoint service for communication /// with KMS, specify VPC_ENDPOINT_SERVICE. For help making this choice, /// see Choosing /// a connectivity option in the Key Management Service Developer Guide.An Amazon VPC endpoint service keeps your communication with KMS in a private address /// space entirely within Amazon Web Services, but it requires more configuration, including /// establishing a Amazon VPC with multiple subnets, a VPC endpoint service, a network /// load balancer, and a verified private DNS name. A public endpoint is simpler to set /// up, but it might be slower and might not fulfill your security requirements. You might /// consider testing with a public endpoint, and then establishing a VPC endpoint service /// for production tasks. Note that this choice does not determine the location of the /// external key store proxy. Even if you choose a VPC endpoint service, the proxy can /// be hosted within the VPC or outside of Amazon Web Services such as in your corporate /// data center. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] [AWSConstantClassSource("Amazon.KeyManagementService.XksProxyConnectivityType")] public Amazon.KeyManagementService.XksProxyConnectivityType XksProxyConnectivity { get; set; } #endregion #region Parameter XksProxyUriEndpoint /// /// /// Specifies the endpoint that KMS uses to send requests to the external key store proxy /// (XKS proxy). This parameter is required for custom key stores with a CustomKeyStoreType /// of EXTERNAL_KEY_STORE.The protocol must be HTTPS. KMS communicates on port 443. Do not specify the port /// in the XksProxyUriEndpoint value.For external key stores with XksProxyConnectivity value of VPC_ENDPOINT_SERVICE, /// specify https:// followed by the private DNS name of the VPC endpoint /// service.For external key stores with PUBLIC_ENDPOINT connectivity, this endpoint /// must be reachable before you create the custom key store. KMS connects to the external /// key store proxy while creating the custom key store. For external key stores with /// VPC_ENDPOINT_SERVICE connectivity, KMS connects when you call the ConnectCustomKeyStore /// operation.The value of this parameter must begin with https://. The remainder can /// contain upper and lower case letters (A-Z and a-z), numbers (0-9), dots (.), /// and hyphens (-). Additional slashes (/ and \) /// are not permitted.Uniqueness requirements: /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String XksProxyUriEndpoint { get; set; } #endregion #region Parameter XksProxyUriPath /// /// /// Specifies the base path to the proxy APIs for this external key store. To find this /// value, see the documentation for your external key store proxy. This parameter is /// required for all custom key stores with a CustomKeyStoreType of EXTERNAL_KEY_STORE.The value must start with / and must end with /kms/xks/v1 /// where v1 represents the version of the KMS external key store proxy API. /// This path can include an optional prefix between the required elements such as /prefix/kms/xks/v1.Uniqueness requirements: /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String XksProxyUriPath { get; set; } #endregion #region Parameter XksProxyVpcEndpointServiceName /// /// /// Specifies the name of the Amazon VPC endpoint service for interface endpoints that /// is used to communicate with your external key store proxy (XKS proxy). This parameter /// is required when the value of CustomKeyStoreType is EXTERNAL_KEY_STORE /// and the value of XksProxyConnectivity is VPC_ENDPOINT_SERVICE.The Amazon VPC endpoint service must fulfill /// all requirements for use with an external key store. Uniqueness requirements: /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String XksProxyVpcEndpointServiceName { get; set; } #endregion #region Parameter Select /// /// Use the -Select parameter to control the cmdlet output. The default value is 'CustomKeyStoreId'. /// Specifying -Select '*' will result in the cmdlet returning the whole service response (Amazon.KeyManagementService.Model.CreateCustomKeyStoreResponse). /// Specifying the name of a property of type Amazon.KeyManagementService.Model.CreateCustomKeyStoreResponse will result in that property being returned. /// Specifying -Select '^ParameterName' will result in the cmdlet returning the selected cmdlet parameter value. /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public string Select { get; set; } = "CustomKeyStoreId"; #endregion #region Parameter PassThru /// /// Changes the cmdlet behavior to return the value passed to the CustomKeyStoreName parameter. /// The -PassThru parameter is deprecated, use -Select '^CustomKeyStoreName' instead. This parameter will be removed in a future version. /// [System.Obsolete("The -PassThru parameter is deprecated, use -Select '^CustomKeyStoreName' instead. This parameter will be removed in a future version.")] [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public SwitchParameter PassThru { get; set; } #endregion #region Parameter Force /// /// This parameter overrides confirmation prompts to force /// the cmdlet to continue its operation. This parameter should always /// be used with caution. /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public SwitchParameter Force { get; set; } #endregion protected override void ProcessRecord() { this._AWSSignerType = "v4"; base.ProcessRecord(); var resourceIdentifiersText = FormatParameterValuesForConfirmationMsg(nameof(this.CustomKeyStoreName), MyInvocation.BoundParameters); if (!ConfirmShouldProceed(this.Force.IsPresent, resourceIdentifiersText, "New-KMSCustomKeyStore (CreateCustomKeyStore)")) { return; } var context = new CmdletContext(); // allow for manipulation of parameters prior to loading into context PreExecutionContextLoad(context); #pragma warning disable CS0618, CS0612 //A class member was marked with the Obsolete attribute if (ParameterWasBound(nameof(this.Select))) { context.Select = CreateSelectDelegate(Select) ?? throw new System.ArgumentException("Invalid value for -Select parameter.", nameof(this.Select)); if (this.PassThru.IsPresent) { throw new System.ArgumentException("-PassThru cannot be used when -Select is specified.", nameof(this.Select)); } } else if (this.PassThru.IsPresent) { context.Select = (response, cmdlet) => this.CustomKeyStoreName; } #pragma warning restore CS0618, CS0612 //A class member was marked with the Obsolete attribute context.CloudHsmClusterId = this.CloudHsmClusterId; context.CustomKeyStoreName = this.CustomKeyStoreName; #if MODULAR if (this.CustomKeyStoreName == null && ParameterWasBound(nameof(this.CustomKeyStoreName))) { WriteWarning("You are passing $null as a value for parameter CustomKeyStoreName which is marked as required. In case you believe this parameter was incorrectly marked as required, report this by opening an issue at https://github.com/aws/aws-tools-for-powershell/issues."); } #endif context.CustomKeyStoreType = this.CustomKeyStoreType; context.KeyStorePassword = this.KeyStorePassword; context.TrustAnchorCertificate = this.TrustAnchorCertificate; context.XksProxyAuthenticationCredential_AccessKeyId = this.XksProxyAuthenticationCredential_AccessKeyId; context.XksProxyAuthenticationCredential_RawSecretAccessKey = this.XksProxyAuthenticationCredential_RawSecretAccessKey; context.XksProxyConnectivity = this.XksProxyConnectivity; context.XksProxyUriEndpoint = this.XksProxyUriEndpoint; context.XksProxyUriPath = this.XksProxyUriPath; context.XksProxyVpcEndpointServiceName = this.XksProxyVpcEndpointServiceName; // allow further manipulation of loaded context prior to processing PostExecutionContextLoad(context); var output = Execute(context) as CmdletOutput; ProcessOutput(output); } #region IExecutor Members public object Execute(ExecutorContext context) { var cmdletContext = context as CmdletContext; // create request var request = new Amazon.KeyManagementService.Model.CreateCustomKeyStoreRequest(); if (cmdletContext.CloudHsmClusterId != null) { request.CloudHsmClusterId = cmdletContext.CloudHsmClusterId; } if (cmdletContext.CustomKeyStoreName != null) { request.CustomKeyStoreName = cmdletContext.CustomKeyStoreName; } if (cmdletContext.CustomKeyStoreType != null) { request.CustomKeyStoreType = cmdletContext.CustomKeyStoreType; } if (cmdletContext.KeyStorePassword != null) { request.KeyStorePassword = cmdletContext.KeyStorePassword; } if (cmdletContext.TrustAnchorCertificate != null) { request.TrustAnchorCertificate = cmdletContext.TrustAnchorCertificate; } // populate XksProxyAuthenticationCredential var requestXksProxyAuthenticationCredentialIsNull = true; request.XksProxyAuthenticationCredential = new Amazon.KeyManagementService.Model.XksProxyAuthenticationCredentialType(); System.String requestXksProxyAuthenticationCredential_xksProxyAuthenticationCredential_AccessKeyId = null; if (cmdletContext.XksProxyAuthenticationCredential_AccessKeyId != null) { requestXksProxyAuthenticationCredential_xksProxyAuthenticationCredential_AccessKeyId = cmdletContext.XksProxyAuthenticationCredential_AccessKeyId; } if (requestXksProxyAuthenticationCredential_xksProxyAuthenticationCredential_AccessKeyId != null) { request.XksProxyAuthenticationCredential.AccessKeyId = requestXksProxyAuthenticationCredential_xksProxyAuthenticationCredential_AccessKeyId; requestXksProxyAuthenticationCredentialIsNull = false; } System.String requestXksProxyAuthenticationCredential_xksProxyAuthenticationCredential_RawSecretAccessKey = null; if (cmdletContext.XksProxyAuthenticationCredential_RawSecretAccessKey != null) { requestXksProxyAuthenticationCredential_xksProxyAuthenticationCredential_RawSecretAccessKey = cmdletContext.XksProxyAuthenticationCredential_RawSecretAccessKey; } if (requestXksProxyAuthenticationCredential_xksProxyAuthenticationCredential_RawSecretAccessKey != null) { request.XksProxyAuthenticationCredential.RawSecretAccessKey = requestXksProxyAuthenticationCredential_xksProxyAuthenticationCredential_RawSecretAccessKey; requestXksProxyAuthenticationCredentialIsNull = false; } // determine if request.XksProxyAuthenticationCredential should be set to null if (requestXksProxyAuthenticationCredentialIsNull) { request.XksProxyAuthenticationCredential = null; } if (cmdletContext.XksProxyConnectivity != null) { request.XksProxyConnectivity = cmdletContext.XksProxyConnectivity; } if (cmdletContext.XksProxyUriEndpoint != null) { request.XksProxyUriEndpoint = cmdletContext.XksProxyUriEndpoint; } if (cmdletContext.XksProxyUriPath != null) { request.XksProxyUriPath = cmdletContext.XksProxyUriPath; } if (cmdletContext.XksProxyVpcEndpointServiceName != null) { request.XksProxyVpcEndpointServiceName = cmdletContext.XksProxyVpcEndpointServiceName; } CmdletOutput output; // issue call var client = Client ?? CreateClient(_CurrentCredentials, _RegionEndpoint); try { var response = CallAWSServiceOperation(client, request); object pipelineOutput = null; pipelineOutput = cmdletContext.Select(response, this); output = new CmdletOutput { PipelineOutput = pipelineOutput, ServiceResponse = response }; } catch (Exception e) { output = new CmdletOutput { ErrorResponse = e }; } return output; } public ExecutorContext CreateContext() { return new CmdletContext(); } #endregion #region AWS Service Operation Call private Amazon.KeyManagementService.Model.CreateCustomKeyStoreResponse CallAWSServiceOperation(IAmazonKeyManagementService client, Amazon.KeyManagementService.Model.CreateCustomKeyStoreRequest request) { Utils.Common.WriteVerboseEndpointMessage(this, client.Config, "AWS Key Management Service", "CreateCustomKeyStore"); try { #if DESKTOP return client.CreateCustomKeyStore(request); #elif CORECLR return client.CreateCustomKeyStoreAsync(request).GetAwaiter().GetResult(); #else #error "Unknown build edition" #endif } catch (AmazonServiceException exc) { var webException = exc.InnerException as System.Net.WebException; if (webException != null) { throw new Exception(Utils.Common.FormatNameResolutionFailureMessage(client.Config, webException.Message), webException); } throw; } } #endregion internal partial class CmdletContext : ExecutorContext { public System.String CloudHsmClusterId { get; set; } public System.String CustomKeyStoreName { get; set; } public Amazon.KeyManagementService.CustomKeyStoreType CustomKeyStoreType { get; set; } public System.String KeyStorePassword { get; set; } public System.String TrustAnchorCertificate { get; set; } public System.String XksProxyAuthenticationCredential_AccessKeyId { get; set; } public System.String XksProxyAuthenticationCredential_RawSecretAccessKey { get; set; } public Amazon.KeyManagementService.XksProxyConnectivityType XksProxyConnectivity { get; set; } public System.String XksProxyUriEndpoint { get; set; } public System.String XksProxyUriPath { get; set; } public System.String XksProxyVpcEndpointServiceName { get; set; } public System.Func Select { get; set; } = (response, cmdlet) => response.CustomKeyStoreId; } } }