saltpack 0.1.0.pre.20200506181314

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 00f82f95cf674c68df8092b2bf5c8ec467edebf53bf617874fe5207aa7be30f5
+  data.tar.gz: 4567c6a8b231262759793746d3a88b13b27eac5d166cb8441e9b3e32512ada80
+SHA512:
+  metadata.gz: f00b2a1e3accb96737555074bdcb6b08186b6b52c623de55ef3b75129ac57a37de4ffe3984e36aaac63c4cc6cdb140a0b4588f5851d3c972bb4d2b71d1daeee0
+  data.tar.gz: 1dc2f735ae85c06d9bb2ef42b7364f66c6c0659a08755fd4dc6e501d2574d7a7b77301fe7dbeee2d45f1e12d0b9be308850a0ace6b4d906d7c5d468dc37ab512

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+README.md
+ChangeLog.md
+
+LICENSE.txt

data/.rdoc_options

@@ -0,0 +1,16 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+static_path: []
+rdoc_include:
+  - .
+charset: UTF-8
+exclude: 
+hyperlink_all: false
+line_numbers: false
+main_page: README.md
+markup: markdown
+show_hash: false
+tab_width: 8
+title: Saltpack Documentation
+visibility: :protected
+webcvs:

data/.simplecov

@@ -0,0 +1,9 @@
+# Simplecov config
+
+SimpleCov.start do
+	add_filter 'spec'
+	add_filter 'integration'
+	add_group "Needing tests" do |file|
+		file.covered_percent < 90
+	end
+end

data/ChangeLog

@@ -0,0 +1,55 @@
+2019-09-10  Michael Granger  <ged@FaerieMUD.org>
+
+@  	* lib/saltpack.rb, lib/saltpack/header.rb, lib/saltpack/message.rb:
+|  	Start refactoring the Header parts
+|  	[472adffb8160] [tip]
+|
+2019-08-05  Michael Granger  <ged@FaerieMUD.org>
+
+o  	* Manifest.txt, Rakefile, examples/post_signed_message.rb,
+|  	lib/saltpack.rb, lib/saltpack/armor.rb, lib/saltpack/header.rb,
+|  	lib/saltpack/message.rb, spec/data/msg1-ciphertext.txt,
+|  	spec/data/msg1.txt, spec/saltpack/armor_spec.rb,
+|  	spec/saltpack_spec.rb, spec/spec_helper.rb:
+|  	Start splitting out the mega-methods
+|  	[11c1e2a2a876]
+|
+2019-07-05  Michael Granger  <ged@FaerieMUD.org>
+
+o  	* LICENSE.txt, lib/saltpack.rb, lib/saltpack/header.rb,
+|  	spec/saltpack_spec.rb:
+|  	More work on the header and specs
+|  	[ae40008f4913]
+|
+o  	* .gems, .ruby-version, README.md, Rakefile, lib/saltpack.rb,
+|  	lib/saltpack/errors.rb, lib/saltpack/header.rb,
+|  	lib/saltpack/message.rb, lib/saltpack/payload.rb,
+|  	lib/saltpack/refinements.rb, spec/saltpack_spec.rb,
+|  	spec/spec_helper.rb:
+|  	Checkpoint of work on encrypt/decrypt
+|  	[93ec1ec832de]
+|
+2019-07-02  Michael Granger  <ged@FaerieMUD.org>
+
+o  	* lib/saltpack/header.rb, spec/saltpack/header_spec.rb:
+|  	Add work on Header.generate
+|  	[f36117158674]
+|
+2018-10-29  Michael Granger  <ged@FaerieMUD.org>
+
+o  	* .gems, .hgignore, .ruby-version, README.md, Rakefile,
+|  	examples/post_signed_message.rb, lib/saltpack.rb,
+|  	lib/saltpack/errors.rb, lib/saltpack/header.rb,
+|  	lib/saltpack/recipient.rb, saltpack.gemspec,
+|  	spec/saltpack/header_spec.rb, spec/saltpack/recipient_spec.rb:
+|  	Add project files, recipient and header classes
+|  	[4a279ccbc93b]
+|
+2018-10-23  Michael Granger  <ged@FaerieMUD.org>
+
+o  	* .document, .editorconfig, .gems, .hgignore, .pryrc, .rdoc_options,
+   	.ruby-gemset, .ruby-version, .simplecov, Gemfile, History.md,
+   	LICENSE.txt, Manifest.txt, README.md, Rakefile, certs/ged.pem,
+   	lib/saltpack.rb, spec/saltpack_spec.rb, spec/spec_helper.rb:
+   	Initial commit.
+   	[7fbbd4e46123]

