conjur-api 4.13.0 → 4.14.0

data/lib/conjur/api/hosts.rb

@@ -21,8 +21,11 @@
 require 'conjur/host'
 
 module Conjur
+
   class API
     class << self
+      # @api private
+      # TODO WTF does this do!
       def enroll_host(url)
         if Conjur.log
           Conjur.log << "Enrolling host with URL #{url}\n"
@@ -36,13 +39,69 @@ module Conjur
         [ mime_type, body ]
       end
     end
-    
-    def create_host options = {}
+
+    #@!group Directory: Hosts
+
+    # Create a new `host` asset.
+    #
+    # By default this method will create a host with a random id.  However, you may create a host with a
+    # specific name by passing an `:id` option.
+    #
+    # ### Permissions
+    #
+    # * Any Conjur role may perform this method without an `:ownerid` option.  The new hosts owner will be the current role.
+    # * If you pass an ``:ownerid` option, you must be a member of the given role.
+    #
+    # @example
+    #   # Create a host with a random id
+    #   anon = api.create_host
+    #   anon.id # => "wyzg17"
+    #
+    #   # Create a host with a given id
+    #   foo = api.create_host id: 'foo'
+    #   foo.id # => "foo"
+    #
+    #   # Trying to create a new host named foo fails
+    #   foo2 = api.create_host id: 'foo' # raises RestClient::Conflict
+    #
+    #   # Create a host owned by user 'alice' (assuming we're authenticated as
+    #   # a role of which alice is a member).
+    #   alice_host = api.create_host id: "host-for-alice", ownerid: 'conjur:user:ailce'
+    #   alice_host.ownerid # => "conjur:user:alice"
+    #
+    # @param [Hash,nil] options options for the new host
+    # @option options [String] :id the id for the new host
+    # @option options [String] :ownerid set the new hosts owner to this role
+    # @return [Conjur::Host] the created host
+    # @raise RestClient::Conflict when id is given and a host with that id already exists.
+    # @raise RestClient::Forbidden when ownerid is given and the owner role does not exist, or you are not
+    #   a member of the owner role.
+    #
+    def create_host options = nil
       standard_create Conjur::Core::API.host, :host, nil, options
     end
-    
+
+    # Get a host by its *unqualified id*.
+    #
+    # Like other Conjur methods, this will return a {Conjur::Host} whether
+    # or not the record is found, and you must use the {Conjur::Exists#exists?} method
+    # to check this.
+    #
+    # @example
+    #   api.create_host id: 'foo'
+    #   foo = api.host "foo" # => returns a Conjur::Host
+    #   puts foo.resourceid # => "conjur:host:foo"
+    #   puts foo.id # => "foo"
+    #   mistake = api.host "doesnotexist" # => Also returns a Conjur::Host
+    #   foo.exists? # => true
+    #   mistake.exists? # => false
+    #
+    # @param [String] id the unqualified id of the host
+    # @return [Conjur::Host] an object representing the host, which may or may not exist.
     def host id
       standard_show Conjur::Core::API.host, :host, id
     end
+
+    #@!endgroup
   end
 end

data/lib/conjur/api/layers.rb

@@ -2,16 +2,61 @@ require 'conjur/layer'
 
 module Conjur
   class API
+    #@!group Directory: Layers
+
+    # Create a new layer with the given id
+    #
+    # @example
+    #   # create a new layer named 'webservers'
+    #   webservers = api.create_layer 'webservices'
+    #
+    #   # create layer is *not* idempotent
+    #   api.create_layer 'webservices' # raises RestClient::Conflict
+    #
+    #   # create a layer owned by user 'alice'
+    #   api.create_layer 'webservices', ownerid: 'alice'
+    #   api.owner # => 'conjur:user:alice'
+    #
+    # @param [String] id an *unqualified* id for the layer.
+    # @return [Conjur::Layer]
     def create_layer(id, options = {})
       standard_create Conjur::API.layer_asset_host, :layer, id, options
     end
-    
-    def layers(options = {})
+
+    # Get all layers visible to the current role.
+    #
+    # The `options` parameter is only included for backwards
+    # compatibility and has no effect. You should call this method
+    # without arguments.
+    #
+    # @param [Hash] options deprecated, unused
+    # @return [Array<Conjur::Layer>] all layers visible to the current role
+    def layers options={}
       standard_list Conjur::API.layer_asset_host, :layer, options
     end
