e3db 2.0.0 → 2.1.1

data/examples/simple.rb

@@ -58,10 +58,6 @@ end
 isaac_client_id = 'db1744b9-3fb6-4458-a291-0bc677dba08b'
 client.share('test-contact', isaac_client_id)
 
-# Share all of the records of type 'test-contact' with Isaac's email address.
-# This only works if the client has opted into discovery of their client_id.
-client.share('test-contact', 'ijones+feedback@tozny.com')
-
 # ---------------------------------------------------------
 # More complex queries
 # ---------------------------------------------------------
@@ -106,38 +102,19 @@ end
 # ---------------------------------------------------------
 # Learning about other clients
 # ---------------------------------------------------------
-isaac_client_info = client.client_info('ijones+feedback@tozny.com')
+isaac_client_info = client.client_info(isaac_client_id)
 puts isaac_client_info.inspect
 
 # Fetch the public key:
 isaac_pub_key = client.client_key(isaac_client_id)
 puts isaac_pub_key.inspect
 
-# ---------------------------------------------------------
-# More reading and inspection of records
-# ---------------------------------------------------------
-
-# read_raw gets a record without decrypting its data
-rawRecord = client.read_raw(record_id)
-newRecord = client.read(record_id)
-
-# So let's compare them:
-
-puts (rawRecord.meta == newRecord.meta).to_s # true
-puts (rawRecord.data == newRecord.data).to_s # false
-
-puts newRecord.data[:name] + ' encrypts to ' + rawRecord.data[:name]
-
-# Records contain a few other fields that are fun to look at, and this gives
-# you a good sense for what's encrypted and what's not:
-puts rawRecord.inspect
-
 # ---------------------------------------------------------
 # Clean up - Comment these out if you want to experiment
 # ---------------------------------------------------------
 
 # Revoke the sharing created by the client.share
-client.revoke('test-contact', 'ijones+feedback@tozny.com')
+client.revoke('test-contact', isaac_client_id)
 
 # Delete the record we created above
 client.delete(record_id)

data/lib/e3db.rb

@@ -9,8 +9,8 @@
 require 'e3db/version'
 require 'e3db/types'
 require 'e3db/config'
-require 'e3db/client'
 require 'e3db/crypto'
+require 'e3db/client'
 
 # Ruby client library for the Tozny End-to-End Encrypted Database (E3DB) service.
 #

data/lib/e3db/client.rb

@@ -40,7 +40,12 @@ module E3DB
   # the affected record and retry the update operation.
   class ConflictError < StandardError
     def initialize(record)
-      super('Conflict updating record: ' + record.meta.record_id)
+      if record.is_a? E3DB::Record
+        super('Conflict updating record: ' + record.meta.record_id)
+      else
+        super('Conflict updating record: ' + record)
+      end
+
       @record = record
     end
 
@@ -66,12 +71,34 @@ module E3DB
   #   @return [String] the client's unique ID string
   # @!attribute public_key
   #   @return [PublicKey] the client's public key information
+  # @!attribute validated
+  #   @return [Bool]
   class ClientInfo < Dry::Struct
     attribute :client_id, Types::Strict::String
     attribute :public_key, PublicKey
     attribute :validated, Types::Strict::Bool
   end
 
+  # Information about a newly-created E3DB client
+  #
+  # @!attribute client_id
+  #   @return [String] the client's unique ID string
+  # @!attribute api_key_id
+  #   @return [String]
+  # @!attribute api_secret
+  #   @return [String]
+  # @!attribute public_key
+  #   @return [PublicKey] the client's public key information
+  # @!attribute name
+  #   @return [String] the client's name.
+  class ClientDetails < Dry::Struct
+    attribute :client_id, Types::Strict::String
+    attribute :api_key_id, Types::Strict::String
+    attribute :api_secret, Types::Strict::String
+    attribute :public_key, PublicKey
+    attribute :name, Types::Strict::String
+  end
+
   # Meta-information about an E3DB record, such as who wrote it,
   # when it was written, and the type of data stored.
   #
