Approov CLI Tool Reference

Overview

The Approov command line tool is used for administering the operation of your Approov service. Builds of the tool are available for Linux, MacOS and Windows. All commands require a valid management token. The general form of all commands is:

approov <command> [<management-token-path>] [option]...

A full list of valid commands can be obtained by invoking the tool with no parameters. The valid command arguments are api, device, devicecheck, management, metrics, monitoring, pin, policy, registration, sdk, secret, token, usage and whoami. The options available for each of those commands is provided in the following sections. Help for any command can be obtained by invoking with:

approov <command>

The management token may be specified as a path as the second parameter or, alternatively, the token may be held in the environment variable APPROOV_MANAGEMENT_TOKEN. If specified on the command line then this overrides any environment variable token.

An Approov 1 backwardly compatible version of registration options is made available by invoking the tool with an executable name registration (or registration.exe for Windows). More details at Approov Legacy Registration Tool Mode.

API Command

approov api [<management-token-path>] [option]...
Option Description
-add <domain> Adds the given new domain to the set that Approov tokens will be served for. By default a leaf certificate public key pin will be set for the domain. A check is made that the local and remote views of the certificate at the given domain endpoint are the same, and the domain will not only be added if so. This behavior can be changed using the -pinType option. Note that additions are immediately added into production apps so that they are able to obtain Approov tokens for the given domain.
-check Checks all of the API domains to ensure that they are both accessible and that the pins specified match at least one certificate in the chain. The certificate chain is obtained via a local network access. This command can be used in a periodic check script to generate some kind of alert if the pins are incorrect and may be causing app failures in production.
-jwe Used in conjunction with the -add option to specify that the newly added API domain that have encrypted JWE Approov tokens issued for it.
-list Lists all of the API domains on which Approov tokens are served for this account. Also shows if an API domain uses JWE Approov tokens.
-pinType <type> Selects the type of leaf public key pin that will be obtained for the -add command. Possible options are as follows:
  • matching: This is the default. It indicates that a leaf pin should be obtained both via local network access and remotely using the Approov servers. They must match for the operation to succeed.
  • local: Indicates that the pin used should be the one obtained from local network access.
  • remote: Indicates that the pin used should be the one observed by the Approov servers rather than the one obtained from local network access.
  • none: Indicates that no pin should be obtained and can be used to add a new domain where no pin is added.
-remove <domain> Removes the given API domain from the set on which Approov tokens are served. Note that this has an immediate impact on production apps so must be used with care. An administration level management token is required to perform this operation.
-setAll <pathname> Sets all of the API domains and the pinning information for the account. The format of this file is explained in Public Key Pinning. Note that this may also be used to determine which API domains will server JWE (as opposed to JWS) Approov tokens using the jwe flag as pin for the domain. An administration level management token is required to use this option and the impact on production is immediate so care must be taken with any modifications. An initial check of the domains is performed first to give the user confidence that they are correct.

Device Command

approov device [<management-token-path>] [option]...
Option Description
-add <device-ID> Adds the given device-id to the set that have an explicit override security policy for them. The device-id is a base64 encoded identification string that can be obtained from logging on the device or from the did claim in an Approov token generated on the device. The -policy option may be used in conjunction with this option to determine the specific policy to be set for the device, otherwise the current security policy for the account is used. The -pinMode option may be used in conjunction with this option to determine the pinning mode for the device, otherwise the default pins are used. Note if a particular device-id has previously had a policy set for it then this option allows the previous settings to be updated.
-banMode <mode> This option may be used in conjunction with the -add option to specify a DeviceCheck banning mode for an iOS device. This option is only useful if DeviceCheck has been enabled using the `approov devicecheck` commands. This specifies a particular banning stance for the device with the selected ID where mode means:
  • query: Indicates that banning should be based on the current state of the bits for a physical device as held by Apple. This is the default.
  • ban: Indicates that when the device next tries to attest its bits should be set and it should become a banned device, that is no longer able to receive valid Approov tokens.
  • unban: Indicates that when the device next tries to attest its bits should be cleared, thus clearing any banned status for the device. Thus it should be able to receive valid Approov tokens again if it otherwise meets the required criteria.