data/History.md

@@ -0,0 +1,4 @@
+## v0.0.1 [YYYY-MM-DD] Michael Granger <ged@FaerieMUD.org>
+
+Initial release.
+

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright © 2018-2019 Michael Granger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,25 @@
+.document
+.rdoc_options
+.simplecov
+ChangeLog
+History.md
+LICENSE.txt
+Manifest.txt
+README.md
+Rakefile
+examples/post_signed_message.rb
+lib/saltpack.rb
+lib/saltpack/armor.rb
+lib/saltpack/errors.rb
+lib/saltpack/header.rb
+lib/saltpack/message.rb
+lib/saltpack/payload.rb
+lib/saltpack/recipient.rb
+lib/saltpack/refinements.rb
+spec/data/msg1-ciphertext.txt
+spec/data/msg1.txt
+spec/saltpack/armor_spec.rb
+spec/saltpack/header_spec.rb
+spec/saltpack/recipient_spec.rb
+spec/saltpack_spec.rb
+spec/spec_helper.rb

data/README.md

@@ -0,0 +1,89 @@
+# Saltpack
+
+home
+: https://hg.sr.ht/~ged/Saltpack
+
+github
+: https://github.com/ged/saltpack-ruby
+
+docs
+: https://deveiate.org/code/saltpack
+
+
+## Description
+
+A Ruby implementation of Saltpack, a modern crypto messaging format based on Dan Bernstein's [NaCl][].
+
+See also: <https://saltpack.org/>
+
+
+## Prerequisites
+
+* Ruby
+
+
+## Installation
+
+    $ gem install saltpack
+
+
+## Contributing
+
+You can check out the current development source with Mercurial via its
+[project page][saltpack-ruby]. Or if you prefer Git, via 
+[its Github mirror][github-mirror].
+
+After checking out the source, run:
+
+    $ gem install -Ng
+    $ rake setup
+
+This task will install any missing dependencies and do any necessary developer
+setup.
+
+
+## Authors
+
+- Michael Granger <ged@faeriemud.org>
+
+
+## License
+
+Large portions of this library are ported from the [saltpack-python][] library by
+Jack O'Connor &lt;oconnor663+pypi@gmail.com&gt;, used under the terms of the MIT
+License. No license statement is included in the source, but I'm assuming it's
+something like:
+
+> Copyright © 2018 Jack O'Connor
+>
+> Permission is hereby granted, free of charge, to any person obtaining
+> a copy of this software and associated documentation files (the
+> “Software”), to deal in the Software without restriction, including
+> without limitation the rights to use, copy, modify, merge, publish,
+> distribute, sublicense, and/or sell copies of the Software, and to
+> permit persons to whom the Software is furnished to do so, subject to
+> the following conditions:
+>
+> The above copyright notice and this permission notice shall be
+> included in all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY
+> KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+> WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+> NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+> LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+> OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+> WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+The port and the rest of the code is:
+
+Copyright © 2018-2019, Michael Granger
+All rights reserved.
+
+And is also distributed under the terms of the MIT license.
+
+
+[NaCl]: https://nacl.cr.yp.to/
+[saltpack-ruby]: https://hg.sr.ht/~ged/Saltpack
+[github-mirror]: https://github.com/ged/saltpack-ruby
+[saltpack-python]: https://github.com/keybase/saltpack-python

data/Rakefile

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby -S rake
+
+require 'rake/deveiate'
+
+Rake::DevEiate.setup( 'saltpack' ) do |project|
+	project.publish_to = 'deveiate:/usr/local/www/public/code'
+	project.licenses = [ 'MIT' ]
+end
+

