You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: API-PROTECTION.md
+24-21Lines changed: 24 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,32 +11,43 @@ approov api -add your.domain
11
11
```
12
12
Approov tokens will then be added automatically to any requests to that domain (using the `Approov-Token` header, by default).
13
13
14
-
Note that this will also add a public key certicate pin for connections to the domain to ensure that no Man-in-the-Middle attacks on your app's communication are possible. Please read [Managing Pins](https://approov.io/docs/latest/approov-usage-documentation/#public-key-pinning-configuration) to understand this in more detail.
14
+
Note that this will use [Managed Trust Roots](https://approov.io/docs/latest/approov-usage-documentation/#managed-trust-roots) to ensure that no Man-in-the-Middle attacks on your app's communication are possible.
15
15
16
16
> **NOTE:** By default a symmetric account key is used to sign the Approov token (HS256 algorithm), so that all API domains will share the same signing secret. Alternatively, it is possible to use a [keyset key](https://approov.io/docs/latest/approov-usage-documentation/#managing-key-sets) which may differ for each API domain and for which a wide range of different signing algorithms and key types are available. This requires you to first [add a new key](https://approov.io/docs/latest/approov-usage-documentation/#adding-a-new-key), and then specify it when [adding each API domain](https://approov.io/docs/latest/approov-usage-documentation/#keyset-key-api-addition). Note that this will impact how you verify the token on your API backend.
17
17
18
-
## REGISTERING APPS
19
-
In order for Approov to recognize the app as being valid it needs to be registered with the service. Extract the [IPA](https://approov.io/docs/latest/approov-usage-documentation/#ios-ipa-extraction) and then register it with Approov:
18
+
## ADD YOUR SIGNING CERTIFICATE TO APPROOV
19
+
You should add the signing certificate used to sign apps. These are available in your Apple development account portal. Go to the initial screen showing program resources:
20
20
21
-
```
22
-
approov registration -add /path/to/your/app.ipa
23
-
```
24
-
25
-
If you are building and running on an iOS simulator then there will be no `.ipa` file and you must ensure the app [always passes](https://approov.io/docs/latest/approov-usage-documentation/#adding-a-device-security-policy) on your simulator without needing to perform a registration.
21
+
26
22
27
-
> **IMPORTANT:** The registration takes up to 30 seconds to propagate across the Approov Cloud Infrastructure, therefore don't try to run the app again before this time has elapsed. During development of your app you can ensure it [always passes](https://approov.io/docs/latest/approov-usage-documentation/#adding-a-device-security-policy) on your device to not have to register the IPA each time you modify it.
23
+
Click on `Certificates` and you will be presented with the full list of development and distribution certificates for the account. Click on the certificate being used to sign applications from your particular Xcode installation and you will be presented with the following dialog:
28
24
29
-
[Managing Registrations](https://approov.io/docs/latest/approov-usage-documentation/#managing-registrations) provides more details for app registrations, especially for releases to the Apple App Store.
Bitcode is supported by Approov (if you included the appropriate Swift package) but its use requires a command line option to be specified when registering apps:
27
+
Now click on the `Download` button and a file with a `.cer` extension is downloaded, e.g. `development.cer`. Add it to Approov with:
32
28
33
29
```
34
-
approov registration -add YourApp.ipa -bitcode
30
+
approov appsigncert -add development.cer -autoReg
35
31
```
36
32
33
+
This ensures that any app signed with the certificate will be recognized by Approov.
34
+
35
+
If it is not possible to download the correct certificate from the portal then it is also possible to [add app signing certificates from the app](https://approov.io/docs/latest/approov-usage-documentation/#adding-apple-app-signing-certificates-from-app).
36
+
37
+
> **IMPORTANT:** Apps built to run on the iOS simulator are not code signed and thus auto-registration does not work for them. In this case you can consider [forcing a device ID to pass](https://approov.io/docs/latest/approov-usage-documentation/#forcing-a-device-id-to-pass) to get a valid attestation.
38
+
37
39
## FURTHER OPTIONS
38
40
See [Exploring Other Approov Features](https://approov.io/docs/latest/approov-usage-documentation/#exploring-other-approov-features) for information about additional Approov features you may wish to try.
39
41
42
+
### Development Key
43
+
You may wish to [set a development key](https://approov.io/docs/latest/approov-usage-documentation/#using-a-development-key) in order to force an app to be passed, if it may be resigned by a different app signing certificate to which you don't have access. Perform the call:
See [using a development key](https://approov.io/docs/latest/approov-usage-documentation/#using-a-development-key) to understand how to obtain the development key which is the parameter to the call.
50
+
40
51
### Changing Approov Token Header Name
41
52
The default header name of `Approov-Token` can be changed as follows:
42
53
@@ -65,15 +76,7 @@ ApproovService.prefetch()
65
76
This initiates the process of fetching an Approov token as a background task, so that a cached token is available immediately when subsequently needed, or at least the fetch time is reduced. Note that there is no point in performing a prefetch if you are using token binding.
66
77
67
78
### Prechecking
68
-
You may wish to do an early check in your app to present a warning to the user if it is not going to be able to obtain valid Approov tokens because it fails the attestation process. To do this you first need to enable the [Secure Strings](https://approov.io/docs/latest/approov-usage-documentation/#secure-strings) feature:
69
-
70
-
```
71
-
approov secstrings -setEnabled
72
-
```
73
-
74
-
> Note that this command requires an [admin role](https://approov.io/docs/latest/approov-usage-documentation/#account-access-roles).
75
-
76
-
Here is an example of calling the appropriate method in `ApproovService`:
79
+
You may wish to do an early check in your app to present a warning to the user if it is not going to be able to obtain valid Approov tokens because it fails the attestation process. Here is an example of calling the appropriate method in `ApproovService`:
Copy file name to clipboardExpand all lines: README.md
+1-4Lines changed: 1 addition & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
This quickstart is written specifically for native iOS apps that are written in Swift and making API calls using [`URLSession`](https://developer.apple.com/documentation/foundation/urlsession) that you wish to protect with Approov. If this is not your situation then check if there is a more relevant quickstart guide available.
4
4
5
-
This quickstart provides the basic steps for integrating Approov into your app. A more detailed step-by-step guide using a[Shapes App Example](https://github.com/approov/quickstart-ios-swift-urlsession/blob/master/SHAPES-EXAMPLE.md) is also available.
5
+
This page provides all the steps for integrating Approov into your app. Additionally, a step-by-step tutorial guide using our[Shapes App Example](https://github.com/approov/quickstart-ios-swift-urlsession/blob/master/SHAPES-EXAMPLE.md) is also available.
6
6
7
7
To follow this guide you should have received an onboarding email for a trial or paid Approov account.
8
8
@@ -61,6 +61,3 @@ The version of [`dataTaskPublisher(for:)`](https://developer.apple.com/documenta
61
61
If you wish to use an Approov protected version then please call `dataTaskPublisherApproov` instead. Note though that this method may block when it is called when requesting network communication with the Approov cloud. Therefore you shouldn't call this method from the main UI thread.
62
62
63
63
Note also that the methods related to `Performing Asynchronous Transfers` (introduced at iOS 15) do not currently provide Approov protection.
64
-
65
-
## BITCODE SUPPORT
66
-
The `ApproovService` swift package provides different versions with and without `bitcode` support. If you would like to support `bitcode` in your application, you should install a version of the `ApproovService` that supports it as well. You should use the latest version ending `-bitcode`.
Copy file name to clipboardExpand all lines: REFERENCE.md
+7Lines changed: 7 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,6 +27,13 @@ public static func setProceedOnNetworkFailure(proceed: Bool)
27
27
28
28
Note that this should be used with *CAUTION* because it may allow a connection to be established before any dynamic pins have been received via Approov, thus potentially opening the channel to a MitM.
29
29
30
+
## setDevKey
31
+
[Sets a development key](https://approov.io/docs/latest/approov-usage-documentation/#using-a-development-key) in order to force an app to be passed. This can be used if the app has to be resigned in a test environment and would thus fail attestation otherwise.
32
+
33
+
```ObjectiveC
34
+
+ (void)setDevKey:(NSString *)devKey;
35
+
```
36
+
30
37
## setApproovHeader
31
38
Allows to set the name of the header (`approovTokenHeader`) that the Approov token is added on, as well as an optional `prefix` String (such as "`Bearer `"). Set `approovTokenPrefix` to the empty string if it is not required. By default the token is provided on `Approov-Token` with no prefix.
Copy file name to clipboardExpand all lines: SECRETS-PROTECTION.md
+25-34Lines changed: 25 additions & 34 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,43 +3,23 @@ You should use this option if you wish to protect app secrets, including API key
3
3
4
4
These additional steps require access to the [Approov CLI](https://approov.io/docs/latest/approov-cli-tool-reference/), please follow the [Installation](https://approov.io/docs/latest/approov-installation/) instructions.
5
5
6
-
## ENABLING MANAGED TRUST ROOTS
7
-
Client secrets or API keys also need to be protected in transit. For 3rd party APIs you should not pin against their certificates since you are not in control of when they might be changed. Instead the [Managed Trust Roots](https://approov.io/docs/latest/approov-usage-documentation/#managed-trust-roots) feature can be used to protect TLS.
8
-
9
-
Ensure managed trust roots are enabled using:
10
-
11
-
```
12
-
approov pin -setManagedTrustRoots on
13
-
```
14
-
15
-
> Note that this command requires an [admin role](https://approov.io/docs/latest/approov-usage-documentation/#account-access-roles).
16
-
17
-
This ensures connections may only use official certificates, and blocks the use of self signed certificates that might be used by a Man-in-the-Middle (MitM) attacker.
18
-
19
6
## ADDING API DOMAINS
20
7
In order for secrets or API keys to be protected when being transmitted externally by the app, it is necessary to inform Approov about the domains on which they may be sent. Execute the following command:
21
8
22
9
```
23
10
approov api -add your.domain -noApproovToken
24
11
```
25
12
26
-
This informs Approov that it should be active for the domain, but does not need to send Approov tokens for it. Adding the domain ensures that the channel will be protected against Man-in-the-Middle (MitM) attacks.
13
+
This informs Approov that it should be active for the domain, but does not need to send Approov tokens for it. Adding the domain uses [Managed Trust Roots](https://approov.io/docs/latest/approov-usage-documentation/#managed-trust-roots) to ensure that the channel will be protected against Man-in-the-Middle (MitM) attacks.
27
14
28
15
## MIGRATING THE SECRET INTO APPROOV
29
-
It is assumed that you already have some client secrets and/or API keys in your app that you would like to migrate for protection by Approov. To do this you first need to enable the [Secure Strings](https://approov.io/docs/latest/approov-usage-documentation/#secure-strings) feature:
30
-
31
-
```
32
-
approov secstrings -setEnabled
33
-
```
34
-
> Note that this command requires an [admin role](https://approov.io/docs/latest/approov-usage-documentation/#account-access-roles).
35
-
36
-
You must inform Approov what the value of each secret is as follows:
16
+
It is assumed that you already have some client secrets and/or API keys in your app that you would like to migrate for protection by Approov. You must inform Approov what the value of each secret is as follows:
> Note that this command also requires an [admin role](https://approov.io/docs/latest/approov-usage-documentation/#account-access-roles).
22
+
> Note that this command requires an [admin role](https://approov.io/docs/latest/approov-usage-documentation/#account-access-roles).
43
23
44
24
These values can be changed at any time and will propagate within 5 minutes to all running instances of your apps. Since earlier released versions of the app may have already leaked `your-secret-value`, you may wish to refresh the secret at some later point when any older version of the app is no longer in use. You can of course do this update over-the-air using Approov without any need to modify the app.
45
25
@@ -111,28 +91,39 @@ approov policy -setRejectionReasons on
111
91
112
92
You will then be able to use the `rejectionReasons` value in the `ApproovError.rejectionError` returned from the network call to obtain a comma separated list of [device properties](https://approov.io/docs/latest/approov-usage-documentation/#device-properties) responsible for causing the rejection.
113
93
114
-
## REGISTERING APPS
115
-
In order for Approov to recognize the app as being valid it needs to be registered with the service. Extract the [IPA](https://approov.io/docs/latest/approov-usage-documentation/#ios-ipa-extraction) and then register it with Approov:
116
-
117
-
```
118
-
approov registration -add /path/to/your/app.ipa
119
-
```
94
+
## ADD YOUR SIGNING CERTIFICATE TO APPROOV
95
+
You should add the signing certificate used to sign apps. These are available in your Apple development account portal. Go to the initial screen showing program resources:
120
96
121
-
If you are building and running on an iOS simulator then there will be no `.ipa` file and you must ensure the app [always passes](https://approov.io/docs/latest/approov-usage-documentation/#adding-a-device-security-policy) on your simulator without needing to perform a registration.
97
+
122
98
123
-
> **IMPORTANT:** The registration takes up to 30 seconds to propagate across the Approov Cloud Infrastructure, therefore don't try to run the app again before this time has elapsed. During development of your app you can ensure it [always passes](https://approov.io/docs/latest/approov-usage-documentation/#adding-a-device-security-policy) on your device to not have to register the IPA each time you modify it.
99
+
Click on `Certificates` and you will be presented with the full list of development and distribution certificates for the account. Click on the certificate being used to sign applications from your particular Xcode installation and you will be presented with the following dialog:
124
100
125
-
[Managing Registrations](https://approov.io/docs/latest/approov-usage-documentation/#managing-registrations) provides more details for app registrations, especially for releases to the Apple App Store. Of particular interest to iOS is the use of codesigning certificates that belong to different team identifiers.
Bitcode is supported by Approov (if you included the appropriate Swift package) but its use requires a command line option to be specified when registering apps:
103
+
Now click on the `Download` button and a file with a `.cer` extension is downloaded, e.g. `development.cer`. Add it to Approov with:
128
104
129
105
```
130
-
approov registration -add YourApp.ipa -bitcode
106
+
approov appsigncert -add development.cer -autoReg
131
107
```
132
108
109
+
This ensures that any app signed with the certificate will be recognized by Approov.
110
+
111
+
If it is not possible to download the correct certificate from the portal then it is also possible to [add app signing certificates from the app](https://approov.io/docs/latest/approov-usage-documentation/#adding-apple-app-signing-certificates-from-app).
112
+
113
+
> **IMPORTANT:** Apps built to run on the iOS simulator are not code signed and thus auto-registration does not work for them. In this case you can consider [forcing a device ID to pass](https://approov.io/docs/latest/approov-usage-documentation/#forcing-a-device-id-to-pass) to get a valid attestation.
114
+
133
115
## FURTHER OPTIONS
134
116
See [Exploring Other Approov Features](https://approov.io/docs/latest/approov-usage-documentation/#exploring-other-approov-features) for information about additional Approov features you may wish to try.
135
117
118
+
### Development Key
119
+
You may wish to [set a development key](https://approov.io/docs/latest/approov-usage-documentation/#using-a-development-key) in order to force an app to be passed, if it may be resigned by a different app signing certificate to which you don't have access. Perform the call:
See [using a development key](https://approov.io/docs/latest/approov-usage-documentation/#using-a-development-key) to understand how to obtain the development key which is the parameter to the call.
126
+
136
127
### Header Prefixes
137
128
In some cases the value to be substituted on a header may be prefixed by some fixed string. A common case is the presence of `Bearer` included in an authorization header to indicate the use of a bearer token. In this case you can specify a prefix as follows:
0 commit comments