README.md in slosilo-1.1.0 vs README.md in slosilo-2.0.0

@@ -1,10 +1,10 @@
 # Slosilo
 
 Slosilo is providing a ruby interface to some cryptographic primitives:
 - symmetric encryption,
-- a mixin for easy encryption of object attributes (WARNING: unauthenticated, see below),
+- a mixin for easy encryption of object attributes,
 - asymmetric encryption and signing,
 - a keystore in a postgres sequel db -- it allows easy storage and retrieval of keys,
 - a keystore in files.
 
 ## Installation
@@ -15,37 +15,57 @@
 
 And then execute:
 
     $ bundle
 
+## Compatibility
+
+Version 2.0 introduced new symmetric encryption scheme using AES-256-GCM
+for authenticated encryption. It allows you to provide AAD on all symmetric
+encryption primitives. It's also **NOT COMPATIBLE** with CBC used in version <2.
+
+This means you'll have to migrate all your existing data. There's no easy way to
+do this currently provided; it's recommended to create a database migration and
+put relevant code fragments in it directly. (This will also have the benefit of making
+the migration self-contained.)
+
+Since symmetric encryption is used in processing asymetrically encrypted messages,
+this incompatibility extends to those too.
+
 ## Usage
 
 ### Symmetric encryption
 
 ```ruby
 sym = Slosilo::Symmetric.new
 key = sym.random_key
-ciphertext = sym.encrypt "secret message", key: key
+# additional authenticated data
+message_id = "message 001"
+ciphertext = sym.encrypt "secret message", key: key, aad: message_id
 ```
 
 ```ruby
 sym = Slosilo::Symmetric.new
-message = sym.decrypt ciphertext, key: key
+message = sym.decrypt ciphertext, key: key, aad: message_id
 ```
 
 ### Encryption mixin
 
 ```ruby
 require 'slosilo'
 
 class Foo
   attr_accessor :foo
-  attr_encrypted :foo
+  attr_encrypted :foo, aad: :id
 
   def raw_foo
     @foo
   end
+
+  def id
+    "unique record id"
+  end
 end
 
 Slosilo::encryption_key = Slosilo::Symmetric.new.random_key
 
 obj = Foo.new
@@ -53,16 +73,9 @@
 obj.raw_foo # => "\xC4\xEF\x87\xD3b\xEA\x12\xDF\xD0\xD4hk\xEDJ\v\x1Cr\xF2#\xA3\x11\xA4*k\xB7\x8F\x8F\xC2\xBD\xBB\xFF\xE3"
 obj.foo # => "bar"
 ```
 
 You can safely use it in ie. ActiveRecord::Base or Sequel::Model subclasses.
-
-#### Warning
-
-The encrypted data is not authenticated; it's intended to prevent
-opportunistic access to secrets by a third party which gets hold of a database
-dump. *IT DOES NOT prevent tampering.* If your threat model includes an attacker
-which can modify the database, `attr_encrypted` by itself IS NOT SECURE.
 
 ### Asymmetric encryption and signing
 
 ```ruby
 private_key = Slosilo::Key.new