Class: S33r::S3ACL::Policy

Inherits:
Object
  • Object
show all
Defined in:
lib/s33r/s3_acl.rb,
lib/s33r/s3_logging.rb

Overview

An S3 ACL document, incorporating one or more Grants (see docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingACL.html).

Represents both retrieved ACL XML or can be built up using objects and converted to XML. NB the Policy is oblivious to the resource it is going to be applied to.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(owner, grants = []) ⇒ Policy

owner: S33r::S3ACL::CanonicalUser instance



19
20
21
22
 
# File 'lib/s33r/s3_acl.rb', line 19

def initialize(owner, grants=[])
  @grants = grants
  @owner = owner
end

Instance Attribute Details

#grants ⇒ Object

List of grants to be applied.



16
17
18
 
# File 'lib/s33r/s3_acl.rb', line 16

def grants
  @grants
end

#owner ⇒ Object

List of grants to be applied.



16
17
18
 
# File 'lib/s33r/s3_acl.rb', line 16

def owner
  @owner
end

Class Method Details

.from_xml(acl_xml) ⇒ Object

Create an Policy instance from a raw Access Control Policy XML document.

acl_xml is a raw Access Control Policy XML string (NOT libxml Document or Node).

Returns nil if the ACL XML is nil.



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/s33r/s3_acl.rb', line 29

def self.from_xml(acl_xml)
  return nil if acl_xml.nil?

  acl_xml = S33r.remove_namespace(acl_xml)
  doc = XML.get_xml_doc(acl_xml)
  
  owner_xml = doc.find('//Owner').to_a.first
  owner = CanonicalUser.from_xml(owner_xml)
  
  grants = []
  doc.find('//AccessControlList/Grant').to_a.each do |g|
    grantee_xml = g.find('Grantee').to_a.first
    grantee = Grantee.from_xml(grantee_xml)
    permission = g.xget('Permission')
    
    grants << Grant.new(grantee, permission)
  end
  
  Policy.new(owner, grants)
end

Instance Method Details

#add_grant(grant) ⇒ Object

Add a grant to the ACL document.

Returns true if grant was added; false otherwise (grant already exists).



77
78
79
80
81
82
 
# File 'lib/s33r/s3_acl.rb', line 77

def add_grant(grant)
  unless @grants.include?(grant)
    @grants << grant
  end
  self
end

#add_log_target_grants ⇒ Object

Add permissions to an instances which give READ_ACL and WRITE permissions to the LogDelivery group. Used to enable a bucket as a logging destination.

Returns true if grants added, false otherwise (if already a log target).



77
78
79
80
81
82
83
84
 
# File 'lib/s33r/s3_logging.rb', line 77

def add_log_target_grants
  if log_targetable?
    return false
  else
    Grant.log_target_grants.each { |g| add_grant(g) }
    return true
  end
end

#add_public_read_grant ⇒ Object

Add a public READ permission to this instance.



109
110
111
 
# File 'lib/s33r/s3_acl.rb', line 109

def add_public_read_grant
  add_grant(Grant.public_read_grant)
end

#log_targetable? ⇒ Boolean

Does the ACL make the associated resource available as a log target?

Returns:

  • (Boolean) 


65
66
67
68
69
 
# File 'lib/s33r/s3_logging.rb', line 65

def log_targetable?
  log_target_grants = Grant.log_target_grants
  log_target_grants.each { |g| return false if !grants.include?(g) }
  return true
end

#public_readable? ⇒ Boolean

Does the ACL contain a grant for public reads? (i.e. grants holds a Grant object for :all_users with :read permission)

Returns:

  • (Boolean) 


100
101
102
103
104
105
106
 
# File 'lib/s33r/s3_acl.rb', line 100

def public_readable?
  pr_grant = Grant.public_read_grant
  grants.each do |g|
    return true if pr_grant == g
  end
  return false
end

#remove_grant(grant) ⇒ Object

Remove a grant from the ACL document. Note that if you set a grant for an AmazonCustomer, you want be able to remove it by specifying the same grant. This is because grants set by AmazonCustomer are converted at the S3 end into CanonicalUser grants - so you will need to remove a CanonicalUser grant instead. See Grant.for_amazon_customer for a few more details.

Returns true if grant was removed; false if it wasn’t in the document.



93
94
95
96
 
# File 'lib/s33r/s3_acl.rb', line 93

def remove_grant(grant)
  @grants.delete_if { |g| grant == g }
  self
end

#remove_log_target_grants ⇒ Object

Remove log target ACLs from the document.

Returns true if all log target grants were removed; false otherwise.

NB even if this method returns false, that doesn’t mean the bucket is still a log target. Use log_targetable? to check whether a bucket can be used as a log target.



94
95
96
97
98
 
# File 'lib/s33r/s3_logging.rb', line 94

def remove_log_target_grants
  ok = true
  Grant.log_target_grants.each { |g| ok = ok and remove_grant(g) }
  ok
end

#remove_public_read_grant ⇒ Object

Remove the public READ permission from this instance.



114
115
116
 
# File 'lib/s33r/s3_acl.rb', line 114

def remove_public_read_grant
  remove_grant(Grant.public_read_grant)
end

#to_s ⇒ Object

String representation of the policy.



119
120
121
 
# File 'lib/s33r/s3_acl.rb', line 119

def to_s
  @grants.inject('') {|acc, grant| acc += "* " + grant.to_s + "\n"}
end

#to_xml ⇒ Object

Generate AccessControlPolicy XML document.



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/s33r/s3_acl.rb', line 51

def to_xml
  xml_str = ""
  xml = Builder::XmlMarkup.new(:target => xml_str, :indent => 0)
  
  xml.instruct!
  
  # Access control policy XML.
  xml.AccessControlPolicy({"xmlns" => RESPONSE_NAMESPACE_URI}) {
    xml.Owner {
      xml.ID owner.user_id
      xml.DisplayName owner.display_name
    }
    xml.AccessControlList {
      grants.each do |grant|
        xml << grant.to_xml
      end
    }
  }
  
  xml_str
end