-    
+
+
+    # Get a layer by its *unqualified id*.
+    #
+    # Like other Conjur methods, this will return a {Conjur::Layer} whether
+    # or not the record is found, and you must use the {Conjur::Exists#exists?} method
+    # to check this.
+    #
+    # @example
+    #   api.create_layer id: 'foo'
+    #   foo = api.layer "foo" # => returns a Conjur::Layer
+    #   puts foo.resourceid # => "conjur:layer:foo"
+    #   puts foo.id # => "foo"
+    #   mistake = api.layer "doesnotexist" # => Also returns a Conjur::Layer
+    #   foo.exists? # => true
+    #   mistake.exists? # => false
+    #
+    # @param [String] id the unqualified id of the layer
+    # @return [Conjur::Layer] an object representing the layer, which may or may not exist.
     def layer id
       standard_show Conjur::API.layer_asset_host, :layer, id
     end
+
+    #@!endgroup
   end
 end

data/lib/conjur/api/pubkeys.rb

@@ -20,33 +20,164 @@
 #
 
 module Conjur
-  class API
-    # Return all of a user's public keys, as a newline delimited string
-    # (the format expected by authorized-keys)
+
+   class API
+    # @!group Public Keys Service
+
+    # Fetch *all*  public keys for the user.  This method returns a newline delimited
+    # String for compatibility with the authorized_keys SSH format.
+    #
+    #
+    # If the given user does not exist, an empty String will be returned.  This is to prevent attackers from determining whether
+    # a user exists.
+    #
+    # ## Permissions
+    # You do not need any special permissions to call this method, since public keys are, well, public.
+    #
+    #
+    # @example
+    #   puts api.public_keys('jon')
+    #   # ssh-rsa [big long string] jon@albert
+    #   # ssh-rsa [big long string] jon@conjurops
+    #
+    # @param [String] username the *unqualified* Conjur username
+    # @return [String] newline delimited public keys
     def public_keys username
       public_keys_resource(username).get
     end
+
     
-    # Return a specific public key for a given user and key name
+    # Fetch a specific key by name.  The key name is the last token in the public key itself,
+    # typically formatted as `'<login>@<hostname>'`.
+    #
+    # ## Permissions
+    # You do not need any special permissions to call this method, since public keys are, well, public.
+    #
+    # @example Get bob's key for  'bob@somehost'
+    #   key = begin
+    #     api.public_key 'bob', 'bob@somehost'
+    #   rescue RestClient::ResourceNotFound
+    #     puts "Key or user not found!"
+    #     # Deal with it
+    #   end
+    #
+    #
+    # @param [String] username A Conjur username
+    # @param [String] keyname The name or identifier of the key
+    # @return [String] the public key
+    # @raise [RestClient::ResourceNotFound] if the user or key does not exist.
     def public_key username, keyname
       public_keys_resource(username, keyname).get
     end
-    
-    # Add a public key for the given user
+
+    # List the public key names for the given user.
+    #
+    # If the given user does not exist, an empty Array will be returned.  This is to prevent attackers from determining whether
+    # a user exists.
+    #
+    # ## Permissions
+    # You do not need any special permissions to call this method, since public keys are, well, public.
+    #
+    #
+    # @example List the names of public keys for 'otto'
+    #   api.public_key_names('otto').each{|n| puts n}
+    #   # otto@somehost
+    #   # admin@someotherhost
+    #
+    # @example A non existent user has no public keys
+    #   user = api.user('doesnotexist')
+    #   user.exists? # => false
+    #   user.public_key_names # => []
+    #
+    # @param [String] username the Conjur username
+    # @return [Array<String>] the names of the user's public keys
+     def public_key_names username
+      public_keys(username).lines.map{|s| s.split(' ')[-1]}
+    end
+
+    # Add an SSH public key for `username`.
+    #
+    # ## Key Format
+    #
+    # This method will raise an exception if `key` is not of the format
+    # `"<algorithm> <data> <name>"` (that is, key.split(\s+\)).length must be 3).  The `<name>` field is used by the service
+    # to identify individual keys for a user.
+    #
+    # ## Permissions
+    #
+    # You must have permission to `'update'` the pubkeys service resource.  When the Conjur appliance
+    # is configured, it creates the pubkeys service resource with this identifier
+    # `'<organizational account>:service:pubkeys-1.0/public-keys'`.
+    #
+    # Rather than granting permissions to this resource directly to user roles, we recommend that you add them to the
+    # 'key-managers' group, whose *unqualified identifier* is 'pubkeys-1.0/key-managers', which has permission to add public
+    # keys.
+    #
+    # ## Hiding Existence
+    #
+    # Because attackers could use this method to determine the existence of Conjur users, it will not
+    # raise an error if the user does not exist.
+    #
+    # @example add a user's public key
+    #   # Check that the user exists so that we can fail when he doesn't.  Otherwise, this method
+    #   # will silently fail.
+    #   raise "No such user!" unless api.user('bob').exists?
+    #
+    #   # Add a key from a file
+    #   key = File.read('/path/to/public/key.pub')
+    #   api.add_public_key('bob', key)
+    #
+    # @param [String] username the name of the Conjur
+    # @param [String] key an SSH formated public key
+    # @return void
+    # @raise RestClient::BadRequest when the key is not in the correct format.
     def add_public_key username, key
       public_keys_resource(username).post key
     end
