Adds an exclusion URL regular expression. If a URL for a request matches this regular expression
then it will not be subject to any Approov protection. Note that this facility must be used with
EXTREME CAUTION due to the impact of dynamic pinning. Pinning may be applied to all domains added
using Approov, and updates to the pins are received when an Approov fetch is performed. If you
exclude some URLs on domains that are protected with Approov, then these will be protected with
Approov pins but without a path to update the pins until a URL is used that is not excluded. Thus
you are responsible for ensuring that there is always a possibility of calling a non-excluded
URL, or you should make an explicit call to fetchToken if there are persistent pinning failures.
Conversely, use of those option may allow a connection to be established before any dynamic pins
have been received via Approov, thus potentially opening the channel to a MitM.
Adds the name of a header which should be subject to secure strings substitution. This
means that if the header is present then the value will be used as a key to look up a
secure string value which will be substituted into the header value instead. This allows
easy migration to the use of secure strings. Note that this should be done on initialization
rather than for every request as it will require a new OkHttpClient to be built. A required
prefix may be specified to deal with cases such as the use of "Bearer " prefixed before values
in an authorization header.
Enables automatic message signing for outgoing requests. The Approov SDK provides the signing key after a
successful attestation and the resulting signature is attached to each protected request via the standard
Signature and Signature-Input headers as defined by the HTTP Message Signatures specification. Provide
a defaultFactory to control which components are included in the canonical representation, or optionally
override the configuration for specific hosts via hostFactories.
Fetches a custom JWT with the given payload. Note that this call will require network
transaction and thus will take some time. It should always be called with await.
If the attestation fails for any reason then an ApproovException is thrown. This will be
ApproovRejectionException if the app has failed Approov checks or ApproovNetworkException
for networking issues where a user initiated retry of the operation should be allowed.
Fetches a secure string with the given key. If newDef is not null then a
secure string for the particular app instance may be defined. In this case the
new value is returned as the secure string. Use of an empty string for newDef removes
the string entry. Note that this call may require network transaction and thus may take some
time. You should always call with await. If the attestation fails for any reason then an
ApproovException is thrown. This will be ApproovRejectionException if the app has failed
Approov checks or ApproovNetworkException for networking issues where a user initiated retry
of the operation should be allowed. Note that the returned string should NEVER be cached by
your app, you should call this function when it is needed.
Initiates a request to obtain an Approov token and other results. If an Approov token fetch has been completed
previously and the tokens are unexpired then this may return the same one without a need to perform a network
transaction. Note though that the caller should never cache the Approov token as it may become invalidated at any point.
Gets the signature for the given message using the account message signing key. This is a
convenience alias for getMessageSignature that mirrors the native SDK naming and may provide
clearer intent when working alongside install message signing.
Gets the device ID used by Approov to identify the particular device that the SDK is running on. Note that
different Approov apps on the same device will return a different ID. Moreover, the ID may be changed by an
uninstall and reinstall of the app.
Gets the signature for the given message using the install message signing
key, the per-installation ECDSA P-256 key whose public half is carried in the
Approov token as the ipk claim. A backend verifies the signature with that
public key, so the token must be sent alongside the signature.
Gets the signature for the given message. This uses an account specific message signing key that is
transmitted to the SDK after a successful token fetch if the facility is enabled for the account and
the token is received from the primary (rather than failover) Approov cloud. Note
that if the attestation failed then the signing key provided is actually random so that the
signature will be incorrect. An Approov token should always be included in the message
being signed and sent alongside this signature to prevent replay attacks.
Fetches the pins from the current configuration of the SDK. This is returned as a map from URL domain (hostname
only) to the possible pins for that domain. If there is no map entry for a domain then that indicates that the
connection is not specifically pinned, or managed trust roots should be used if they are present (keyed from the
"*" domain). The type of pin requested determines the data in each of the pins. This is typically the base64 encoding
of the hash of some aspect of the certificate. A connection is considered to be valid if any certificate in the chain
presented is one with the same hash as one in the array of hashes.
Initialize the Approov SDK. This must be called prior to any other methods on the ApproovService.
The returned future completes once initialization has finished: a non-empty config is forwarded
to the native Approov SDK and awaited, so a failure (for instance a different configuration string
already in force in this process) surfaces here as an ApproovException and leaves the service
layer state unchanged. Other methods that require initialization await the same result.
Returns whether Approov-backed protection (token injection, pinning, secure
string substitution) is actually active. Returns false when the service
layer is initialized in bypass mode with an empty configuration string. Like
isInitialized, the answer is read from process-wide native state (a static,
shared across FlutterEngines) rather than a per-isolate Dart flag, and returns
false (rather than throwing) only when the native layer reports protection
inactive or is unreachable.
Returns whether the Approov service layer has been initialized. This is true
even when initialized in bypass mode with an empty configuration string - it
does not indicate that Approov protection is actually active. Use
isApproovEnabled for that. The answer is read from the native layer, which
holds the state process-wide - a static, so it is shared by every
FlutterEngine in the process, not just the one this isolate belongs to -
rather than a local Dart flag: Dart-level
state is per-isolate and a background isolate that never itself called
initialize would otherwise report false even though the SDK is already
initialized from another isolate. Returns false, rather than throwing, only
when the native layer reports uninitialized or is unreachable.
Performs a precheck to determine if the app will pass attestation. This requires secure
strings to be enabled for the account, although no strings need to be set up. This will
likely require network access so may take some time to complete. It should always be called
with await to allow capture of any ApproovException thrown, if the precheck fails or if there
is some other problem. ApproovRejectionException is thrown if the app has failed Approov checks
or ApproovNetworkException for networking issues where a user initiated retry of the operation
should be allowed. An ApproovRejectionException may provide additional information about the
cause of the rejection.
Restores static initialization and runtime configuration state, so one
test cannot leak state into the next. _isRootIsolate is included
deliberately: it is written by a successful initialize and then selects
between the callback and blocking background-channel paths, so leaving it
set would make later tests order-dependent.
Snapshot of the mutable runtime configuration, so tests can assert that a
successful (re-)initialization resets every field
(TESTING_REQUIREMENTS.md §1, "Service-Layer State Only Updated On
Success") rather than the subset with individual getters.
Sets the header that the Approov token is added on, as well as an optional
prefix String (such as "Bearer "). By default the token is provided on
"Approov-Token" with no prefix.
Sets a binding header that must be present on all requests using the Approov service. A
header should be chosen whose value is unchanging for most requests (such as an
Authorization header). A hash of the header value is included in the issued Approov tokens
to bind them to the value. This may then be verified by the backend API integration. This
method should typically only be called once.
Sets a hash of the given data value into any future Approov tokens obtained in the 'pay' claim. If the data values
are transmitted to the API backend along with the Approov token then this allows the backend to check that the
data value was indeed known to the app at the time of the token fetch and hasn't been spoofed. If the data is the
same as any previous one set then the token does not need to be updated. Otherwise the next token fetch causes a
new attestation to fetch a new token. Note that this should not be done frequently due to the additional latency on
token fetching that will be caused. The hash appears in the 'pay' claim of the Approov token as a base64 encoded
string of the SHA256 hash of the data. Note that the data is hashed locally and never sent to the Approov cloud service.
Sets a development key indicating that the app is a development version and it should
pass attestation even if the app is not registered or it is running on an emulator. The
development key value can be rotated at any point in the account if a version of the app
containing the development key is accidentally released. This is primarily
used for situations where the app package must be modified or resigned in
some way as part of the testing process.
Obsolete no-op. Retained so existing code keeps compiling; the value is
ignored and network-failure behaviour is decided entirely by the service
mutator.
Substitutes the given query parameter in the Uri. If no substitution is made then the
original Uri is returned, otherwise a new one is constructed with the revised query
parameter value. Since this modifies the Uri itself this must be done before making the
request. If it is not currently possible to fetch secure strings token due to
networking issues then ApproovNetworkException is thrown and a user initiated retry of the
operation should be allowed. ApproovRejectionException may be thrown if the attestation
fails and secure strings cannot be obtained. Other ApproovExecptions represent a more
permanent error condition.
Version of this service layer, reported to the Approov SDK as a user
property at initialization so the attestation record shows which layer and
which release produced it. approov-service-okhttp reports the same way.
