Skip to content
Collections of tools and helper libraries for android to issue and use identities on the uPort platform
Branch: develop
Clone or download
mirceanis Merge pull request #97 from uport-project/feature/165089772-replace-e…
…mbeded-with-remote-dependencies

replace embedded with remote dependencies
Latest commit 47bd190 May 20, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci change the test results root path for better test name inference in c… Feb 20, 2019
.github/ISSUE_TEMPLATE Add issue templates Dec 3, 2018
credentials import kotlin-did-jwt@0.2.0 May 17, 2019
demoapp remove `signer` module which has been migrated back to its own repo May 13, 2019
docs Make front matter index unique Jan 17, 2019
fuelingservice migrate `demoapp` module to use exported repos and updated dependencies Apr 30, 2019
gradle/wrapper remove `signer` module which has been migrated back to its own repo May 13, 2019
identity remove `signer` module which has been migrated back to its own repo May 13, 2019
sdk remove `signer` module which has been migrated back to its own repo May 13, 2019
transport fix credentials `authenticateDisclosure` and the related tests ( with… May 17, 2019
.codacy.yml first attempt to configure codacy using a config file Jan 16, 2019
.gitignore update publishing configuration Jan 10, 2019
LICENSE Initial commit May 25, 2018
README.md remove `signer` module which has been migrated back to its own repo May 13, 2019
build.gradle import kotlin-did-jwt@0.2.0 May 17, 2019
gradle.properties use audience in credentials check and update test data to new verific… May 17, 2019
gradlew first public draft May 25, 2018
gradlew.bat first public draft May 25, 2018
publishing.gradle remove `signer` module which has been migrated back to its own repo May 13, 2019
settings.gradle remove `signer` module which has been migrated back to its own repo May 13, 2019

README.md

title index category type
uPort Android SDK
1
android-sdk
content

uPort Android SDK

Identity for your Android dApps.

This is a preview version of the uPort android SDK. Many intended features are still missing, and the ones already present are under heavy development. Expect some breaking changes

Development planning is done at https://www.pivotaltracker.com/n/projects/2198688

Installation

This SDK is available through jitpack

In your main build.gradle file, add:

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
        //...
    }
}

In your application build.gradle file, add:

def uport_sdk_version = "v0.4.2"
dependencies {
    //...
    // core SDK
    implementation "com.github.uport-project.uport-android-sdk:sdk:$uport_sdk_version"
}

Usage

Configure uPort in your Application class

override fun onCreate() {
    
    val config = Uport.Configuration()
                    .setApplicationContext(this)
    
    Uport.initialize(config)
}

defaultAccount

This preview version of the SDK has the concept of defaultAccount as a nullable field in the Uport object. If there is no default account when a new one is created, it becomes the default.

Uport.defaultAccount?.address // Returns the mnid address of the default account
Uport.defaultAccount?.publicAddress // Returns the hex address of the default account
Uport.defaultAccount?.network // Returns the network id of the default account

//returns the ETH balance of the deviceAddress (measured in wei)
Uport.defaultAccount?.getBalance() { err, balance ->
    // do something with balance or respond to err
}

//or as a coroutine:
val balanceInWei = Uport.defaultAccount?.getBalance()

Account Creation

if (Uport.defaultAccount == null) {
    
    Uport.createAccount(network = Networks.rinkeby) { err, account ->
            // update UI to reflect the existence of a defaultAccount
    }
    
}

In case the app gets killed during the account creation process, the createAccount method will try to resume the process where it left off. It can be instructed to start from scratch, but that may cost additional fuel.

Account management

Account objects have a handle field that can be used to refer to them in the future. The handle right now is an ethereum address but it should be treated as an opaque string, as it will change in a future release. You should not send funds to that address.

Key management

The signer library is used to create and manage keys for uport accounts. Read full details in key management documentation

Ethereum interaction

uPort SDK lets you create, sign, and submit Ethereum transactions.

This SDK preview version uses simple KeyPair accounts which require self-funding. There is also support for proxy-contract accounts and metaTransactions but it is not used by default any more.

//transfer value
val destination: String = "0x010101...."
val amountInWei = BigInteger.valueOf(1_000_000_000)

Uport.defaultAccount?.send(activity, destination, amountInWei) { err, txHash ->
  // Update UI to indicate that transaction has been sent and is confirming
  Networks.rinkeby.awaitConfirmation(txHash) { err, receipt ->
    // Complete operation in UX
  }
}


//`send` can also be used in coroutines

//call contract
val contractAddress = "0x010101..."
val data : ByteArray = <ABI encoded contract method call>

