lib/msf/core/payload/uuid.rb
# -*- coding => binary -*-
require 'rex/text'
require 'rex/arch'
#
# This class provides methods for calculating, extracting, and parsing
# unique ID values used by payloads.
#
class Msf::Payload::UUID
#
# Constants
#
Architectures = {
0 => nil,
1 => Rex::Arch::ARCH_X86,
2 => Rex::Arch::ARCH_X64, # removed Rex::Arch::ARCH_X86_64, now consistent across the board
3 => Rex::Arch::ARCH_X64,
4 => Rex::Arch::ARCH_MIPS,
5 => Rex::Arch::ARCH_MIPSLE,
6 => Rex::Arch::ARCH_MIPSBE,
7 => Rex::Arch::ARCH_PPC,
8 => Rex::Arch::ARCH_PPC64,
9 => Rex::Arch::ARCH_CBEA,
10 => Rex::Arch::ARCH_CBEA64,
11 => Rex::Arch::ARCH_SPARC,
12 => Rex::Arch::ARCH_ARMLE,
13 => Rex::Arch::ARCH_ARMBE,
14 => Rex::Arch::ARCH_CMD,
15 => Rex::Arch::ARCH_PHP,
16 => Rex::Arch::ARCH_TTY,
17 => Rex::Arch::ARCH_JAVA,
18 => Rex::Arch::ARCH_RUBY,
19 => Rex::Arch::ARCH_DALVIK,
20 => Rex::Arch::ARCH_PYTHON,
21 => Rex::Arch::ARCH_NODEJS,
22 => Rex::Arch::ARCH_FIREFOX,
23 => Rex::Arch::ARCH_ZARCH,
24 => Rex::Arch::ARCH_AARCH64,
25 => Rex::Arch::ARCH_MIPS64,
26 => Rex::Arch::ARCH_PPC64LE,
27 => Rex::Arch::ARCH_R,
28 => Rex::Arch::ARCH_PPCE500V2
}
Platforms = {
0 => nil,
1 => 'windows',
2 => 'netware',
3 => 'android',
4 => 'java',
5 => 'ruby',
6 => 'linux',
7 => 'cisco',
8 => 'solaris',
9 => 'osx',
10 => 'bsd',
11 => 'openbsd',
12 => 'bsdi',
13 => 'netbsd',
14 => 'freebsd',
15 => 'aix',
16 => 'hpux',
17 => 'irix',
18 => 'unix',
19 => 'php',
20 => 'js',
21 => 'python',
22 => 'nodejs',
23 => 'firefox',
24 => 'r',
25 => 'apple_ios',
26 => 'juniper',
27 => 'unifi',
28 => 'brocade',
29 => 'mikrotik',
30 => 'arista'
}
# The raw length of the UUID structure
RawLength = 16
# The base64url-encoded length of the UUID structure
UriLength = 22
# Validity constraints for UUID timestamps in UTC
TimestampMaxFuture = Time.now.utc.to_i + (30*24*3600) # Up to 30 days in the future
TimestampMaxPast = 1420070400 # Since 2015-01-01 00:00:00 UTC
#
# Class Methods
#
#
# Generate a raw 16-byte payload UUID given a seed, platform, architecture, and timestamp
#
# @option opts [String] :seed An optional string to use for generated the unique payload ID, deterministic
# @option opts [String] :puid An optional 8-byte string to use as the unique payload ID
# @option opts [String] :arch The hardware architecture for this payload
# @option opts [String] :platform The operating system platform for this payload
# @option opts [String] :timestamp The timestamp in UTC Unix epoch format
# @option opts [Integer] :xor1 An optional 8-bit XOR ID for obfuscation
# @option opts [Integer] :xor2 An optional 8-bit XOR ID for obfuscation
# @return [String] The encoded payoad UUID as a binary string
#
def self.generate_raw(opts={})
plat_id = find_platform_id(opts[:platform]) || 0
arch_id = find_architecture_id(opts[:arch]) || 0
tstamp = opts[:timestamp] || Time.now.utc.to_i
puid = opts[:puid]
if opts[:seed]
puid = seed_to_puid(opts[:seed])
end
puid ||= SecureRandom.random_bytes(8)
if puid.length != 8
raise ArgumentError, "The :puid parameter must be exactly 8 bytes"
end
plat_xor = opts[:xor1] || rand(256)
arch_xor = opts[:xor2] || rand(256)
# Recycle the previous two XOR bytes to keep our output small
time_xor = [plat_xor, arch_xor, plat_xor, arch_xor].pack('C4').unpack('N').first
# Combine the payload UID with the arch/platform and use xor to
# obscure the platform, architecture, and timestamp
puid +
[
plat_xor, arch_xor,
plat_xor ^ plat_id,
arch_xor ^ arch_id,
time_xor ^ tstamp
].pack('C4N')
end
#
# Parse a raw 16-byte payload UUID and return the payload ID, platform, architecture, and timestamp
#
# @param raw [String] The raw 16-byte payload UUID to parse
# @return [Hash] A hash containing the Payload ID, platform, architecture, and timestamp
#
def self.parse_raw(raw)
if raw.to_s.length < 16
raise ArgumentError, "Raw UUID must be at least 16 bytes"
end
puid, plat_xor, arch_xor, plat_id, arch_id, tstamp = raw.unpack('a8C4N')
plat = find_platform_name(plat_xor ^ plat_id)
arch = find_architecture_name(arch_xor ^ arch_id)
time_xor = [plat_xor, arch_xor, plat_xor, arch_xor].pack('C4').unpack('N').first
time = time_xor ^ tstamp
{ puid: puid, platform: plat, arch: arch, timestamp: time, xor1: plat_xor, xor2: arch_xor }
end
#
# Generate a 8-byte payload ID given a seed string
#
# @param seed [String] The seed to use to calculate a deterministic payload ID
# @return [String] The 8-byte payload ID
#
def self.seed_to_puid(seed)
Rex::Text.sha1_raw(seed)[12,8]
end
#
# Filter out UUIDs with obviously invalid fields and return either
# a validated UUID or a UUID with the arch, platform, and timestamp
# fields strippped out.
#
# @param uuid [Hash] The UUID in hash format
# @return [Hash] The filtered UUID in hash format
#
def self.filter_invalid(uuid)
# Verify the UUID fields and return just the Payload ID unless the
# timestamp is within our constraints and the UUID has either a
# valid architecture or platform
if uuid[:timestamp] > TimestampMaxFuture ||
uuid[:timestamp] < TimestampMaxPast ||
(uuid[:arch].nil? && uuid[:platform].nil?)
return { puid: uuid[:puid] }
end
uuid
end
#
# Parse a 22-byte base64url-encoded payload UUID and return the hash
#
# @param uri [String] The 22-byte base64url-encoded payload UUID to parse
# @return [Hash] A hash containing the Payload ID, platform, architecture, and timestamp
#
def self.parse_uri(uri)
parse_raw(Rex::Text.decode_base64url(uri))
end
#
# Look up the numeric platform ID given a string or PlatformList as input
#
# @param platform [String] The name of the platform to lookup
# @return [Integer] The integer value of this platform
#
def self.find_platform_id(platform)
# Handle a PlatformList input by grabbing the first entry
if platform.respond_to?(:platforms)
platform = platform.platforms.first.realname.downcase
end
# Map a platform abbreviation to the real name
name = platform ? Msf::Platform.find_platform(platform) : nil
if name && name.respond_to?(:realname)
name = name.realname.downcase
end
( Platforms.keys.select{ |k|
Platforms[k] == name
}.first || Platforms[0] ).to_i
end
#
# Look up the numeric architecture ID given a string as input
#
# @param name [String] The name of the architecture to lookup
# @return [Integer] The integer value of this architecture
#
def self.find_architecture_id(name)
name = name.first if name.kind_of? ::Array
( Architectures.keys.select{ |k|
Architectures[k] == name
}.first || Architectures[0] ).to_i
end
def self.find_platform_name(num)
Platforms[num]
end
def self.find_architecture_name(num)
Architectures[num]
end
#
# Instance methods
#
def initialize(opts=nil)
opts = load_new if opts.nil?
opts = load_uri(opts[:uri]) if opts[:uri]
opts = load_raw(opts[:raw]) if opts[:raw]
self.puid = opts[:puid]
self.timestamp = opts[:timestamp]
self.arch = opts[:arch]
self.platform = opts[:platform]
self.xor1 = opts[:xor1]
self.xor2 = opts[:xor2]
self.timestamp = nil
self.name = nil
self.registered = false
if opts[:seed]
self.puid = self.class.seed_to_puid(opts[:seed])
end
# Generate some sensible defaults
self.puid ||= SecureRandom.random_bytes(8)
self.xor1 ||= rand(256)
self.xor2 ||= rand(256)
self.timestamp ||= Time.now.utc.to_i
end
#
# Initializes a UUID object given a raw 16+ byte blob
#
# @param raw [String] The string containing at least 16 bytes of encoded data
# @return [Hash] The attributes encoded into this UUID
#
def load_raw(raw)
self.class.filter_invalid(self.class.parse_raw(raw))
end
#
# Initializes a UUID object given a 22+ byte URI
#
# @param uri [String] The URI containing at least 22 bytes of encoded data
# @return [Hash] The attributes encoded into this UUID
#
def load_uri(uri)
self.class.filter_invalid(self.class.parse_uri(uri))
end
def load_new
self.class.parse_raw(self.class.generate_raw())
end
#
# Provides a string representation of a UUID
#
# @return [String] The human-readable version of the UUID data
#
def to_s
arch_id = self.class.find_architecture_id(self.arch).to_s
plat_id = self.class.find_platform_id(self.platform).to_s
[
self.puid_hex,
[ self.arch || "noarch", arch_id ].join("="),
[ self.platform || "noplatform", plat_id ].join("="),
Time.at(self.timestamp.to_i).utc.strftime("%Y-%m-%dT%H:%M:%SZ")
].join("/")
end
#
# Return a string that represents the Meterpreter arch/platform
#
def session_type
# mini-patch for x86 so that it renders x64 instead. This is
# mostly to keep various external modules happy.
arch = self.arch
if arch == ARCH_X86_64
arch = ARCH_X64
end
"#{arch}/#{self.platform}"
end
#
# Provides a hash representation of a UUID
#
# @return [Hash] The hash representation of the UUID suitable for creating a new one
#
def to_h
{
puid: self.puid,
arch: self.arch, platform: self.platform,
timestamp: self.timestamp,
xor1: self.xor1, xor2: self.xor2
}
end
#
# Provides a raw byte representation of a UUID
#
# @return [String] The 16-byte raw encoded version of the UUID
#
def to_raw
self.class.generate_raw(self.to_h)
end
#
# Provides a URI-encoded representation of a UUID
#
# @return [String] The 22-byte URI encoded version of the UUID
#
def to_uri
Rex::Text.encode_base64url(self.to_raw)
end
#
# Provides a hex representation of the Payload UID of the UUID
#
# @return [String] The 16-byte hex string representing the Payload UID
#
def puid_hex
self.puid.unpack('H*').first
end
#
# Clears the two random XOR keys used for obfuscation
#
def xor_reset
self.xor1 = self.xor2 = nil
self
end
attr_accessor :registered
attr_accessor :timestamp
attr_accessor :name
attr_reader :arch
attr_reader :platform
def arch=(arch_str)
if arch_str.nil?
@arch = nil
return
end
arch_id = self.class.find_architecture_id(arch_str)
if arch_id == 0
raise ArgumentError, "Invalid architecture: '#{arch_str}'"
end
arch_name = self.class.find_architecture_name(arch_id)
@arch = arch_name
end
def platform=(plat_str)
if plat_str.nil?
@platform = nil
return
end
plat_id = self.class.find_platform_id(plat_str)
if plat_id == 0
raise ArgumentError, "Invalid platform: '#{plat_str}'"
end
plat_name = self.class.find_platform_name(plat_id)
@platform = plat_name
end
attr_accessor :timestamp
attr_accessor :puid
attr_accessor :xor1
attr_accessor :xor2
end