conjur-api 4.14.0 → 4.15.0

data/lib/conjur/has_id.rb

@@ -19,11 +19,23 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+
+  # Included in classes for assets that derive their id from their urls.
   module HasId
+    # @api private
+    # This method is provided to support basic JSON serialization for all objects with `id`s.
+    #
+    # @param [Hash] options provided for backwards compatibility, do not use.
+    # @return [Hash] the JSON hash.
     def to_json(options = {})
       { id: id }
     end
-  
+
+
+    # Get this assets id.  This is the *unqualified* Conjur id for the asset,
+    # and is derived from the asset's url.
+    #
+    # @return [String] the asset's id
     def id
       URI.unescape self.url.split('/')[-1]
     end    

data/lib/conjur/has_identifier.rb

@@ -19,13 +19,16 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+  # Included in Conjur assets that have an identifier attribute.
   module HasIdentifier
-    def self.included(base)
-      base.instance_eval do
-        include HasAttributes
-      end
-    end
-    
+    include HasAttributes
+
+    # Get the identifier attribute.  This is a *fully qualified* Conjur id.
+    #
+    # ### Permissions
+    # You must have the "`read`" permission on the underlying resource to call this method.
+    #
+    # @return [String] the asset's fully qualified id
     def identifier
       attributes['identifier']
     end    

data/lib/conjur/has_owner.rb

@@ -19,17 +19,31 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+  # Included in assets that have an *owner*.
   module HasOwner
-    def self.included(base)
-      base.instance_eval do
-        include HasAttributes
-      end
-    end
-    
+    include HasAttributes
+
+    # Return the `userid` attribute.  This is the id of the Conjur role that
+    # created this asset.
+    #
+    # ### Permissions
+    # You must have the "`read`" permission on the underlying resource to call this method.
+    #
+    # @return [String] the userid
     def userid
       attributes['userid']
     end    
-    
+
+
+    # Return the owner of this resource or asset.
+    #
+    # The owner of a resource or an asset with an underlying resource is allowed to do anything to the resource,
+    # including granting permissions to other roles.
+    #
+    # ### Permissions
+    # You must have the "`read`" permission on the underlying resource to call this method.
+    #
+    # @return [String] the fully qualified role id of the asset's  owner.
     def ownerid
       attributes['ownerid']
     end    

data/lib/conjur/host.rb

@@ -19,7 +19,15 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+  # This class represents a {http://developer.conjur.net/reference/services/directory/host
+  # Conjur Host} asset.  You should not create {Conjur::Host} instances directly, but use {Conjur::API}
+  # methods such as {Conjur::API#create_host} and {Conjur::API#host}.
   class Host < Deputy
+
+    # @api private
+    # @deprecated
+    #
+    # This method was used before conjurize came along.  It's no longer in use.
     def enrollment_url
       log do |logger|
         logger << "Fetching enrollment_url for #{id}"

data/lib/conjur/layer-api.rb

@@ -1,5 +1,9 @@
 class Conjur::API
   class << self
+    # @api private
+    #
+    # Url to the layers service.
+    # @return [String] the url
     def layer_asset_host
       ENV["CONJUR_LAYER_ASSET_URL"] || Conjur::Core::API.host
     end

data/lib/conjur/layer.rb

@@ -1,8 +1,37 @@
 module Conjur
+
+  # A {http://developer.conjur.net/reference/services/directory/layer Conjur Layer}
+  # represents a collection of
+  # {http://developer.conjur.net/reference/services/directory/host Conjur Hosts} with the
+  # ssame permissions on other Conjur resources.
+  #
+  # @example Allow hosts in the layer `dev/database` to access a `dev/database_uri` secret
+  #   # Create the layer and add a couple of EC2 hosts
+  #   layer = api.create_layer 'dev/database'
+  #   hosts = ['ec2-iac5ed', 'ec2-iadc31'].map{ |hostid| api.create_host id: hostid }
+  #   hosts.each{ |host| layer.add_host host }
+  #
+  #   # A Variable representing the database uri secret
+  #   database_uri  = api.variable 'dev/database_uri'
+  #
+  #   # Currently none of the hosts can access it:
+  #   hosts.any?{ |host| host.role.permitted? database_uri, 'execute' } # => false
+  #
+  #   # Grant permission on the layer
+  #   database_uri.resource.permit 'execute', layer
+  #
+  #   # Now all hosts in the layer have the execute permission on the secret through the layer
+  #   hosts.all?{ |host| host.role.permitted? database_uri, 'execute' } # => true
+  #
   class Layer < RestClient::Resource
     include ActsAsAsset
     include ActsAsRole
