v1.3.0

fix #5

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    tls-map (1.2.0)
+    tls-map (1.3.0)
       docopt (~> 0.6)
       paint (~> 2.2)
       rexml (~> 3.2)
@@ -44,6 +44,7 @@ GEM
       i18n
     ruby-progressbar (1.11.0)
     unicode-display_width (2.0.0)
+    webrick (1.7.0)
     yard (0.9.26)
 
 PLATFORMS
@@ -59,6 +60,7 @@ DEPENDENCIES
   redcarpet (~> 3.5)
   rubocop (~> 1.10)
   tls-map!
+  webrick (~> 1.7)
   yard (~> 0.9)
 
 BUNDLED WITH

README.md

@@ -25,7 +25,10 @@
 
 - CLI and library
 - Search feature: hexadecimal codepoint and major TLS libraries cipher algorithm name: IANA, OpenSSL, GnuTLS, NSS
+  - get extra info about a cipher
 - Export to files: markdown table, expanded JSON, minified JSON, Ruby marshalized hash
+- Extract ciphers from external tools file output (SSLyze, sslscan2, testssl.sh, ssllabs-scan)
+- Bulk search (file with one cipher per line)
 
 ## Installation
 

bin/tls-map

@@ -10,11 +10,14 @@ require 'tls_map/cli'
 require 'docopt'
 require 'paint'
 
+# can't specify 2 options with the same name even if used in different commands
+# https://github.com/docopt/docopt/issues/296#issuecomment-857477191
 doc = <<~DOCOPT
   TLS map #{TLSmap::VERSION}
 
   Usage:
     tls-map search <critera> <term> [-o <output> --force -e -a] [--no-color --debug]
+    tls-map bulk <critera> <file> [-q <output> --force] [--no-color --debug]
     tls-map export <filename> <format> [--force] [--debug]
     tls-map extract <filename> <format> [--no-color --debug]
     tls-map update [--debug]
@@ -28,6 +31,11 @@ doc = <<~DOCOPT
     -e, --extended          (Online) Display additional information about the cipher (requires output = all or iana)
     -a, --acronym           (Online) Display full acronym name (requires -e / --extended option)
 
+  Bulk options: (offline) search and translate cipher names between SSL/TLS libraries in bulk
+    <critera>               The type of term. Accepted values: codepoint, iana, openssl, gnutls, nss.
+    <file>                  File containing the cipher algorithm names, one per line.
+    -q, --output2 <output>  Displayed fields. Accepted values: codepoint, iana, openssl, gnutls, nss. [default: iana]
+
   Export options: (offline) export the list of all ciphers (mapping) in various formats
     <filename>              The output file name to write to.
     <format>                Supported formats: markdown (a markdown table), json_pretty (expanded JSON), json_compact (minified JSON), marshal (Ruby marshalized hash).
@@ -39,7 +47,7 @@ doc = <<~DOCOPT
   Update options: (online) DANGEROUS, will break database integrity, force option will be required
 
   Other options:
-    --force     Force parsing even if intigrity check failed (DANGEROUS, may result in command execution vulnerability)
+    --force     Force parsing even if integrity check failed (DANGEROUS, may result in command execution vulnerability)
     --no-color  Disable colorized output
     --debug     Display arguments
     -h, --help  Show this screen
@@ -80,6 +88,13 @@ begin
         end
       end
     end
+  elsif args['bulk']
+    cli = TLSmap::CLI.new(args['--force'])
+    res = cli.bulk_search(args['<critera>'].to_sym, args['<file>'], args['--output2'].to_sym)
+    puts Paint['No match found', :red] if res.empty?
+    res.each do |h|
+      puts "#{Paint[h[args['--output2'].to_sym], :green]}"
+    end
   elsif args['export']
     cli = TLSmap::CLI.new(args['--force'])
     cli.export(args['<filename>'], args['<format>'].to_sym)

docs/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [1.3.0]
+
+Additions:
+
+- add `bulk_search()` method for bulk search (file with one cipher per line)
+  - new `bulk` CLI command
+
+Documentation:
+
+- add `webrick` in dev dependencies to be able to use `yard server`
+
 ## [1.2.0]
 
 Additions:

docs/pages/documentation.md

