ruby_aem 2.1.0 → 2.2.0

data/lib/ruby_aem/handlers/json.rb

@@ -41,10 +41,12 @@ module RubyAem
     end
 
     # Handle package JSON payload. Result status is determined directly by success field.
+    # NOTE: _response_spec and _call_params are not used in the implementation
+    # of this method, but they are needed for the handler signature.
     #
     # @param response HTTP response containing status_code, body, and headers
-    # @param response_spec response specification as configured in conf/spec.yaml
-    # @param call_params additional call_params information
+    # @param _response_spec response specification as configured in conf/spec.yaml
+    # @param _call_params additional call_params information
     # @return RubyAem::Result
     def self.json_package_service(response, _response_spec, _call_params)
       json = JSON.parse(response.body)
@@ -113,5 +115,103 @@ module RubyAem
       result.data = agent_names
       result
     end
+
+    # Truststore payload handler, checks for the existence of certificate within
+    # AEM Truststore, identified by cert_alias call parameter.
+    #
+    # @param response HTTP response containing status_code, body, and headers
+    # @param response_spec response specification as configured in conf/spec.yaml
+    # @param call_params API call parameters
+    # @return RubyAem::Result
+    def self.json_certificate_exists(response, response_spec, call_params)
+      truststore_info = response.body
+
+      result = Handlers.simple(response, response_spec, call_params)
+
+      certificate_exists = false
+      truststore_info.aliases.each { |certificate_alias|
+        certificate_exists = true if certificate_alias.serial_number.to_s == call_params[:serial_number].to_s
+      }
+      if certificate_exists == false
+        result.data = false
+        result.message = 'Certificate not found'
+      else
+        result.data = true
+        result.message = 'Certificate exists'
+      end
+
+      result
+    end
+
+    # Authorizable keystore payload handler, checks for the existence of certificate within
+    # AEM Truststore, identified by cert_alias call parameter.
+    #
+    # @param response HTTP response containing status_code, body, and headers
+    # @param response_spec response specification as configured in conf/spec.yaml
+    # @param call_params API call parameters
+    # @return RubyAem::Result
+    def self.json_certificate_chain_exists(response, response_spec, call_params)
+      authorizable_keystore_info = response.body
+
+      result = Handlers.simple(response, response_spec, call_params)
+
+      certificate_chain_exists = false
+      authorizable_keystore_info.aliases.each { |certificate_chain_alias|
+        certificate_chain_exists = true if certificate_chain_alias._alias.to_s == call_params[:private_key_alias].to_s
+      }
+      if certificate_chain_exists == false
+        result.data = false
+        result.message = 'Certificate chain not found'
+      else
+        result.data = true
+        result.message = 'Certificate chain exists'
+      end
+
+      result
+    end
+
+    # Truststore payload handler, checks for exists and aliases properties in
+    # order to identify existence.
+    #
+    # @param response HTTP response containing status_code, body, and headers
+    # @param response_spec response specification as configured in conf/spec.yaml
+    # @param call_params API call parameters
+    # @return RubyAem::Result
+    def self.json_truststore_exists(response, response_spec, call_params)
+      truststore_info = response.body
+
+      result = Handlers.simple(response, response_spec, call_params)
+
+      if truststore_info.exists == false
+        result.data = false
+        result.message = 'Truststore not found'
+      elsif truststore_info.aliases.is_a?(Array)
+        result.data = true
+      end
+
+      result
+    end
+
+    # Authorizable keystore payload handler, checks for exists and aliases
+    # properties in order to identify existence.
+    #
+    # @param response HTTP response containing status_code, body, and headers
+    # @param response_spec response specification as configured in conf/spec.yaml
+    # @param call_params API call parameters
+    # @return RubyAem::Result
+    def self.json_authorizable_keystore_exists(response, response_spec, call_params)
+      keystore_info = response.body
+
+      result = Handlers.simple(response, response_spec, call_params)
+
+      if keystore_info.exists == false
+        result.data = false
+        result.message = 'Authorizable keystore not found'
+      elsif keystore_info.aliases.is_a?(Array)
+        result.data = true
+      end
+
+      result
+    end
   end
 end

