Class: SafeDb::KeyIdent

Inherits:
Object
  • Object
show all
Defined in:
lib/keytools/key.ident.rb

Overview

This class knows how to derive information from the machine environment to aide in producing identifiers unique to the machine and/or workstation, with functionality similar to that required by licensing software.

Identity is Similar to Licensing Software | Except Deeper

Deriving the identity string follows similar principles to licensing software that attempts to determine whether the operating environment is the same or different. But it goes deeper than licensing software as it is not only concerned about the same workstation - it is also concerned about the same shell or command line interface.

Known Issues

The dependent macaddr gem is known to fail in scenarios where a VPN tunnel is active and a tell tale sign is the ifconfig command returning the tun0 interface rather than “eth0” or something that resembles “ensp21”.

This is one of the error messages resulting from such a case.

macaddr.rb:86 from_getifaddrs undefined method pfamily (NoMethodError)

Class Method Summary collapse

Class Method Details

.derive_machine_identifier ⇒ String

This method uses a one-way function to return a combinatorial digested machine identification string using a number of distinct input parameters to deliver the characteristic of producing the same identifier for the same machine, virtual machine, workstation and/or compute element, and reciprocally, a different one on a different machine.

The userspace is also a key machine identifier so a different machine user generates a different identifier when all other things remain equal.

Returns:

  • (String) —

    a one line textual machine workstation or compute element identifier that is (surprisingly) different when the machine user changes.



155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/keytools/key.ident.rb', line 155

def self.derive_machine_identifier

  require 'socket'

  identity_text = [
    Etc.getlogin,
    get_machine_id(),
    Socket.gethostname()
  ].join.reverse

  return identity_text

end

.derive_shell_identifier(use_grandparent_pid = false) ⇒ String

This method returns a plaintext string hat is guaranteed to be the same whenever called within the same shell for the same user on the same workstation, virtual machine, container or SSH session and different whenever a new shell is acquired.

What is really important is that the shell identity string changes when

  • the command shell changes

  • the user switches to another workstation user

  • the workstation or machine host is changed

  • the user SSH’s into another shell

Unchanged | When Should it Remain Unchanged?

Remaining unchanged is a feature that is as important and this must be so when and/or after

  • the user returns to a command shell

  • the user switches back to using a domain

  • the user exits their remote SSH session

  • sudo is used to execute the commands

  • the user comes back to their workstation

  • the clock ticks into another day, month, year …

Parameters:

  • use_grandparent_pid (Boolean) (defaults to: false) —

    Optional boolean parameter. If set to true the PID (process ID) used as part of an obfuscator key and normally acquired from the parent process should now be acquired from the grandparent’s process.

    Set to true when accessing the safe’s credentials from a sub process rather than directly through the logged in shell.

Returns:

  • (String) —

    Return a one line textual shell identity string.

    As key derivation algorithms enforcing a maximum length may be length may be applied, each character must add value so non-alphanumerics (mostly hyphens) are cleansed out before returning.



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/keytools/key.ident.rb', line 70

def self.derive_shell_identifier( use_grandparent_pid = false )

  require 'socket'

  # -- Ensure that the most significant data points
  # -- come first just like with numbers.

  identity_text =
  [
    get_ancestor_pid( use_grandparent_pid ),
    get_bootup_id(),
    Etc.getlogin(),
    Socket.gethostname()
  ].join

  return identity_text.to_alphanumeric

end

.get_ancestor_pid(use_grandparent_pid) ⇒ String

Return an ancestor process ID meaning return either the parent process ID or the grandparent process ID. The one returned depends on the paremeter boolean value.

Command Used to find the grandparent process ID.

$ ps -fp 31870 | awk "/tty/"' { print $3 } '
$ ps -fp 31870 | awk "/31870/"' { print $3 } '

The one liner finds the parental process ID of the process with the given parameter process ID.

$ ps -fp 31870

UID        PID  PPID  C STIME TTY          TIME CMD
joe      31870  2618  0 12:55 tty2     00:01:03 /usr/bin/emacs25

The ps command outputs two (2) lines and awk is employed to select the line containing the already known ID. We then print the 3rd string in the line which we expect to be the parent PID of the PID.

Warning | Do Not Use $PPID

Using $PPID is fools gold because the PS command itself runs as another process so $PPID is this (calling) process ID and the number returned is exactly the same as the parent ID of this process - which is actually the grandparent of the invoked ps process.

Parameters:

  • use_grandparent_pid (Boolean) —

    Set to true if the grandparent process ID is required and false if only the parent process ID should be returned.

Returns:

  • (String) —

    Return ancestor process ID that belongs to either the parent process or the grandparent process.



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/keytools/key.ident.rb', line 125

def self.get_ancestor_pid( use_grandparent_pid )

  parental_process_id = Process.ppid.to_s()
  grandparent_pid_cmd = "ps -fp #{parental_process_id} | awk \"/#{parental_process_id}/\"' { print $3 } '"
  raw_grandparent_pid = %x[#{grandparent_pid_cmd}]
  the_grandparent_pid = raw_grandparent_pid.chomp

  log.debug(x) { "QQQQQ ~> QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ" }
  log.debug(x) { "QQQQQ ~> Request Bool Use GPPID is ~> [[ #{use_grandparent_pid} ]]" }
  log.debug(x) { "QQQQQ ~> Main Parent Process ID is ~> [[ #{parental_process_id} ]]" }
  log.debug(x) { "QQQQQ ~> GrandParent Process ID is ~> [[ #{the_grandparent_pid} ]]" }
  log.debug(x) { "QQQQQ ~> QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ" }

  return ( use_grandparent_pid ? the_grandparent_pid : parental_process_id )

end

.get_bootup_id ⇒ String

If you need to know whether a Linux computer has been rebooted or you need an identifier that stays the same until the computer reboots, look no further than the read only (non sudoer accessible) **boot id**.

In the modern era of virtualization you should always check the behaviour of the above identifiers when used inside

  • docker containers

  • Amazon EC2 servers (or Azure or GCE)

  • vagrant (VirtualBox/VMWare)

  • Windows MSGYWIN (Ubuntu) environments

  • Kubernetes pods

Returns:

  • (String) —

    the bootup ID hash value



184
185
186
187
188
189
190
 
# File 'lib/keytools/key.ident.rb', line 184

def self.get_bootup_id

  bootup_id_cmd = "cat /proc/sys/kernel/random/boot_id"
  bootup_id_str = %x[ #{bootup_id_cmd} ]
  return bootup_id_str.chomp

end

.get_machine_id ⇒ String

The machine identifier is a UUID based hash value that is tied to the CPU and motherboard of the machine. This read-only identifier can be accessed without sudoer permissions so is perfect for license generators and environment sensitive software.

In the modern era of virtualization you should always check the behaviour of the above identifiers when used inside

  • docker containers

  • Amazon EC2 servers (or Azure or GCE)

  • vagrant (VirtualBox/VMWare)

  • Windows MSGYWIN (Ubuntu) environments

  • Kubernetes pods

Returns:

  • (String) —

    the machine ID hash value



208
209
210
211
212
213
214
 
# File 'lib/keytools/key.ident.rb', line 208

def self.get_machine_id

  machine_id_cmd = "cat /etc/machine-id"
  machine_id_str = %x[ #{machine_id_cmd} ]
  return machine_id_str.chomp

end