ronin-support 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. checksums.yaml +4 -4
  2. data/ChangeLog.md +21 -0
  3. data/lib/ronin/support/archive/core_ext/file.rb +43 -0
  4. data/lib/ronin/support/archive/core_ext.rb +1 -1
  5. data/lib/ronin/support/binary/array.rb +1 -1
  6. data/lib/ronin/support/binary/buffer.rb +3 -3
  7. data/lib/ronin/support/binary/core_ext.rb +2 -0
  8. data/lib/ronin/support/binary/cstring.rb +43 -0
  9. data/lib/ronin/support/binary/ctypes/array_type.rb +1 -1
  10. data/lib/ronin/support/binary/ctypes/os/bsd.rb +1 -1
  11. data/lib/ronin/support/binary/ctypes/unbounded_array_type.rb +1 -1
  12. data/lib/ronin/support/binary/packet.rb +77 -0
  13. data/lib/ronin/support/binary/stack.rb +3 -3
  14. data/lib/ronin/support/binary/template.rb +1 -5
  15. data/lib/ronin/support/binary.rb +1 -0
  16. data/lib/ronin/support/compression/core_ext/file.rb +16 -0
  17. data/lib/ronin/support/core_ext/kernel.rb +0 -4
  18. data/lib/ronin/support/crypto/core_ext/file.rb +32 -0
  19. data/lib/ronin/support/crypto/core_ext/string.rb +34 -2
  20. data/lib/ronin/support/encoding/base16.rb +1 -1
  21. data/lib/ronin/support/encoding/base32.rb +1 -1
  22. data/lib/ronin/support/encoding/c/core_ext/string.rb +1 -1
  23. data/lib/ronin/support/encoding/c.rb +2 -2
  24. data/lib/ronin/support/encoding/core_ext/string.rb +2 -2
  25. data/lib/ronin/support/encoding/hex/core_ext/string.rb +1 -1
  26. data/lib/ronin/support/encoding/hex.rb +2 -2
  27. data/lib/ronin/support/encoding/js.rb +1 -1
  28. data/lib/ronin/support/encoding/powershell.rb +1 -1
  29. data/lib/ronin/support/encoding/quoted_printable.rb +3 -1
  30. data/lib/ronin/support/encoding/ruby.rb +1 -1
  31. data/lib/ronin/support/encoding/uuencoding.rb +3 -1
  32. data/lib/ronin/support/encoding/xml.rb +1 -1
  33. data/lib/ronin/support/network/dns/mixin.rb +2 -10
  34. data/lib/ronin/support/network/http/core_ext/uri/http.rb +8 -0
  35. data/lib/ronin/support/network/ip.rb +41 -13
  36. data/lib/ronin/support/network/ip_range.rb +4 -4
  37. data/lib/ronin/support/path.rb +1 -1
  38. data/lib/ronin/support/text/homoglyph/core_ext/string.rb +33 -0
  39. data/lib/ronin/support/text/patterns/network.rb +20 -20
  40. data/lib/ronin/support/text/random/mixin.rb +17 -17
  41. data/lib/ronin/support/text/random.rb +23 -23
  42. data/lib/ronin/support/text/typo/core_ext/string.rb +24 -0
  43. data/lib/ronin/support/version.rb +1 -1
  44. metadata +2 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e4a9cca292661aabc9b8b8360bef73af12a140bac7b80bbe969671a78d5c4cb8
4
- data.tar.gz: cb8920fa647c56bcf03c9a4b5796f6e58fd732d82ea79027bce10d77246f1af6
3
+ metadata.gz: 9e7362a5af595979050611362ff0d48ace6148032006e9f05e9d90976b44487c
4
+ data.tar.gz: a6c6277a8af8169bf8fb374782b65169ae460c8cd6f4cac28a0c82d7ce7648b5
5
5
  SHA512:
