Android SDK

Evervault Android SDK

The Evervault Android SDK is a library for encrypting data and collecting credit cards data on Android Devices. It's simple to integrate, easy to use and it supports a wide range of data types.

Features

Core encryption capabilities for various data types.
A secure and customizable PaymentCard Compose view.
Built-in data type recognition and appropriate encryption handling.

Installation

Our Android SDK distributed via maven, and can be installed using your preferred build tool.

If you are installing evervault-inputs from version 2.0.0 and onwards you will also need to add the JitPack repository to your build file:

Usage

Configuration

Before using the Evervault Android SDK, you need to configure it with your Evervault Team ID and App ID. This step is essential for establishing a connection with the Evervault encryption service.

Make sure to replace <TEAM_ID> and <APP_ID> with your actual Evervault Team ID and App ID which can be found in the Evervault Dashboard

Encrypting Data

Once the SDK is configured, you can use the encrypt method to encrypt sensitive data. The encrypt method accepts Java's primitive data types and an optional role

Here's an example of encrypting a social security number:

A role defines an encryption policy to be applied to the return ciphertext. The encrypt function takes as an optional parameter role which is the id of the role created in your Evervault App

The encrypt method returns an Any type, so you will need to safely cast the result based on the data type you provided. For Boolean, Numerics, and Strings, the encrypted data is returned as a String. For Arrays, Lists and Maps, the encrypted data maintains the same structure but is encrypted (except that Arrays become Lists). For ByteArray, the encrypted data is returned as encrypted ByteArray, which can be useful for encrypting files.

Decrypting Data

Decrypts data previously encrypted with the encrypt() function or through Relay. The decrypt() function allows you to decrypt previously encrypted data using a token.

The token is a time bound token for decrypting data. The token can be generated using our backend SDKs or through our REST API. The payload must be the same payload that was used to create the token and expires 10 minutes after creation. The payload must be a map and the response is Any which can, and should be, cast to Map<String, Any>

Inputs

The Evervault Android SDK also provides a Compose view called PaymentCard. This view is designed for capturing credit card information and automatically encrypts the credit card number and CVC without exposing the unencrypted data. The PaymentCard view can be customized to fit your application's design.

Here's an example of using the PaymentCard composable:

The encrypted credit card number and CVC are captured in the PaymentCardData, as well as the expiry month and year and validation fields.

Styling

The PaymentCard and its components can be customized to fit your application's design. The view excepts a number of parameters that enable you to customize the modifier, text and placeholder styles. The content parameter accepts a @Composable PaymentCardInputScope.() function, which can be used to customize the view's layout. The PaymentCardInputScope components can be customized with a modifier (Modifier), label (String or @Composable), placeholder (String or @Composable), text style (TextStyle), and input field colors (TextFieldColors).

Two build-in layouts are provided:

Inline

InlinePaymentCard (the default layout) - This layout displays the card number, expiry and CVC fields inline.

inlinePaymentCardInputLayout

Rows

RowsPaymentCard - Displays the credit card number on a single row. Below it, places the expiry and cvc fields next to each other.

rowsPaymentCardInputLayout

You can also customize these layout through theming and modifiers:

Custom Layout

If these two layouts do not fit your application's design, you can create your own layout by passing a @Composable function to the content parameter. The @Composable function will receive a PaymentCardInputScope (together with the PaymentCard Modifier) object, which contains the CardImage, CardNumberField, ExpiryField and CVCField fields. You can use these fields to create your own layout:

Optional Rendering

Fields can be optionally displayed by passing in a list of CardFields. For example if you with to only render the Card Number field use the following code.

Enclaves

The Evervault Enclaves SDK provides an accessible solution for developers to deploy Docker containers within a Secure Enclave. It enables you to interact with your Enclaves endpoints via standard HTTPS requests directly from your Android applications. A key feature that enables this is the attestation verification performed before completing the TLS handshake. For a deeper understanding of this process, you can explore our TLS Attestation documentation.

The attestation verification is executed using a custom Trust Manager on a OkHttpClient.Builder. This Trust Manager needs initialization with an AttestationData object:

It is crucial to ensure that the supplied PCRs align with the PCRs of the respective Enclave.

Then you configure the HTTP Client with the attestations:

Only use this client for requests to your Enclave. For all other requests, use a separate client.

Enclave PCR Manager

If the PCRs of your Enclave change, the attestation connection will fail from all clients that are not updated with the new PCRs. The EnclaveTrustManager is a service that can optionally be used to cache a list of PCRs that are returned from an API under your control. The EnclaveTrustManager can be used by passing a PcrCallback and the enclaveName as a parameter to AttestationData that is used to build the OkHttpClient. The EnclaveTrustManager will cache the response PCRs from the PcrCallback and refresh them at a default interval of 5 minutes. This refresh can be configured by passing the callbackInterval parameter.

This example below show how to call an endpoint that returns a list of PCRs as the callback function.

The endpoint returning the PCRs must return the PCRs in the format

Using the Evervault API as a PCR Provider

The Evervault API exposes an endpoint to retrieve the PCRs for all active versions of your Enclave which you can use to keep your clients in sync with your Enclave across deployments.

Considerations

It's crucial to note that the PCR values associated with a Enclave change with each new deployment. Consequently, older versions of your app with hardcoded PCRs may stop functioning. To alleviate this, you can accommodate previous deployments by providing multiple PCRs objects or use the EnclaveTrustManager:

Using the EnclaveTrustManager by passing a PcrCallback to the AttestationData allows you do update your PCRs remotely via an endpoint you control. When a Enclave is deployed and the PCRs change the list of PCRs returned from the endpoint should expand to hold the new PCRs e.g

The EnclaveTrustManager will cache the new PCRs and old PCRs. Over time you can then remove the old PCRs from your endpoints response leaving just the new PCRs.

This allows for the updating of a Enclave without having to re-publish your client with new PCRs.

Please be aware that the Android SDK is compatible only with Enclaves that have the API Key Authentication set to false in your enclave.toml file:

Only use the OkHttpClient configured with the AttestationData for requests to your Enclave. For all other requests, use a separate client. If you have multiple Enclaves, you will need to configure a separate OkHttpClient for each Enclave.
When calling an endpoint of your Enclave, use make sure you do not have any underscore _ in the request url. Replace any underscore, such as the one in your App ID, with hyphens -.

These considerations are essential to remember for a seamless integration and operation of the Evervault Enclaves SDK in your Android applications.

Google Pay

Evervault Google Pay for Android is currently in Beta. Please contact support@evervault.com for more information.

The Evervault SDK provides a Google Pay component that allows your customers to make payments in your app using credit and debit cards saved to their Google Account

All users of Google Pay agree to adhere to the Google Pay Terms and Conditions

Prerequisites

To support Evervault Google Pay in Android, you need to add the following to your build.gradle.kts:

You will also need to add the JitPack repository to your build file:

To use Google Pay, first you need to enable the Google Pay API by adding the following to the <application> tag of your AndroidManifest.xml:

Instantiate the `EvervaultPaymentViewModel`

The Evervault Android SDK provides a Google Pay button composable and view model to encapsulate all Google Pay setup, readiness checks, payment data handling, and interception of the Google Pay token to provide you with direct access to the encrypted payment method, which can then be sent to any payment processor using Evervault Relay.

To initiate the view model you need to pass a Config with a minimum of appId and merchantId.

React to `PaymentState`

PaymentState is your single source of truth for what should happen in the UI. Handle it reactively so that screens transition automatically as soon as the view model publishes a new state. An example of handling these can be found at the bottom of this section.

State	Typical timing	What you should do
`NotStarted`	Immediately after composition, before you call `start()`	Display a progress indicator or a placeholder so users know something is loading.
`Unavailable`	`start()` has been called but Google Pay isn’t available on the device.	Display other payment options instead.
`Available`	`start()` has been called and Google Pay is available on the device.	Display the Google Pay button.
`Error`	Something went wrong - likely something with the payment sheet and it closed with an error.	Display an error message to the user via a toast or similar.
`PaymentComplete`	The user completed the Payment and Evervault has provided encrypted payment details back to you.	Display a success screen or receipt and trigger your server side flow for payment processing with one of your PSPs.