-    
+
+    # Add a host to this layer.  The host's role will become a member of the layer's role, and have
+    # all privileges of the layer.
+    #
+    # @param [String, Conjur::Host] hostid A *qualified* Conjur id for the host, or a {Conjur::Host} instance.
+    # @return [void]
     def add_host(hostid)
       hostid = cast(hostid, :roleid)
       log do |logger|
@@ -12,7 +41,12 @@ module Conjur
         RestClient::Resource.new(self['hosts'].url, options).post(hostid: hostid) 
       end
     end
-    
+
+    # Remove a host from this layer.  The host will lose all privileges it had through this
+    # layer.
+    #
+    # @param [String, Conjur::Host] hostid A *qualified* Conjur id for the host, or a {Conjur::Host} instance.
+    # @return [void]
     def remove_host(hostid)
       hostid = cast(hostid, :roleid)
       log do |logger|
@@ -23,11 +57,24 @@ module Conjur
       end
     end
     
-    # Lists the roles that have been granted access to the hosts owned roles.
+    # Lists the roles that have been granted access to the host's owned roles.
+    #
+    # `role_name` can be either `admin_host` or `use_host`.  This method corresponds
+    # to {Conjur::ActsAsAsset#add_member} in that members added with that method
+    # will be returned by this method.
+    #
+    # @param [String] role_name Either `use_host` or `admin_host`
+    # @return [Conjur::RoleGrant] the grants associated with this host (the return type
+    #   is identical to that of {Conjur::Role#members}).
+    # @see Conjur::ActsAsAsset#add_member
     def hosts_members(role_name)
       owned_role(role_name).members
     end
 
+
+    # Return all hosts in the layer.
+    #
+    # @return [Array<Conjur::Host>] the hosts in the layer.
     def hosts
       self.attributes['hosts'].collect do |id|
         Conjur::Host.new(Conjur::API.core_asset_host, options)["hosts/#{fully_escape id}"]

data/lib/conjur/log.rb

@@ -21,11 +21,26 @@
 require 'logger'
 
 module Conjur
-  # You can also configure logging by the environment variable CONJURAPI_LOG.
+  # Assign a Logger for use by Conjur API methods.  This method accepts
+  # several argument forms:
+  # * The strings 'stdout' and 'stderr' cause log messages to be sent to the corresponding stream.
+  # * Other stings are treated as paths and will cause log messages to be sent to those files.
+  # * A `Logger` instance will be used as is.
+  #
+  # Note that the logger specified by the `CONJURAPI_LOG` environment variable will override
+  # the value set here.
+  #
+  # @param [String, Logger,nil] log the new logger to use
+  # @return [void]
   def self.log= log
     @@log = create_log log
   end
 
+  # @api private
+  # Create a log from a String or Logger param
+  #
+  # @param [String, Logger, nil] param the value to create the logger from
+  # @return Logger
   def self.create_log param
     if param
       if param.is_a? String
@@ -46,7 +61,12 @@ module Conjur
 
   @@log = nil
 
-  def self.log # :nodoc:
+  # @api private
+  # @note this method may return nil if no log has been set, so you **must** check the value
+  # before attempting to use the logger.
+  #
+  # You should consider using {Conjur::LogSource} instead.
+  def self.log
     @@env_log || @@log
   end
 end

data/lib/conjur/log_source.rb

