Guides

iOS SDK

You can use our iOS SDK to:

  • Encrypt data
  • Embed Inputs
  • Attest Cages

Supported Platforms

  • iOS 15+
  • macOS 12+

Quickstart

Install SDK

The Evervault iOS SDK can be installed using the Swift Package Manager.

  1. Open your Xcode project.
  2. Navigate to File > Swift Packages > Add Package Dependency.
  3. Enter the repository URL for the Evervault iOS SDK: https://github.com/evervault/evervault-ios.git.
  4. Choose the latest available version or specify a version rule.
  5. Click Next and follow the instructions to integrate the package into your project.

Initialize SDK

Now, let's initialize the SDK using our App and Team ID. If you don't have one yet, you can get one by creating an App in the Evervault Dashboard.

1
import EvervaultCore
2
3
Evervault.shared.configure(teamId: "<TEAM_ID>", appId: "<APP_ID>")

If you need multiple instances of the Evervault SDK you can use the initializer as follows:

1
import EvervaultCore
2
3
let evervault = Evervault.init(teamId: "<TEAM_ID>", appId: "<APP_ID>")

Encrypting Data

Once the SDK is configured, you can use the encrypt method to encrypt your sensitive data. The encrypt method accepts various data types, including Boolean, Numerics, Strings, Arrays, Dictionaries, and Data.

Here's an example of encrypting a password:

1
let encryptedPassword = Evervault.shared.encrypt("Super Secret Password")

Or using a dedicated instance:

1
let encryptedPassword = evervault.encrypt("Super Secret Password")

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 and Dictionaries, the encrypted data maintains the same structure but is encrypted. For Data, the encrypted data is returned as encrypted Data, which can be useful for encrypting files.

Decrypting Data

Decrypts data previously encrypted with the encrypt() function or through Relay.

The decrypt() method 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 in a maximum of 10 minutes depending on the expiry set when creating the token.

1
let encryptedPassword = Evervault.shared.encrypt("Super Secret Password")
2
let decrypted: String = Evervault.shared.decrypt('<token generated by your backend application>', encryptedPassword)

## Inputs

The Evervault iOS SDK also includes the EvervaultInputs module, which provides a SwiftUI view called PaymentCardInput. This view is designed for capturing credit card information and automatically encrypts the credit card number and CVC without exposing the unencrypted data. The PaymentCardInput view can be customized to fit your application's design.

To use PaymentCardInput, make sure you have imported the EvervaultInputs module in your file, and then simply add the view to your SwiftUI hierarchy:

1
import EvervaultInputs
2
3
struct ContentView: View {
4
5
@State private var cardData = PaymentCardData()
6
7
var body: some View {
8
VStack {
9
PaymentCardInput(cardData: $cardData)
10
11
// Data captured:
12
Text("Encrypted credit card number: \(cardData.card.number)")
13
}
14
}
15
}

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

Styling

Internally, the PaymentCardInput view uses SwiftUI TextFields. These can be customized using SwiftUI modifiers like any other TextFields in your application:

1
PaymentCardInput(cardData: $cardData)
2
.font(.footnote)
3
.foregroundColor(.blue)

To provide more customization options, the PaymentCardInput can be styled using a PaymentCardInputStyle. There are two build-in styles:

  • InlinePaymentCardInputView (the default style) - puts the credit card number, expiry and cvc fields all on a single row.

Screenshot of the iOS PaymentCardInput with Inline styling

To explicitly use this style:

1
PaymentCardInput(cardData: $cardData)
2
.paymentCardInputStyle(.inline)
  • RowsPaymentCardInputStyle - puts the credit card number on a single row. Below it, places the expiry and cvc fields next to each other.

Screenshot of the iOS PaymentCardInput with Rows styling

To use this style:

1
PaymentCardInput(cardData: $cardData)
2
.paymentCardInputStyle(.rows)

If these two styles do not match your use case, you can create your own style:

1
struct CustomPaymentCardInputStyle: PaymentCardInputStyle {
2
3
func makeBody(configuration: Configuration) -> some View {
4
VStack(alignment: .center) {
5
configuration.cardImage
6
7
Text("CC Number").font(.title3)
8
configuration.cardNumberField
9
10
Divider()
11
12
Text("Expiry").font(.title3)
13
configuration.expiryField
14
15
Divider()
16
17
Text("CVC").font(.title3)
18
configuration.cvcField
19
}
20
}
21
}
1
PaymentCardInput(cardData: $cardData)
2
.paymentCardInputStyle(CustomPaymentCardInputStyle())

Attest Cages

The Evervault iOS SDK includes the ability to attest connections to Cages.

To attest your Cage, you need to provide the expected PCRs to a Cage session.