@@ -166,23 +193,99 @@ module E3DB
     attribute :record_type, Types::Strict::String
   end
 
+  # Represents an "encrypted access key" that can be used to encrypt
+  # and decrypt records.
+  #
+  # Should only be obtained by calling {Client#create_writer_key} or
+  # {Client#get_reader_key}.
+  #
+  # To serialize to JSON (for storage), use `JSON.dump(eak.to_hash)`. 
+  # To load from JSON, use `E3DB::EAK.new(JSON.parse(eak, symbolize_names: true))`.
+  class EAK < Dry::Struct
+    attribute :eak, Types::Strict::String
+    attribute :authorizer_public_key, PublicKey
+    attribute :authorizer_id, Types::Strict::String
+  end
+
   # A connection to the E3DB service used to perform database operations.
   #
   # @!attribute [r] config
   #   @return [Config] the client configuration object
   class Client
+    include Crypto
+    class << self
+      include Crypto
+    end
+
     attr_reader :config
 
+    # Register a new client with a specific account given that account's registration token
+    #
+    # @param registration_token [String]  Token for a specific InnoVault account
+    # @param client_name        [String]  Unique name for the client being registered
+    # @param public_key         [String]  Base64URL-encoded public key component of a Curve25519 keypair
+    # @param private_key        [String]  Optional Base64URL-encoded private key component of a Curve25519 keypair
+    # @param backup             [Boolean] Optional flag to automatically back up the newly-created credentials to the account service
+    # @param api_url            [String]  Optional URL of the API against which to register
+    # @return [ClientDetails] Credentials and details about the newly-created client
+    def self.register(registration_token, client_name, public_key, private_key=nil, backup=false, api_url=E3DB::DEFAULT_API_URL)
+      url = "#{api_url.chomp('/')}/v1/account/e3db/clients/register"
+      payload = JSON.generate({:token => registration_token, :client => {:name => client_name, :public_key => {:curve25519 => public_key}}})
+
+      conn = Faraday.new(api_url) do |faraday|
+        faraday.request :json
+        faraday.response :raise_error
+        faraday.adapter :net_http_persistent
+      end
+
+      resp = conn.post(url, payload)
+      client_info = ClientDetails.new(JSON.parse(resp.body, symbolize_names: true))
+      backup_client_id = resp.headers['x-backup-client']
+
+      if backup
+        if private_key.nil?
+          raise 'Cannot back up client credentials without a private key!'
+        end
+
+        # Instantiate a client
+        config = E3DB::Config.new(
+            :version      => 1,
+            :client_id    => client_info.client_id,
+            :api_key_id   => client_info.api_key_id,
+            :api_secret   => client_info.api_secret,
+            :client_email => '',
+            :public_key   => public_key,
+            :private_key  => private_key,
+            :api_url      => api_url,
+            :logging      => false
+        )
+        client = E3DB::Client.new(config)
+
+        # Back the client up
+        client.backup(backup_client_id, registration_token)
+      end
+
+      client_info
+    end
+
+    # Generate a random Curve25519 keypair.
+    #
+    # @return [Array<String>] A two element array containing the public and private keys (respectively) for the new keypair.
+    def self.generate_keypair
+      keys = RbNaCl::PrivateKey.generate
+
+      return encode_public_key(keys.public_key), encode_private_key(keys)
+    end
+
     # Create a connection to the E3DB service given a configuration.
     #
     # @param config [Config] configuration and credentials to use
     # @return [Client] a connection to the E3DB service
     def initialize(config)
       @config = config
-      @public_key = RbNaCl::PublicKey.new(Crypto.base64decode(@config.public_key))
-      @private_key = RbNaCl::PrivateKey.new(Crypto.base64decode(@config.private_key))
+      @public_key = RbNaCl::PublicKey.new(base64decode(@config.public_key))
+      @private_key = RbNaCl::PrivateKey.new(base64decode(@config.private_key))
 
