- NP --> ARES</code></pre> <p>The antipiracy package contains tools for the detection of different categories of pirate software that may be installed and running on target devices. </p> <p>At its core, this package runs a battery of tests against all the installed applications to check for potential active pirate software, which depending on your policies may be a security environment issue. It then compiles the results into an attestation (it can either be uninitialized, clear, or failed) which is returned to your app, where you can check what has been found and act accordingly.</p> <div class="admonition question"> <p class=admonition-title>Purpose of the <code>antipiracy</code> package</p> <p>You may want to use this package if you consider that executing your app alongside pirate software which may be interfering/bypassing your code/protections is a security environment issue.</p> </div> <div class="admonition warning"> <p class=admonition-title>Tampering and System protection</p> <p>The <code>antipiracy</code> package by itself does not do any kind of signature/tampering check (for that, refer to <a href=../../integrity/integrity/ >integrity</a> package) or system wide verification (<a href=../../rooting/rooting/ >rooting</a>). It just tells you whether software that may be trying/have already interfered/bypassed your protection mechanisms is installed or not.</p> </div> <p>To <a href=../implementation/ >implement</a> this, you initialize <code>KevlarAntipiracy</code> and provide your desired settings (which influence what is to be detected and what not). Then you can submit attestation requests (which will be executed according to your settings).</p> <p>Each attestation request will cause Kevlar to grab the package list, run the appropriate checks and return an attestation.</p> <p>The settings you provide influence what will be included in the attestation.</p> <h2 id=attestation-process-overview>Attestation process overview<a class=headerlink href=#attestation-process-overview title="Permanent link">¶</a></h2> <p>When you require an attestation (through <code>antipiracy.attestate(context)</code>), kevlar executes the following operations:</p> <ol> <li>The installed package list is queried from the <code>PackageManager</code>. Make sure to <a href=../privacy/ >have the right permissions</a> to do that, since from Android 11 you need to add queries in your app's manifest, see the <a href=../implementation/ >implement</a> page;</li> <li>The test battery is initialized (to match your scan parameters) and ran on all packages, against the precompiled dataset onboard the library;</li> <li>The results are collected, processed, filtered, and returned in an <code>AntipiracyAttestation</code>.</li> </ol> <p>There is only one type of attestation that can be produced.</p> <p>The attestation is returned in <code>AntipiracyAttestation</code> (sealed class), which depending on the detection status can be of three types:</p> <ul> <li><code>Blank</code>: This is a non-processed status. It should not be interpreted, as it does not carry any meaning about the attestation result. It is not to be interpreted as <code>Clear</code>;</li> <li><code>Clear</code>: The attestation has passed. There is nothing to report. This means that no installed software has triggered the detection from the battery of tests that have been executed, in compliance with the given scan parameters;</li> <li><code>Failed</code>: The attestation has not passed. Pirated software has been detected. You can read which software has tripped the detection in the attestation result. The action you were about to do may be compromised, and you should not proceed.</li> </ul> <div class="admonition warning"> <p class=admonition-title>Warning</p> <p><code>Blank</code> is completely different from <code>Clear</code> (or <code>Failed</code>). It means that the software is initialized but that nothing has been done yet. Do not mix them up.</p> </div> <h2 id=performance>Performance<a class=headerlink href=#performance title="Permanent link">¶</a></h2> <p>Package detection and testing make use of coroutines to run scan operations in parallel for each package, to minimize the time taken to run through all packages.</p> <p>Most of the checks consist of some type of string analysis (characters & regex matching and abstract alphabet inference, more details in <a href=../detection/ >detection</a>), which have pretty decent running times while being precise and reliable tools.</p> <p>Scan settings are taken into account intelligently to analyze and run the battery of tests over all packages in one single pass, regardless of how many checks are to be performed, and to execute the single package battery test in parallel.</p> <div class="admonition tip"> <p class=admonition-title>Timing</p> <p>The full attestation process takes from start to finish ≈ 75-200ms for my devices and emulators (assuming the full app list is returned, which it won't for Android 11+ [which is actually good news for performance, since the time taken for computing the whole attestation is linearly proportional to the number of applications returned by <code>PackageManager</code>]). It is mainly influenced by the processing power of the device, the number of apps installed, and your scan configuration.</p> <p>It is decently fast, given that it is intended to be run quickly in the background before business-critical transactions (e.g. when the user clicks "purchase", we first check that the device is clean and then actually contact Google Play to initiate the high-value transaction).</p> </div> <h2 id=configuring-kevlarantipiracy>Configuring <code>KevlarAntipiracy</code><a class=headerlink href=#configuring-kevlarantipiracy title="Permanent link">¶</a></h2> <p>The antipiracy module is easy to configure, since it works automatically: you just have to choose which search criteria is used.</p> <p>You may choose to configure the antipiracy module manually (using the dedicated DSL, more flexibility), or just using one of the default configurations.</p> <div class=highlight><span class=filename>Default Configurations</span><pre><span></span><code><a id=__codelineno-0-1 name=__codelineno-0-1 href=#__codelineno-0-1></a><span class=kd>private</span><span class=w> </span><span class=kd>val</span><span class=w> </span><span class=nv>antipiracy</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>KevlarAntipiracy</span><span class=p>.</span><span class=na>Defaults</span><span class=p>.</span><span class=na>Full</span><span class=p>()</span>
0 commit comments