1
import EvervaultCore
2
import EvervaultCages
3
4
let url = URL(string: "https://<CAGE_NAME>.)
5
let cageSession = Evervault.cageSession(
6
cageAttestationData: AttestationData(
7
cageName: "<CAGE_NAME>",
8
pcrs: PCRs(
9
pcr0: "<PCR0>",
10
pcr1: "<PCR1>",
11
pcr2: "<PCR2>",
12
pcr8: "<PCR8>",
13
)
14
)
15
)
16
17
do {
18
let response = try await cageSession.data(from: url)
19
// ...
20
} catch {
21
// ...
22
}

Considerations

As Cages currently use a self-signed certificate, it's necessary to include an exception for your Cage within the App Transport Security Settings in your Info.plist file.

1
<key>NSAppTransportSecurity</key>
2
<dict>
3
<key>NSExceptionDomains</key>
4
<dict>
5
<key>evervault.com</key>
6
<dict>
7
<key>NSIncludesSubdomains</key>
8
<true/>
9
<key>NSExceptionAllowsInsecureHTTPLoads</key>
10
<true/>
11
</dict>
12
</dict>
13
</dict>

Full example

A complete working example is included in the Evervault iOS package, located in the EvervaultIOSApp directory.

Runing the Sample App

To run the sample app:

  1. Open the EvervaultIOSApp.xcodeproj file in Xcode.
  2. Configure your Team ID and App ID in EvervaultIOSAppApp.swift or add EV_TEAM_UUID and EV_APP_UUID Environment Variables the Run Scheme.
  3. Select a simulator or physical device as the build target.
  4. Build and run the app.

Reference

EvervaultCore

Evervault.shared.config(teamId: String, appId: String)

A shared instance of the Evervault class. This is the simplest way to get up and running if you only need to use a single Evervault team/app.

1
import EvervaultCore
2
3
Evervault.shared.configure(teamId: "<TEAM_ID>", appId: "<APP_ID>")
Parameters
teamIdRequiredString

The Uuid of your Evervault Team

appIdRequiredString

The Uuid of your Evervault App

Evervault(teamId: String, appId: String)

Initializes a single instance of the Evervault class. You'll need to use this initializer if you require more than one Evervault team/app.

1
import EvervaultCore
2
3
let evervault = Evervault(teamId: "<TEAM_ID>", appId: "<APP_ID>")
Parameters
teamIdRequiredString

The Uuid of your Evervault Team

appIdRequiredString

The Uuid of your Evervault App

Evervault.encrypt(_ data: Any) async throws -> Any

Encrypts the provided data using Evervault Encrypt.

The encrypt function supports: Boolean, Numerics, String, Array, Dictionary and Data.

1
let encryptedData = try await Evervault.shared.encrypt("Super Secret Password")
2
// or
3
let encryptedData = try await evervault.encrypt("Super Secret Password")
Parameters
dataRequiredAny

The data you want to encrypt.

EvervaultInputs

PaymentCardInput(cardData: PaymentCardData)

Create a PaymentCardInput SwiftUI view

1
import EvervaultInputs
2
3
struct ContentView: View {
4
5
@State private var cardData = PaymentCardData()
6
7
var body: some View {
8
VStack {
9
PaymentCardInput(cardData: $cardData)
10
11
// Data captured:
12
Text("Encrypted credit card number: \(cardData.card.number)")
13
}
14
}
15
}
Parameters
cardDataRequiredPaymentCardData

The card data state for the PaymentCardInput view

EvervaultCages

Evervault.cageSession(cageAttestationData: AttestationData)

Create a URLSession which will attest connections to your Evervault Cage.

1
import EvervaultCore
2
import EvervaultCages
3
4
let cageSession = Evervault.cageSession(
5
cageAttestationData: AttestationData(
6
cageName: "<CAGE_NAME>",
7
pcrs: PCRs(
8
pcr0: "<PCR0>",
9
pcr1: "<PCR1>",
10
pcr2: "<PCR2>",
11
pcr8: "<PCR8>",
12
)
13
)
14
)
Parameters
cageAttestationDataRequiredAttestationData

The values used during the attestation handshake with your Cage

AttestationData

Config used to compare against the attestation doc served to the client from a Cage.

AttestationData
cageNameRequiredString

The name of the Cage to attest

pcrsRequiredPCRs

The platform configuration registers to compare against the attestation doc returned from the Cage

PCRs

The attestation measurements measurement expected to be embedded in the attestation document returned from a Cage.

PCRs
pcr0RequiredString

The value for PCR0 to attest

pcr1RequiredString

The value for PCR1 to attest

pcr2RequiredString

The value for PCR2 to attest

pcr8RequiredString

The value for PCR8 to attest