6
- metadata.gz: '04831026ac5813990e5db208ac229f707f24cfb0bcff277ff0da70eecdce58b379925ed944b5377ead08ac63f7e6fce0a323bcfe05a4a617a6d0cfa5987ec90b'
7
- data.tar.gz: ed25a967fe35242afdb9a9d2e3dc8dff096de0e7737494100b6a54c96f67c4288d2ff21ab2e6eadce4f07fe6284037e454e37498ae1b108dfeda024b115bf26b
6
+ metadata.gz: f927d978f7af471f00bac7b97cc2bc9244df4b04683af3f6ce89ae6988d8f09cf7b28c16422673414a55b2711c9db05695afa0ffae35b1889b0c35117b7597fa
7
+ data.tar.gz: 519478e67e3fd01efa02d800d4badb66ce21a867165f300d4310e5a2a4411614ecacd7292c8095b8cef3ae444306b4402cf96e54fb5054f9d4eeb3d19350a335
data/ChangeLog.md CHANGED
@@ -1,3 +1,24 @@
1
+ ### 1.0.2 / 2023-06-09
2
+
3
+ * Fixed a bug in {Ronin::Support::Encoding::Base32.decode},
4
+ {Ronin::Support::Encoding::Hex.unescape},
5
+ {Ronin::Support::Encoding::C.unescape},
6
+ {Ronin::Support::Encoding::JS.unescape},
7
+ {Ronin::Support::Encoding::PowerShell.unescape},
8
+ {Ronin::Support::Encoding::Ruby.unescape},
9
+ {Ronin::Support::Encoding::XML.unescape},
10
+ {Ronin::Support::Path#join}, {String#encode_bytes}, and {String#encode_chars}
11
+ where ASCII-bit Strings were always being returned instead of UTF-8 Strings.
12
+ * Fixed a bug where {Ronin::Support::Network::IP#address} was being improperly
13
+ cached.
14
+ * Added missing `require` for {File.tar}, {File.untar}, {File.zip}, and
15
+ {File.unzip} core-ext methods.
16
+ * Added missing `require` for {Integer#pack} and {Float#pack} core-ext methods.
17
+ * No longer include {Ronin::Support::Mixin} into {Kernel} which caused Mixin
18
+ methods to be included into *every* Class and object.
19
+ * Added more example code to documentation.
20
+ * Documentation fixes.
21
+
1
22
  ### 1.0.1 / 2023-03-01
2
23
 
3
24
  * {Ronin::Support::Network::HTTP.connect_uri} can now infer when to enable
@@ -38,6 +38,22 @@ class File
38
38
  # @return [Ronin::Support::Archive::Tar::Reader]
39
39
  # The tar reader object.
40
40
  #
41
+ # @example Enumerating over each entry in the tar archive:
42
+ # File.untar('file.tar') do |tar|
43
+ # tar.each do |entry|
44
+ # puts entry.full_name
45
+ # puts '-' * 80
46
+ # puts entry.read
47
+ # puts '-' * 80
48
+ # end
49
+ # end
50
+ #
51
+ # @example Reads a specific file from the tar archive:
52
+ # File.untar('file.tar') do |tar|
53
+ # data = tar.read('foo.txt')
54
+ # # ...
55
+ # end
56
+ #
41
57
  # @api public
42
58
  #
43
59
  # @since 1.0.0
@@ -61,6 +77,12 @@ class File
61
77
  # @return [Ronin::Support::Archive::Tar::Writer]
62
78
  # The tar writer object.
63
79
  #
80
+ # @example
81
+ # File.tar('output.tar') do |tar|
82
+ # tar.mkdir('foo')
83
+ # tar.add_file('foo/bar.txt','Hello World!')
84
+ # end
85
+ #
64
86
  # @api public
65
87
  #
66
88
  # @since 1.0.0
@@ -84,6 +106,22 @@ class File
84
106
  # @return [Ronin::Support::Archive::Zip::Reader]
85
107
  # The zip reader object.
86
108
  #
109
+ # @example Enumerating over each file in a zip archive:
110
+ # File.unzip('file.zip') do |zip|
111
+ # zip.each do |entry|
112
+ # puts entry.name
113
+ # puts '-' * 80
114
+ # puts entry.read
115
+ # puts '-' * 80
116
+ # end
117
+ # end
118
+ #
119
+ # @example Reads a specific file from a zip archive:
120
+ # File.unzip('file.zip') do |zip|
121
+ # data = zip.read('foo.txt')
122
+ # # ...
123
+ # end
124
+ #
87
125
  # @api public
88
126
  #
89
127
  # @since 1.0.0
@@ -107,6 +145,11 @@ class File
107
145
  # @return [Ronin::Support::Archive::Zip::Writer]
108
146
  # The zip writer object.
109
147
  #
148
+ # @example
149
+ # File.zip('output.zip') do |zip|
150
+ # zip.add_file('foo/bar.txt','Hello World!')
151
+ # end
152
+ #
110
153
  # @api public
111
154
  #
112
155
  # @since 1.0.0
@@ -16,4 +16,4 @@
16
16
  # along with ronin-support. If not, see <https://www.gnu.org/licenses/>.
17
17
  #
18
18
 
19
- require 'ronin/support/compression/core_ext/file'
19
+ require 'ronin/support/archive/core_ext/file'
@@ -35,7 +35,7 @@ module Ronin
35
35
  #
36
36
  # Creating an array of `int32`s:
37
37
  #
38
- # array = Binary::Array.new(:int32, 4)
38
+ # array = Binary::Binary::Array.new(:int32, 4)
39
39
  # # => #<Ronin::Support::Binary::Binary::Array: "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00">
40
40
  # array[0] = 0x11111111
41
41
  # array[1] = 0x22222222
@@ -30,7 +30,7 @@ module Ronin
30
30
  #
31
31
  # Writing bytes into an empty buffer:
32
32
  #
33
- # buffer = Buffer.new(10)
33
+ # buffer = Binary::Buffer.new(10)
34
34
  # # => #<Ronin::Support::Binary::Buffer: "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00">
35
35
  # buffer[0] = 0x41
36
36
  # buffer[1] = 0x42
@@ -40,7 +40,7 @@ module Ronin
40
40
  #
41
41
  # Writing different types of data to a buffer:
42
42
  #
43
- # buffer = Buffer.new(16)
43
+ # buffer = Binary::Buffer.new(16)
44
44
  # # => #<Ronin::Support::Binary::Buffer: "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00">
45
45
  # buffer.put_uint32(0,0x11223344)
46
46
  # buffer.put_int32(4,-1)
@@ -51,7 +51,7 @@ module Ronin
51
51
  #
52
52
  # Creating a buffer from an existing String:
53
53
  #
54
- # buffer = Buffer.new("\x41\x00\x00\x00\x42\x00\x00\x00")
54
+ # buffer = Binary::Buffer.new("\x41\x00\x00\x00\x42\x00\x00\x00")
55
55
  # # => #<Ronin::Support::Binary::Buffer: "A\u0000\u0000\u0000B\u0000\u0000\u0000">
56
56
  # buffer.get_uint32(0)
57
57
  # # => 65
@@ -16,6 +16,8 @@
16
16
  # along with ronin-support. If not, see <https://www.gnu.org/licenses/>.
17
17
  #
18
18
 
19
+ require 'ronin/support/binary/core_ext/integer'
20
+ require 'ronin/support/binary/core_ext/float'
19
21
  require 'ronin/support/binary/core_ext/string'
20
22
  require 'ronin/support/binary/core_ext/array'
21
23
  require 'ronin/support/binary/core_ext/io'
@@ -24,6 +24,49 @@ module Ronin
24
24
  #
25
25
  # Represents a null terminated C string.
26
26
  #
27
+ # ## Examples
28
+ #
29
+ # ### Initializing C Strings
30
+ #
31
+ # From a String:
32
+ #
33
+ # str = Binary::CString.new("hello ")
34
+ # # => #<Ronin::Support::Binary::CString:0x00007fc94ba577f8 @string="hello \u0000">
35
+ #
36
+ # From a binary C string:
37
+ #
38
+ # str = Binary::CString.new("world\0".b)
39
+ # # => #<Ronin::Support::Binary::CString:0x00007fc94ba06f88 @string="world\u0000">
40
+ #
41
+ # From characters:
42
+ #
43
+ # str = Binary::CString['A', 'B', 'C']
44
+ # # => #<Ronin::Support::Binary::CString:0x00007fc94ba6f268 @string="ABC\x00">
45
+ #
46
+ # ### Modifying C Strings
47
+ #
48
+ # Concating Strings to a C String:
49
+ #
50
+ # str = Binary::CString.new("hello ")
51
+ # str.concat("world")
52
+ # # => #<Ronin::Support::Binary::CString:0x00007fc94b978df0 @string="hello world\u0000">
53
+ # str.to_s
54
+ # # => "hello world"
55
+ #
56
+ # Appending two C Strings:
57
+ #
58
+ # str1 = Binary::CString.new("hello ")
59
+ # str2 = Binary::CString.new("world\0")
60
+ # str = str1 + str2
61
+ # # => #<Ronin::Support::Binary::CString:0x00007fc94b9523f8 @string="hello world\u0000">
62
+ #
63
+ # Setting characters:
64
+ #
65
+ # str = Binary::CString.new("hello")
66
+ # str[0] = 'X'
67
+ # str.to_s
68
+ # # => "Xello"
69
+ #
27
70
  # @api public
28
71
  #
29
72
  # @since 1.0.0
@@ -152,7 +152,7 @@ module Ronin
152
152
  if @pack_string
153
153
  super(array)
154
154
  else
155
- buffer = String.new("", encoding: Encoding::ASCII_8BIT)
155
+ buffer = String.new
156
156
 
157
157
  @length.times do |index|
158
158
  value = array[index] || @type.uninitialized_value
@@ -33,7 +33,7 @@ module Ronin
33
33
  class BSD < UNIX
34
34
 
35
35
  #
36
- # Initializes the FreeBSD types object.
36
+ # Initializes the common BSD types object.
37
37
  #
38
38
  # @param [#[]] types
39
39
  # The base types module.
@@ -149,7 +149,7 @@ module Ronin
149
149
  if @pack_string
150
150
  super(array)
151
151
  else
152
- buffer = String.new('', encoding: Encoding::ASCII_8BIT)
152
+ buffer = String.new
153
153
 
154
154
  array.each do |element|
155
155
  buffer << @type.pack(element)
@@ -24,6 +24,83 @@ module Ronin
24
24
  #
25
25
  # Represents a network packet in network byte-order.
26
26
  #
27
+ # ## Examples
28
+ #
29
+ # ### Defining Packet Fields
30
+ #
31
+ # class Packet < Ronin::Support::Binary::Packet
32
+ #
33
+ # member :flags, :uint8
34
+ # member :src, :uint32
35
+ # member :dst, :uint32
36
+ # member :length, :uint32
37
+ #
38
+ # end
39
+ #
40
+ # ### Initializing Packets
41
+ #
42
+ # From a Hash:
43
+ #
44
+ # packet = Packet.new(
45
+ # flags: 0x0c,
46
+ # src: IPAddr.new('1.2.3.4').to_i,
47
+ # dst: IPAddr.new('5.6.7.8').to_i,
48
+ # length: 1024
49
+ # )
50
+ #
51
+ # From a buffer:
52
+ #
53
+ # packet = Packet.unpack("\f\x01\x02\x03\x04\x05\x06\a\b\x00\x00\x04\x00")
54
+ #
55
+ # ### Reading Fields
56
+ #
57
+ # packet = Packet.new("\f\x01\x02\x03\x04\x05\x06\a\b\x00\x00\x04\x00")
58
+ # packet[:flags]
59
+ # # => 12
60
+ # packet.flags
61
+ # # => 12
62
+ #
63
+ # ### Packing Packets
64
+ #
65
+ # class Packet < Ronin::Support::Binary::Packet
66
+ #
67
+ # member :flags, :uint8
68
+ # member :src, :uint32
69
+ # member :dst, :uint32
70
+ # member :length, :uint32
71
+ #
72
+ # end
73
+ #
74
+ # packet = Packet.new(
75
+ # flags: 0x0c,
76
+ # src: IPAddr.new('1.2.3.4').to_i,
77
+ # dst: IPAddr.new('5.6.7.8').to_i,
78
+ # length: 1024
79
+ # )
80
+ # packet.pack
81
+ # # => "\f\x01\x02\x03\x04\x05\x06\a\b\x00\x00\x04\x00"
82
+ #
83
+ # ### Unpacking Packets
84
+ #
85
+ # class Packet < Ronin::Support::Binary::Packet
86
+ #
87
+ # member :flags, :uint8
88
+ # member :src, :uint32
89
+ # member :dst, :uint32
90
+ # member :length, :uint32
91
+ #
92
+ # end
93
+ #
94
+ # packet = Packet.unpack("\f\x01\x02\x03\x04\x05\x06\a\b\x00\x00\x04\x00")
95
+ # packet.flags
96
+ # # => 12
97
+ # packet.src
98
+ # # => 16909060
99
+ # packet.dst
100
+ # # => 84281096
101
+ # packet.length
102
+ # # => 1024
103
+ #
27
104
  class Packet < Binary::Struct
28
105
 
29
106
  platform endian: :net
@@ -36,7 +36,7 @@ module Ronin
36
36
  #
37
37
  # Creating a new stack:
38
38
  #
39
- # stack = Stack.new
39
+ # stack = Binary::Stack.new
40
40
  # # => #<Ronin::Support::Binary::Stack: "">
41
41
  # stack.push 0x41414141
42
42
  # # => #<Ronin::Support::Binary::Stack: "AAAA\x00\x00\x00\x00">
@@ -49,7 +49,7 @@ module Ronin
49
49
  #
50
50
  # Creating a stack from an existing String:
51
51
  #
52
- # stack = Stack.new("\x41\x00\x00\x00\x00\x00\x00\x00\x42\x00\x00\x00\x00\x00\x00\x00")
52
+ # stack = Binary::Stack.new("\x41\x00\x00\x00\x00\x00\x00\x00\x42\x00\x00\x00\x00\x00\x00\x00")
53
53
  # stack[0]
54
54
  # # => 65
55
55
  # stack[8]
@@ -125,7 +125,7 @@ module Ronin
125
125
  @size = @string.bytesize
126
126
  @length = @size / @machine_word.size
127
127
  else
128
- @string = String.new("", encoding: Encoding::ASCII_8BIT)
128
+ @string = String.new
129
129
  @size = 0
130
130
  @length = 0
131
131
  end
@@ -36,10 +36,6 @@ module Ronin
36
36
  # * `:int16` - signed 16-bit integer.
37
37
  # * `:int32` - signed 32-bit integer.
38
38
  # * `:int64` - signed 64-bit integer.
39
- # * `:uint16_le` - unsigned 16-bit integer, little endian.
40
- # * `:uint32_le` - unsigned 32-bit integer, little endian.
41
- # * `:uint16_be` - unsigned 16-bit integer, big endian.
42
- # * `:uint32_be` - unsigned 32-bit integer, big endian.
43
39
  # * `:uchar` - unsigned character.
44
40
  # * `:ushort` - unsigned short integer, native endian.
45
41
  # * `:uint` - unsigned integer, native endian.
@@ -209,7 +205,7 @@ module Ronin
209
205
 
210
206
  values.pack(@pack_string)
211
207
  else
212
- buffer = String.new('', encoding: Encoding::ASCII_8BIT)
208
+ buffer = String.new
213
209
 
214
210
  @types.each do |type|
215
211
  # shift off the next value and pack it
@@ -19,6 +19,7 @@
19
19
  require 'ronin/support/binary/core_ext'
20
20
  require 'ronin/support/binary/template'
21
21
  require 'ronin/support/binary/buffer'
22
+ require 'ronin/support/binary/cstring'
22
23
  require 'ronin/support/binary/array'
23
24
  require 'ronin/support/binary/stack'
24
25
  require 'ronin/support/binary/struct'
@@ -36,6 +36,13 @@ class File
36
36
  # @return [Ronin::Support::Compression::Gzip::Reader]
37
37
  # The gzip reader object.
38
38
  #
39
+ # @example
40
+ # File.gunzip('wordlist.gz') do |gz|
41
+ # gz.each_line do |line|
42
+ # # ...
43
+ # end
44
+ # end
45
+ #
39
46
  # @api public
40
47
  #
41
48
  # @since 1.0.0
@@ -59,6 +66,15 @@ class File
59
66
  # @return [Ronin::Support::Compression::Gzip::Writer]
60
67
  # The gzip writer object.
61
68
  #
69
+ # @example
70
+ # File.gunzip('file.gz') do |gz|
71
+ # # gzip header info
72
+ # gz.mtime = Time.now
73
+ # gz.orig_name = 'file.txt'
74
+ #
75
+ # gz.write('Hello World!')
76
+ # end
77
+ #
62
78
  # @api public
63
79
  #
64
80
  # @since 1.0.0
@@ -16,11 +16,7 @@
16
16
  # along with ronin-support. If not, see <https://www.gnu.org/licenses/>.
17
17
  #
18
18
 
19
- require 'ronin/support/mixin'
20
-
21
19
  module Kernel
22
- include Ronin::Support::Mixin
23
-
24
20
  #
25
21
  # Calls the given block and ignores any raised exceptions.
26
22
  #
@@ -224,6 +224,10 @@ class File
224
224
  # @return [String]
225
225
  # The encrypted data.
226
226
  #
227
+ # @example
228
+ # File.encrypt('file.txt', 'aes-256-cbc', password: 's3cr3t')
229
+ # # => "..."
230
+ #
227
231
  # @see http://rubydoc.info/stdlib/openssl/OpenSSL/Cipher
228
232
  #
229
233
  # @since 0.6.0
@@ -281,6 +285,10 @@ class File
281
285
  # @return [String]
282
286
  # The decrypted data.
283
287
  #
288
+ # @example
289
+ # File.decrypt('encrypted.bin', 'aes-256-cbc', password: 's3cr3t')
290
+ # # => "..."
291
+ #
284
292
  # @see http://rubydoc.info/stdlib/openssl/OpenSSL/Cipher
285
293
  #
286
294
  # @since 0.6.0
@@ -338,6 +346,10 @@ class File
338
346
  # @raise [ArgumentError]
339
347
  # Either the the `key:` or `password:` keyword argument must be given.
340
348
  #
349
+ # @example
350
+ # File.aes_encrypt('file.txt', key_size: 256, password: 's3cr3t')
351
+ # # => "..."
352
+ #
341
353
  # @since 1.0.0
342
354
  #
343
355
  def self.aes_encrypt(path, block_size: 16384, output: nil, **kwargs,&block)
@@ -390,6 +402,10 @@ class File
390
402
  # @raise [ArgumentError]
391
403
  # Either the the `key:` or `password:` keyword argument must be given.
392
404
  #
405
+ # @example
406
+ # File.aes_decrypt('encrypted.bin', key_size: 256, password: 's3cr3t')
407
+ # # => "..."
408
+ #
393
409
  # @since 1.0.0
394
410
  #
395
411
  def self.aes_decrypt(path, block_size: 16384, output: nil, **kwargs,&block)
@@ -439,6 +455,10 @@ class File
439
455
  # @raise [ArgumentError]
440
456
  # Either the the `key:` or `password:` keyword argument must be given.
441
457
  #
458
+ # @example
459
+ # File.aes128_encrypt('file.txt', password: 's3cr3t')
460
+ # # => "..."
461
+ #
442
462
  # @since 1.0.0
443
463
  #
444
464
  def self.aes128_encrypt(path, block_size: 16384, output: nil, **kwargs,&block)
@@ -488,6 +508,10 @@ class File
488
508
  # @raise [ArgumentError]
489
509
  # Either the the `key:` or `password:` keyword argument must be given.
490
510
  #
511
+ # @example
512
+ # File.aes256_decrypt('encrypted.bin', password: 's3cr3t')
513
+ # # => "..."
514
+ #
491
515
  # @since 1.0.0
492
516
  #
493
517
  def self.aes128_decrypt(path, block_size: 16384, output: nil, **kwargs,&block)
@@ -537,6 +561,10 @@ class File
537
561
  # @raise [ArgumentError]
538
562
  # Either the the `key:` or `password:` keyword argument must be given.
539
563
  #
564
+ # @example
565
+ # File.aes256_encrypt('file.txt', password: 's3cr3t')
566
+ # # => "..."
567
+ #
540
568
  # @since 1.0.0
541
569
  #
542
570
  def self.aes256_encrypt(path, block_size: 16384, output: nil, **kwargs,&block)
@@ -586,6 +614,10 @@ class File
586
614
  # @raise [ArgumentError]
587
615
  # Either the the `key:` or `password:` keyword argument must be given.
588
616
  #
617
+ # @example
618
+ # File.aes256_decrypt('encrypted.bin', password: 's3cr3t')
619
+ # # => "..."
620
+ #
589
621
  # @since 1.0.0
590
622
  #
591
623
  def self.aes256_decrypt(path, block_size: 16384, output: nil, **kwargs,&block)
@@ -54,10 +54,10 @@ class String
54
54
 
55
55
  #
56
56
  # @return [String]
57
- # The SHA2 checksum of the String.
57
+ # The SHA256 checksum of the String.
58
58
  #
59
59
  # @example
60
- # "hello".sha2
60
+ # "hello".sha256
61
61
  # # => "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
62
62
  #
63
63
  # @api public
@@ -152,6 +152,10 @@ class String
152
152
  # @return [String]
153
153
  # The encrypted String.
154
154
  #
155
+ # @example
156
+ # "top secret".encrypt('aes-256-cbc', password: 's3cr3t')
157
+ # # => "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\"
158
+ #
155
159
  # @see http://rubydoc.info/stdlib/openssl/OpenSSL/Cipher
156
160
  #
157
161
  # @since 0.6.0
@@ -191,6 +195,10 @@ class String
191
195
  # @return [String]
192
196
  # The decrypted String.
193
197
  #
198
+ # @example
199
+ # "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\".decrypt('aes-256-cbc', password: 's3cr3t')
200
+ # # => "top secret"
201
+ #
194
202
  # @see http://rubydoc.info/stdlib/openssl/OpenSSL/Cipher
195
203
  #
196
204
  # @since 0.6.0
@@ -236,6 +244,10 @@ class String
236
244
  # @raise [ArgumentError]
237
245
  # Either the the `key:` or `password:` keyword argument must be given.
238
246
  #
247
+ # @example
248
+ # "top secret".aes_encrypt(key_size: 256, password: 's3cr3t')
249
+ # # => "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\"
250
+ #
239
251
  # @since 1.0.0
240
252
  #
241
253
  def aes_encrypt(**kwargs)
@@ -275,6 +287,10 @@ class String
275
287
  # @raise [ArgumentError]
276
288
  # Either the the `key:` or `password:` keyword argument must be given.
277
289
  #
290
+ # @example
291
+ # "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\".aes_decrypt(key_size: 256, password: 's3cr3t')
292
+ # # => "top secret"
293
+ #
278
294
  # @since 1.0.0
279
295
  #
280
296
  def aes_decrypt(**kwargs)
@@ -311,6 +327,10 @@ class String
311
327
  # @raise [ArgumentError]
312
328
  # Either the the `key:` or `password:` keyword argument must be given.
313
329
  #
330
+ # @example
331
+ # "top secret".aes128_encrypt(password: 's3cr3t')
332
+ # # => "\x88\xA53\xE9|\xE2\x8E\xA0\xABv\xCF\x94\x17\xBB*\xC5"
333
+ #
314
334
  # @since 1.0.0
315
335
  #
316
336
  def aes128_encrypt(**kwargs)
@@ -347,6 +367,10 @@ class String
347
367
  # @raise [ArgumentError]
348
368
  # Either the the `key:` or `password:` keyword argument must be given.
349
369
  #
370
+ # @example
371
+ # "\x88\xA53\xE9|\xE2\x8E\xA0\xABv\xCF\x94\x17\xBB*\xC5".aes128_decrypt(password: 's3cr3t')
372
+ # # => "top secret"
373
+ #
350
374
  # @since 1.0.0
351
375
  #
352
376
  def aes128_decrypt(**kwargs)
@@ -383,6 +407,10 @@ class String
383
407
  # @raise [ArgumentError]
384
408
  # Either the the `key:` or `password:` keyword argument must be given.
385
409
  #
410
+ # @example
411
+ # "top secret".aes256_encrypt(password: 's3cr3t')
412
+ # # => "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\"
413
+ #
386
414
  # @since 1.0.0
387
415
  #
388
416
  def aes256_encrypt(**kwargs)
@@ -419,6 +447,10 @@ class String
419
447
  # @raise [ArgumentError]
420
448
  # Either the the `key:` or `password:` keyword argument must be given.
421
449
  #
450
+ # @example
451
+ # "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\".aes256_decrypt(password: 's3cr3t')
452
+ # # => "top secret"
453
+ #
422
454
  # @since 1.0.0
423
455
  #
424
456
  def aes256_decrypt(**kwargs)
@@ -71,7 +71,7 @@ module Ronin
71
71
  # # => "hello"
72
72
  #
73
73
  def self.decode(data)
74
- decoded = String.new
74
+ decoded = String.new(encoding: Encoding::ASCII_8BIT)
75
75
 
76
76
  data.scan(/../).each do |hex_char|
77
77
  decoded << hex_char.to_i(16).chr
@@ -63,7 +63,7 @@ module Ronin
63
63
  # The Base32 decoded String.
64
64
  #
65
65
  def self.decode(data)
66
- decoded = String.new
66
+ decoded = String.new(encoding: Encoding::UTF_8)
67
67
 
68
68
  each_chunk(data,8) do |chunk|
69
69
  chunk.decode(decoded)
@@ -47,7 +47,7 @@ class String
47
47
  # The unescaped C String.
48
48
  #
49
49
  # @example
50
- # "\x68\x65\x6c\x6c\x6f\x20\x77\x6f\x72\x6c\x64".c_unescape
50
+ # "\\x68\\x65\\x6c\\x6c\\x6f\\x20\\x77\\x6f\\x72\\x6c\\x64".c_unescape
51
51
  # # => "hello world"
52
52
  #
53
53
  # @see Ronin::Support::Encoding::C.unescape
@@ -213,11 +213,11 @@ module Ronin
213
213
  # The unescaped C String.
214
214
  #
215
215
  # @example
216
- # Encoding::C.unescape("\x68\x65\x6c\x6c\x6f\x20\x77\x6f\x72\x6c\x64")
216
+ # Encoding::C.unescape("\\x68\\x65\\x6c\\x6c\\x6f\\x20\\x77\\x6f\\x72\\x6c\\x64")
217
217
  # # => "hello world"
218
218
  #
219
219
  def self.unescape(data)
220
- unescaped = String.new
220
+ unescaped = String.new(encoding: Encoding::UTF_8)
221
221
  scanner = StringScanner.new(data)
222
222
 
223
223
  until scanner.eos?
@@ -48,7 +48,7 @@ class String
48
48
  def encode_bytes(include: nil, exclude: nil)
49
49
  included = (Chars::CharSet.new(*include) if include)
50
50
  excluded = (Chars::CharSet.new(*exclude) if exclude)
51
- formatted = String.new
51
+ formatted = String.new(encoding: ::Encoding::UTF_8)
52
52
 
53
53
  each_byte do |b|
54
54
  formatted << if (included.nil? || included.include_byte?(b)) &&
@@ -90,7 +90,7 @@ class String
90
90
  def encode_chars(include: nil, exclude: nil)
91
91
  included = (Chars::CharSet.new(*include) if include)
92
92
  excluded = (Chars::CharSet.new(*exclude) if exclude)
93
- formatted = String.new
93
+ formatted = String.new(encoding: ::Encoding::UTF_8)
94
94
 
95
95
  each_char do |c|
96
96
  formatted << if (included.nil? || included.include_char?(c)) &&