Add description, validation_message, and introduced fields into openssl resourcesopenssl_fix

This follows the pattern used on docs.chef.io right now. We may change
it later, but this will get us autogenerated docs for now.

Signed-off-by: Tim Smith <tsmith@chef.io>

3 files changed, 99 insertions, 37 deletions

diff --git a/lib/chef/resource/openssl_dhparam.rb b/lib/chef/resource/openssl_dhparam.rb
index 693061f535..9bf349b485 100644
--- a/lib/chef/resource/openssl_dhparam.rb
+++ b/lib/chef/resource/openssl_dhparam.rb
@@ -19,26 +19,47 @@ require "chef/resource"
 
 class Chef
   class Resource
-    # a resource for generating dhparam.pem files.
-    # If a valid dhparam.pem file is found at the specified location, no new
-    # file will be created. If a file is found at the specified location but it
-    # is not a valid dhparam file, it will be overwritten.
-    #
-    # @since 14.0
     class OpensslDhparam < Chef::Resource
       require "chef/mixin/openssl_helper"
       include Chef::Mixin::OpenSSLHelper
 
       resource_name :openssl_dhparam
 
-      property :path,        String, name_property: true
-      property :key_length,  equal_to: [1024, 2048, 4096, 8192], default: 2048
-      property :generator,   equal_to: [2, 5], default: 2
-      property :owner,       [String, nil]
-      property :group,       [String, nil]
-      property :mode,        [Integer, String], default: "0640"
+      description "Use the openssl_dhparam resource to generate dhparam.pem files. If a"\
+                  " valid dhparam.pem file is found at the specified location, no new file"\
+                  " will be created. If a file is found at the specified location but it is"\
+                  " not a valid dhparam file, it will be overwritten."
+      introduced "14.0"
+
+      property :path, String,
+               description: "The path to write the file to if it's different than the resource name.",
+               name_property: true
+
+      property :key_length, Integer,
+               equal_to: [1024, 2048, 4096, 8192],
+               validation_message: "key_length must be 1024, 2048, 4096, or 8192.",
+               description: "The desired bit length of the generated key.",
+               default: 2048
+
+      property :generator, Integer,
+               equal_to: [2, 5],
+               validation_message: "generator must be either 2 or 5.",
+               description: "The desired Diffie-Hellmann generator.",
+               default: 2
+
+      property :owner, [String, nil],
+               description: "The owner of all files created by the resource."
+
+      property :group, [String, nil],
+               description: "The group of all files created by the resource."
+
+      property :mode, [Integer, String],
+               description: "The permission mode of all files created by the resource.",
+               default: "0640"
 
       action :create do
+        description "Create the dhparam file"
+
         unless dhparam_pem_valid?(new_resource.path)
           converge_by("Create a dhparam file #{new_resource.path}") do
             dhparam_content = gen_dhparam(new_resource.key_length, new_resource.generator).to_pem
diff --git a/lib/chef/resource/openssl_rsa_private_key.rb b/lib/chef/resource/openssl_rsa_private_key.rb
index 4b0bae2fd0..729d5a585a 100644
--- a/lib/chef/resource/openssl_rsa_private_key.rb
+++ b/lib/chef/resource/openssl_rsa_private_key.rb
@@ -19,13 +19,6 @@ require "chef/resource"
 
 class Chef
   class Resource
-    # A resource for generating rsa private key files.
-    # If a valid rsa key file can be opened at the specified location, no new file
-    # will be created. If the RSA key file cannot be opened, either because it
-    # does not exist or because the password to the RSA key file does not match
-    # the password in the recipe, it will be overwritten.
-    #
-    # @since 14.0
     class OpensslRsaPrivateKey < Chef::Resource
       require "chef/mixin/openssl_helper"
       include Chef::Mixin::OpenSSLHelper
@@ -34,14 +27,45 @@ class Chef
       provides :openssl_rsa_private_key
       provides :openssl_rsa_key # legacy cookbook resource name
 