-      @ak_cache = LruRedux::ThreadSafeCache.new(1024)
       @oauth_client = OAuth2::Client.new(
           config.api_key_id,
           config.api_secret,
@@ -204,17 +307,17 @@ module E3DB
         end
         faraday.adapter :net_http_persistent
       end
+
+      @ak_cache = LruRedux::ThreadSafeCache.new(1024)
     end
 
     # Query the server for information about an E3DB client.
     #
-    # @param client_id [String] client ID or e-mail address to look up
+    # @param client_id [String] client ID to look up
     # @return [ClientInfo] information about this client
     def client_info(client_id)
       if client_id.include? "@"
-        base_url = get_url('v1', 'storage', 'clients', 'find')
-        url = base_url + sprintf('?email=%s', CGI.escape(client_id))
-        resp = @conn.post(url)
+        raise "Client discovery by email is not supported!"
       else
         resp = @conn.get(get_url('v1', 'storage', 'clients', client_id))
       end
@@ -230,27 +333,32 @@ module E3DB
       if client_id == @config.client_id
         @public_key
       else
-        Crypto.decode_public_key(client_info(client_id).public_key.curve25519)
+        decode_public_key(client_info(client_id).public_key.curve25519)
       end
     end
 
-    # Read a single record by ID from E3DB and return it without
-    # decrypting the data fields.
-    #
-    # @param record_id [String] record ID to look up
-    # @return [Record] encrypted record object
-    def read_raw(record_id)
-      resp = @conn.get(get_url('v1', 'storage', 'records', record_id))
-      json = JSON.parse(resp.body, symbolize_names: true)
-      Record.new(json)
-    end
-
     # Read a single record by ID from E3DB and return it.
     #
     # @param record_id [String] record ID to look up
+    # @param fields    [Array]  Optional array of fields to filter
     # @return [Record] decrypted record object
-    def read(record_id)
-      decrypt_record(read_raw(record_id))
+    def read(record_id, fields = nil)
+      path = get_url('v1', 'storage', 'records', record_id)
+
+      unless fields.nil?
+        resp = @conn.get(path) do |req|
+          req.options.params_encoder = Faraday::FlatParamsEncoder
+          req.params['field'] = fields
+        end
+      else
+        resp = @conn.get(path)
+      end
+
+      record = Record.new(JSON.parse(resp.body, symbolize_names: true))
+      writer_id = record.meta.writer_id
+      user_id = record.meta.user_id
+      type = record.meta.type
+      decrypt_record(record, get_eak(writer_id, user_id, type))
     end
 
     # Write a new record to the E3DB storage service.
@@ -258,16 +366,23 @@ module E3DB
     # @param type [String] free-form content type name of this record
     # @param data [Hash<String, String>] record data to be stored encrypted
     # @param plain [Hash<String, String>] record data to be stored unencrypted for querying
-    # @return [Record] the newly created record object
+    # @return [Record] the newly created record object (with decrypted values).
     def write(type, data, plain=Hash.new)
       url = get_url('v1', 'storage', 'records')
       id = @config.client_id
-      meta = Meta.new(record_id: nil, writer_id: id, user_id: id,
-                      type: type, plain: plain, created: nil,
-                      last_modified: nil, version: nil)
-      record = Record.new(meta: meta, data: data)
-      resp = @conn.post(url, encrypt_record(record).to_hash)
-      decrypt_record(Record.new(JSON.parse(resp.body, symbolize_names: true)))
+
+      begin
+        eak = get_eak(id, id, type)
+      rescue Faraday::ClientError => e
+        if e.response[:status] == 404
+          eak = create_writer_key(type)
+        else
+          raise e
+        end
+      end
+
+      resp = @conn.post(url, encrypt_record(type, data, plain, id, eak).to_hash)
+      decrypt_record(resp.body, eak)
     end
 
     # Update an existing record in the E3DB storage service.
@@ -280,28 +395,82 @@ module E3DB
     # the new version number and modification time returned by the server.
     #
     # @param record [Record] the record to update
+    # @return [Nil] Always returns nil.
     def update(record)
       record_id = record.meta.record_id
       version = record.meta.version
       url = get_url('v1', 'storage', 'records', 'safe', record_id, version)
+
       begin
-        resp = @conn.put(url, encrypt_record(record).to_hash)
+        type = record.meta.type
+        encrypted_record = encrypt_existing(record, get_eak(@config.client_id, @config.client_id, record.meta.type))
+        resp = @conn.put(url, encrypted_record.to_hash)
+        json = JSON.parse(resp.body, symbolize_names: true)
+        record.meta = Meta.new(json[:meta])
+        nil
       rescue Faraday::ClientError => e
         if e.response[:status] == 409
           raise E3DB::ConflictError, record
         else
           raise e   # re-raise on other failures
         end
-      end
-      json = JSON.parse(resp.body, symbolize_names: true)
-      record.meta = Meta.new(json[:meta])
+     end
     end
 
-    # Delete a record from the E3DB storage service.
+    # Delete a record from the E3DB storage service. If a version
+    # is provided and does not match, an E3DB::ConflicError exception
+    # will be raised.
+    #
+    # Always returns +nil+.
     #
     # @param record_id [String] unique ID of record to delete
-    def delete(record_id)
-      resp = @conn.delete(get_url('v1', 'storage', 'records', record_id))
+    # @param version [String] version ID that must match before deleting the record.
+    # @return [Nil] Always returns nil.
+    def delete(record_id, version=nil)
+      if version.nil?
+        resp = @conn.delete(get_url('v1', 'storage', 'records', record_id))
+      else
+        begin
+          resp = @conn.delete(get_url('v1', 'storage', 'records', 'safe', record_id, version))
+        rescue Faraday::ClientError => e
+          if e.response[:status] == 409
+            raise E3DB::ConflictError, record_id
+          else
+            raise e   # re-raise on other failures
+          end
+        end
+      end
+      
+      nil
+    end
+
+    # Back up the client's configuration to E3DB in a serialized
+    # format that can be read by the Admin Console. The stored
+    # configuration will be shared with the specified client, and the
+    # account service notified that the sharing has taken place.
+    #
+    # @param client_id          [String] Unique ID of the client to which we're backing up
+    # @param registration_token [String] Original registration token used to create the client
+    # @return [Nil] Always returns nil.
+    def backup(client_id, registration_token)
+      credentials = {
+          :version      => '1',
+          :client_id    => @config.client_id.to_json,
+          :api_key_id   => @config.api_key_id.to_json,
+          :api_secret   => @config.api_secret.to_json,
+          :client_email => @config.client_email.to_json,
+          :public_key   => @config.public_key.to_json,
+          :private_key  => @config.private_key.to_json,
+          :api_url      => @config.api_url.to_json
+      }
+
+      write('tozny.key_backup', credentials, {:client => @config.client_id})
+      share('tozny.key_backup', client_id)
+
+      url = get_url('v1', 'account', 'backup', registration_token, @config.client_id)
+      @conn.post(url)
+
+      nil
     end
 
     class Query < Dry::Struct
@@ -338,11 +507,11 @@ module E3DB
     # fetch all records into an array first.
     class Result
       include Enumerable
+      include Crypto
 
-      def initialize(client, query, raw)
+      def initialize(client, query)
         @client = client
         @query = query
-        @raw = raw
       end
 
       # Invoke a block for each record matching a query.
@@ -356,18 +525,12 @@ module E3DB
           json = @client.instance_eval { query1(q) }
           results = json[:results]
           results.each do |r|
-            record = Record.new(meta: r[:meta], data: r[:record_data] || Hash.new)
-            if q.include_data && !@raw
-              access_key = r[:access_key]
-              if access_key
-                record = @client.instance_eval {
-                  ak = decrypt_eak(access_key)
-                  decrypt_record_with_key(record, ak)
-                }
-              else
-                record = @client.instance_eval { decrypt_record(record) }
-              end
+            if q.include_data
+              record = @client.decrypt_record(Record.new({ :meta => r[:meta], :data => r[:record_data] }), EAK.new(r[:access_key]))
+            else
+              record = Record.new(data: Hash.new, meta: Meta.new(r[:meta]))
             end
+
             yield record
           end
 
@@ -407,10 +570,9 @@ module E3DB
     # @param type [String,Array<string>] select records with these types
     # @param plain [Hash] plaintext query expression to select
     # @param data [Boolean] include data in records
-    # @param raw [Boolean] when true don't decrypt record data
     # @param page_size [Integer] number of records to fetch per request
     # @return [Result] a result set object enumerating matched records
-    def query(data: true, raw: false, writer: nil, record: nil, type: nil, plain: nil, page_size: DEFAULT_QUERY_COUNT)
+    def query(data: true, writer: nil, record: nil, type: nil, plain: nil, page_size: DEFAULT_QUERY_COUNT)
       all_writers = false
       if writer == :all
         all_writers = true
@@ -421,7 +583,7 @@ module E3DB
                     record_ids: record, content_types: type, plain: plain,
                     user_ids: nil, count: page_size,
                     include_all_writers: all_writers)