val txHash : String = Uport.defaultAccount?.send(activity, contractAddress, data)
val receipt = Networks.rinkeby.awaitConfirmation(txHash)

off-chain interaction

Off-chain interaction is essentially signing and verifying JWTs using uport-specific JWT algorithms. Verification of such tokens implies resolving a Decentralized Identity (DID) document that will contain the keys or address that should match a JWT signature. To obtain a DIDDocument one needs to use a DIDResolver.

The UniversalDID is a global registry of DIDResolvers for apps using the SDK. During SDK initialization this registry gets populated with default resolvers for uport-did, ethr-did and https-did You can register your own resolver(s) using UniversalDID.registerResolver(resolver) Registering a new resolver that resolves the same DID method will override the previous one.

These DIDDocuments are used during verification of compatible JWT tokens.

verify a JWT token

//in a coroutine context:
val tokenPayload : JWTPayload? = JWTTools().verify(token)

if (tokenPayload != null) {
    //verified
} else {
    //token cannot be verified
}

create a JWT token

val payload = mapOf( "claims" to mapOf( "name" to "R Daneel Olivaw" ) )

val signer = KPSigner("0x1234")
val issuer = "did:ethr:0x${signer.getAddress()}"

//in a coroutine context
val jwt : String = JWTTools().create(payload, issuer, signer)

Encrypted messaging

//compute an encryption publicKey starting from a private key (can be an ethereum private key) 
val publicKey = Crypto.getEncryptionPublicKey(privateKeyBytes)

//encrypt a message with an intended recipient
val encryptedBundle = Crypto.encrypt("hello world", recipientPublicKeyBase64)
val serializedMessage = encryptedBundle.toJson()

//decrypt a message
val receivedBundle = EncryptedMessage.fromJson(serializedMessage)
val decryptedMessage = Crypto.decrypt(receivedBundle, recipientSecretKey)

Dependencies

This library uses KEthereum for a lot of the ethereum related work.

The smart-contract binding code is generated using bivrost-kotlin

Currently there is a transient dependency on spongycastle but that may be removed when pure kotlin implementations of the required cryptographic primitives become available.

Contributing

Want to contribute to uport-android-sdk? Cool, please read our contribution guidelines to get an understanding of the process we use for making changes to this repo.

Changelog

  • 0.5.x - upcoming

    • separated signer, common, jwt, did-resolvers
    • Account is now an interface and the default implementation used is HDAccount
  • 0.4.2

    • updated infura JsonRPC endpoint URLs. To avoid sudden disconnect you are strongly encouraged to use your own project on infura or to use a dedicated JsonRPC endpoint for your use case.
  • 0.4.1

    • maintenance release
  • 0.4.0

    • core module is a simple java library (and can be used as a dependency in JVM tests)
    • [breaking] AccountCreator interface methods are now using suspend instead of callbacks.
    • [breaking] The callback variant of createAccount from the Uport object has been deprecated.
    • [breaking] all available JsonRPC methods are suspend methods and are full members of the class (and can now be easily mocked). The callback variants no longer exist.
    • network_id field in EthNetwork was renamed to networkId
    • add Transports.sendExpectingResult() functionality
    • add createPersonalSignRequest, createVerificationSignatureRequest, createEthereumTransactionRequest convenience methods to Credentials to interact with the uPort app
    • extensive refactoring of tests with better mocks and ability to run offline
    • also publishing sources.jar for each module
  • 0.3.2

    • JWT timestamps are checked with allowance for clock drift
    • JWT verification is more explicit about failures
    • added method to extract shareResp JWTs from callback URIs
    • expose getDID() method on Account objects
  • 0.3.1

    • add https DID resolver
    • use UniversalDID for JWT verification
    • add encryption/decryption functionality
  • 0.3.0

    • add universal DID resolver
    • add cleaner way of creating JWTs with abstracted signer
    • updated to kethereum 0.63 which has a different key derivation and mnemonic API. If you're using an older version in parallel, you need to update as well.
  • 0.2.2

    • update of dependencies for coroutines and build tools
  • 0.2.1

    • bugfix: crash when decrypting fingerprint protected seed
  • 0.2.0

  • 0.1.1

    • add option to import seeds phrases as account
    • bugfix: default account is updated on first creation
  • 0.1.0

    • default account type is KeyPair
    • updated kethereum to 0.53 , some APIs have changed to extension functions
    • updated uport-android-signer - allows minSDK to be 21
    • renamed Uport.defaultAccount?.proxyAddress to publicAddress
  • 0.0.2

    • add coroutine support for account creation
    • add getAddress to Account objects
  • 0.0.1

    • initial release
You can’t perform that action at this time.