Check Google Pay is available on the device

Now that you have created the view model, you need to check that Google Pay is supported and that a payment can be made. If this method fails and Google Pay is not supported then PaymentState.Unavailable will be emitted.

This should be called once (e.g. in a LaunchEffect(Unit) { ... })

This API checks the following minimum requirements to finish a transaction using the Google Pay API:

Device is running on a supported Android system version and also has a supported version of Google Play services installed.
Google Pay API has launched in the user's country.
User either has or can add a card in flow according to the specifications given for the Config passed during initialisation of the EvervaultPaymentViewModel.

Create a `Transaction`

Next you will need to create a transaction to describe the payment you want to process. You will need to provide the currency, country, line items, and total for the transaction.

Render the Pay Button

Now that you have created a transaction and checked that Google Pay is supported, you can create and display the Google Pay button to your users by using the EvervaultPaymentButton composable.

Handle the result

When the user completes the payment, cancels, or otherwise exits the Google Pay sheet, a callback is delivered to onActivityResult(). In the event of a successful payment, the Google Pay Payment token needs to be decrypted in order to be passed on to your PSP for processing. Call the handlePaymentDataIntent() method on the viewModel to handle this.

Once handlePaymentDataIntent() has been called, the EvervaultPaymentViewModel will handle decryption of the Google Pay token and tokenize any sensitive PCI data for you and emit PaymentState.PaymentComplete(response) with the tokenized payload or PaymentState.Error if an error occurred.

Process the Payment

If the payment is handled successfully, the Evervault encrypted payment method is available in PaymentState.PaymentComplete(response). The response is a JSON object containing the payment method details encrypted with the Evervault public key. You can send this encrypted payment method to your server and use Evervault Relay to decrypt the payment details when you send them to your PSP.

Google Pay can return a NetworkTokenResponse or a CardResponse object, typically depending on whether the supported method was PAN_ONLY or CRYPTOGRAM_3DS and whether or not the network supports that method.

A NetworkTokenResponse object contains the following fields:

A CardResponse object contains the following fields:

If available, both objects will also contain a billingAddress which is a the root and contains the following:

Google Pay responses containing a networkToken offer inherent security due to their device-bound nature. However, responses containing only card details carry a higher risk and require additional authentication steps. We recommend leveraging our 3DS API to perform this necessary authentication for card-based responses.

Complete example

Below is a full example of Evervault Google Pay in action:

The `Config` object

The Config object initialises your EvervaultPaymentViewModel with everything it needs to handle the interactions with the Google Pay API. At a minimum you’re required to provide your Evervault App ID and Evervault Merchant ID. There are other options to allow you to customise how the Google Pay payment sheet functions. Below is an example with all the possible options:

When you’re testing the Evervault Google Pay integration in an emulator or on a real device, the environment should be set to the test environment. When you’re ready to go live, you should set the environment to EvervaultConstants.ENVIRONMENT_PRODUCTION.

For the supportedNetworks option, all of the networks listed above, including those in the comment are enabled. If you wish to only support a select few of the networks, please override the list as shown above.

For the supportedMethods, please refer to Google’s documentation on PAN_ONLY vs CRYPTOGRAM_3DS. Depending on the values you use here, you may encounter errors when initialising the component, for example, JCB and DISCOVER don’t support CRYPTOGRAM_3DS because they don’t support DPANs.

Customize the Google Pay Button

Google Pay allows you to customize the appearance of the payment button with various predefined styles. These can be passed as additional options when initializing the EvervaultPaymentButton. Below is an example:

The default theme is Dark and the default type is Pay.

Proguard Rules

If you are using code shrinking with ProGuard you will need to specify exclusion rules for evervault-core dependencies. To do this add the following lines to your proguard-rules.pro

Sample App

The Evervault Android SDK Package includes a sample app, located in the sampleapplication directory. The sample app demonstrates various use cases of the SDK, including string encryption, file (image) encryption, the usage of the PaymentCard view with customized styling and how to contruct an attested Enclave client.