Heavily document the necessity of using `Sensitive` when using the new Deferred function

[sgnn7]

Is your feature request related to a problem? Please describe.

Per https://github.com/cyberark/conjur-puppet/issues/192 findings, skipping Sensitive wrapping of the resultant value returned from conjur::secret works but it may lead to credential disclosure. Because of this, we have to heavily document that use of Sensitive to wrap the function is a requirement.

Describe the solution you would like

AC

• [ ] Need for the invocations to use Sensitive around conjur::secret is prominently documented in the README

Describe alternatives you have considered

N/A

Additional context

N/A

[sgnn7]

We may also need to include some user-provided info on this:

• Requirement that the defering of template rendering is require if var is used in a template
• Change from a String to a Sensitive in the response from conjur::secret

[frankmundt]

When using Sensitive with the deferred function one must be careful. The deferred secret needs to be wrapped with Sensitive when used in a Puppet class:

$test_variable = Sensitive(Deferred(conjur::secret, ['some/secret'])) file { '/tmp/testing.txt': ensure => file, content => $test_variable.unwrap, }

However - when passing a Sensitive Deferred value to a template - the retrieval of the secret must be deferred as well. Attempting to use the $test_variable from above results in the template receiving a doubly wrapped Sensitive variable.

file { '/tmp/text.txt': ensure => file, content => Deferred('inline_epp', ['test_value=<%= $test_value.unwrap %> testing_variable=<%= $test_variable.unwrap.unwrap %>', { 'test_value' => Deferred(conjur::secret, ['some/secret']), 'test_variable' => $test_variable, }]), }

[sgnn7]

Released via v3.0.0 on Puppet Forge.

@frankmundt: Take a look at our expanded/updated docs on this release - we've revised some of the usage guidelines to remove the need for a double unwrap in most cases.