@@ -19,7 +19,34 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+  # This module provides logging support for actions taken by the Conjur API.
+  #
+  # @example
+  #     class Example
+  #       include LogSource
+  #
+  #       def something_interesting param
+  #         log{|l| l << "doing something interesting with #{param}"}
+  #
+  #         # Do something interesting...
+  #       end
+  #
+  #     end
+  #     # ...
+  #
+  #     Example.new.something_interesting 'foo'
+  #     # will log:
+  #     # [admin] doing something interesting with foo
+  #
   module LogSource
+    # Yield a logger to the block.  You should use the `<<` method to write to the
+    # logger so that you don't send newlines or formatting.  The block will only be called
+    # if {Conjur.log} is not nil.
+    #
+    # The log format is `"[<username>]<messages logged in block>\n"`.
+    #
+    # @yieldparam [#<<] logger a logger to write messages
+    # @return [void]
     def log(&block)
       if Conjur.log
         Conjur.log << "["

data/lib/conjur/path_based.rb

@@ -19,21 +19,66 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+  # This module provides methods for determining Conjur id components from an asset's
+  # REST URL.
   module PathBased
+    # Return the Conjur {http://developer.conjur.net/reference/services/authorization#Organization.Account
+    # organizational account} for this role or resource.  The `account`
+    # is the first token in a fully qualified Conjur id, like `"account:kind:identifier"`
+    #
+    # @example
+    #   role = api.role 'foo:bar:baz'
+    #   role.account # => 'foo'
+    #
+    # @return [String] the Conjur organizational account
     def account
       match_path(0..0)
     end
 
+    # Return the *kind* for this role or resource.  The kind partitions the space of roles and resources, generally
+    # according to their purpose (for example, roles representing users have kind `'user'`).  The `kind` of a role or
+    # resource is the second token of a fully qualified Conjur id, like `"account:kind:identifier"`.
+    #
+    # @example Get the kind of a role
+    #   role = api.host('postgres-1').role
+    #   role.kind # => 'host'
+    #
+    # @example Get the kind of a resource
+    #   res  = api.host('postgres-1').resource
+    #   res.kind # => 'host'
+    #
+    # @return [String] the kind of the role or resource
     def kind
       match_path(2..2)
     end
     
     protected
-    
+
+    # @api private
+    #
+    # Returns the path parts in the given range.
+    #
+    # @example
+    #   self.url # => "https://10.0.3.100/api/authz/foo/roles/bar/baz"
+    #   self.match_path 0..2 # => "foo/roles/bar"
+    #   self.match_path 2..-1 # => "bar/baz"
+    #
+    # @param [Range] range the range of parts
+    # @return [String] the parts joined by `'/'`
     def match_path(range)
       tokens[range].map{|t| URI.unescape(t)}.join('/')
     end
-    
+
+    # @api private
+    #
+    # Returns the components of this asset's path starting with the first component
+    # that isn't part of the authz service url.
+    #
+    # @example
+    #   self.url # => "https://10.0.3.100/api/authz/foo/roles/bar/baz"
+    #   self.tokens # => ["foo", "roles", "bar", "baz"]
+    #
+    # @return [Array<String>] the path components
     def tokens
       self.url[RestClient::Resource.new(Conjur::Authz::API.host)[''].url.length..-1].split('/')
     end

data/lib/conjur/pubkeys-api.rb

@@ -22,6 +22,14 @@ require 'conjur/api'
 require 'conjur/configuration'
 
 class Conjur::Configuration
+  # @!attribute pubkeys_url
+  # The url for the {http://developer.conjur.net/reference/services/pubkyes Conjur public keys service}.
+  #
+  # @note You should not generally set this value.  Instead, Conjur will derive it from the
+  #   {Conjur::Configuration#account} and {Conjur::Configuration#appliance_url}
+  #   properties.
+  #
+  # @return [String] the pubkeys service url
   add_option :pubkeys_url do
     account_service_url 'pubkeys', 400
   end
@@ -29,6 +37,10 @@ end
 
 class Conjur::API
   class << self
