ecies 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33b1046a11dbb7f36abc039da9e124a16f3db9751cfedbc869bde97b01b08091
-  data.tar.gz: 2138b78219252211b76b8f63db73489c94ec7be3cef8c922c689d1cb5ca29a94
+  metadata.gz: b9b17b5e59affac68ce47a7afe053747c90c287201202fffe9a97550644d6c5c
+  data.tar.gz: 161fb791e8f8e67252ce565fa06fd1196228629e45b3ccbc07384b5b9f207a4a
 SHA512:
-  metadata.gz: 233a031a01b0a1db77727ce486b9a419361b69b0a894c2e333c4769772abfc4850d2715db01bccffd8c714b5ae99266e45c9af880313d66c4eabeb24cc1aae99
-  data.tar.gz: 644a95d9c983e7c2b3711f0f89369867cacbd3aa4674237864c35bf312e37e98d58680854d73e118fbb72e21d9cbb1f8e4da60cb5bc5f7ea5b51959604f0e757
+  metadata.gz: df3185e4b726f977a8834c9718f0cbd9ffedec22f00ff597c7d7e877a1a730283b7d8ef66091a0351c3d5c71939cac60196b613a750c822d0d33e0b7d50b3d90
+  data.tar.gz: 148151802478d20abde87b33cfe0765bda7bf1714507c0e6c818105beeb57fcaf55f5735625c42f9cd7d8b524a09c2e5550b7d91c205e74830988c2f5718b503

data/CHANGELOG.md

@@ -4,6 +4,13 @@ Change log
 This gem follows [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html).
 All classes and public methods are part of the public API.
 
+0.2.0
+---
+Release 2018-04-19
+
+- Add support for hex-encoded keys in `Crypt#encrypt` and `Crypt#decrypt` methods.
+- Add new option `ec_group` in `Crypt` constructor.
+
 0.1.0
 ----
 Released on 2018-04-18

data/README.md

@@ -8,6 +8,8 @@ This library implements Elliptical Curve Integrated Encryption System (ECIES), a
 
 ECIES is a public-key encryption scheme based on ECC. It is designed to be semantically secure in the presence of an adversary capable of launching chosen-plaintext and chosen-ciphertext attacks.
 