-      result = Result.new(self, q, raw)
+      result = Result.new(self, q)
       if block_given?
         result.each do |rec|
           yield rec
@@ -434,7 +596,8 @@ module E3DB
     # Grant another E3DB client access to records of a particular type.
     #
     # @param type [String] type of records to share
-    # @param reader_id [String] client ID or e-mail address of reader to grant access to
+    # @param reader_id [String] client ID of reader to grant access to
+    # @return [Nil] Always returns nil.
     def share(type, reader_id)
       if reader_id == @config.client_id
         return
@@ -443,17 +606,27 @@ module E3DB
       end
 
       id = @config.client_id
-      ak = get_access_key(id, id, id, type)
-      put_access_key(id, id, reader_id, type, ak)
+      ak = get_access_key(id, id, type)
+
+      begin
+        put_access_key(id, id, reader_id, type, ak)
+      rescue Faraday::ClientError => e
+        # Ignore 403, means AK already exists.
+        if e.response[:status] != 403
+          raise e
+        end
+      end
 
       url = get_url('v1', 'storage', 'policy', id, id, reader_id, type)
       @conn.put(url, JSON.generate({:allow => [{:read => {}}]}))
+      nil
     end
 
     # Revoke another E3DB client's access to records of a particular type.
     #
     # @param type [String] type of records to revoke access to