@@ -11,6 +11,8 @@ $ npm i docsify-cli -g
 $ docsify serve docs
 ```
 
+Documentation available at: http://localhost:3000/
+
 ## Library doc
 
 The output directory of the library documentation will be `docs/yard`.
@@ -24,3 +26,13 @@ For developers who only want to use the library.
 ```plaintext
 $ bundle exec yard doc
 ```
+
+### Serve locally
+
+Serve with live reload:
+
+```
+$ bundle exec yard server --reload
+```
+
+Documentation available at: http://localhost:8808/

docs/pages/examples.md

@@ -120,7 +120,7 @@ TLS_AES_256_GCM_SHA384
 TLS_CHACHA20_POLY1305_SHA256
 TLS_AES_128_GCM_SHA256
 
-$ tls-map extract oldwebsite.json ssllabs-scan 
+$ tls-map extract oldwebsite.json ssllabs-scan
 SSL2.0
 SSL_CK_RC4_128_WITH_MD5
 SSL_CK_DES_192_EDE3_CBC_WITH_MD5
@@ -152,6 +152,31 @@ word so you have to use the `--force` option every time to bypass the security
 check. So it is recommended to not use the update command and wait for official
 release.
 
+### Bulk search
+
+Search and translate cipher names between SSL/TLS libraries **in bulk**
+
+`test/file_sample/bulk_IANA.txt`
+
+```
+TLS_DH_RSA_WITH_AES_256_CBC_SHA
+TLS_RSA_WITH_RC4_128_SHA
+TLS_RSA_WITH_AES_128_CBC_SHA
+TLS_INVALID
+TLS_CHACHA20_POLY1305_SHA256
+TLS_AES_256_GCM_SHA384
+```
+
+```
+$ tls-map bulk iana test/file_sample/bulk_IANA.txt -q openssl
+DH-RSA-AES256-SHA
+RC4-SHA
+AES128-SHA
+
+TLS_CHACHA20_POLY1305_SHA256
+TLS_AES_256_GCM_SHA384
+```
+
 ## Library
 
 Basic usage, searching for cipher name equivalent in other libraries.
@@ -242,7 +267,7 @@ extractor.parse('ssllabs-scan', 'oldwebsite.json')
 
 # Access to all extracted ciphers
 extractor.ciphers
-=> 
+=>
 # {"SSL2.0"=>["SSL_CK_RC4_128_WITH_MD5", "SSL_CK_DES_192_EDE3_CBC_WITH_MD5"],
 #  "SSL3.0"=>["TLS_RSA_WITH_3DES_EDE_CBC_SHA", "TLS_RSA_WITH_RC4_128_SHA", "TLS_RSA_WITH_RC4_128_MD5"],
 #  "TLS1.0"=>
@@ -263,3 +288,26 @@ extractor.ciphers
 extractor.ssl20
 # => ["SSL_CK_RC4_128_WITH_MD5", "SSL_CK_DES_192_EDE3_CBC_WITH_MD5"]
 ```
+
+Search and translate cipher names between SSL/TLS libraries **in bulk**:
+
+```ruby
+require 'tls_map'
+
+tm = TLSmap::App.new
+
+tm.bulk_search(:iana, 'test/file_sample/bulk_IANA.txt', :openssl)
+# => [{:openssl=>"DH-RSA-AES256-SHA"}, {:openssl=>"RC4-SHA"}, {:openssl=>"AES128-SHA"}, {}, {:openssl=>"TLS_CHACHA20_POLY1305_SHA256"}, {:openssl=>"TLS_AES_256_GCM_SHA384"}]
+
+tm.bulk_search(:iana, 'test/file_sample/bulk_IANA.txt', :codepoint)
+# => [{:codepoint=>"0037"}, {:codepoint=>"0005"}, {:codepoint=>"002F"}, {}, {:codepoint=>"1303"}, {:codepoint=>"1302"}]
+
+tm.bulk_search(:iana, 'test/file_sample/bulk_IANA.txt')
+# =>
+# [{:codepoint=>"0037", :iana=>"TLS_DH_RSA_WITH_AES_256_CBC_SHA", :openssl=>"DH-RSA-AES256-SHA", :gnutls=>nil, # :nss=>"TLS_DH_RSA_WITH_AES_256_CBC_SHA"},
+#  {:codepoint=>"0005", :iana=>"TLS_RSA_WITH_RC4_128_SHA", :openssl=>"RC4-SHA", :gnutls=>"RSA_ARCFOUR_128_SHA1", # :nss=>"TLS_RSA_WITH_RC4_128_SHA"},
+#  {:codepoint=>"002F", :iana=>"TLS_RSA_WITH_AES_128_CBC_SHA", :openssl=>"AES128-SHA", :gnutls=>"RSA_AES_128_CBC_SHA1", # :nss=>"TLS_RSA_WITH_AES_128_CBC_SHA"},
+#  {},
+#  {:codepoint=>"1303", :iana=>"TLS_CHACHA20_POLY1305_SHA256", :openssl=>"TLS_CHACHA20_POLY1305_SHA256", # :gnutls=>"CHACHA20_POLY1305_SHA256", :nss=>"TLS_CHACHA20_POLY1305_SHA256"},
+#  {:codepoint=>"1302", :iana=>"TLS_AES_256_GCM_SHA384", :openssl=>"TLS_AES_256_GCM_SHA384", :gnutls=>"AES_256_GCM_SHA384", # :nss=>"TLS_AES_256_GCM_SHA384"}]
+```