+ECIES can be used to encrypt messages to bitcoin addresses with keys published on the blockchain, and subsequently to decrypt messages by the holders of the address's private key.
+
 ## Installation
 
 This library is distributed as a gem named [ecies](https://rubygems.org/gems/ecies) at RubyGems.org.  To install it, run:
@@ -38,16 +40,37 @@ encrypted = crypt.encrypt(key, 'secret message')
 Finally, decrypt the message. In order to decrypt, the key must contain the private component.
 
 ```ruby
-crypt.decrypt(key, encrypted) # => 'secret message'
+crypt.decrypt(key, encrypted) # => "secret message"
 ```
 
-When constructing a `Crypt` object, the default hash digest function is 'SHA256', and the default cipher algorithm is 'AES-256-CTR'. You can also specify alternative cipher or digest algorithms. For example:
+### Encrypting a message to a Bitcoin address
+
+Bitcoin P2PKH addresses themselves contain only *hashes* of public keys (hence the name, pay-to-public-key-hash). However, any time a P2PKH output is spent, the public key associated with the address is published on the blockchain in the transaction's scriptSig. This allows you to encrypt a message to any bitcoin address that has sent a transaction (or published its public key in other ways). To demonstrate this, we'll encrypt a message to Satoshi's public key from Bitcoin's genesis block:
 
 ```ruby
-crypt = ECIES::Crypt.new(cipher: 'AES-256-CBC', digest: 'SHA512')
+public_key_hex =
+    "04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb"\
+    "649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5f"
+encrypted = ECIES::Crypt.new.encrypt(public_key_hex, 'you rock!')
 ```
 
-The `Crypt` object must be initialized with the same parameters when encrypting and decrypting messages.
+To decrypt this message, Satoshi would follow these steps:
+
+```ruby
+private_key_hex = "<satoshi's private key>"
+ECIES::Crypt.new.decrypt(private_key_hex, encrypted) # => "you rock!"
+```
+
+### Default parameters
+
+By default, when constructing a new `ECIES::Crypt` object, it will use the following parameters for ECIES:
+
+ - KDF: ANSI-X9.63-KDF with SHA256
+ - MAC: HMAC-SHA-256-128
+ - Cipher: AES-256-CTR
+ - EC Group: secp256k1
+
+These defaults work well for encrypting messages to bitcoin keys. This library also supports alternate algorithms as described in the below 'Compatibility' section. In order to utilize these other algorithms, initialize an `ECIES::Crypt` object with alternate parameters (see the `ECIES::Crypt.new` documentation for details). The `Crypt` object must be initialized with the same parameters when encrypting and decrypting messages.
 
 ## Compatibility
 
@@ -75,7 +98,7 @@ The sec1-v2 document allows for a many combinations of various algorithms for EC
       - HMAC-SHA-256-128
       - HMAC-SHA-256-256
       - HMAC-SHA-384-192
-      - HMAC-SHA-384-384 (I believe sec1-v2 has a typo here, they state "HMAC-SHA-384-284". 284 bits would be 35.5 bytes, which is non-sensical)
+      - HMAC-SHA-384-384 (I believe sec1-v2 has a typo here, they state "HMAC-SHA-384-284". 284 bits would be 35.5 bytes, which is nonsensical)
       - HMAC-SHA-512-256
       - HMAC-SHA-512-512
     - Not supported:
@@ -100,6 +123,14 @@ The sec1-v2 document allows for a many combinations of various algorithms for EC
 
 Ruby 2.0 and above.
 
+## Contributing
+
+Bug reports and pull requests welcome! I happily accept any feedback that can improve this library's security.
+
+## Disclaimer
+
+While I have taken every effort to make this library as secure as possible, it is still an early version and has not yet been reviewed by a wide audience. Use at your own risk.
+
 ## Documentation
 
 For complete documentation, see the [ECIES page on RubyDoc.info](http://rubydoc.info/gems/ecies).

data/ecies.gemspec

@@ -6,6 +6,11 @@ Gem::Specification.new do |s|
   s.authors     = ['Stephen McCarthy']
   s.email       = 'sjmccarthy@gmail.com'
   s.summary     = 'Elliptical Curve Integrated Encryption System (ECIES), as specified by SEC 1 - Ver. 2.0'
+  s.description = <<-DESCRIPTION
+  ECIES is a public-key encryption scheme based on ECC. It can be used to encrypt
+  messages to bitcoin addresses with keys published on the blockchain, and
+  subsequently to decrypt messages by the holders of the address's private key.
+  DESCRIPTION
   s.homepage    = 'https://github.com/jamoes/ecies'
   s.license     = 'MIT'
 

data/lib/ecies/crypt.rb

@@ -27,6 +27,9 @@ module ECIES
     #     length will be equal to half the mac_digest's digest_legnth. If
     #     :full, the mac length will be equal to the mac_digest's
     #     digest_length.
+    # @param ec_group [OpenSSL::PKey::EC::Group,String] The elliptical curve
+    #     group to use when the key is passed in hex form to `encrypt` or
+    #     `decrypt`.
     # @param kdf_digest [String,OpenSSL::Digest,nil] The digest algorithm to
     #     use for KDF. If not specified, the `digest` argument will be used.
     # @param mac_digest [String,OpenSSL::Digest,nil] The digest algorithm to
@@ -35,8 +38,9 @@ module ECIES
     #     info used for KDF, also known as SharedInfo1.
     # @param mac_shared_info [String] Optional. A string containing the shared
     #     info used for MAC, also known as SharedInfo2.
-    def initialize(cipher: 'AES-256-CTR', digest: 'SHA256', mac_length: :half, kdf_digest: nil, mac_digest: nil, kdf_shared_info: '', mac_shared_info: '')
+    def initialize(cipher: 'AES-256-CTR', digest: 'SHA256', mac_length: :half, ec_group: 'secp256k1', kdf_digest: nil, mac_digest: nil, kdf_shared_info: '', mac_shared_info: '')
       @cipher = OpenSSL::Cipher.new(cipher)
+      @ec_group = OpenSSL::PKey::EC::Group.new(ec_group)
       @mac_digest = OpenSSL::Digest.new(mac_digest || digest)
       @kdf_digest = OpenSSL::Digest.new(kdf_digest || digest)
       @kdf_shared_info = kdf_shared_info
@@ -53,10 +57,17 @@ module ECIES
 
     # Encrypts a message to a public key using ECIES.
     #
-    # # @param key [OpenSSL::EC:PKey] The public key.
+    # @param key [OpenSSL::EC:PKey,String] The public key. An OpenSSL::EC:PKey
+    #     containing the public key, or a hex-encoded string representing the
+    #     public key on this Crypt's `ec_group`.
     # @param message [String] The plain-text message.
     # @return [String] The octet string of the encrypted message.
     def encrypt(key, message)
+      if key.is_a?(String)
+        new_key = OpenSSL::PKey::EC.new(@ec_group)
+        new_key.public_key = OpenSSL::PKey::EC::Point.new(@ec_group, OpenSSL::BN.new(key, 16))
+        key = new_key
+      end
       key.public_key? or raise "Must have public key to encrypt"
       @cipher.reset
 
@@ -83,9 +94,17 @@ module ECIES
     # Decrypts a message with a private key using ECIES.
     #
     # @param key [OpenSSL::EC:PKey] The private key.
+    # @param key [OpenSSL::EC:PKey,String] The private key. An OpenSSL::EC:PKey
+    #     containing the private key, or a hex-encoded string representing the
+    #     private key on this Crypt's `ec_group`.
     # @param encrypted_message [String] Octet string of the encrypted message.
     # @return [String] The plain-text message.
     def decrypt(key, encrypted_message)
+      if key.is_a?(String)
+        new_key = OpenSSL::PKey::EC.new(@ec_group)
+        new_key.private_key = OpenSSL::BN.new(key, 16)
+        key = new_key
+      end
       key.private_key? or raise "Must have private key to decrypt"
       @cipher.reset
 

data/lib/ecies/version.rb

@@ -1,4 +1,4 @@
 module ECIES
   # This gem's version.
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/spec/crypt_spec.rb

@@ -12,6 +12,35 @@ describe ECIES::Crypt do
       expect(crypt.decrypt(key, encrypted)).to eq 'secret'
     end
 
+    it 'Supports hex-encoded keys' do
+      key = OpenSSL::PKey::EC.new('secp256k1').generate_key
+      public_key_hex = key.public_key.to_bn.to_s(16)
+      private_key_hex = key.private_key.to_s(16)
+
+      crypt = ECIES::Crypt.new
+
+      encrypted = crypt.encrypt(public_key_hex, 'secret')
+      expect(crypt.decrypt(private_key_hex, encrypted)).to eq 'secret'
+    end
+
+    it 'Supports other EC curves' do
+      key = OpenSSL::PKey::EC.new('secp224k1').generate_key
+      crypt = ECIES::Crypt.new(ec_group: key.group)
+
+      encrypted = crypt.encrypt(key, 'secret')
+      expect(crypt.decrypt(key, encrypted)).to eq 'secret'
+
+      encrypted = crypt.encrypt(key.public_key.to_bn.to_s(16), 'secret')
+      expect(crypt.decrypt(key.private_key.to_s(16), encrypted)).to eq 'secret'
+    end
+
+    it 'Detects invalid hex-encoded points' do
+      key = OpenSSL::PKey::EC.new('secp224k1').generate_key
+      public_key_hex = key.public_key.to_bn.to_s(16)
+
+      expect{ ECIES::Crypt.new.encrypt(public_key_hex, 'secret') }.to raise_error(OpenSSL::PKey::EC::Point::Error)
+    end
+
     it 'Encrypts to known values' do
       OpenSSL::PKey::EC.class_eval do
         # Overwrites `generate_key` for both the test code below, and the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecies
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Stephen McCarthy
@@ -30,7 +30,7 @@ cert_chain:
   kts216EGG4oP6dVuZmf2Ii2F4lQTBDdZM/cisW8jCkO7KeEzJAPhIw1JJwHltHya
   0TpOI3t2Mz/FJ+rudtz9PJ/d8QvhrF7M7+qH4w==
   -----END CERTIFICATE-----
-date: 2018-04-18 00:00:00.000000000 Z
+date: 2018-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -130,7 +130,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
-description: 
+description: |2
+    ECIES is a public-key encryption scheme based on ECC. It can be used to encrypt
+    messages to bitcoin addresses with keys published on the blockchain, and
+    subsequently to decrypt messages by the holders of the address's private key.
 email: sjmccarthy@gmail.com
 executables: []
 extensions: []