-    # @param reader_id [String] client ID of reader to revoke access from
+    # @param reader_id [String] client ID of reader to revoke access from    
+    # @return [Nil] Always returns nil.
     def revoke(type, reader_id)
       if reader_id == @config.client_id
         return
@@ -464,8 +637,15 @@ module E3DB
       id = @config.client_id
       url = get_url('v1', 'storage', 'policy', id, id, reader_id, type)
       @conn.put(url, JSON.generate({:deny => [{:read => {}}]}))
+
+      delete_access_key(id, id, reader_id, type)
+      nil
     end
 
+    # Gets a list of record types that this client has shared with
+    # others.
+    #
+    # @return [Array<OutgoingSharingPolicy>]
     def outgoing_sharing
       url = get_url('v1', 'storage', 'policy', 'outgoing')
       resp = @conn.get(url)
@@ -473,6 +653,10 @@ module E3DB
       return json.map {|x| OutgoingSharingPolicy.new(x)}
     end
 
+    # Gets a list of record types that others have shared with this
+    # client.
+    #
+    # @return [Array<IncomingSharingPolicy>]
     def incoming_sharing
       url = get_url('v1', 'storage', 'policy', 'incoming')
       resp = @conn.get(url)
@@ -480,8 +664,207 @@ module E3DB
       return json.map {|x| IncomingSharingPolicy.new(x)}
     end
 