-list Lists all of the devices that have explicit override policies set for them. This also lists the name of the user (obtained from their management token) that last set the policy for the device to help determine the user of the device. Note, however, that any management token can be used to remove any device from the list.
-pinMode <value> This option may be used in conjunction with the -add option to specify a particular pinning mode for the device. If an option is used (other than the default pin) then this causes a custom dynamic configuration to be sent to the device the next time it connects. Pinning mode options are as follows:
  • pin: Indicates that pinning should be applied as normal to the device, this is the default.
  • unpin: Indicates that all pins for the device should be removed. This can be used for analysis or pentesting when it may be necessary to allow analysis of the app’s communication.
  • block: Indicates that a pinning failure should be forced on all user specified domains that have any pins set.
  • blockAll: Indicates that a pinning failure should be forced on all user specified domains and the Approov SDK communication with the Approov cloud. This will typically cause a MITM_DETECTED error.
-policy <policy> This option may be used in conjunction with the -add option to set the specific policy for a device. This is provided as three comma separated items as follows in the given order:
  • rules-policy: Name of the overall rules policy to be used, typically default.
  • rejection-policy: Policy to be used to determine which devices to reject so that they do not obtain a valid Approov token.
  • annotation-policy: Policy for the inclusion of some characteristics of the device in the anno claim of Approov tokens.

A full list of available policy combinations is available in the Security Policies section.

-remove <device-ID> Removes the given device-id from the list that have an explicit override policy. The device will then default to use the standard policy for the account.

DeviceCheck Command

approov devicecheck [<management-token-path>] [option]...

Note that the devicecheck command (apart from -get) requires the use of an admin level management token.