-    
-    # Delete a public key for the given user and key name
+
+    # Delete a specific public key for a user.
+    #
+    # ## Permissions
+    # You must have permission to `'update'` the pubkeys service resource.  When the Conjur appliance
+    # is configured, it creates the pubkeys service resource with this identifier
+    # `'<organizational account>:service:pubkeys-1.0/public-keys'`.
+    #
+    # Rather than granting permissions to this resource directly to user roles, we recommend that you add them to the
+    # 'key-managers' group, whose *unqualified identifier* is 'pubkeys-1.0/key-managers', which has permission to add public
+    # keys.
+    #
+    # ## Hiding Existence
+    #
+    # Because attackers could use this method to determine the existence of Conjur users, it will not
+    # raise an error if the user does not exist.
+    #
+    # @example Delete all public keys for 'bob'
+    #
+    #   api.public_key_names('bob').count # => 6
+    #   api.public_key_names('bob').each do |keyname|
+    #     api.delete_public_key 'bob', keyname
+    #   end
+    #   api.public_key_names('bob').count # => 0
+    #
+    #
+    # @param [String] username the Conjur username/login
+    # @param [String] keyname the individual key to delete.
+    # @return [void]
     def delete_public_key username, keyname
       public_keys_resource(username, keyname).delete
     end
+
+    #@!endgroup
     
     protected
+    # @api private
+    # Returns a RestClient::Resource with the pubkeys host and the given path.
     def public_keys_resource *path
       RestClient::Resource.new(Conjur::API.pubkeys_asset_host, credentials)[public_keys_path *path]
     end
-    
+
+    # @api private
+    # This method simply escapes each segment in `args` and joins them around `/`.
     def public_keys_path *args
       args.map{|a| fully_escape(a)}.join('/')
     end

data/lib/conjur/api.rb

@@ -47,6 +47,18 @@ class RestClient::Resource
   include Conjur::LogSource
   include Conjur::Cast
   extend  Conjur::BuildFromResponse
+
+  alias_method :initialize_without_defaults, :initialize
+
+  def initialize url, options = nil, &block
+    initialize_without_defaults url, default_options.merge(options || {}), &block
+  end
+
+  def default_options
+    {
+      ssl_cert_store: OpenSSL::SSL::SSLContext::DEFAULT_CERT_STORE
+    }
+  end
   
   def core_conjur_account
     Conjur::Core::API.conjur_account
@@ -72,4 +84,4 @@ class RestClient::Resource
   def username
     options[:user] || options[:username]
   end
-end
+end

data/lib/conjur/base.rb

@@ -22,8 +22,6 @@ require 'rest-client'
 require 'json'
 require 'base64'
 
-require 'conjur/patches/rest-client'
-
 require 'conjur/exists'
 require 'conjur/has_attributes'
 require 'conjur/has_owner'
@@ -35,6 +33,33 @@ require 'conjur/standard_methods'
 require 'conjur/cast'
 
 module Conjur
+  # NOTE: You have to put all 'class level' api docs here, because YARD is stoopid :-(
+
+  # This class provides access to Conjur services
+  # **TODO MOAR**
+  #
+  # # Conjur Services
+  #
+  # ### Public Keys Service
+  # The {http://developer.conjur.net/reference/services/pubkeys Conjur Public Keys} service provides a
+  # simple database of public keys with access controlled by Conjur.  Reading a user's public keys requires
+  # no authentication at all -- the user's public keys are public information, after all.
+  #
+  # Adding or deleting a public key may only be done if you have permission to update the *public keys
+  # resource*, which is created when the appliance is launched, and has a resource id
+  # `'<organizational account>:service:pubkeys-1.0/public-keys'`.  The appliance also comes with a Group named
+  # `'pubkeys-1.0/key-managers'` that has this permission.  Rather than granting each user permission to
+  # modify the public keys database, you should consider adding users to this group.
+  #
+  # A very common use case is {http://developer.conjur.net/tutorials/ssh public key management for SSH}
+  #
+  #
+  # ### Audit Service
+  #
+  # The {http://developer.conjur.net/reference/services/audit Conjur Audit Service} allows you to
+  # fetch audit records.
+  #
+  # Generally you will need to have *at least one* privilege on the subject of an event in order to see it.
   class API
     include Escape
     include LogSource