+    # Create and return a key for encrypting the given record type.
+    # The value returned is encrypted such that it can only be used by this
+    # client.
+    #
+    # Can be saved for use with {#encrypt_existing}, {#encrypt_record}
+    # and {#decrypt_record} later.
+    #
+    # @return [EAK]
+    def create_writer_key(type)
+      id = @config.client_id
+      begin
+        put_access_key(id, id, id, type, new_access_key)
+      rescue Faraday::ClientError => e
+        # Ignore 409, as it means a key already exists. Otherwise, raise.
+        if e.response[:status] != 409
+          raise e
+        end
+      end
+
+      get_eak(id, id, type)
+    end
+
+    # Retrieve a key for reading records shared with this client. 
+    #
+    # +writer_id+ is the ID of the client who wrote the shared records. +user_id+
+    # is the ID of the user that the record pertains to. +type+ is the type of
+    # the shared record.
+    #
+    # The value returned is encrypted such that it can only be used by
+    # this client.
+    #
+    # @return [EAK]
+    def get_reader_key(writer_id, user_id, type)
+      get_eak(writer_id, user_id, type)
+    end
+
+    # Encrypts an existing record. The record must contain plaintext values.
+    #
+    # +plain_record+ should be a {Record} instance to encrypt. 
+    # +eak+ should be an {EAK} instance.
+    #
+    # @return [Record] An instance containg the encrypted data.
+    def encrypt_existing(plain_record, eak)
+      cache_key = [plain_record.meta.writer_id, plain_record.meta.user_id, plain_record.meta.type]
+      if ! @ak_cache.has_key? cache_key
+        @ak_cache[cache_key] = { :eak => eak, :ak => decrypt_box(eak.eak, eak.authorizer_public_key.curve25519, @private_key) }
+      end
+      ak = @ak_cache[cache_key][:ak]
+
+      encrypted_record = Record.new(meta: plain_record.meta, data: Hash.new)
+      plain_record.data.each do |k, v|
+        dk =   new_data_key
+        efN =  secret_box_random_nonce
+        ef =   RbNaCl::SecretBox.new(dk).encrypt(efN, v)
+
+        edkN = secret_box_random_nonce
+        edk =  RbNaCl::SecretBox.new(ak).encrypt(edkN, dk)
+
+        encrypted_record.data[k] = [edk, edkN, ef, efN].map { |f| base64encode(f) }.join(".")
+      end
+
+      encrypted_record
+    end
+
+    # Encrypt a new record consisting of the given data.
+    #
+    # +type+ is a string giving the record type. +data+ should be a
+    # dictionary of string values. +plain+ should be a dictionary of
+    # string values. +id+ should be the ID of the client creating the
+    # record. +eak+ should be an {EAK} instance.
+    #
+    # @return [Record] An instance containing the encrypted data.
+    def encrypt_record(type, data, plain, id, eak)
+      meta = Meta.new(record_id: nil, writer_id: id, user_id: id,
+                      type: type, plain: plain, created: nil,
+                      last_modified: nil, version: nil)
+
+      encrypt_existing(Record.new(:meta => meta, :data => data), eak)
+    end
+
+    # Decrypts a record using the given secret key.
+    #
+    # The record should be either a JSON document (as a string) or a
+    # {Record} instance. +eak+ should be an {EAK} instance.
+    #
+    # @return [Record] An instance containing the decrypted data.
+    def decrypt_record(encrypted_record, eak)
+      encrypted_record = Record.new(JSON.parse(encrypted_record, symbolize_names: true)) if encrypted_record.is_a? String
+      raise 'Can only decrypt JSON string or Record instance.' if ! encrypted_record.is_a? Record
+
+      cache_key = [encrypted_record.meta.writer_id, encrypted_record.meta.user_id, encrypted_record.meta.type]
+      if ! @ak_cache.has_key? cache_key
+        @ak_cache[cache_key] = { :eak => eak, :ak => decrypt_box(eak.eak, eak.authorizer_public_key.curve25519, @private_key) }
+      end
+      ak = @ak_cache[cache_key][:ak]
+
+      plain_record = Record.new(data: Hash.new, meta: Meta.new(encrypted_record.meta))
+      encrypted_record[:data].each do |k, v|
+        edk, edkN, ef, efN = v.split('.', 4).map { |f| base64decode(f) }
+
+        dk = RbNaCl::SecretBox.new(ak).decrypt(edkN, edk)
+        pv = RbNaCl::SecretBox.new(dk).decrypt(efN, ef)
+
+        plain_record.data[k] = pv
+      end
+
+      plain_record
+    end
+
     private
 
