Secure Cell passphrase API: RbThemis

CHANGELOG.md

@@ -122,6 +122,42 @@ _Code:_
 - **Ruby**
 
   - New function `Themis::gen_sym_key()` can be used to generate symmetric keys for Secure Cell ([#561](https://github.com/cossacklabs/themis/pull/561)).
+  - Secure Cell API updates ([#603](https://github.com/cossacklabs/themis/pull/603)).
+
+    - RbThemis now supports _passphrase API_ of Secure Cell in Seal mode:
+
+      ```ruby
+      require 'rbthemis'
+
+      cell = Themis::ScellSealPassphrase.new('secret string')
+
+      encrypted = cell.encrypt('message data')
+      decrypted = cell.decrypt(encrypted)
+      ```
+
+      You can safely and securely use human-readable passphrases as text strings with this new API.
+
+      Existing master key API (`Themis::Scell...`) is not secure when used with passphrases. You should use it with symmetric encryption keys, such as generated by `Themis::gen_sym_key` ([#561](https://github.com/cossacklabs/themis/pull/561)).
+
+    - Secure Cell mode can now be selected by instantiating an appropriate subclass:
+
+      | New API | Old API |
+      | ------- | ------- |
+      | `Themis::ScellSeal.new(key)`                  | `Themis::Scell.new(key, Themis::Scell::SEAL_MODE)`            |
+      | `Themis::ScellSealPassphrase.new(passphrase)` | _not available_                                               |
+      | `Themis::ScellTokenProtect.new(key)`          | `Themis::Scell.new(key, Themis::Scell::TOKEN_PROTECT_MODE)`   |
+      | `Themis::ScellContextImprint.new(key`         | `Themis::Scell.new(key, Themis::Scell::CONTEXT_IMPRINT_MODE)` |
+
+      `Themis::Scell` class is **deprecated** and should be replaced with new API.
+
+    - Token Protect mode now accepts encrypted data and token as separate arguments instead of requiring an array:
+
+      ```ruby
+      decrypted = cell.decrypt([encrypted, token], context) # old
+      decrypted = cell.decrypt(encrypted, token, context)   # new
+      ```
+
+      (Arrays are still accepted for compatibility but this API is deprecated.)
 
 - **Rust**
 

docs/examples/ruby/scell_test.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 #
 # Copyright (c) 2015 Cossack Labs Limited
 #
@@ -12,41 +13,48 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-#
 
-#!/usr/bin/env ruby
-
-require 'rubygems'
 require 'rbthemis'
+require 'base64'
 
-key = 'password'
+passphrase = 'open sesame'
+master_key = Themis::gen_sym_key
 context = 'context'
 message = 'test message'
 
-scell_full = Themis::Scell.new(key, Themis::Scell::SEAL_MODE)
-mm = scell_full.encrypt(message, context)
-p mm
-p scell_full.decrypt(mm, context)
-
-mm = scell_full.encrypt(message)
-p mm
-p scell_full.decrypt(mm)
-
-scell_auto_split = Themis::Scell.new(key, Themis::Scell::TOKEN_PROTECT_MODE)
-
-mm, ss = scell_auto_split.encrypt(message, context)
-p mm, ss
-p scell_auto_split.decrypt([mm, ss], context)
-
-mm = scell_auto_split.encrypt(message)
-p mm
-p scell_auto_split.decrypt(mm)
-
-scell_user_split = Themis::Scell.new(key, Themis::Scell::CONTEXT_IMPRINT_MODE)
-mm = scell_user_split.encrypt(message, context)
-p mm
-p scell_user_split.decrypt(mm, context)
-
-# mm = scell_user_split.encrypt(message)
-# p mm
-# p scell_user_split.decrypt(mm)
+puts "Secure Cell - Seal mode (master key)"
+scell = Themis::ScellSeal.new(master_key)
+encrypted = scell.encrypt(message, context)
+decrypted = scell.decrypt(encrypted, context)
+puts "Encoded:   #{Base64.encode64 message}"
+puts "Encrypted: #{Base64.encode64 encrypted}"
+puts "Decrypted: #{decrypted}"
+puts
+
+puts "Secure Cell - Seal mode (passphrase)"
+scell = Themis::ScellSealPassphrase.new(passphrase)
+encrypted = scell.encrypt(message, context)
+decrypted = scell.decrypt(encrypted, context)
+puts "Encoded:   #{Base64.encode64 message}"
+puts "Encrypted: #{Base64.encode64 encrypted}"
+puts "Decrypted: #{decrypted}"
+puts
+
+puts "Secure Cell - Token Protect mode"
+scell = Themis::ScellTokenProtect.new(master_key)
+encrypted, token = scell.encrypt(message, context)
+decrypted = scell.decrypt(encrypted, token, context)
+puts "Encoded:   #{Base64.encode64 message}"
+puts "Encrypted: #{Base64.encode64 encrypted}"
+puts "Token:     #{Base64.encode64 token}"
+puts "Decrypted: #{decrypted}"
+puts
+
+puts "Secure Cell - Context Imprint mode"
+scell = Themis::ScellContextImprint.new(master_key)
+encrypted = scell.encrypt(message, context)
+decrypted = scell.decrypt(encrypted, context)
+puts "Encoded:   #{Base64.encode64 message}"
+puts "Encrypted: #{Base64.encode64 encrypted}"
+puts "Decrypted: #{decrypted}"
+puts