+    # @api private
+    #
+    # Url to the pubkeys service.
+    # @return [String] the url
     def pubkeys_asset_host 
       Conjur.configuration.pubkeys_url
     end

data/lib/conjur/role.rb

@@ -21,20 +21,47 @@
 require 'conjur/role_grant'
 
 module Conjur
+  # A {http://developer.conjur.net/reference/services/authorization/role Conjur Role} represents an actor that
+  # can be granted or denied permissionto do various things to
+  # {http://developer.conjur.net/reference/services/authorization/resource Conjur Resources}.  Roles are hierarchical:
+  # if role a is a **member of** role b, a is permitted to do everything b is permitted
+  # to do.  This relationship is transitive, so if a is a member of b, b is a member of c,
+  # and c is a member of d, a has all of d's permissions.
+  #
+  # This class represents a Role with a particular identifier.  The actual Conjur role *may or may not
+  # exist!*
   class Role < RestClient::Resource
     include Exists
     include PathBased
 
+    # The *unqualified* identifier for this role.
+    #
+    # @example
+    #   api.role('conjur:foo:bar').identifier # => "bar"
+    #
+    # @return [String] the unqualified identifier
     def identifier
       match_path(3..-1)
     end
     
     alias id identifier
-    
+
+    # The *qualified* identifier for this role.
+    #
+    # @example
+    #   api.user('bob').role_id # => "conjur:user:bob"
+    #
+    # @return [String] the *qualified* identifier
     def roleid
       [ account, kind, identifier ].join(':')
     end
-    
+
+    alias role_id roleid
+
+    # @api private
+    # Create this role.
+    #
+    # You probably want to use {Conjur::API#create_role} instead.
     def create(options = {})
       log do |logger|
         logger << "Creating role #{kind}:#{identifier}"
@@ -44,7 +71,32 @@ module Conjur
       end
       self.put(options)
     end
-   
+
+    # Find all roles of which this role is a member.  This relationship is recursively expanded,
+    # so if `a` is a member of `b`, and `b` is a member of `c`, `a.all` will include `c`.
+    #
+    # ### Permissions
+    # You must be a member of the role to call this method (note that the `admin` user is
+    # a member of every role).
+    #
+    # You can restrict the roles returned to one or more role ids.  This feature is mainly useful
+    # for checking whether this role is a member of any of a set of roles.
+    #
+    # @example Show all roles of which `"conjur:group:pubkeys-1.0/key-managers"` is a member
+    #   # Add alice to the group, so we see something interesting
+    #   key_managers = api.group('pubkeys-1.0/key-managers')
+    #   key_managers.add_member api.user('alice')
+    #
+    #   # Show the memberships, mapped to the member ids.
+    #   key_managers.role.all.map(&:roleid)
+    #   # => ["conjur:group:pubkeys-1.0/admin", "conjur:user:alice"]
+    #
+    # @example See if role `"conjur:user:alice"` is a member of either `"conjur:groups:developers"` or `"conjur:group:ops"`
+    #   is_member = not api.role('conjur:user:alice').all(filter: ['conjur:group:developers', 'conjur:group:ops']).empty?
+    #
+    # @param [Hash] options options for the request
+    # @option options [String, #roleid, Array<String, #roleid>] :filter only return roles in this list
+    # @return [Array<Conjur::Role>] Roles of which this role is a member
     def all(options = {})
       query_string = "?all"
       
@@ -59,14 +111,95 @@ module Conjur
     end
     
     alias memberships all
