Puppet Function: simplib::passgen::set

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

Overview

simplib::passgen::set(String[1] $identifier, String[1] $password, String[1] $salt, Hash $password_options, Optional[Hash] $simpkv_options) ⇒ Nil

Sets a generated password with attributes

  • Sets the password and salt, backs up the previous password and salt, and depending upon mode selected, persists other password information.

  • Supports 2 modes:

    • simpkv

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

        • simpkv key is the identifier.

        • simpkv value is a Hash with ‘password’ and ‘salt’ attributes

        • simpkv metadata is a Hash with ‘complexity’, ‘complex_only’ and ‘history’ attributes

          • ‘complexity’ and ‘complex_only’ attributes are stored so that the user can regenerate the password the same characteristics as the current password, as needed.

          • ‘history’ attribute stores up to 10 most recent <password,salt> pairs.

      • 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/`.

        • Password is stored in a file named for the identifier.

        • Salt is stored in a separate file named <identifier>.salt`.

      • Backs up most recent password and salt files

        • Backup files are named ‘<identifier>.last` and <identifier>.salt.last`.

      • Terminates catalog compilation if any password files cannot be created/modified by the user.

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

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.

  • password (String[1]) —

    Password value

  • salt (String[1]) —

    Salt for the password for use in encryption operations

  • password_options (Hash) —

    Password options to be used/persisted

  • simpkv_options (Optional[Hash]) —

    simpkv configuration when in simpkv mode.

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

Options Hash (password_options):

  • 'complexity' (Integer[0,2]) —

    Specifies the types of characters in the password

    * `0` => Only Alphanumeric characters
* `1` => Alphanumeric characters plus reasonably safe symbols
* `2` => Printable ASCII
* Required by simpkv mode
* Unused by legacy mode
  • 'complex_only' (Boolean) —

    Whether the password contains only the characters explicitly added by the complexity rules. For example, when ‘complexity` is `1`, the password contains only safe symbols.

    * Required by simpkv mode
* Unused by legacy mode
  • 'user' (String) —

    User for generated files/directories

    * Defaults to the user compiling the catalog.
* Only useful when running `puppet apply` as the `root` user.
* Optional for legacy mode
* Unused by simpkv mode
  • 'group' (String) —

    Group for generated files/directories

    * Defaults to the group compiling the catalog.
* Only useful when running `puppet apply` as the `root` user.
* Optional for legacy mode
* Unused by simpkv mode

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:

  • (Nil)

Raises:

  • Exception if required ‘password_options` missing, a simpkv operation fails, or any legacy password files cannot be be created/modified by the user.



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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/puppet/functions/simplib/passgen/set.rb', line 32

Puppet::Functions.create_function(:'simplib::passgen::set') 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 password
  #   Password value
  #
  # @param salt
  #   Salt for the password for use in encryption operations
  #
  # @param password_options
  #   Password options to be used/persisted
  #
  # @option password_options [Integer[0,2]] 'complexity'
  #   Specifies the types of characters in the password
  #     * `0` => Only Alphanumeric characters
  #     * `1` => Alphanumeric characters plus reasonably safe symbols
  #     * `2` => Printable ASCII
  #     * Required by simpkv mode
  #     * Unused by legacy mode
  #
  # @option password_options [Boolean] 'complex_only'
  #   Whether the password contains only the characters explicitly added by the
  #   complexity rules.  For example, when `complexity` is `1`, the password
  #   contains only safe symbols.
  #     * Required by simpkv mode
  #     * Unused by legacy mode
  #
  # @option password_options [String] 'user'
  #   User for generated files/directories
  #     * Defaults to the user compiling the catalog.
  #     * Only useful when running `puppet apply` as the `root` user.
  #     * Optional for legacy mode
  #     * Unused by simpkv mode
  #
  # @option password_options [String] 'group'
  #   Group for generated files/directories
  #     * Defaults to the group compiling the catalog.
  #     * Only useful when running `puppet apply` as the `root` user.
  #     * Optional for legacy mode
  #     * Unused by simpkv mode
  #
  # @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 [Nil]
  # @raise Exception if required `password_options` missing, a simpkv operation
  #   fails, or any legacy password files cannot be be created/modified by the
  #   user.
  #
  dispatch :set do
    required_param 'String[1]',    :identifier
    required_param 'String[1]',    :password
    required_param 'String[1]',    :salt
    required_param 'Hash',         :password_options
    optional_param 'Hash',         :simpkv_options
  end

  def set(identifier, password, salt, password_options,
      simpkv_options={'app_id' => 'simplib::passgen'})

    use_simpkv = call_function('lookup', 'simplib::passgen::simpkv',
      { 'default_value' => false })

    if use_simpkv
      unless password_options.key?('complexity')
        msg = "simplib::passgen::set: password_options must contain 'complexity' in simpkv mode"
        raise ArgumentError.new(msg)
      end

      unless password_options.key?('complex_only')
        msg = "simplib::passgen::set: password_options must contain 'complex_only' in simpkv mode"
        raise ArgumentError.new(msg)
      end

      call_function('simplib::passgen::simpkv::set', identifier, password, salt,
        password_options['complexity'], password_options['complex_only'],
        simpkv_options)
    else
      args = [ 'simplib::passgen::legacy::set', identifier, password, salt ]
      args << password_options['user'] if password_options.key?('user')
      args << password_options['group'] if password_options.key?('group')
      call_function(*args)
    end
  end
end