data/examples/post_signed_message.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+
+require 'rbnacl'
+require 'saltpack'
+
+key1 = RbNaCl::PrivateKey.
+	new( ["1e42fd5f0ba92398e6e87b633d06987467f237caac217693c7ee14056f153b3a"].pack('h*') )
+key2 = RbNaCl::PrivateKey.
+	new( ["3d8ff66ec5d042a41fdcc93e57b909647e9017a6599f8120dd1726a4772a0626"].pack('h*') )
+
+msg = Saltpack::Message.new( 'Hey, want to get a beer later?', from: key1, to: key2 )
+
+msg.add_recipient( key3 )
+# -or-
+msg.add_anonymous_recipient( key3 )
+
+puts msg.encrypt
+# -or-
+puts msg.encrypt( armor: true )
+
+

data/lib/saltpack.rb

@@ -0,0 +1,112 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'rbnacl'
+require 'loggability'
+
+
+# Saltpack -- a modern crypto messaging format based on Dan Bernstein's NaCl.
+#
+# Refs:
+# - https://saltpack.org/
+# - https://nacl.cr.yp.to/
+module Saltpack
+	extend Loggability
+
+	# Package version
+	VERSION = '0.0.1'
+
+	# Version control revision
+	REVISION = %q$Revision: e216e8bc10bb $
+
+	# The default options for the ::encrypt/::decrypt methods.
+	DEFAULT_ENCRYPTION_OPTIONS = {
+		chunk_size: 10 ** 6,
+		visible_recipients: false,
+	}
+
+	# The 32-byte zero string used to create the recipient hashes/MAC keys
+	ZEROS_32 = RbNaCl::Util.zeros( 32 )
+
+
+	# Create a logger for this library
+	log_as :saltpack
+
+
+	require 'saltpack/errors'
+
+	autoload :Armor, 'saltpack/armor'
+	autoload :Header, 'saltpack/header'
+	autoload :Message, 'saltpack/message'
+	autoload :Payload, 'saltpack/payload'
+	autoload :Recipient, 'saltpack/recipient'
+
+
+	### Encrypt the given +message+ for the given +recipient_public_keys+ using the
+	### +sender_key+.
+	def self::encrypt( message, sender_key, *recipient_public_keys, **options )
+		msg = Saltpack::Message.new( message, sender_key, *recipient_public_keys, **options )
+		return msg.to_s
+	end
+
+
+	### Decrypt the given +message+ with the specified +recipient_key+.
+	def self::decrypt( message, recipient_key )
+		msg = Saltpack::Message.read( message, recipient_key )
+		return msg.decrypt
+	end
+
+
+	### Return the +input_bytes+ ascii-armored using the specified +options+
+	def self::armor( input, **options )
+		return Saltpack::Armor.armor( input, **options )
+	end
+
+
+	### Decode the ascii-armored data from the specified +input_chars+ using
+	### the given +options+.
+	def self::dearmor( input_chars, **options )
+		return Saltpack::Armor.dearmor( input_chars, **options )
+	end
+
+
+	#
+	# Utility functions
+	#
+
+	### Calculate a MAC hash for the recipient at the given +index+ given the specified
+	### +header_hash+, and the two keypairs.
+	def self::calculate_recipient_hash( header_hash, index, keypair1, keypair2 )
+
+		# 9. Concatenate the first 16 bytes of the header hash from step 7 above, with the
+		# recipient index from step 4 above. This is the basis of each recipient's MAC
+		# nonce.
+		mac_key_nonce_prefix = header_hash[0, 16]
+		basis = mac_key_nonce_prefix + [ index ].pack('Q>')
+
+		# Clear the least significant bit of byte 15. That is: nonce[15] &= 0xfe.
+		nonce1 = basis.dup
+		nonce1[15] = (nonce1[15].ord & 0xfe).chr
+
+		# Modify the nonce from step 10 by setting the least significant bit of byte
+		# That is: nonce[15] |= 0x01.
+		nonce2 = basis.dup
+		nonce2[15] = (nonce2[15].ord | 0x01).chr
+
+		# Encrypt 32 zero bytes using crypto_box with the recipient's public key, the
+		# sender's long-term private key, and the nonce from the previous step.
+		# Encrypt 32 zero bytes again, as in step 11, but using the ephemeral private
+		# key rather than the sender's long term private key.
+		box1 = RbNaCl::Box.new( *keypair1 ).encrypt( nonce1, ZEROS_32 )
+		box2 = RbNaCl::Box.new( *keypair2 ).encrypt( nonce2, ZEROS_32 )
+
+		# Concatenate the last 32 bytes each box from steps 11 and 13. Take the SHA512
+		# hash of that concatenation. The recipient's MAC Key is the first 32 bytes of
+		# that hash.
+		mac_hash = RbNaCl::Hash.sha512( box1[-16..] + box2[-16..] )
+
+		return mac_hash[ 0, 32 ]
+	end
+
+end # module Saltpack
+

