Skip to content

Latest commit

 

History

History
363 lines (277 loc) · 8.26 KB

3ip-10.md

File metadata and controls

363 lines (277 loc) · 8.26 KB
Raw
3ip title author discussions-to status created requires
10
3ID JSON-RPC
oed@3box.io
Draft
2019-09-02
7

Simple Summary

This 3IP describes the json-rpc interface which wallets can implement to natively support 3Box.

Abstract

The json-rpc described in this document outlines the interface for all functions that are needed by the 3box-js client when interacting with an identity. The IdentityWallet SDK will natively support these functions, making it easy for wallets to add 3id support.

Motivation

By specifying a json-rpc interface we make the 3ID system more modular. We can allow wallets to natively support 3box through an injected provider, or systems like WalletConnect. It also makes it simpler for non ethereum wallets to support 3box as well.

Specification

3id_getLink

Returns an address that has been associated with the 3ID of the user. This is used in 3box-js to fetch the rootstore which contains the authData needed in the authentication step.

Returns:

An address that can be used to look up the 3ID of the user.

Example:

    // Request
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "3id_getLink",
      "params": {}
    }

    // Result
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": "0xabcde12345..."
    }

3id_linkManagementKey

Links the managementKey to the users 3ID. This is used to find the user data if the 3ID is unknown before the authentication step.

Parameters:

  1. did - The 3ID of the user

Returns:

An address link object formated according to the Address Linking spec.

Example:

    // Request
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "3id_linkManagementKey",
      "params": {
        "did": "did:3:bafy..."
      }
    }

    // Result
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": {
        "msg": "the message that was signed",
        "timestamp": 8734586734,
        "sig": "0x12341abcde..",
      }
    }

3id_authenticate

Method for authenticating to get access to the requested spaces.

Parameters:

  1. spaces - An array of space names as String
  2. authData - An array of authData objects
  3. address - String, The address associated with this 3ID (optional)

Returns:

An object containing the public keys for the main account and for any requested space.

Example:

    // Request
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "3id_authenticate",
      "params": {
        "spaces": ["space1", "space2"],
        "authData": []
      }
    }

    // Result
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": {
        "main": {
          "signingkey": "0xexample",
          "managementkey": "0xexample",
          "encryptionkey": "0xexample"
        },
        "spaces": {
          "space1": {
            "signingKey": "0xexample",
            "encryptionKey": "0xexample"
          },
          "space2": {
            "signingKey": "0xexample",
            "encryptionKey": "0xexample"
          }
        }
      }
    }

3id_isAuthenticated

Checks if the user has already authenticated this app. If no spaces are given as parameters it just checks if the main account is authenticated.

Parameters:

  1. spaces - An array of space names as Strings, can be empty

Returns:

An Boolean that is true if all given spaces have been authenticated.

Example:

    // Request
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "3id_isAuthenticated",
      "params": {
        "spaces": ["space1", "space2"]
      }
    }

    // Result
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": true
    }

3id_signClaim

Signs a claim with the desired DID. The format of the signed claim is a JWT.

Parameters:

  1. payload - An object containing the data that should be encoded in the claim
  2. did - The DID that is the issuer of the claim
  3. space - The space which this claim should be issued by
  4. expiresIn - number of seconds until the claim expires (optional)

Returns:

A JWT encoded as a string.

Example:

    // Request
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "3id_signClaim",
      "params": {
        "payload": <object>,
        "did": "did:3:bafy....",
        "space": "space1",
        "expiresIn": 123456
      }
    }

    // Result
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    }

3id_encrypt

Encrypt a message with the desired space encryption keys. If the to parameter is not passed the message will be symmetrically encrypted.

Parameters:

  1. message - String, the message to be encrypted
  2. space - String, the space used for encryption
  3. to - Base64 String, the public encryption key of a receiver
  4. blocksize - Int, a custom blocksize for the message padding

Returns:

An object containing the encrypted data. For symmetrically encrypted messages this object contains a nonce and a ciphertext parameter. For messages encrypted to a public key this object also contains a ephemeralFrom parameter which is an public key of the ephemeral keypair used to encrypt the message.

Example:

    // Request
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "3id_encrypt",
      "params": {
        "message": "a secret message",
        "space": "space1"
      }
    }

    // Result
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": {
        "nonce": "nonce encoded as base64",
        "ciphertext": "ciphertext encoded as base64",
      }
    }

3id_decrypt

Decrypt a message with the desired space encryption keys.

Parameters:

  1. ciphertext - base64 String, the encrypted message
  2. nonce - baes64 String, the nonce that was used to decrypt the message
  3. space - String, the name of the space used to decrypt the message
  4. ephemeralFrom - base64 String, the ephemeral public key that was used to encrypt the message (optional)

Returns:

A String containing the decrypted message.

Example:

    // Request
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "3id_decrypt",
      "params": {
        "ciphertext": "ciphertext encoded as base64",
        "nonce":  "nonce encoded as base64",
        "space": "space1"
      }
    }

    // Result
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": "a decrypted message"
    }

3id_hashEntryKey

Hashes the given key with a salt only known to the specific 3ID.

Parameters:

  1. key - String, the key
  2. space - String, the name of the space used to decrypt the message

Returns:

A String containing the hashed key.

Example:

    // Request
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "3id_hashEntryKey",
      "params": {
        "key":  "a secret key of a property",
        "space": "space1"
      }
    }

    // Result
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": "a multihash"
    }

3id_newAuthMethodPoll

A poll method to get any new authData.

Parameters:

Returns:

An array containing objects with the encrypted authentication data.

Example:

    // Request
    {
      "id": 1,
      "jsonrpc": "2.0",
      "method": "3id_newAuthMethodPoll",
      "params": {}
    }

    // Result
    {
      "id": 1,
      "jsonrpc": "2.0",
      "result": [{
        "nonce": "nonce encoded as base64",
        "ciphertext": "ciphertext encoded as base64",
      }]
    }

Rationale

This specification for a 3ID JSON-RPC simply formalises the functions needed by 3Box from api of the IdentityWallet SDK. There shouldn't really be anything surprising here. By decoupling the main IdentityWallet SDK implementation from the rpc spec we also make it easier for third parties to create custom implementations of the functionality in the IdentityWallet SDK.

Implementation

No implementation is yet available for this 3IP.

Copyright

Copyright and related rights waived via CC0.