+    # Returns the encrypted access key for this client for the
+    # given writer/user/type combination. Throws
+    # Faraday::ResourceNotFound if the key does not exist.
+    #
+    # Returns an instance of E3DB::EAK.
+    def get_eak(writer_id, user_id, type)
+      get_cached_key(writer_id, user_id, type)[:eak]
+    end
+
+    # Retrieve the access key for the given combination of writer,
+    # user and typ with this client as reader. Throws
+    # Faraday::ResourceNotFound if the key does not exist.
+    #
+    # Returns an string of bytes representing the access key.
+    def get_access_key(writer_id, user_id, type)
+      get_cached_key(writer_id, user_id, type)[:ak]
+    end
+
+    # Manages EAK caching, and goes to the server if a given access
+    # key has not been fetched. Throws Faraday::ResourceNotFound if
+    # the key does not exist.
+    #
+    # Returns a dictionary with +:eak+ and +:ak+ entries (containing
+    # the encrypted and unencrypted versions of the key,
+    # respectively).
+    def get_cached_key(writer_id, user_id, type)
+      cache_key = [writer_id, user_id, type]
+      if @ak_cache.has_key? cache_key
+        @ak_cache[cache_key]
+      else
+        url = get_url('v1', 'storage', 'access_keys', writer_id, user_id, @config.client_id, type)
+        json = JSON.parse(@conn.get(url).body, symbolize_names: true)
+        @ak_cache[cache_key] = {
+          :eak => EAK.new(json),
+          :ak => decrypt_box(json[:eak], json[:authorizer_public_key][:curve25519], @private_key)
+        }
+      end
+    end
+
+    # Store an access key for the given combination of writer, user,
+    # reader and type. `ak` should be an string of bytes representing
+    # the access key.
+    #
+    # If an access key for the given combination exists, this method
+    # will have no effect.
+    #
+    # Returns +nil+ in all cases.
+    def put_access_key(writer_id, user_id, reader_id, type, ak)
+      if reader_id == @client_id
+        reader_key = @public_key
+      else
+        resp = @conn.get(get_url('v1', 'storage', 'clients', reader_id))
+        reader_key = decode_public_key(JSON.parse(resp.body, symbolize_names: true)[:public_key][:curve25519])
+      end
+
+      encoded_eak = encrypt_box(ak, reader_key, @private_key)
+
+      url = get_url('v1', 'storage', 'access_keys', writer_id, user_id, reader_id, type)
+      resp = @conn.put(url, { :eak => encoded_eak })
+      cache_key = [writer_id, user_id, type]
+      @ak_cache[cache_key] = {
+        ak: ak,
+        eak: EAK.new(
+          {
+            eak: encoded_eak,
+            authorizer_public_key: {
+              curve25519: encode_public_key(reader_key)
+            },
+            authorizer_id: @config.client_id
+          }
+        )
+      }
+
+      nil
+    end
+
+    # Delete the access key for the given combination of writer, user,
+    # reader and type.
+    #
+    # Returns nil in all cases.
+    def delete_access_key(writer_id, user_id, reader_id, type)
+      url = get_url('v1', 'storage', 'access_keys', writer_id, user_id, reader_id, type)
+      @conn.delete(url)
+
+      cache_key = [writer_id, user_id, type]
+      @ak_cache.delete(cache_key)
+
+      nil
+    end
+
     # Fetch a single page of query results. Used internally by {Client#query}.
     def query1(query)
       url = get_url('v1', 'storage', 'search')
@@ -490,7 +873,7 @@ module E3DB
     end
 
     def get_url(*paths)
-      sprintf('%s/%s', @config.api_url.chomp('/'), paths.map { |x| CGI.escape x }.join('/'))
+      "#{@config.api_url.chomp('/')}/#{ paths.map { |x| CGI.escape x }.join('/')}"
     end
   end
 end