@@ -42,6 +67,7 @@ module Conjur
     include Cast
 
     class << self
+      # @api private
       # Parse a role id into [ account, 'roles', kind, id ]
       def parse_role_id(id)
         id = id.role if id.respond_to?(:role)
@@ -54,6 +80,7 @@ module Conjur
         end
       end
 
+      # @api private
       # Parse a resource id into [ account, 'resources', kind, id ]
       def parse_resource_id(id)
         id = id.resource if id.respond_to?(:resource)
@@ -66,7 +93,8 @@ module Conjur
         end
       end
     
-      # Converts flat id into path components, with mixed-in "super-kind" 
+      # @api private
+      # Converts flat id into path components, with mixed-in "super-kind"
       #                                     (not that kind which is part of id)
       # NOTE: name is a bit confusing, as result of 'parse' is just recombined
       #       representation of parts, not an object of higher abstraction level
@@ -83,15 +111,72 @@ module Conjur
         [ paths[0], kind, paths[1], paths[2..-1].join(':') ]
       end
 
+
+      # Create a new {Conjur::API} instance from a username and a password or api key.
+      #
+      # @example Create an API with valid credentials
+      #   api = Conjur::API.new_from_key 'admin', '<admin password>'
+      #   api.current_role # => 'conjur:user:admin'
+      #   api.token['data'] # => 'admin'
+      #
+      # @example Authentication is lazy
+      #   api = Conjur::API.new_from_key 'admin', 'wrongpassword'   # succeeds
+      #   api.user 'foo' # raises a 401 error
+      #
+      # @param [String] username the username to use when making authenticated requests.
+      # @param [Sring] api_key the api key or password for `username`
+      # @return [Conjur::API] an api that will authenticate with the given username and api key.
       def new_from_key(username, api_key)
         self.new username, api_key, nil
       end
 
+
+      # Create a new {Conjur::API} instance from a token issued by the
+      # {http://developer.conjur.net/reference/services/authentication Conjur authentication service}
+      #
+      # Generally, you will have a Conjur identitiy (username and api key), and create an {Conjur::API} instance
+      # for the identity using {.new_from_key}.  This method is useful when you are performing authorization checks
+      # given a token.  For example, a Conjur gateway that requires you to prove that you can 'read' a resource named
+      # 'super-secret' might get the token from a request header, create an {Conjur::API} instance with this method,
+      # and use {Conjur::Resource#permitted?} to decide whether to accept and forward the request.
+      #
+      # Note that Conjur tokens are issued as JSON.  This method expects to get the token as a parsed JSON Hash.
+      # When sending tokens as headers, you will normally use base64 encoded strings.  Authorization headers
+      # used by Conjur have the form `'Token token="#{b64encode token.to_json}"'`, but this format is in no way
+      # required.
+      #
+      # @example A simple gatekeeper
+      #   RESOURCE_NAME = 'protected-service'
+      #
+      #   def handle_request request
+      #     token_header = request.header 'X-Conjur-Token'
+      #     token = JSON.parse Base64.b64decode(token_header)
+      #
+      #     api = Conjur::API.new_from_token token
+      #     raise Forbidden unless api.resource(RESOURCE_NAME).permitted? 'read'
+      #
+      #     proxy_to_service request
+      #   end
+      #
+      # @param [Hash] token the authentication token as parsed JSON to use when making authenticated requests
+      # @return [Conjur::API] an api that will authenticate with the token
       def new_from_token(token)
         self.new nil, nil, token
       end
     end
     
+    # Create a new instance from a username and api key or a token.
+    #
+    # @note You should use {Conjur::API.new_from_token} or {Conjur::API.new_from_key} instead of calling this method
+    #   directly.
+    #
+    # This method requires that you pass **either** a username and api_key **or** a token Hash.
+    #
+    # @param [String] username the username to authenticate as
+    # @param [String] api_key the api key or password to use when authenticating
+    # @param [Hash] token the token to use when making authenticated requuests.
+    #
+    # @api internal
     def initialize username, api_key, token
       @username = username
       @api_key = api_key
@@ -100,12 +185,14 @@ module Conjur
       raise "Expecting ( username and api_key ) or token" unless ( username && api_key ) || token
     end
     
-    attr_reader :api_key, :username
-    
+    attr_reader :api_key
+
+    #
     def username
       @username || @token['data']
     end
-    
+
+
     def host
       self.class.host
     end