data/lib/ruby_aem/handlers/simple.rb

@@ -76,5 +76,17 @@ module RubyAem
       result = Handlers.simple(response, response_spec, call_params)
       raise RubyAem::Error.new(result.message, result)
     end
+
+    # Simple handler with response body as result data.
+    #
+    # @param response HTTP response containing status_code, body, and headers
+    # @param response_spec response specification as configured in conf/spec.yaml
+    # @param call_params API call parameters
+    # @return RubyAem::Result
+    def self.simple_body(response, response_spec, call_params)
+      result = Handlers.simple(response, response_spec, call_params)
+      result.data = response.body
+      result
+    end
   end
 end

data/lib/ruby_aem/resources/aem.rb

@@ -50,8 +50,10 @@ module RubyAem
       # https://github.com/shinesolutions/aem-healthcheck
       # to be installed.
       #
-      # @param tags comma separated tags
-      # @param combine_tags_or
+      # @param opts optional parameters:
+      # - tags: comma separated tags of AEM Health Check tags
+      # - combine_tags_or: if true, the check needs to only pass one of the check tags in order to get the health check pass,
+      #   if false, all check tags need to pass in order to get the health check pass.
       # @return RubyAem::Result
       def get_aem_health_check(opts = {})
         @call_params = @call_params.merge(opts)

data/lib/ruby_aem/resources/authorizable_keystore.rb

@@ -0,0 +1,102 @@
+# Copyright 2016-2017 Shine Solutions
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'openssl'
+require 'retries'
+require 'tempfile'
+require 'ruby_aem/error'
+
+module RubyAem
+  module Resources
+    # AEM class contains API calls related to managing the AEM Authorizable Keystore.
+    class AuthorizableKeystore
+      # Initialise an Authorizable Keystore
+      #
+      # @param client RubyAem::Client
+      # @param intermediate_path AEM User home path
+      # @param authorizable_id AEM User id
+      # @return new RubyAem::Resources::AuhtorizableKeystore instance
+      def initialize(client, intermediate_path, authorizable_id)
+        @client = client
+        @call_params = {
+          intermediate_path: intermediate_path,
+          authorizable_id: authorizable_id
+        }
+      end
+
+      # Create AEM Authorizable Keystore.
+      #
+      # @param password Password for the keystore
+      # @return RubyAem::Result
+      def create(password)
+        @call_params[:password] = password
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      # Change the password of an AEM Authorizable Keystore
+      #
+      # @param old_password Current password for the authorizable keystore
+      # @param new_password New password for the authorizable keystore
+
+      # @return RubyAem::Result
+      def change_password(old_password, new_password)
+        @call_params[:old_password] = old_password
+        @call_params[:new_password] = new_password
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      # Read an authorizable keystore in PKCS#12 Format
+      #
+      # @param file_path local file path to Keystore PKCS12 file
+      # @param password Password of the Keystore PKCS12 File
+      # @return OpenSSL::PKCS12
+      def read(file_path, password)
+        authorizable_keystore_raw = File.read file_path
+        OpenSSL::PKCS12.new(authorizable_keystore_raw, password)
+      end
+
+      # Download the AEM Keystore to a specified directory.
+      #
+      # @param file_path the directory where the Keystore will be downloaded to
+      # @return RubyAem::Result
+      def download(
+        file_path
+      )
+        @call_params[:file_path] = file_path
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      # Delete AEM Authorizable Keystore
+      #
+      # @return RubyAem::Result
+      def delete
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      # Check if a keystore for the given authorizable id already exists.
+      #
+      # @return RubyAem::Result
+      def exists
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      # Retrieve AEM Authorizable Keystore info.
+      #
+      # @return RubyAem::Result
+      def info
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+    end
+  end
+end

data/lib/ruby_aem/resources/certificate.rb