-    
+
+    # Check to see if this role is a member of another role.  Membership is transitive.
+    #
+    # ### Permissions
+    # You must be logged in as a member of this role in order to call this method.  Note that if you
+    # pass a role of which you aren't a member to this method, it will return false rather than raising an
+    # exception.
+    #
+    # @example Permissions
+    #   alice_api = Conjur::API.new_from_key "alice", "alice-password"
+    #   admin_api = Conjur::API.new_from_key "admin", "admin-password"
+    #
+    #   # admin_view is the role as seen by the admin user
+    #   admin_view = admin_api.role('conjur:group:pubkeys-1.0/key-managers')
+    #   admin_view.member_of? alice_api.current_role # => false
+    #   alice_api.current_role.member_of? admin_view # => false
+    #
+    #   # alice_view is the role as seen by alice (who isn't a member of the key-managers group)
+    #   alice_view = alice_api.role('conjur:group:pubkeys-1.0/key-managers')
+    #   alice_view.member_of? alice_api.current_role # raises RestClient::Forbidden
+    #   alice_api.current_role.member_of? alice_view # false
+    #
+    # @param [String, #roleid] other_role the role or role id of which we might be a member
+    # @return [Boolean] whether this role is a member of `other_role`
+    # @raise [RestClient::Forbidden] if you don't have permission to perform this operation
     def member_of?(other_role)
       other_role = cast(other_role, :roleid)
       not all(filter: other_role).empty?
     end
-    
-    # @param [Hash] options
-    #   * *admin_option* enables the +member+ to manage members of this role
+
+    # Grant this role to another one.  The role given by the `member` argument will become
+    # a member of this role, and have all of its permissions.
+    #
+    # ### Permissions
+    # You must have admin permissions on this role.
+    #
+    # @example Allow `'alice'` to do everything that `'bob'` can do (perhaps better!).
+    #   bob = api.role 'cook:bob'
+    #   alice = api.role 'cook:alice'
+    #
+    #   # bob is allowed to 'fry' a resource called 'food:bacon'
+    #   bob.permitted? "food:bacon", "fry" # => true
+    #
+    #   # alice isn't
+    #   alice.permitted? "food:bacon", "fry" # => false
+    #
+    #   # grant the role 'cook:bob'  to alice, so that she can participate in our culture's
+    #   # bizarre bacon obsession!
+    #   bob.grant_to alice
+    #
+    #   # Now she can fry some bacon!
+    #   alice.permitted? 'food:bacon', 'fry' # => true
+    #
+    # @example Make `alice` a member of `job:cook`, and let her grant that role to others
+    #   # Create an api logged in as 'alice'.  We assume that `api` is an admin.
+    #   alice_api = Conjur::API.new_from_key 'alice', 'alice-password'
+    #
+    #   # First do it without the `admin_option`
+    #   api.role('job:cook').grant_to alice_api.current_role
+    #
+    #   # Alice can't grant the role to bob
+    #   alice_api.role('job:cook').grant_to 'user:bob' # => raises RestClient::Forbidden
+    #
+    #   # Make alice an admin of the role
+    #   api.role('job:cook').grant_to alice_api.current_role, admin_option: true
+    #
+    #   # Now she can grant the role to bob
+    #   alice_api.role('job:cook').grant_to 'user:bob' # Works!
+    #
+    # @example Take away a member's admin privilege
+    #   # alice_api is an api logged in as user "alice", who has admin rights on the role 'job:cooks'.
+    #   # Notice that she can grant the role to 'eve'
+    #   alice_api.role('job:cook').grant_to 'eve'
+    #
+    #   # We don't want her to do this any more
+    #   admin_api.role('job:cook').grant_to 'user:alice', admin_option: false
+    #
+    #   # She's still a member
+    #   alice_api.member_of?('job:cook') # => true
+    #
+    #   # But she can't grant the role to 'bob'
+    #   alice_api.role('job:cook').grant_to 'user:bob' # raises RestClient:Forbidden
+    #
+    # @param [String, #roleid] member the role that will become a member of this role
+    # @param [Hash] options options for the grant
+    # @option options [Boolean] :admin_option when given, the admin flag on the role grant will be set to
+    #   this value.
+    # @return [void]
+    # @raise [RestClient::Forbidden] if you don't have permission to perform the operation
     def grant_to(member, options={})
       member = cast(member, :roleid)
       log do |logger|
@@ -78,6 +211,35 @@ module Conjur
       self["?members&member=#{query_escape member}"].put(options)
     end
 