docs/pages/quick-start.md

@@ -12,10 +12,11 @@ See [Installation](/pages/install)
 
 ```plaintext
 $ tls-map --help
-TLS map 1.2.0
+TLS map 1.3.0
 
 Usage:
   tls-map search <critera> <term> [-o <output> --force -e -a] [--no-color --debug]
+  tls-map bulk <critera> <file> [-q <output> --force] [--no-color --debug]
   tls-map export <filename> <format> [--force] [--debug]
   tls-map extract <filename> <format> [--no-color --debug]
   tls-map update [--debug]
@@ -29,6 +30,11 @@ Search options: (offline) search and translate cipher names between SSL/TLS libr
   -e, --extended          (Online) Display additional information about the cipher (requires output = all or iana)
   -a, --acronym           (Online) Display full acronym name (requires -e / --extended option)
 
+Bulk options: (offline) search and translate cipher names between SSL/TLS libraries in bulk
+  <critera>               The type of term. Accepted values: codepoint, iana, openssl, gnutls, nss.
+  <file>                  File containing the cipher algorithm names, one per line.
+  -q, --output2 <output>  Displayed fields. Accepted values: codepoint, iana, openssl, gnutls, nss. [default: iana]
+
 Export options: (offline) export the list of all ciphers (mapping) in various formats
   <filename>              The output file name to write to.
   <format>                Supported formats: markdown (a markdown table), json_pretty (expanded JSON), json_compact (minified JSON), marshal (Ruby marshalized hash).
@@ -40,7 +46,7 @@ Extract options: (offline) extract ciphers from external tools output file
 Update options: (online) DANGEROUS, will break database integrity, force option will be required
 
 Other options:
-  --force     Force parsing even if intigrity check failed (DANGEROUS, may result in command execution vulnerability)
+  --force     Force parsing even if integrity check failed (DANGEROUS, may result in command execution vulnerability)
   --no-color  Disable colorized output
   --debug     Display arguments
   -h, --help  Show this screen

docs/pages/usage.md

@@ -4,10 +4,11 @@
 
 ```plaintext
 $ tls-map --help
-TLS map 1.2.0
+TLS map 1.3.0
 
 Usage:
   tls-map search <critera> <term> [-o <output> --force -e -a] [--no-color --debug]
+  tls-map bulk <critera> <file> [-q <output> --force] [--no-color --debug]
   tls-map export <filename> <format> [--force] [--debug]
   tls-map extract <filename> <format> [--no-color --debug]
   tls-map update [--debug]
@@ -21,6 +22,11 @@ Search options: (offline) search and translate cipher names between SSL/TLS libr
   -e, --extended          (Online) Display additional information about the cipher (requires output = all or iana)
   -a, --acronym           (Online) Display full acronym name (requires -e / --extended option)
 
+Bulk options: (offline) search and translate cipher names between SSL/TLS libraries in bulk
+  <critera>               The type of term. Accepted values: codepoint, iana, openssl, gnutls, nss.
+  <file>                  File containing the cipher algorithm names, one per line.
+  -q, --output2 <output>  Displayed fields. Accepted values: codepoint, iana, openssl, gnutls, nss. [default: iana]
+
 Export options: (offline) export the list of all ciphers (mapping) in various formats
   <filename>              The output file name to write to.
   <format>                Supported formats: markdown (a markdown table), json_pretty (expanded JSON), json_compact (minified JSON), marshal (Ruby marshalized hash).