@@ -0,0 +1,153 @@
+# Copyright 2016-2018 Shine Solutions
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'openssl'
+require 'retries'
+require 'tempfile'
+require 'ruby_aem/error'
+require 'ruby_aem/resources/truststore'
+
+module RubyAem
+  module Resources
+    # AEM class contains API calls related to managing a certificate within AEM Truststore.
+    # Since there is only 0 or 1 AEM Truststore with a global scope, a certificate
+    # is by default associated to that global AEM Truststore.
+    class Certificate
+      # Initialise certificate.
+      # Certificate resource uses serial number as identifier because AEM API endpoint
+      # for importing a certificate does not allow the ability to specify an alias,
+      # hence alias is assigned randomly by AEM, and this force us to use serial
+      # number as the identifier because serial number is immutable on the certificate.
+      # This is obviously not ideal, but we have to do it due to AEM API limitations.
+      #
+      # @param client RubyAem::Client
+      # @param serial_number the certificate's serial number
+      # @return new RubyAem::Resources::Certificate instance
+      def initialize(
+        client,
+        serial_number
+      )
+        @client = client
+        @truststore = RubyAem::Resources::Truststore.new(client)
+        @serial_number = serial_number
+        @call_params = {
+          serial_number: serial_number
+        }
+        @cert_alias = _get_alias
+      end
+
+      # Create is an alias to import.
+      # Create is needed to satisfy Puppet resource `ensure`.
+      #
+      # @param file_path local file path to certificate file
+      # @return RubyAem::Result
+      def create(file_path)
+        import(file_path)
+      end
+
+      # Import a certificate file into AEM Truststore.
+      #
+      # @param file_path local file path to certificate file
+      # @return RubyAem::Result
+      def import(file_path)
+        @call_params[:file_path] = file_path
+        result = @client.call(self.class, __callee__.to_s, @call_params)
+        @cert_alias = _get_alias
+        result
+      end
+
+      # Export a certificate file from AEM Truststore.
+      #
+      # @param truststore_password Password for AEM Truststore
+      # @return RubyAem::Result
+      def export(truststore_password)
+        temp_file = Tempfile.new.path
+        @truststore.download(temp_file)
+
+        truststore_raw = File.read temp_file
+        truststore = OpenSSL::PKCS12.new(truststore_raw, truststore_password)
+
+        certificate = nil
+        truststore.ca_certs.each { |ca_cert|
+          certificate = ca_cert if ca_cert.serial.to_s == @serial_number.to_s
+        }
+        result = RubyAem::Result.new('Certificate exported', nil)
+        result.data = certificate
+        result
+      end
+
+      # Delete a specific certificate from AEM Truststore by alias name or serial number.
+      #
+      # @return RubyAem::Result
+      def delete
+        result = exists
+        raise RubyAem::Error.new('Certificate not found', result) if result.data == false
+        @call_params[:cert_alias] = @cert_alias
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      # Check if the certificate exists in AEM truststore.
+      #
+      # @return RubyAem::Result
+      def exists
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      def _get_alias
+        truststore_info = @truststore.info.data
+        cert_alias = nil
+        truststore_info.aliases.each { |certificate_alias|
+          cert_alias = certificate_alias._alias.to_s if certificate_alias.serial_number.to_s == @serial_number.to_s
+        }
+        cert_alias
+      end
+
+      # Import a certificate file into AEM Truststore and wait until the certificate is imported.
+      #
+      # @param file_path local file path to certificate file
+      # @param opts optional parameters:
+      # - _retries: retries library's options (http://www.rubydoc.info/gems/retries/0.0.5#Usage), restricted to max_tries, base_sleep_seconds, max_sleep_seconds
+      # @return RubyAem::Result
+      def import_wait_until_ready(
+        file_path,
+        opts = {
+          _retries: {
+            max_tries: 30,
+            base_sleep_seconds: 2,
+            max_sleep_seconds: 2
+          }
+        }
+      )
+        opts[:_retries] ||= {}
+        opts[:_retries][:max_tries] ||= 30
+        opts[:_retries][:base_sleep_seconds] ||= 2
+        opts[:_retries][:max_sleep_seconds] ||= 2
+
+        # ensure integer retries setting (Puppet 3 passes numeric string)
+        opts[:_retries][:max_tries] = opts[:_retries][:max_tries].to_i
+        opts[:_retries][:base_sleep_seconds] = opts[:_retries][:base_sleep_seconds].to_i
+        opts[:_retries][:max_sleep_seconds] = opts[:_retries][:max_sleep_seconds].to_i
+
+        result = import(file_path)
+
+        with_retries(max_tries: opts[:_retries][:max_tries], base_sleep_seconds: opts[:_retries][:base_sleep_seconds], max_sleep_seconds: opts[:_retries][:max_sleep_seconds]) { |retries_count|
+          check_result = exists
+          puts format('Import check #%<retries_count>d: %<check_result_data>s - %<check_result_message>s', retries_count: retries_count, check_result_data: check_result.data, check_result_message: check_result.message)
+          raise StandardError.new(check_result.message) if check_result.data == false
+        }
+        result
+      end
+    end
+  end
+end

