Puppet Function: simplib::passgen::get

Defined in:
lib/puppet/functions/simplib/passgen/get.rb
Function type:
Ruby 4.x API

Overview

simplib::passgen::get(String[1] $identifier, Optional[Hash] $simpkv_options) ⇒ Hash

Retrieves a generated password and any stored attributes

  • Supports 2 modes:

    • simpkv

      • Password info is stored in a key/value store and retrieved using simpkv.

      • Terminates catalog compilation if any simpkv operation fails.

    • Legacy

      • Password info is stored in files on the local file system at ‘Puppet.settings/simp/environments/$environment/simp_autofiles/gen_passwd/`.

      • Terminates catalog compilation if the password storage directory cannot be accessed by the user.

  • To enable the simpkv mode, set ‘simplib::passgen::simpkv` to `true` in hieradata. When that setting absent or false, legacy mode will be used.

  • Terminates compilation if a simpkv operation fails or a legacy password file is inaccessible by the user.

Parameters:

  • identifier (String[1]) —

    Unique ‘String` to identify the password usage. Must conform to the following:

    • Identifier must contain only the following characters:

      • a-z

      • A-Z

      • 0-9

      • The following special characters:

        • ‘._:-` for the legacy implementation

        • ‘._:-/` for the simpkv-enabled implementation

    • Identifier may not contain ‘/./’ or ‘/../’ sequences.

  • simpkv_options (Optional[Hash]) —

    simpkv configuration when in simpkv mode.

    * Will be merged with `simpkv::options`.
* All keys are optional.

Options Hash (simpkv_options):

  • 'app_id' (String) —

    Specifies an application name that can be used to identify which backend configuration to use via fuzzy name matching, in the absence of the ‘backend` option.

    * More flexible option than `backend`.
* Useful for grouping together simpkv function calls found in different
  catalog resources.
* When specified and the `backend` option is absent, the backend will be
  selected preferring a backend in the merged `backends` option whose
  name exactly matches the `app_id`, followed by the longest backend
  name that matches the beginning of the `app_id`, followed by the
  `default` backend.
* When absent and the `backend` option is also absent, this function
  will use the `default` backend.
  • 'backend' (String) —

    Definitive name of the backend to use.

    * Takes precedence over `app_id`.
* When present, must match a key in the `backends` option of the
  merged options Hash or the function will fail.
* When absent in the merged options, this function will select
  the backend as described in the `app_id` option.
  • 'backends' (Hash) —

    Hash of backend configurations

    * Each backend configuration in the merged options Hash must be
  a Hash that has the following keys:

  * `type`:  Backend type.
  * `id`:  Unique name for the instance of the backend. (Same backend
    type can be configured differently).

 * Other keys for configuration specific to the backend may also be
   present.
  • 'environment' (String) —

    Puppet environment to prepend to keys.

    * When set to a non-empty string, it is prepended to the key used in
  the backend operation.
* Should only be set to an empty string when the key being accessed is
  truly global.
* Defaults to the Puppet environment for the node.
  • 'softfail' (Boolean) —

    Whether to ignore simpkv operation failures.

    * When `true`, this function will return a result even when the
  operation failed at the backend.
* When `false`, this function will fail when the backend operation
  failed.
* Defaults to `false`.

Returns:

  • (Hash) —

    Password information or {} if the password does not exist

    • ‘value’- Hash containing ‘password’ and ‘salt’ attributes

    • ‘metadata’ - Hash containing a ‘history’ attribute, and when available, ‘complexity’ and ‘complex_only’ attributes.

      * 'history' is an Array of up to the last 10 <password,salt> pairs.
  history[0][0] is the most recent password and history[0][1] is its
  salt.

Raises:

  • Exception if a simpkv operation fails or a legacy password file is inaccessible by the user



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/puppet/functions/simplib/passgen/get.rb', line 17

Puppet::Functions.create_function(:'simplib::passgen::get') do

  # @param identifier Unique `String` to identify the password usage.
  #   Must conform to the following:
  #   * Identifier must contain only the following characters:
  #     * a-z
  #     * A-Z
  #     * 0-9
  #     * The following special characters:
  #       * `._:-` for the legacy implementation
  #       * `._:-/` for the simpkv-enabled implementation
  #   * Identifier may not contain '/./' or '/../' sequences.
  #
  # @param simpkv_options
  #   simpkv configuration when in simpkv mode.
  #
  #     * Will be merged with `simpkv::options`.
  #     * All keys are optional.
  #
  # @option simpkv_options [String] 'app_id'
  #   Specifies an application name that can be used to identify which backend
  #   configuration to use via fuzzy name matching, in the absence of the
  #   `backend` option.
  #
  #     * More flexible option than `backend`.
  #     * Useful for grouping together simpkv function calls found in different
  #       catalog resources.
  #     * When specified and the `backend` option is absent, the backend will be
  #       selected preferring a backend in the merged `backends` option whose
  #       name exactly matches the `app_id`, followed by the longest backend
  #       name that matches the beginning of the `app_id`, followed by the
  #       `default` backend.
  #     * When absent and the `backend` option is also absent, this function
  #       will use the `default` backend.
  #
  # @option simpkv_options [String] 'backend'
  #   Definitive name of the backend to use.
  #
  #     * Takes precedence over `app_id`.
  #     * When present, must match a key in the `backends` option of the
  #       merged options Hash or the function will fail.
  #     * When absent in the merged options, this function will select
  #       the backend as described in the `app_id` option.
  #
  # @option simpkv_options [Hash] 'backends'
  #   Hash of backend configurations
  #
  #     * Each backend configuration in the merged options Hash must be
  #       a Hash that has the following keys:
  #
  #       * `type`:  Backend type.
  #       * `id`:  Unique name for the instance of the backend. (Same backend
  #         type can be configured differently).
  #
  #      * Other keys for configuration specific to the backend may also be
  #        present.
  #
  # @option simpkv_options [String] 'environment'
  #   Puppet environment to prepend to keys.
  #
  #     * When set to a non-empty string, it is prepended to the key used in
  #       the backend operation.
  #     * Should only be set to an empty string when the key being accessed is
  #       truly global.
  #     * Defaults to the Puppet environment for the node.
  #
  # @option simpkv_options [Boolean] 'softfail'
  #   Whether to ignore simpkv operation failures.
  #
  #     * When `true`, this function will return a result even when the
  #       operation failed at the backend.
  #     * When `false`, this function will fail when the backend operation
  #       failed.
  #     * Defaults to `false`.
  #
  #
  # @return [Hash] Password information or {} if the password does not exist
  #
  #   * 'value'- Hash containing 'password' and 'salt' attributes
  #   * 'metadata' - Hash containing a 'history' attribute, and when available,
  #     'complexity' and 'complex_only' attributes.
  #      * 'history' is an Array of up to the last 10 <password,salt> pairs.
  #        history[0][0] is the most recent password and history[0][1] is its
  #        salt.
  #
  # @raise Exception if a simpkv operation fails or a legacy password file is
  #   inaccessible by the user
  #
  dispatch :get do
    required_param 'String[1]', :identifier
    optional_param 'Hash',      :simpkv_options
  end

  def get(identifier, simpkv_options={'app_id' => 'simplib::passgen'})
    use_simpkv = call_function('lookup', 'simplib::passgen::simpkv',
      { 'default_value' => false })

    password_info = nil
    if use_simpkv
      password_info = call_function('simplib::passgen::simpkv::get', identifier,
        simpkv_options)
    else
      password_info = call_function('simplib::passgen::legacy::get', identifier)
    end
    password_info
  end
end