/******************************************************************************* * 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.S3; using Amazon.S3.Model; namespace Amazon.PowerShell.Cmdlets.S3 { /// /// Sets the permissions on an existing bucket using access control lists (ACL). For more /// information, see Using /// ACLs. To set the ACL of a bucket, you must have WRITE_ACP permission. /// /// /// /// You can use one of the following two ways to set a bucket's permissions: /// /// You cannot specify access permission using both the body and the request headers. /// /// Depending on your application needs, you may choose to set the ACL on a bucket using /// either the request body or the headers. For example, if you have an existing application /// that updates a bucket ACL using the request body, then you can continue to use that /// approach. /// /// If your bucket uses the bucket owner enforced setting for S3 Object Ownership, ACLs /// are disabled and no longer affect permissions. You must use policies to grant access /// to your bucket and the objects in it. Requests to set ACLs or update ACLs fail and /// return the AccessControlListNotSupported error code. Requests to read /// ACLs are still supported. For more information, see Controlling /// object ownership in the Amazon S3 User Guide. ///
Permissions
/// You can set access permissions by using one of the following methods: ///
  • /// Specify a canned ACL with the x-amz-acl request header. Amazon S3 supports /// a set of predefined ACLs, known as canned ACLs. Each canned ACL has a predefined /// set of grantees and permissions. Specify the canned ACL name as the value of x-amz-acl. /// If you use this header, you cannot use other access control-specific headers in your /// request. For more information, see Canned /// ACL. ///
  • /// Specify access permissions explicitly with the x-amz-grant-read, x-amz-grant-read-acp, /// x-amz-grant-write-acp, and x-amz-grant-full-control headers. /// When using these headers, you specify explicit access permissions and grantees (Amazon /// Web Services accounts or Amazon S3 groups) who will receive the permission. If you /// use these ACL-specific headers, you cannot use the x-amz-acl header to /// set a canned ACL. These parameters map to the set of permissions that Amazon S3 supports /// in an ACL. For more information, see Access /// Control List (ACL) Overview. /// /// You specify each grantee as a type=value pair, where the type is one of the following: ///
    • id – if the value specified is the canonical user ID of an Amazon Web /// Services account ///
    • uri – if you are granting permissions to a predefined group ///
    • emailAddress – if the value specified is the email address of an Amazon /// Web Services account /// /// Using email addresses to specify a grantee is only supported in the following Amazon /// Web Services Regions: ///
      • /// US East (N. Virginia) ///
      • /// US West (N. California) ///
      • /// US West (Oregon) ///
      • /// Asia Pacific (Singapore) ///
      • /// Asia Pacific (Sydney) ///
      • /// Asia Pacific (Tokyo) ///
      • /// Europe (Ireland) ///
      • /// South America (São Paulo) ///
      /// For a list of all the Amazon S3 supported Regions and endpoints, see Regions /// and Endpoints in the Amazon Web Services General Reference. ///
    /// For example, the following x-amz-grant-write header grants create, overwrite, /// and delete objects permission to LogDelivery group predefined by Amazon S3 and two /// Amazon Web Services accounts identified by their email addresses. /// x-amz-grant-write: uri="http://acs.amazonaws.com/groups/s3/LogDelivery", id="111122223333", /// id="555566667777"
/// You can use either a canned ACL or specify access permissions explicitly. You cannot /// do both. ///
Grantee Values
/// You can specify the person (grantee) to whom you're assigning access rights (using /// request elements) in the following ways: ///
  • /// By the person's ID: /// <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID><>ID<></ID><DisplayName><>GranteesEmail<></DisplayName> /// </Grantee> /// DisplayName is optional and ignored in the request ///
  • /// By URI: /// <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group"><URI><>http://acs.amazonaws.com/groups/global/AuthenticatedUsers<></URI></Grantee>
  • /// By Email address: /// <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail"><EmailAddress><>Grantees@email.com<></EmailAddress>&</Grantee> /// The grantee is resolved to the CanonicalUser and, in a response to a GET Object acl /// request, appears as the CanonicalUser. /// /// Using email addresses to specify a grantee is only supported in the following Amazon /// Web Services Regions: ///
    • /// US East (N. Virginia) ///
    • /// US West (N. California) ///
    • /// US West (Oregon) ///
    • /// Asia Pacific (Singapore) ///
    • /// Asia Pacific (Sydney) ///
    • /// Asia Pacific (Tokyo) ///
    • /// Europe (Ireland) ///
    • /// South America (São Paulo) ///
    /// For a list of all the Amazon S3 supported Regions and endpoints, see Regions /// and Endpoints in the Amazon Web Services General Reference. ///
/// The following operations are related to PutBucketAcl: /// ///
[Cmdlet("Set", "S3ACL", SupportsShouldProcess = true, ConfirmImpact = ConfirmImpact.Medium)] [OutputType("None")] [AWSCmdlet("Calls the Amazon Simple Storage Service (S3) PutACL API operation.", Operation = new[] {"PutACL"}, SelectReturnType = typeof(Amazon.S3.Model.PutACLResponse))] [AWSCmdletOutput("None or Amazon.S3.Model.PutACLResponse", "This cmdlet does not generate any output." + "The service response (type Amazon.S3.Model.PutACLResponse) can be referenced from properties attached to the cmdlet entry in the $AWSHistory stack." )] public partial class SetS3ACLCmdlet : AmazonS3ClientCmdlet, IExecutor { #region Parameter BucketName /// /// /// The bucket name that contains the object to which you want to attach the ACL.When using this API with an access point, you must direct requests to the access point hostname. /// The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. /// When using this operation with an access point through the AWS SDKs, you provide the access point /// ARN in place of the bucket name. For more information about access point ARNs, see /// Using Access Points /// in the Amazon Simple Storage Service Developer Guide. /// /// [System.Management.Automation.Parameter(Position = 0, ValueFromPipelineByPropertyName = true, ValueFromPipeline = true, Mandatory = true)] public System.String BucketName { get; set; } #endregion #region Parameter CannedACL /// /// /// The canned ACL to apply to the bucket. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] [Alias("CannedACLName")] [AWSConstantClassSource("Amazon.S3.S3CannedACL")] public Amazon.S3.S3CannedACL CannedACL { get; set; } #endregion #region Parameter ChecksumAlgorithm /// /// /// Indicates the algorithm used to create the checksum for the object. Amazon S3 will /// fail the request with a 400 error if there is no checksum associated with the object. /// For more information, see /// Checking object integrity in the Amazon S3 User Guide. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] [AWSConstantClassSource("Amazon.S3.ChecksumAlgorithm")] public Amazon.S3.ChecksumAlgorithm ChecksumAlgorithm { get; set; } #endregion #region Parameter Owner_DisplayName /// /// /// Container for the display name of the owner. This value is only supported in the following /// Amazon Web Services Regions: /// /// [System.Management.Automation.Parameter(Position = 3, ValueFromPipelineByPropertyName = true)] [Alias("AccessControlList_Owner_DisplayName","ACL_Owner_DisplayName","OwnerDisplayName")] public System.String Owner_DisplayName { get; set; } #endregion #region Parameter ExpectedBucketOwner /// /// /// The account ID of the expected bucket owner. /// If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String ExpectedBucketOwner { get; set; } #endregion #region Parameter AccessControlList_Grant /// /// /// A collection of grants. /// /// [System.Management.Automation.Parameter(Position = 4, ValueFromPipelineByPropertyName = true)] [Alias("AccessControlList_Grants","ACL_Grants","Grant","Grants")] public Amazon.S3.Model.S3Grant[] AccessControlList_Grant { get; set; } #endregion #region Parameter Owner_Id /// /// /// The unique identifier of the owner. /// /// [System.Management.Automation.Parameter(Position = 2, ValueFromPipelineByPropertyName = true)] [Alias("AccessControlList_Owner_Id","ACL_Owner_Id","OwnerId")] public System.String Owner_Id { get; set; } #endregion #region Parameter Key /// /// /// The key of an S3 object. /// If not specified, the ACLs are applied to the bucket. /// Key for which the PUT action was initiated.When using this action with an access point, you must direct requests to the access point hostname. /// The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. /// When using this action with an access point through the Amazon Web Services SDKs, you provide the access point ARN in place of the bucket name. /// For more information about access point ARNs, see /// Using Access Points in the Amazon S3 User Guide.When you use this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. /// The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. /// When you use this action with S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. /// For more information about S3 on Outposts ARNs, see /// What is S3 on Outposts in the Amazon S3 User Guide. /// /// [System.Management.Automation.Parameter(Position = 1, ValueFromPipelineByPropertyName = true)] public System.String Key { get; set; } #endregion #region Parameter VersionId /// /// /// If set and an object key has been specified, the ACLs are applied /// to the specific version of the object. /// This property is ignored if the ACL is to be set on a Bucket. /// /// [System.Management.Automation.Parameter(Position = 5, ValueFromPipelineByPropertyName = true)] public System.String VersionId { get; set; } #endregion #region Parameter Select /// /// Use the -Select parameter to control the cmdlet output. The cmdlet doesn't have a return value by default. /// Specifying -Select '*' will result in the cmdlet returning the whole service response (Amazon.S3.Model.PutACLResponse). /// 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; } = "*"; #endregion #region Parameter PassThru /// /// Changes the cmdlet behavior to return the value passed to the BucketName parameter. /// The -PassThru parameter is deprecated, use -Select '^BucketName' instead. This parameter will be removed in a future version. /// [System.Obsolete("The -PassThru parameter is deprecated, use -Select '^BucketName' 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 = "s3"; base.ProcessRecord(); var resourceIdentifiersText = FormatParameterValuesForConfirmationMsg(nameof(this.Key), MyInvocation.BoundParameters); if (!ConfirmShouldProceed(this.Force.IsPresent, resourceIdentifiersText, "Set-S3ACL (PutACL)")) { 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.BucketName; } #pragma warning restore CS0618, CS0612 //A class member was marked with the Obsolete attribute context.Owner_DisplayName = this.Owner_DisplayName; context.Owner_Id = this.Owner_Id; if (this.AccessControlList_Grant != null) { context.AccessControlList_Grant = new List(this.AccessControlList_Grant); } context.CannedACL = this.CannedACL; context.BucketName = this.BucketName; context.ChecksumAlgorithm = this.ChecksumAlgorithm; context.ExpectedBucketOwner = this.ExpectedBucketOwner; context.Key = this.Key; context.VersionId = this.VersionId; // 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.S3.Model.PutACLRequest(); // populate AccessControlList var requestAccessControlListIsNull = true; request.AccessControlList = new Amazon.S3.Model.S3AccessControlList(); List requestAccessControlList_accessControlList_Grant = null; if (cmdletContext.AccessControlList_Grant != null) { requestAccessControlList_accessControlList_Grant = cmdletContext.AccessControlList_Grant; } if (requestAccessControlList_accessControlList_Grant != null) { request.AccessControlList.Grants = requestAccessControlList_accessControlList_Grant; requestAccessControlListIsNull = false; } Amazon.S3.Model.Owner requestAccessControlList_accessControlList_Owner = null; // populate Owner var requestAccessControlList_accessControlList_OwnerIsNull = true; requestAccessControlList_accessControlList_Owner = new Amazon.S3.Model.Owner(); System.String requestAccessControlList_accessControlList_Owner_owner_DisplayName = null; if (cmdletContext.Owner_DisplayName != null) { requestAccessControlList_accessControlList_Owner_owner_DisplayName = cmdletContext.Owner_DisplayName; } if (requestAccessControlList_accessControlList_Owner_owner_DisplayName != null) { requestAccessControlList_accessControlList_Owner.DisplayName = requestAccessControlList_accessControlList_Owner_owner_DisplayName; requestAccessControlList_accessControlList_OwnerIsNull = false; } System.String requestAccessControlList_accessControlList_Owner_owner_Id = null; if (cmdletContext.Owner_Id != null) { requestAccessControlList_accessControlList_Owner_owner_Id = cmdletContext.Owner_Id; } if (requestAccessControlList_accessControlList_Owner_owner_Id != null) { requestAccessControlList_accessControlList_Owner.Id = requestAccessControlList_accessControlList_Owner_owner_Id; requestAccessControlList_accessControlList_OwnerIsNull = false; } // determine if requestAccessControlList_accessControlList_Owner should be set to null if (requestAccessControlList_accessControlList_OwnerIsNull) { requestAccessControlList_accessControlList_Owner = null; } if (requestAccessControlList_accessControlList_Owner != null) { request.AccessControlList.Owner = requestAccessControlList_accessControlList_Owner; requestAccessControlListIsNull = false; } // determine if request.AccessControlList should be set to null if (requestAccessControlListIsNull) { request.AccessControlList = null; } if (cmdletContext.CannedACL != null) { request.CannedACL = cmdletContext.CannedACL; } if (cmdletContext.BucketName != null) { request.BucketName = cmdletContext.BucketName; } if (cmdletContext.ChecksumAlgorithm != null) { request.ChecksumAlgorithm = cmdletContext.ChecksumAlgorithm; } if (cmdletContext.ExpectedBucketOwner != null) { request.ExpectedBucketOwner = cmdletContext.ExpectedBucketOwner; } if (cmdletContext.Key != null) { request.Key = cmdletContext.Key; } if (cmdletContext.VersionId != null) { request.VersionId = cmdletContext.VersionId; } 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.S3.Model.PutACLResponse CallAWSServiceOperation(IAmazonS3 client, Amazon.S3.Model.PutACLRequest request) { Utils.Common.WriteVerboseEndpointMessage(this, client.Config, "Amazon Simple Storage Service (S3)", "PutACL"); try { #if DESKTOP return client.PutACL(request); #elif CORECLR return client.PutACLAsync(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 Owner_DisplayName { get; set; } public System.String Owner_Id { get; set; } public List AccessControlList_Grant { get; set; } public Amazon.S3.S3CannedACL CannedACL { get; set; } public System.String BucketName { get; set; } public Amazon.S3.ChecksumAlgorithm ChecksumAlgorithm { get; set; } public System.String ExpectedBucketOwner { get; set; } public System.String Key { get; set; } public System.String VersionId { get; set; } public System.Func Select { get; set; } = (response, cmdlet) => null; } } }