data/lib/ruby_aem/resources/certificate_chain.rb

@@ -0,0 +1,119 @@
+# Copyright 2016-2018 Shine Solutions
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'openssl'
+require 'retries'
+require 'tempfile'
+require 'ruby_aem/error'
+require 'ruby_aem/resources/authorizable_keystore'
+
+module RubyAem
+  module Resources
+    # AEM class contains API calls related to managing a certificate chain within AEM Authorizable Keystore.
+    class CertificateChain
+      # Initialise certificate chain
+      #
+      # @param client RubyAem::Client
+      # @param private_key_alias Alias of the private key associated to this certificate chain
+      # @param keystore_intermediate_path AEM User home path
+      # @param keystore_authorizable_id AEM User id
+      # @return new RubyAem::Resources::AuhtorizableKeystore instance
+      def initialize(client, private_key_alias, keystore_intermediate_path, keystore_authorizable_id)
+        @client = client
+        @truststore = RubyAem::Resources::Truststore.new(client)
+        @private_key_alias = private_key_alias
+        @call_params = {
+          private_key_alias: private_key_alias,
+          keystore_intermediate_path: keystore_intermediate_path,
+          keystore_authorizable_id: keystore_authorizable_id
+        }
+      end
+
+      # Create is an alias to import.
+      # Create is needed to satisfy Puppet resource `ensure`.
+      #
+      # @param certificate_chain_file_path file path to certificate chain file
+      # @param private_key_file_path file path to private key associated to the certificate chain
+      # @return RubyAem::Result
+      def create(certificate_chain_file_path, private_key_file_path)
+        import(certificate_chain_file_path, private_key_file_path)
+      end
+
+      # Import a certificate file into AEM Truststore.
+      #
+      # @param certificate_chain_file_path file path to certificate chain file
+      # @param private_key_file_path file path to private key associated to the certificate chain
+      # @return RubyAem::Result
+      def import(certificate_chain_file_path, private_key_file_path)
+        @call_params[:file_path_certificate] = certificate_chain_file_path
+        @call_params[:file_path_private_key] = private_key_file_path
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      # Delete a specific certificate chain by its associated private key alias.
+      #
+      # @return RubyAem::Result
+      def delete
+        result = exists
+        raise RubyAem::Error.new('Certificate chain not found', result) if result.data == false
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      # Check if certificate chain exists in the Authorizable Keystore.
+      #
+      # @return RubyAem::Result
+      def exists
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      # Import a certificate file into AEM Truststore and wait until the certificate is imported.
+      #
+      # @param certificate_chain_file_path file path to certificate chain file
+      # @param private_key_file_path file path to private key associated to the certificate chain
+      # @param opts optional parameters:
+      # - _retries: retries library's options (http://www.rubydoc.info/gems/retries/0.0.5#Usage), restricted to max_tries, base_sleep_seconds, max_sleep_seconds
+      # @return RubyAem::Result
+      def import_wait_until_ready(
+        certificate_chain_file_path,
+        private_key_file_path,
+        opts = {
+          _retries: {
+            max_tries: 30,
+            base_sleep_seconds: 2,
+            max_sleep_seconds: 2
+          }
+        }
+      )
+        opts[:_retries] ||= {}
+        opts[:_retries][:max_tries] ||= 30
+        opts[:_retries][:base_sleep_seconds] ||= 2
+        opts[:_retries][:max_sleep_seconds] ||= 2
+
+        # ensure integer retries setting (Puppet 3 passes numeric string)
+        opts[:_retries][:max_tries] = opts[:_retries][:max_tries].to_i
+        opts[:_retries][:base_sleep_seconds] = opts[:_retries][:base_sleep_seconds].to_i
+        opts[:_retries][:max_sleep_seconds] = opts[:_retries][:max_sleep_seconds].to_i
+
+        result = import(certificate_chain_file_path, private_key_file_path)
+
+        with_retries(max_tries: opts[:_retries][:max_tries], base_sleep_seconds: opts[:_retries][:base_sleep_seconds], max_sleep_seconds: opts[:_retries][:max_sleep_seconds]) { |retries_count|
+          check_result = exists
+          puts format('Import check #%<retries_count>d: %<check_result_data>s - %<check_result_message>s', retries_count: retries_count, check_result_data: check_result.data, check_result_message: check_result.message)
+          raise StandardError.new(check_result.message) if check_result.data == false
+        }
+        result
+      end
+    end
+  end
+end