@@ -32,7 +38,7 @@ Extract options: (offline) extract ciphers from external tools output file
 Update options: (online) DANGEROUS, will break database integrity, force option will be required
 
 Other options:
-  --force     Force parsing even if intigrity check failed (DANGEROUS, may result in command execution vulnerability)
+  --force     Force parsing even if integrity check failed (DANGEROUS, may result in command execution vulnerability)
   --no-color  Disable colorized output
   --debug     Display arguments
   -h, --help  Show this screen

lib/tls_map.rb

@@ -55,6 +55,23 @@ def search(critera, term, output = :all)
       {}
     end
 
+    # Search for corresponding cipher algorithms in other libraries in bulk
+    # @param critera [Symbol] The type of `term`.
+    #   Accepted values: `:codepoint`, `:iana`, `:openssl`, `:gnutls`, `:nss`.
+    # @param file [String] File containing the cipher algorithm names, one per line.
+    # @param output [Symbol] The corresponding type to be included in the return value.
+    #   Accepted values: `:all` (default), `:codepoint`, `:iana`, `:openssl`,
+    #   `:gnutls`, `:nss`.
+    # @return [Array<Hash>] The corresponding type, same as {search} return value
+    #   but one per line stored in an array.
+    def bulk_search(critera, file, output = :all)
+      res = []
+      File.foreach(file) do |line|
+        res.push(search(critera, line.chomp, output))
+      end
+      res
+    end
+
     protected :parse
   end
 end

lib/tls_map/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TLSmap
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

test/file_sample/bulk_IANA.txt

@@ -0,0 +1,6 @@
+TLS_DH_RSA_WITH_AES_256_CBC_SHA
+TLS_RSA_WITH_RC4_128_SHA
+TLS_RSA_WITH_AES_128_CBC_SHA
+TLS_INVALID
+TLS_CHACHA20_POLY1305_SHA256
+TLS_AES_256_GCM_SHA384

test/test_app.rb

@@ -17,6 +17,18 @@ def test_App_search
     assert_equal({:codepoint=>"1302", :iana=>"TLS_AES_256_GCM_SHA384", :openssl=>"TLS_AES_256_GCM_SHA384", :gnutls=>"AES_256_GCM_SHA384", :nss=>"TLS_AES_256_GCM_SHA384"}, @tm.search(:nss, 'TLS_AES_256_GCM_SHA384'))
   end
 
+  def test_App_bulk_search
+    res = @tm.bulk_search(:iana, 'test/file_sample/bulk_IANA.txt', :openssl)
+    assert_equal({:openssl=>"DH-RSA-AES256-SHA"}, res[0])
+    assert_equal({:openssl=>"RC4-SHA"}, res[1])
+    assert_equal({:openssl=>"AES128-SHA"}, res[2])
+    assert_equal({}, res[3])
+    res = @tm.bulk_search(:iana, 'test/file_sample/bulk_IANA.txt', :codepoint)
+    assert_equal({:codepoint=>"1303"}, res[4])
+    res = @tm.bulk_search(:iana, 'test/file_sample/bulk_IANA.txt', :iana)
+    assert_equal({:iana=>"TLS_AES_256_GCM_SHA384"}, res[5])
+  end
+
   def test_App_export
     formats = [:markdown, :json_pretty, :json_compact, :marshal]
     formats.each do |format|

tls-map.gemspec

@@ -36,10 +36,11 @@ Gem::Specification.new do |s|
   s.add_development_dependency('bundler', ['>= 2.1.0', '< 2.3'])
   s.add_development_dependency('commonmarker', '~> 0.21') # for GMF support in YARD
   s.add_development_dependency('github-markup', '~> 4.0') # for GMF support in YARD
-  s.add_development_dependency('minitest', '~> 5.12')
-  s.add_development_dependency('minitest-skip', '~> 0.0')
-  s.add_development_dependency('rake', '~> 13.0')
+  s.add_development_dependency('minitest', '~> 5.12') # unit tests
+  s.add_development_dependency('minitest-skip', '~> 0.0') # skip dummy tests
+  s.add_development_dependency('rake', '~> 13.0') # used to run tests
   s.add_development_dependency('redcarpet', '~> 3.5') # for GMF support in YARD
-  s.add_development_dependency('rubocop', '~> 1.10')
+  s.add_development_dependency('rubocop', '~> 1.10') # lint
+  s.add_development_dependency('webrick', '~> 1.7') # for server support in YARD
   s.add_development_dependency('yard', '~> 0.9')
 end