Option Description
-addAuthKey <auth-file> Adds a DeviceCheck key to your account and enables the use of Apple DeviceCheck in your account. The key is downloaded from the Apple developer portal and should be of the form AuthKey_ID.p8, where the ID is the identifier for your particular key. The key must have been granted DeviceCheck privileges. Note that the -teamID option must also be specified.
-bits <value> This determines the individual bits which are available for usage by Approov. Apple allows up to two bits to be persisted for each physical device under your Apple developer account. If bit0 or bit1 is specified then only that bit will be used by Approov and your are free to use the other bit for your own purposes. If not specified then both is assumed, and this automatically enables the automatic banning feature in Approov.
-dev By default the Apple production endpoint (https://api.devicecheck.apple.com) is used. If this option is specified then the development endpoint (https://api.development.devicecheck.apple.com) is used instead.
-expiry <duration> This specifies an expiry duration for any device bans in terms of months. This means that if the last update is older than the specified period then the bits are considered to be cleared. The default period is 12 months. The parameter should be specified as a numeric value followed by m (e.g. 1m for one month).
-get Gets the current device check information.
-remove Removes the device check information from the account. This means that any device bans will be ended.
-teamID <ID> This option must be used in conjunction with -addAuthKey and specifies the team identifier for your apps. This identifies apps as being issued by your team and is required in order to make calls to Apple APIs to get and update the device check bits.

Management Command

approov management [<management-token-path>] [option]...

Note that the management command requires the use of an admin level management token.

Option Description
-add <params> Adds a new management token for a new user. By default this will be a developer token, but an administration token may be added by using the -admin option. The params are composed of three comma separated parameters as follows:
  • user-email: Email address of the user that the token is being issued to. This is simply used as a label to uniquely identify the user.
  • user-name: Name of the user that will be included in the token. Note that to accommodate spaces in the name single quotes can be used around the whole of params.
  • duration: The duration of the issued token, such as 30d to indicate 30 days. Available suffixes are y (years), d (days) and h (hours). Note that it is not possible to create a new token with a duration that is longer than that of the admin token being used to create it.

The result is the string representing the new management token. This should be communicated securely to the new user.

-admin Used in conjunction with the -add option to add a new administration, rather than development, token.
-file <pathname> Used in conjunction with the -add option to write the new management token to the given pathname.
-list Lists all of the management tokens which have the same or earlier expiry times than the administration level token used to access this information. This provides the user name, email, expiry time and the management token string that can be used to resend to the user or to revoke. This information should be treated carefully and not stored in any easily accessible files.
-revoke <token> Revokes the given token string. A revoked token can no longer be used for any operation. Token revocation can be performed if there is a concern that the security of a given token has been compromised, or a management token holder is no longer part of a development project.

Monitoring Command

approov monitoring [<management-token-path>] [option]...

Note that most monitoring commands (apart from getting the -getHealthCheckURL) requires the use of an admin level management token.

Option Description
-add <email> Adds a new email to the monitoring recipient list. This email will be sent a summary of monthly activity at the end of the billing period. If daily summaries are enabled then a daily summary will also be sent at midnight UTC. Note that no email confirmation is sent, so care must be taken to enter a valid email address.
-get Gets the current monitoring configuration, showing the summary period, email recipients and any emergency contact set.
-getHealthCheckURL Gets the URL to be used for any monitoring of the health of the primary Approov service.
-remove <email> Removes the given email address from the list of those that will receive summaries of account activity.
-selectDailySummary Selects the option to receive daily summaries of account activity.
-selectMonthlySummary Selects the option to receive monthly summaries of account activity.
-setEmergencyContact <info> Provides a string providing emergency contact information in case we need to contact you urgently about service operation. This may be an email but ideally should include some means for contact outside of normal office hours.

Metrics Command

Access to the Grafana based metrics dashboards can be initiated without any further options. Simply use:

approov metrics

Pin Command

approov pin [<management-token-path>] [option]...
Option Description
-add <pin> Adds the given pin to the domain specified with -api. The pin should be specified as a base64 encoded 256-bit value, representing a subject public key hash, which is deemed acceptable for a connection to the domain.
-api <domain> Specifies the API domain that various other options are acting upon. If adding or removing pins then this should be a domain that has already been added to the account.
-forceApplyPins Forces application of the current level of pinning to all clients whose last obtained pins via a getPins call was to an earlier version. This asserts the isForceApplyPins flag for future token fetches on those apps and the implementation should ensure that pin bindings are updated at the earliest convenience.
-getCertChainPins Obtains the public key pins for the certificate chain for the domain specified with -api. The leaf certificate is shown first and then the chain right up to the root certificate. The public key pin, expiry date and subject information is provided for each element in the chain. This can be used to obtain the pins for intermediate certificates.
-getCertPin <file> Extracts the public key pin for the certificate provided in the given file. This must be a base64 encoded PEM certificate. This can be used for obtaining the pin for a certificate that has not yet been put into active usage. The expiry date and subject information is also provided. Note that no -api is required.
-getLeafPin <type> Obtains the public key pin for the leaf certificate at the domain specified with -api. The type specifies the pin extraction requirement and may one of:
  • matching: Check local and remote pins and ensure they match.
  • local: Extract the pin as observed via local network access.
  • remote: Extract the pin as observed by the Approov servers,
-list Lists all of the pins associated with the API domain specified with -api.
-remove <pin> Removes pin from the API domain specified with -api.

Policy Command

approov policy [<management-token-path>] [option]...
Option Description
-get Gets the current security policy being applied to the account. This is provided as a comma separated string composed of the rules policy, rejection policy and annotation policy as required by the -set option. However, more detailed information is also provided including a description of the impact of the current policy settings.
-getIPTracking Gets the current IP tracking setting for the account, which may be token, full or none.
-set <policy> This sets the overall security policy for the account. It is provided as three comma separated items as follows in the given order:
  • rules-policy: Name of the overall rules policy to be used, typically default.
  • rejection-policy: Policy to be used to determine which devices to reject so that they do not obtain a valid Approov token.
  • annotation-policy: Policy for the inclusion of some characteristics of the device in the anno claim of Approov tokens.

A full list of available policy combinations is available in the Security Policies section. Modification of the overall security policy requires an administration level management token. It is actioned for production apps within 30 seconds.

-setIPTracking <setting> This sets the IP tracking policy for the account as follows:
  • token: The IP address of the requesting end user device will be put into the ip claim of the Approov token but all logging made by Approov servers will only include a one-way hash of the IP addreses. This is the default behaviour for an account.
  • full: The IP address of the requesting end user device will be put into the ip claim of the Approov token and may be logged by Approov systems.
  • none: The IP address is not present in the Approov token and is only stored as a one-way hash by the Approov server side systems.

Registration Command

approov registration [<management-token-path>] [option]...
Option Description
-add <app-path> Adds (or updates) an app registration for the app package with the given app-path. This package must have an extension of .ipa for iOS or .apk for Android. The required signature characteristics are extracted from the app and transmitted to the Approov cloud service. New registrations are active within 30 seconds. Note that it is important that the package provided is exactly the same one as will be provided in the app store.
-expireAfter <duration> This may be used in conjunction with a -add option to set a temporary period for a registration. By default, a registration is permanent, and this means that it can only be removed using an administration token. Generally, registrations used for development purposes should be temporary and permanent registrations should be reserved for production apps. Note that if a registration already exists then it is updated to have the longest expiry time between its existing status and the new registration being made. The registration time for an app is always updated by a new registration. The options for the duration may be specified in y (years), d (days), h (hours), m (minutes) or s (seconds). Multiple time units may be used as long as they are specified in this order, e.g. 3d12h to register for three and a half days.
-libraryID <ID> The library ID against which an app is registered is normally extracted automatically from the app. If this is not possible, perhaps because the app uses the Approov SDK embedded inside some other SDK, then this option may be used in conjunction -add to specify the SDK library being used.
-list Lists all of the app registrations that are active for the account. They are listed in order of their registration time, so that the most recent registration is always shown at the end of the list. The full registration signature (which may be used for a -remove option) is shown, along with information about the SDK version used and the registration time. The automatic expiry time of the registration is also shown for temporary registrations.
-remove <signature> Removes the app registration with the given signature. This corresponds to the first contiguous string for the app registration obtained with the -list option. Any removal of the registration will have an impact on production apps within 30 seconds. Note that permanent app registrations can only be removed with an administration level management token or with a token issued to the same user name as used to originally register it.
-removeMatching <params> Removes multiple matching app registrations. It is designed to allow easier removal of older registrations that are no longer in active use. The params are two comma separated items as follows:
  • app-name: The app package name that must match for the removal to occur.
  • age: Specifies the minimum age for the registration time to match. This allows removal to be restricted to older registrations. The options for the duration may be specified in y (years), d (days), h (hours), m (minutes) or s (seconds).

Note that an administration level management token is required to use this option.

-versionName <override> This option may be used in conjunction with -add to overwrite the version number of the app in the registration with override. It is not advisable to use this option for permanent registrations so that the actual published app version number can be clearly seen, but for temporary development registrations this is useful for marking a particular registration with some ancillary information, such as a build number of hash from a CI system. Note that any spaces in the override value are removed.

SDK Command

approov sdk [<management-token-path>] [option]...
Option Description
-bitcode This can be used in conjunction with the -getLibrary option and causes a bitcode (rather than native code) version of the iOS SDK to be obtained. We suggest you use the native version where possible for enhanced security, but the bitcode version is available when a bitcode release is mandatory for the project.
-getConfig <pathname> This obtains the latest initial configuration string for the account and saves it to the given file. This file must be integrated into the mobile app and used to initialize the Approov SDK.
-getLibrary <pathname> This obtains a library SDK package that can be integrated with a mobile app. It is written to the given pathname that must have an extension of either .zip (for iOS SDKs) or .aar (for Android SDKs). By default the latest SDK library that is available is obtained. Note that the library obtained may be modified with either the -bitcode or -libraryID options.
-libraryID <ID> This option may be used in conjunction with the -getLibrary option to get a specific version ID of the library. In some cases Approov support may provide you with a specific ID to obtain a library with specific characteristics or one suitable for embedding inside another SDK.

Secret Command

approov secret [<management-token-path>] [option]...

Note that the secret command requires the use of an administration level management token.

The 512-bit secret that is obtained with the -get command is the one used for checking the symmetrically signed JWS tokens. If you wish to decrypt a JWE generated by Approov then the 256-bit key is obtained by performing a SHA256 hash of the secret obtained using the command.

Option Description
-change This causes the Approov token secret to be immediately rotated with a new random value that is output by the command. Typically, this should only be done if there is a significant concern that the prior Approov secret may have been compromised. This change happens immediately so newly generated Approov tokens will use the revised secret. The -forcePrintable option may be added to force the new secret to use printable characters in its raw form.
-clearKeyID Clears any key ID that is being included in JWS tokens generated for the account.
-forcePrintable This may be used in conjunction with the -change option to force the new secret to use printable characters in its raw form. This should only be used if your JWT verification library only supports a printable secret.
-get <representation> This gets the Approov token secret in the selected representation with options as follows:
  • base64: Encoded in base64 format.
  • base64url: Encoded in the base64ul format without the optional padding characters.
  • raw: Raw binary form. However, this is only possible if the secret only contains printable characters, which will not normally be the case.

The binary secret itself is always 64 bytes (512-bits) in length. It should be integrated into backend integrations to check the validity of Approov tokens. Note that the secret should be kept with the utmost care, since it allows valid Approov tokens of arbitrary lifetime to be generated. The token secret itself should never be included in the mobile app or any software in the public domain.

-getJWK This gets the Approov token secret in the JSON Web Key (JWK) format. This may be an easier for integration with those backend systems which support this format.
-getKeyID Gets any key ID that has been set in the account and will appear in the kid field in any JWS headers.
-setKeyID <id> This sets the specific id to become the label for the Approov secret and this will appear in the kid field in the header of JWS tokens for the account. This will also be provided in any JWK obtained with -getJWK.

Token Commands

approov token [<management-token-path>] [option]...
Option Description
-check <token> Checks the validity of the provided token value. This shows if the token is valid (or expired) or not and also decodes the contents of the token. This works with either JWS or JWE Approov tokens. Note that a LoggableToken may be provided, in which case its validity may be checked.
-genExample <domain> Causes an example Approov token to be generated for the given domain. This must be a domain that has been previously added to the account so that Approov tokens can be generated for it. The generate token will have an expiry time of 1 hour to allow it to be used for testing backend integrations. By default the token will be valid, but this can be changed with the -type option. A JWE Approov token is generated if the selected API domain is configured to do this. The token will include typical example claims. A data hash pay claim may be added using the -SetDataHashInTokenOption.
-genLongLived <params> This generates a long lived Approov token that is valid for a longer duration. This is useful to enable server-to-server communication to an API protected with Approov. Long lived tokens should never be put into public clients, such as mobile apps or web pages. The params consists of two comma separated entries:
  • Issuer: This is a string that is placed in the iss claim of the Approov token to identify different sources of long lived Approov tokens.
  • Duration: Provides a duration for the Approov token such as 30d to indicate 30 days. Available suffixes are y (years) and d (days).
Note that this option requires the use of an admin level management token.
-setDataHashInToken <data> This can be used in conjunction with the -genExample option to set the hash in the pay claim of the Approov token. The data parameter should be the data (as would be passed to the similarly named SDK method) to be hashed and bound to the token. This can be used for checking the token binding checking in backend API integrations.
-type <state> Sets the type of an example Approov token. This option may be used in conjunction with -genExample in order to select a token type other than a valid one. Options for state are as follows:
  • invalid: Generates a token that is not signed with the token secret and provides an Approov token that represents a rejection.
  • failover: Generates a token that might have been produced in failover mode and does not contain various claims.
  • valid: Produces a valid token (note that this is the default)

Usage Command

Access to the legacy usage and monitoring portal can be initiated without any further options. Simply use:

approov usage

Whoami Command

This provides information about the management token being used to access the Approov service, either the one added to the APPROOV_MANAGEMENT_TOKEN environment variable or one explicitly provided on the command line. The name of the account and the information about the user the token was issued to is provided, along with the expiry time of the token. To get this information simply use:

approov whoami