data/lib/ruby_aem/resources/config_property.rb

@@ -35,14 +35,12 @@ module RubyAem
 
       # Create a new config property.
       #
-      # @param run_mode AEM run mode: author or publish
-      # @param @param config_node_name the node name of a given OSGI config
+      # @param config_node_name the node name of a given OSGI config
       # @return RubyAem::Result
-      def create(run_mode, config_node_name)
+      def create(config_node_name)
         name = RubyAem::Swagger.property_to_parameter(@call_params[:name])
         type_hint_prefix = name.gsub(/^_/, '')
 
-        @call_params[:run_mode] = run_mode
         @call_params[:config_node_name] = config_node_name
         @call_params[name.to_sym] = @call_params[:value]
         @call_params["#{type_hint_prefix}_type_hint".to_sym] = @call_params[:type]

data/lib/ruby_aem/resources/package.rb

@@ -46,7 +46,7 @@ module RubyAem
       # Update the package with specific filter.
       #
       # @param filter package filter JSON string
-      # example: [{"root":"/apps/geometrixx","rules":[]},{"root":"/apps/geometrixx-common","rules":[]}]
+      #   example: [{ "root": "/apps/geometrixx", "rules": [] }, { "root": "/apps/geometrixx-common", "rules": []}]
       # @return RubyAem::Result
       def update(filter)
         @call_params[:filter] = filter

data/lib/ruby_aem/resources/path.rb

@@ -42,7 +42,6 @@ module RubyAem
 
       # Delete a path.
       #
-      # @param path Define the path which contains the node to delete
       # @return RubyAem::Result
       def delete
         # The path parameter will be combined with the name parameter

data/lib/ruby_aem/resources/saml.rb

@@ -0,0 +1,62 @@
+# Copyright 2016-2017 Shine Solutions
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'ruby_aem/error'
+
+module RubyAem
+  module Resources
+    # AEM class contains API calls related to managing SAML.
+    class Saml
+      # Initialise Saml.
+      #
+      # @param client RubyAem::Client
+      # @return new RubyAem::Resources::Saml instance
+      def initialize(client)
+        @client = client
+        @call_params = {}
+      end
+
+      # Create SAML configuration
+      #
+      # @param opts optional parameters, parameter names can be retrieved from
+      #   AEM OSGI config page for `com.adobe.granite.auth.saml.SamlAuthenticationHandler.config`
+      #   Alternatively, they can also be retrieved from Swagger AEM specification
+      #   at https://github.com/shinesolutions/swagger-aem/blob/master/conf/api.yml
+      #   on operation ID `postConfigAdobeGraniteSamlAuthenticationHandler`
+      #   Some parameters explanation can be found on https://helpx.adobe.com/experience-manager/6-3/sites/administering/using/saml-2-0-authenticationhandler.html
+      # @return RubyAem::Result
+      def create(opts)
+        @call_params = @call_params.merge(opts)
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      # Delete SAML configuration
+      #
+      # @return RubyAem::Result
+      def delete
+        @call_params[:apply] = true
+        @call_params[:delete] = true
+
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+
+      # Get SAML configuration
+      #
+      # @return RubyAem::Result
+      def get
+        @client.call(self.class, __callee__.to_s, @call_params)
+      end
+    end
+  end
+end