MuranoCLI 3.2.0.beta.9 → 3.2.1.pre.beta.3

data/lib/MrMurano/commands/devices.rb

@@ -9,35 +9,37 @@ require 'time'
 require 'MrMurano/Gateway'
 require 'MrMurano/ReCommander'
 
-command :device do |c|
-  c.syntax = %(murano device)
-  c.summary = %(Interact with a device)
-  c.description = %(
-Interact with a device.
+command :device do |cmd|
+  cmd.syntax = %(murano device)
+  cmd.summary = %(Interact with a device)
+  cmd.description = %(
+    Interact with a device.
   ).strip
-  c.project_not_required = true
-  c.subcmdgrouphelp = true
+  cmd.project_not_required = true
+  cmd.subcmdgrouphelp = true
 
-  c.action do |_args, _options|
+  cmd.action do |_args, _options|
     ::Commander::UI.enable_paging unless $cfg['tool.no-page']
-    say MrMurano::SubCmdGroupHelp.new(c).get_help
+    say MrMurano::SubCmdGroupHelp.new(cmd).get_help
   end
 end
 
-command 'device list' do |c|
-  c.syntax = %(murano device list [--options])
-  c.summary = %(List identifiers for a product)
-  c.description = %(
-List identifiers for a product.
+# ***
+
+command 'device list' do |cmd|
+  cmd.syntax = %(murano device list [--options])
+  cmd.summary = %(List identifiers for a product)
+  cmd.description = %(
+    List identifiers for a product.
   ).strip
 
-  c.option '--limit NUMBER', Integer, %(How many devices to return)
-  c.option '--before TIMESTAMP', Integer, %(Show devices before timestamp)
-  c.option '-l', '--long', %(show everything)
-  c.option '-o', '--output FILE', %(Download to file instead of STDOUT)
+  cmd.option '--limit NUMBER', Integer, %(How many devices to return)
+  cmd.option '--before TIMESTAMP', Integer, %(Show devices before timestamp)
+  cmd.option '-l', '--long', %(show everything)
+  cmd.option '-o', '--output FILE', %(Download to file instead of STDOUT)
 
-  c.action do |args, options|
-    c.verify_arg_count!(args)
+  cmd.action do |args, options|
+    cmd.verify_arg_count!(args)
     #options.default limit: 1000
 
     prd = MrMurano::Gateway::Device.new
@@ -91,19 +93,21 @@ List identifiers for a product.
 end
 alias_command 'devices list', 'device list'
 
-command 'device read' do |c|
-  c.syntax = %(murano device read <identifier> [<alias>...] [--options])
-  c.summary = %(Read state of a device)
-  c.description = %(
+# ***
+
+command 'device read' do |cmd|
+  cmd.syntax = %(murano device read <identifier> [<alias>...] [--options])
+  cmd.summary = %(Read state of a device)
+  cmd.description = %(
 Read state of a device.
 
 This reads the latest state values for the resources in a device.
   ).strip
 
-  c.option '-o', '--output FILE', %(Download to file instead of STDOUT)
+  cmd.option '-o', '--output FILE', %(Download to file instead of STDOUT)
 
-  c.action do |args, options|
-    c.verify_arg_count!(args, nil, ['Missing device identifier'])
+  cmd.action do |args, options|
+    cmd.verify_arg_count!(args, nil, ['Missing device identifier'])
 
     prd = MrMurano::Gateway::Device.new
 
@@ -134,17 +138,19 @@ This reads the latest state values for the resources in a device.
   end
 end
 
-command 'device write' do |c|
-  c.syntax = %(murano device write <identifier> <Alias=Value> [<Alias=Value>...])
-  c.summary = %(Write to 'set' of aliases on devices)
-  c.description = %(
+# ***
+
+command 'device write' do |cmd|
+  cmd.syntax = %(murano device write <identifier> <Alias=Value> [<Alias=Value>...])
+  cmd.summary = %(Write to 'set' of aliases on devices)
+  cmd.description = %(
 Write to 'set' of aliases on devices.
 
 If an alias is not settable, this will fail.
   ).strip
 
-  c.action do |args, _options|
-    c.verify_arg_count!(args, nil, ['Missing device identifier'])
+  cmd.action do |args, _options|
+    cmd.verify_arg_count!(args, nil, ['Missing device identifier'])
 
     resources = (MrMurano::Gateway::GweBase.new.info || {})[:resources]
 
@@ -175,117 +181,248 @@ If an alias is not settable, this will fail.
   end
 end
 
-command 'device enable' do |c|
-  c.syntax = %(murano device enable (<identifier>|--file <path>) [--options])
-  c.summary = %(Enable Identifiers in Murano for real world devices)
-  c.description = %(
-Enables Identifiers, creating devices, or digital shadows, in Murano.
-  ).strip
+# ***
 
-  c.option '-e', '--expire HOURS', %(Devices that do not activate within HOURS hours will be deleted for security purposes)
-  c.option '-f', '--file FILE', %(A file of serial numbers, one per line)
-  c.option '--key FILE', %(Path to file containing public TLS key for this device)
-  allowed_types = MrMurano::Gateway::Device::DEVICE_AUTH_TYPES.map(&:to_s).sort
-  c.option '--auth TYPE', %(Type of credential used to authenticate [#{allowed_types.join('|')}])
-  c.option '--cred KEY', %(The credential used to authenticate, e.g., token, password, etc.)
+class DeviceEnableCmd
+  include MrMurano::Verbose
 
-  c.action do |args, options|
-    c.verify_arg_count!(args, 1)
+  def command_init(cmd)
+    configure_command_meta(cmd)
+    configure_command_options(cmd)
+    configure_command_action(cmd)
+  end
 
-    prd = MrMurano::Gateway::Device.new
+  def configure_command_meta(cmd)
+    cmd.syntax = %(murano device enable (<identifier>|--file <path>) [--options])
+    cmd.summary = %(Enable Identifiers in Murano for real world devices)
+    cmd.description = %(
+      Enable one or more Identities to create Devices, a/k/a digital twins, in Murano.
+    ).strip
+    cmd.example %(
+      Use a certificate request to enable a new device identity
+    # and obtain a TLS Client Certificate for the device to use
+    # to communicate with Murano.
+    #
+    # SETUP: Use the web UI to configure your Product's Public Key
+    #        Infrastructure.
+    #
+    #   Navigate to the Product Settings page, e.g.,
+    #
+    #     http://localhost:4000/business/<business.id>/connectivity/<product.id>/settings
+    #
+    #   Select "Enable PKI", and fill in the fields.†
+    #
+    #     [†: The process of signing up with a certificate provider,
+    #      obtaining an API key, and gererating a Client CA certificate
+    #      is beyond the scope of this help documentation.]
+    #
+    # USAGE: You may now enable a device identify and receive a certificate.
+    #
+    # First, generate a certificate request.
+    #
+    # The following is an example of how one might use openssl to make a CSR:
+    #
+    #   openssl genrsa -out rootCA.key 2048
+    #
+    #   openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem
+    #   # 1. Be sure to set the Organization Name as the same name used to the
+    #   #    Client CA Certificate.
+    #   # 2. Set the Common Name to the name of the device identity you want to enable.
+    #
+    #   openssl req -x509 -nodes -days 365 -sha256 \\
+    #     -subj /C=/ST=/L=/O=<ORGANIZATION_NAME>/CN=<COMMON_NAME> \\
+    #     -newkey rsa:2048 -keyout deviceIdent-key.pem
+    #   # Be sure to set ORGANIZATION_NAME and COMMON_NAME appropriately.
+    #
+    #   openssl req -new -key deviceIdent-key.pem -out deviceIdent.csr \\
+    #     -subj "/C=/ST=/L=/O=<ORGANIZATION_NAME>/CN=<COMMON_NAME>"
+    #   # Be sure to set ORGANIZATION_NAME and COMMON_NAME appropriately.
+    #
+    # Next, enable the device and copy the certificate.
+    ).lstrip, 'device_cert=$(murano device enable 12345 --expire 1 --auth csr --csr path/to/deviceIdent.csr)'
+  end
 
+  def configure_command_options(cmd)
+    cmd.option '-e', '--expire HOURS', %(
+      Devices that do not activate within HOURS hours will be deleted for security purposes
+    ).strip
+    cmd.option '-f', '--file FILE', %(A file of serial numbers, one per line)
+    allowed_types = MrMurano::Gateway::Device::DEVICE_AUTH_TYPES.map(&:to_s).sort
+    cmd.option '--auth TYPE', %(
+      Type of credential used to authenticate [#{allowed_types.join('|')}]
+    ).strip
+    cmd.option '--cred KEY', %(
+      The credential used to authenticate, e.g., token, password, etc.
+    ).strip
+    cmd.option '--key FILE', %(Path to file containing public TLS key for this device)
+    # (lb): --csr is identical to --key, but it's included because semantics.
+    cmd.option '--csr FILE', %(Path to CSR file containing certificate request)
+  end
+
+  def configure_command_action(cmd)
+    cmd.action do |args, options|
+      cmd.verify_arg_count!(args, 1)
+      must_specify_device_id_or_file!(args, options)
+      must_specify_auth_or_cred_maybe!(options)
+      must_specify_sane_expire!(options)
+      must_specify_valid_auth!(options)
+      enable_device(args, options)
+    end
+  end
+
+  def must_specify_device_id_or_file!(args, options)
     if args.count.zero? && options.file.to_s.empty?
-      prd.error 'Missing device identifier or --file'
+      error 'Missing device identifier or --file'
       exit 1
     elsif !args.count.zero? && !options.file.to_s.empty?
-      prd.error 'Please specify an identifier or --file but not both'
+      error 'Please specify an identifier or --file but not both'
       exit 1
     end
+  end
 
-    if !options.file.nil? && (!options.key.nil? || !options.auth.nil? || !options.cred.nil?)
-      prd.error %(Cannot use --file with any of: --key, --auth, or --cred)
+  def must_specify_auth_or_cred_maybe!(options)
+    if (
+      !options.file.nil? &&
+      (!options.key.nil? || !options.auth.nil? || !options.cred.nil?)
+    )
+      error %(Cannot use --file with any of: --key, --auth, or --cred)
       exit 1
     end
-    if !options.key.nil? && !options.cred.nil?
-      prd.error %(Please use either --cred or --key but not both)
+    credish_opts = [options.cred, options.key, options.csr]
+    n_credish_opts = credish_opts.count { |opt| !opt.nil? }
+    if n_credish_opts > 1
+      error %(Please use only one of: --cred, --key, or --csr)
       exit 1
     end
-    if options.auth.nil? ^ options.cred.nil?
-      prd.error %(Please specify both --auth and --cred or neither)
+    if options.auth && n_credish_opts.zero?
+      error %(When using --auth, please specify one of: --cred, -key, or --csr)
       exit 1
     end
     options.auth = options.auth.to_sym unless options.auth.nil?
-    unless options.key.nil?
-      if !options.auth.nil? && options.auth != :certificate
-        prd.warning %(You probably mean to use "--auth certificate" with --key)
-      else
-        options.auth = :certificate
-      end
+    return if options.key.nil?
+    if !options.auth.nil? && !%i[certificate csr].include?(options.auth)
+      warning %(You probably mean to use "--auth certificate" with --key)
     end
+    return if options.csr.nil? || options.auth == :csr
+    warning %(The --csr option is only relevant when used with "--auth csr")
+  end
 
-    unless options.expire.nil?
-      unless options.expire =~ /^[0-9]+$/
-        prd.error %(The --expire value is not a number of hours: #{prd.fancy_ticks(options.expire)})
-        exit 1
-      end
-      # The platform expects the expiration time to be an integer
-      # representing microseconds since the epoch, e.g.,
-      #    hours * mins/hour * secs/min * msec/sec * μsec/msec
-      # or hours * 60        * 60       * 1000     * 1000
-      micros_since_epoch = (Time.now.to_f * 1_000_000).to_i
-      mircos_until_purge = options.expire.to_i * 60 * 60 * 1000 * 1000
-      options.expire = micros_since_epoch + mircos_until_purge
+  def must_specify_sane_expire!(options)
+    return if options.expire.nil?
+    unless options.expire =~ /^[0-9]+$/
+      fancy_expire = fancy_ticks(options.expire)
+      error %(
+        The --expire value is not a number of hours: #{fancy_expire}
+      ).strip
+      exit 1
     end
+    # The platform expects the expiration time to be an integer
+    # representing microseconds since the epoch, e.g.,
+    #    hours * mins/hour * secs/min * msec/sec * μsec/msec
+    # or hours * 60        * 60       * 1000     * 1000
+    micros_since_epoch = (Time.now.to_f * 1_000_000).to_i
+    mircos_until_purge = options.expire.to_i * 60 * 60 * 1000 * 1000
+    options.expire = micros_since_epoch + mircos_until_purge
+  end
 
-    unless options.auth.nil?
-      options.auth = options.auth.to_sym
-      unless MrMurano::Gateway::Device::DEVICE_AUTH_TYPES.include?(options.auth)
-        MrMurano::Verbose.error("unrecognized --auth: #{options.auth}")
-        exit 1
-      end
-    end
+  def must_specify_valid_auth!(options)
+    return if options.auth.nil?
+    options.auth = options.auth.to_sym
+    return if MrMurano::Gateway::Device::DEVICE_AUTH_TYPES.include?(options.auth)
+    MrMurano::Verbose.error("unrecognized --auth: #{options.auth}")
+    exit 1
+  end
 
+  def enable_device(args, options)
+    prd = MrMurano::Gateway::Device.new
     if !options.file.to_s.empty?
-      # Check file for headers.
-      begin
-        header = File.new(options.file).gets
-      rescue Errno::ENOENT => err
-        prd.error %(Unable to open file #{prd.fancy_ticks(options.file)}: #{err.message})
-        exit 2
-      end
-      if header.nil?
-        prd.error 'Nothing in file!'
-        exit 1
-      end
-      unless header =~ /\s*ID\s*(,SSL Client Certificate\s*)?/
-        prd.error %(Missing column headers in file "#{options.file}")
-        prd.error %(First line in file should be either "ID" or "ID, SSL Client Certificate")
-        exit 2
-      end
-      prd.enable_batch(options.file, options.expire)
+      enable_device_batch(prd, options)
     elsif args.count > 0
-      opts = {}
-      opts[:expire] = options.expire unless options.expire.nil?
-      opts[:type] = options.auth unless options.auth.nil?
-      if options.key
-        File.open(options.key, 'rb') do |io|
-          prd.enable(args[0], **opts, key: io)
-        end
-      else
-        opts[:key] = options.cred unless options.cred.nil?
-        prd.enable(args[0], **opts)
-      end
+      result = enable_device_single(prd, args[0], options)
+      process_enable_single_result(result, options)
     else
       # Impossible path: neither args nor --file; would've exited by now.
       raise 'Impossible'
     end
   end
+
+  def enable_device_batch(prd, options)
+    header = header_from_file!(options)
+    must_validate_header!(header, options)
+    prd.enable_batch(options.file, options.expire)
+  end
+
+  def header_from_file!(options)
+    # Check file for headers.
+    File.new(options.file).gets
+  rescue Errno::ENOENT => err
+    fancy_file = fancy_ticks(options.file)
+    error %(Unable to open file #{fancy_file}: #{err.message})
+    exit 2
+  end
+
+  def must_validate_header!(header, options)
+    if header.nil?
+      error 'Nothing in file!'
+      exit 1
+    end
+    return if header =~ /\s*ID\s*(,SSL Client Certificate\s*)?/
+    error %(Missing column headers in file "#{options.file}")
+    error %(
+      First line in file should be either "ID" or "ID, SSL Client Certificate"
+    ).strip
+    exit 2
+  end
+
+  def enable_device_single(prd, device_id, options)
+    enable_opts = {}
+    enable_opts[:expire] = options.expire unless options.expire.nil?
+    enable_opts[:type] = options.auth unless options.auth.nil?
+    enable_device_slurp_key(options, enable_opts)
+    prd.enable(device_id, **enable_opts)
+  end
+
+  def enable_device_slurp_key(options, enable_opts)
+    if options.key
+      enable_device_slurp_key_read_file(options.key, enable_opts)
+    elsif options.csr
+      enable_device_slurp_key_read_file(options.csr, enable_opts)
+    elsif !options.cred.nil?
+      enable_opts[:key] = options.cred
+    end
+  end
+
+  def enable_device_slurp_key_read_file(key_file_path, enable_opts)
+    File.open(key_file_path, 'rb') do |io|
+      enable_opts[:key] = io.read
+    end
+  end
+
+  def process_enable_single_result(result, options)
+    return unless options.auth == :csr
+    if result.to_s.empty?
+      warning %(Unexpected: Response missing new device identity certificate)
+    elsif !result.is_a?(Hash) || !result.key?(:certificate)
+      warning %(Unexpected: Unrecognized result format: #{result})
+    else
+      puts result[:certificate]
+    end
+  end
 end
 
-command 'device activate' do |c|
-  c.syntax = %(murano device activate <identifier>)
-  c.summary = %(Activate a serial number, retrieving its CIK)
-  c.description = %(
+def wire_cmd_device_enable
+  device_enable_cmd = DeviceEnableCmd.new
+  command('device enable') { |cmd| device_enable_cmd.command_init(cmd) }
+end
+
+wire_cmd_device_enable
+
+# ***
+
+command 'device activate' do |cmd|
+  cmd.syntax = %(murano device activate <identifier>)
+  cmd.summary = %(Activate a serial number, retrieving its CIK)
+  cmd.description = %(
 Activate an Identifier.
 
 Generally you should not use this.
@@ -300,22 +437,24 @@ Note that you can only activate a device once. After that
 you cannot retrive the CIK again.
   ).strip
 
-  c.action do |args, _options|
-    c.verify_arg_count!(args, nil, ['Missing device identifier'])
+  cmd.action do |args, _options|
+    cmd.verify_arg_count!(args, nil, ['Missing device identifier'])
     prd = MrMurano::Gateway::Device.new
     prd.outf prd.activate(args.first)
   end
 end
 
-command 'device delete' do |c|
-  c.syntax = %(murano device delete <identifier>)
-  c.summary = %(Delete a device)
-  c.description = %(
-Delete a device.
+# ***
+
+command 'device delete' do |cmd|
+  cmd.syntax = %(murano device delete <identifier>)
+  cmd.summary = %(Delete a device)
+  cmd.description = %(
+    Delete a device.
   ).strip
 
-  c.action do |args, _options|
-    c.verify_arg_count!(args, nil, ['Missing device identifier'])
+  cmd.action do |args, _options|
+    cmd.verify_arg_count!(args, nil, ['Missing device identifier'])
     prd = MrMurano::Gateway::Device.new
     snid = args.shift
     ret = prd.remove(snid)
@@ -323,60 +462,68 @@ Delete a device.
   end
 end
 
-command 'device httpurl' do |c|
-  c.syntax = %(murano device httpurl)
-  c.summary = %(Get the URL for the HTTP-Data-API for this Project)
-  c.description = %(
-Get the URL for the HTTP-Data-API for this Project.
+# ***
+
+command 'device httpurl' do |cmd|
+  cmd.syntax = %(murano device httpurl)
+  cmd.summary = %(Get the URL for the HTTP-Data-API for this Project)
+  cmd.description = %(
+    Get the URL for the HTTP-Data-API for this Project.
   ).strip
 
-  c.action do |args, _options|
-    c.verify_arg_count!(args)
+  cmd.action do |args, _options|
+    cmd.verify_arg_count!(args)
     prd = MrMurano::Gateway::GweBase.new
     ret = prd.info
     say "https://#{ret[:fqdn]}/onep:v1/stack/alias"
   end
 end
 
-command 'device lock' do |c|
-  c.syntax = %(murano device lock <identifier>)
-  c.summary = %(Lock a device, not allowing connections to it until unlocked)
-  c.description = %(
-Lock a device, not allowing connections to it until unlocked.
+# ***
+
+command 'device lock' do |cmd|
+  cmd.syntax = %(murano device lock <identifier>)
+  cmd.summary = %(Lock a device, not allowing connections to it until unlocked)
+  cmd.description = %(
+    Lock a device, not allowing connections to it until unlocked.
   ).strip
 
-  c.action do |args, _options|
-    c.verify_arg_count!(args, 1, ['Missing device identifier'])
+  cmd.action do |args, _options|
+    cmd.verify_arg_count!(args, 1, ['Missing device identifier'])
     prd = MrMurano::Gateway::Device.new
     prd.lock(args[0])
   end
 end
 
-command 'device unlock' do |c|
-  c.syntax = %(murano device unlock <identifier>)
-  c.summary = %(Unlock a device, allowing connections to it again)
-  c.description = %(
-Unlock a device, allowing connections to it again.
+# ***
+
+command 'device unlock' do |cmd|
+  cmd.syntax = %(murano device unlock <identifier>)
+  cmd.summary = %(Unlock a device, allowing connections to it again)
+  cmd.description = %(
+    Unlock a device, allowing connections to it again.
   ).strip
 
-  c.action do |args, _options|
-    c.verify_arg_count!(args, 1, ['Missing device identifier'])
+  cmd.action do |args, _options|
+    cmd.verify_arg_count!(args, 1, ['Missing device identifier'])
     prd = MrMurano::Gateway::Device.new
     prd.unlock(args[0])
   end
 end
 
-command 'device revoke' do |c|
-  c.syntax = %(murano device revoke <identifier>)
-  c.summary = %(Force device to reprovision)
-  c.description = %(
+# ***
+
+command 'device revoke' do |cmd|
+  cmd.syntax = %(murano device revoke <identifier>)
+  cmd.summary = %(Force device to reprovision)
+  cmd.description = %(
 Force device to reprovision.
 
 This will revoke the device's keys and cause it to temporarily disconnect. The will then reconnect and be provisioned with new keys.
   ).strip
 
-  c.action do |args, _options|
-    c.verify_arg_count!(args, 1, ['Missing device identifier'])
+  cmd.action do |args, _options|
+    cmd.verify_arg_count!(args, 1, ['Missing device identifier'])
     prd = MrMurano::Gateway::Device.new
     # MAYBE/2017-08-23: This command doesn't return an error if the device
     # ID was not found, or if the keys were already revoked. Do we care?
@@ -385,6 +532,8 @@ This will revoke the device's keys and cause it to temporarily disconnect. The w
   end
 end
 
+# ***
+
 alias_command 'product device', 'device'
 alias_command 'product device list', 'device list'
 alias_command 'product devices list', 'device list'