+    # Remove (revoke) a member from this role. This operation is the inverse of {#grant_to}
+    #
+    # ### Permissions
+    # You must have admin permissions on this role
+    #
+    #
+    # @example Bob has been fired from his job as a cook.
+    #   # currently, he's a member, and therefore is allowed to 'fry' the 'bacon' resource
+    #   bob = api.role('user:bob')
+    #   bob.member_of? 'job:cook' # true
+    #   bob.permitted? 'food:bacon', 'fry' # true
+    #
+    #   # Revoke 'job:cook'
+    #   api.role('job:cook').revoke_from 'user:bob'
+    #
+    #   # Now he's not a member, and he can't fry bacon any more
+    #   bob.member_of? 'job:cook' # false
+    #   bob.permitted? 'food:bacon', 'fry' # false
+    #
+    #   # Note that if alice had her bacon frying permissions through her membership in the role 'user:bob',
+    #   # she'll lose them too:
+    #   api.role('user:alice').member_of? 'user:bob' # true
+    #   api.role('user:alice').permitted? 'food:bacon', 'fry' # => false
+    #
+    #
+    # @param [String, #roleid] member the member to revoke this role from
+    # @param [Hash] options included for backwards compatibility.  Don't use it.
+    # @return [void]
+    # @raise [RestClient::Forbidden] If you don't have permission to perform this operation
     def revoke_from(member, options = {})
       member = cast(member, :roleid)
       log do |logger|
@@ -89,6 +251,46 @@ module Conjur
       self["?members&member=#{query_escape member}"].delete(options)
     end
 
+    # Check to see if this role is allowed to perform `privilege` on `resource`.
+    #
+    # ### Permissions
+    # Any authenticated role may call this method.  However, instead of raising a 404 if a resource
+    # or role doesn't exist, it will return false.  This is to prevent bad guys from finding out which roles
+    # and resources exist.
+    #
+    # @example
+    #   bacon = api.create_resource 'food:bacon'
+    #   eggs  = api.create_resoure 'food:eggs'
+    #   bob = api.create_role 'cook:bob'
+    #
+    #   # Bob can't do anything initially
+    #   bob.permitted? bacon, 'fry' # => false
+    #   bob.permitted? eggs, 'poach' # => false
+    #
+    #   # Let him poach eggs
+    #   eggs.permit 'poach', bob
+    #
+    #   # Now it's permitted
+    #   bob.permitted? eggs, 'poach' # => true
+    #
+    # @example Somethign a bit more realistic
+    #   # Say we have a service layer that needs access to a database connection string.
+    #   # The layer is called 'web', and the connection string is stored in a variable 'mysql-uri'
+    #   web_layer = api.layer 'web'
+    #   mysql_uri = api.variable 'mysql-uri'
+    #
+    #   # The web layer can't see the value of the variable right now:
+    #   web_layer.role.permitted? mysql_uri, 'execute' # => false
+    #
+    #   # Let's permit that
+    #   mysql_uri.permit 'execute', web_layer
+    #
+    #   # Now it's allowed to fetch the connection string
+    #  web_layer.role.permitted? mysql_uri, 'execute' # => true
+    #
+    # @param [#resourceid, String] resource the resource to check the permission against
+    # @param [String] privilege the privilege to check
+    # @return [Boolean] true if this role has the privilege on the resource
     def permitted?(resource, privilege, options = {})
       resource = cast(resource, :resourceid)
       # NOTE: in previous versions there was 'kind' passed separately. Now it is part of id
@@ -98,10 +300,19 @@ module Conjur
       false
     end
     
-    def members options = {}
+
+    # Fetch the members of this role. The results are *not* recursively expanded (in contrast to {#memberships}).
+    #
+    # ### Permissions
+    # You must be a member of the role to call this method.
+    # 
+    # @param [Hash] options unused and included only for backwards compatibility 
+    # @return [Array<Conjur::RoleGrant>] the role memberships
+    # @raise [RestClient::Forbidden] if you don't have permission to perform this operation
+    def members
       JSON.parse(self["?members"].get(options)).collect do |json|
         RoleGrant.parse_from_json(json, self.options)
       end
     end
   end
-end
+end