-      property :path,        String, name_property: true
-      property :key_length,  equal_to: [1024, 2048, 4096, 8192], default: 2048
-      property :key_pass,    String
-      property :key_cipher,  String, default: "des3", equal_to: OpenSSL::Cipher.ciphers
-      property :owner,       [String, nil]
-      property :group,       [String, nil]
-      property :mode,        [Integer, String], default: "0600"
-      property :force,       [true, false], default: false
+      introduced "14.0"
+      description "Use the openssl_rsa_private_key resource to generate RSA private key files."\
+                  " If a valid RSA key file can be opened at the specified location, no new file"\
+                  " will be created. If the RSA key file cannot be opened, either because it does"\
+                  " not exist or because the password to the RSA key file does not match the"\
+                  " password in the recipe, it will be overwritten."
+
+      property :path, String,
+               description: "The path to write the file to it's different than the resource name.",
+               name_property: true
+
+      property :key_length, Integer,
+               equal_to: [1024, 2048, 4096, 8192],
+               validation_message: "key_length must be 1024, 2048, 4096, or 8192.",
+               description: "The desired bit length of the generated key.",
+               default: 2048
+
+      property :key_pass, String,
+               description: "The desired passphrase for the key."
+
+      property :key_cipher, String,
+               equal_to: OpenSSL::Cipher.ciphers,
+               validation_message: "key_cipher must be a cipher known to openssl. Run `openssl list-cipher-algorithms` to see available options.",
+               description: "The designed cipher to use when generating your key. Run `openssl list-cipher-algorithms` to see available options.",
+               default: "des3"
+
+      property :owner, [String, nil],
+               description: "The owner of all files created by the resource."
+
+      property :group, [String, nil],
+               description: "The group of all files created by the resource."
+
+      property :mode, [Integer, String],
+               description: "The permission mode of all files created by the resource.",
+               default: "0600"
+
+      property :force, [true, false],
+               description: "Force creating the key even if the existing key exists.",
+               default: false
 
       action :create do
         return if new_resource.force || priv_key_file_valid?(new_resource.path, new_resource.key_pass)
diff --git a/lib/chef/resource/openssl_rsa_public_key.rb b/lib/chef/resource/openssl_rsa_public_key.rb
index 5ab7206938..a07c5f4d2f 100644
--- a/lib/chef/resource/openssl_rsa_public_key.rb
+++ b/lib/chef/resource/openssl_rsa_public_key.rb
@@ -19,24 +19,41 @@ require "chef/resource"
 
 class Chef
   class Resource
-    # A resource for generating rsa public key files given a rsa private key.
-    #
-    # @since 14.0
     class OpensslRsaPublicKey < Chef::Resource
       require "chef/mixin/openssl_helper"
       include Chef::Mixin::OpenSSLHelper
 
       resource_name :openssl_rsa_public_key
 
-      property :path,                String, name_property: true
-      property :private_key_path,    String
-      property :private_key_content, String
-      property :private_key_pass,    String
-      property :owner,               [String, nil]
-      property :group,               [String, nil]
-      property :mode,                [Integer, String], default: "0640"
+      description "Use the openssl_rsa_public_key resource to generate RSA public key files given a RSA private key"
+      introduced "14.0"
+
+      property :path, String,
+               description: "The path to write the file to if different than the resource's name.",
+               name_property: true
+
+      property :private_key_path, String,
+               description: "The path to the private key."
+
+      property :private_key_content, String,
+               description: "The content of the private key including new lines. Used instead of private_key_path to avoid having to first write a key to disk."
+
+      property :private_key_pass, String,
+               description: "The passphrase of the provided private key."
+
+      property :owner, [String, nil],
+               description: "The owner of all files created by the resource."
+
+      property :group, [String, nil],
+               description: "The group of all files created by the resource."
+
+      property :mode, [Integer, String],
+               description: "The permission mode of all files created by the resource.",
+               default: "0640"
 
       action :create do
+        description "Create the RSA public key."
+
         raise ArgumentError, "You cannot specify both 'private_key_path' and 'private_key_content' properties at the same time." if new_resource.private_key_path && new_resource.private_key_content
         raise ArgumentError, "You must specify the private key with either 'private_key_path' or 'private_key_content' properties." unless new_resource.private_key_path || new_resource.private_key_content
         raise "#{new_resource.private_key_path} not a valid private RSA key or password is invalid" unless priv_key_file_valid?((new_resource.private_key_path || new_resource.private_key_content), new_resource.private_key_pass)