(MODULES-9578) Create authorized_key in root path

Previously, when the `target` property was set, the ssh_authorized_key
resource could not create directories/files within root-owned paths.
This behavior is due to the module switching context to the user, then
attempting to create the directory/file as the specified user,
ultimately failing because of insufficient permissions.

This commit adds a new parameter, `drop_privileges` which when set to
false allows the module to write a ssh_authorized_key file in a
privileged path. Due to the possible security implications of this,
the parameter must be manually specified in order to activate this
functionality.

A path is considered to be privileged/trusted if all of its ancestors:
- do not contain any symlinks
- have the same owner as the user who runs Puppet
- are not world/group writable

1 files changed, 10 insertions, 1 deletions

diff --git a/REFERENCE.md b/REFERENCE.md
index 6f80106..1e6b933 100644
--- a/REFERENCE.md
+++ b/REFERENCE.md
@@ -85,7 +85,8 @@ will autorequire this user if it is being managed as a `user` resource.
 The absolute filename in which to store the SSH key. This
 property is optional and should be used only in cases where keys
 are stored in a non-standard location, for instance when not in
-`~user/.ssh/authorized_keys`.
+`~user/.ssh/authorized_keys`. The parent directory must be present
+if the target is in a privileged path.
 
 Default value: absent
 
@@ -119,6 +120,14 @@ Due to internal limitations, this must be unique across all user accounts;
 if you want to specify one key for multiple users, you must use a different
 comment for each instance.
 
+##### `drop_privileges`
+
+Whether to drop privileges when writing the key file. This is
+useful for creating files in paths not writable by the target user. Note
+the possible security implications of managing file ownership and
+permissions as a privileged user.
+
+Default value: `true`
 
 ### sshkey