data/lib/saltpack/armor.rb

@@ -0,0 +1,211 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'loggability'
+
+require 'saltpack' unless defined?( Saltpack )
+
+
+# Utility functions for armoring and dearmoring.
+module Saltpack::Armor
+	extend Loggability
+
+
+	# The Base64 alphabet
+	B64ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+	# The Base62 alphabet
+	B62ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+	# The Base85 alphabet
+	B85ALPHABET = "!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ" \
+	    "[\\]^_`abcdefghijklmnopqrstu"
+
+	# The default options used by the ::armor/::dearmor methods.
+	DEFAULT_OPTIONS = {
+		alphabet: B62ALPHABET,
+		block_size: 32,
+		char_block_size: 43,
+		raw: false,
+		shift: false,
+		message_type: 'MESSAGE',
+	}
+
+
+	# Loggability -- use the saltpack logger
+	log_to :saltpack
+
+
+	### Given a String-like object, return an Enumerator that will yield successive slices
+	### of the specified +chunk_size+.
+	def self::slice_enum_for( string, chunk_size )
+		string = string.dup.freeze
+		stepper = ( 0 .. string.length ).step( chunk_size )
+		return stepper.lazy.map {|i| string.slice(i, chunk_size) }
+	end
+
+
+	### Return the index of the specified +char+ in +alphabet+, raising an
+	### appropriate error if it is not found.
+	def self::get_char_index( alphabet, char )
+        rval = alphabet.index( char ) or
+			raise IndexError, "Could not find %p in alphabet %p." % [ char, alphabet ]
+		return rval
+	end
+
+
+	### Return the minimum number of characters needed to encode +bytes_size+ bytes
+	### using the given +alphabet+.
+	def self::character_block_size( alphabet_size, bytes_size )
+	    return ( 8 * bytes_size / Math.log2(alphabet_size) ).ceil
+	end
+
+
+	### Return the maximum number of bytes needed to encode +chars_size+ characters
+	### using the given +alphabet+.
+	def self::max_bytes_size( alphabet_size, chars_size )
+	    return ( Math.log2(alphabet_size) / 8 * chars_size ).floor
+	end
+
+
+	### Return the number of bits left over after using an alphabet of the specified
+	### +alphabet_size+ to encode a payload of +bytes_size+ with +chars_size+
+	### characters.
+	def self::extra_bits( alphabet_size, chars_size, bytes_size )
+	    total_bits = ( Math.log2(alphabet_size) * chars_size ).floor
+	    return total_bits - 8 * bytes_size
+	end
+
+
+	###############
+	module_function
+	###############
+
+	### Return the +input_bytes+ ascii-armored using the specified +options+
+	def armor( input, **options )
+		options = Saltpack::Armor::DEFAULT_OPTIONS.merge( options )
+		slicer = Saltpack::Armor.slice_enum_for( input, options[:block_size] )
+
+		output = slicer.
+			each_with_object( String.new(encoding: 'us-ascii') ) do |chunk, buf|
+				buf << Saltpack::Armor.encode_block( chunk, options[:alphabet], options[:shift] )
+			end
+
+		self.log.debug "Armor output: %p" % [ output ]
+
+		if options[:raw]
+			out_slicer = Saltpack::Armor.slice_enum_for( output, 43 )
+			return out_slicer.to_a.join( ' ' )
+		end
+
+		word_slicer = Saltpack::Armor.slice_enum_for( output, 15 )
+		sentences = word_slicer.each_slice( 200 )
+
+		joined = sentences.map {|words| words.to_a.join(' ') }.to_a.join( "\n" )
+		header = "BEGIN SALTPACK %s. " % [ options[:message_type] ]
+		footer = ". END SALTPACK %s." % [ options[:message_type] ]
+
+		return header + joined + footer
+	end
+
+
+	### Decode the ascii-armored data from the specified +input_chars+ using
+	### the given +options+.
+	def dearmor( input, **options )
+		options = Saltpack::Armor::DEFAULT_OPTIONS.merge( options )
+
+		unless options[:raw]
+			_header, input, _footer = input.split( '.', 3 )
+			self.log.debug "Stripped input: %p" % [ input ]
+		end
+
+		input = input.gsub( /\p{Space}+/, '' )
+		chunks = Saltpack::Armor.slice_enum_for( input, options[:char_block_size] )
+
+		output = String.new( encoding: 'binary' )
+		chunks.each do |chunk|
+			output << Saltpack::Armor.decode_block( chunk, options[:alphabet], options[:shift] )
+		end
+
+		return output
+	end
+
+
+	### Encode a single block of ascii-armored output from +bytes_block+ using the
+	### specified +alphabet+ and +shift+.
+	def encode_block( bytes_block, alphabet=Saltpack::Armor::B62ALPHABET, shift=false )
+		block_size = Saltpack::Armor.character_block_size( alphabet.length, bytes_block.length )
+		extra = Saltpack::Armor.extra_bits( alphabet.length, block_size, bytes_block.length )
+
+		# Convert the bytes into an integer, big-endian.
+		bytes_int = bytes_block.unpack1( 'H*' ).hex
+
+		# Shift left by the extra bits.
+		bytes_int <<= extra if shift
+
+		# Convert the result into our base.
+		places = []
+		( 0 ... block_size ).each do |place|
+			rem = bytes_int % alphabet.length
+			places.unshift( rem )
+			bytes_int /= alphabet.length
+		end
+
+		return places.map {|i| alphabet[i] }.join
+	end
+
+
+	### Decode the specified ascii-armored +chars_block+ using the specified
+	### +alphabet+ and +shift+.
+	def decode_block( chars_block, alphabet=Saltpack::Armor::B62ALPHABET, shift=false )
+	    bytes_size = Saltpack::Armor.max_bytes_size( alphabet.length, chars_block.length )
+	    expected_block_size = Saltpack::Armor.character_block_size( alphabet.length, bytes_size )
+
+		self.log.debug "For %p with an alphabet of %d chars: bytes_size=%d; expected_block_size=%d" %
+			[ chars_block, alphabet.length, bytes_size, expected_block_size ]
+
+		raise ArgumentError, "illegal block size %d, expected %d" %
+			[ chars_block.length, expected_block_size ] unless
+				chars_block.length == expected_block_size
+
+	    extra = Saltpack::Armor.extra_bits( alphabet.length, chars_block.length, bytes_size )
+
+	    # Convert the chars to an integer.
+	    bytes_int = Saltpack::Armor.get_char_index( alphabet, chars_block[0] )
+		chars_block[ 1.. ].chars.each do |char|
+	        bytes_int *= alphabet.length
+	        bytes_int += Saltpack::Armor.get_char_index( alphabet, char )
+		end
+
+	    # Shift right by the extra bits.
+	    bytes_int >>= extra if shift
+
+		return [ bytes_int.to_s(16) ].pack( 'H*' )
+	end
+
+
+	### Return a table of the most efficient number of characters to use between 1
+	### and +chars_size_upper_bound+ using an alphabet of +alphabet_size+. Each row
+	### of the resulting Array will be a tuple of:
+	###
+	###     [ character_size, byte_size, efficiency ]
+	def efficient_chars_sizes( alphabet_size, chars_size_upper_bound=50 )
+	    out = []
+	    max_efficiency = 0.0
+
+		( 1..chars_size_upper_bound ).each do |chars_size|
+			bytes_size = Saltpack::Armor.max_bytes_size( alphabet_size, chars_size )
+			efficiency = bytes_size / chars_size.to_f
+			self.log.debug "Efficiency for %d/%d: %0.3f" % [ bytes_size, chars_size, efficiency ]
+
+			if efficiency > max_efficiency
+				out << [ chars_size, bytes_size, efficiency ]
+				max_efficiency = efficiency
+			end
+		end
+
+		return out
+	end
+
+end # module Saltpack::Armor
+