Verschleierung konfigurieren

Wie die Einstellungen zu Babel gelangen

Das Paket definiert für jedes Attribut der Babel-Aufgabe eine MSBuild-Eigenschaft oder ein MSBuild-Element und übergibt sie an die Aufgabe, wenn das Ziel CoreObfuscate läuft. Die meisten Eigenschaften heißen wie das Attribut der Aufgabe und akzeptieren dieselben Werte wie der entsprechende Schalter der Befehlszeile. Die abweichenden Eigenschaften, etwa BabelLicense, MergeInternalize oder BabelRules, sind in der Tabelle Eigenschaftszuordnung aufgeführt.

Einstellungen stehen in einer PropertyGroup, die meist an die Buildkonfiguration gebunden ist, damit Debug-Builds lesbar bleiben:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <StringEncryption>stream</StringEncryption>
  <ControlFlowObfuscation>if=on;switch=on;call=on</ControlFlowObfuscation>
  <ControlFlowIterations>3</ControlFlowIterations>
  <ValueEncryption>true</ValueEncryption>
  <ResourceEncryption>true</ResourceEncryption>
  <DebuggingProtection>true</DebuggingProtection>
  <VerboseLevel>2</VerboseLevel>
</PropertyGroup>

Dateilisten werden als Elemente in einer ItemGroup angegeben: BabelRules, MergeAssembly, EmbedAssembly, MapInFile und BabelPlugin.

Vom Paket angewendete Standardwerte

Ohne jede Einstellung wird ein Projekt, das das Paket referenziert, wie folgt verschleiert:

• Die Umbenennung von Symbolen ist eingeschaltet für Typen, Methoden, Eigenschaften, Felder, Ereignisse und Parameter, einschließlich virtueller Member, und die Namespaces werden abgeflacht. Die Eigenschaft SymbolsRenaming schaltet all das auf einmal um. Die einzelnen Eigenschaften ObfuscateTypes, ObfuscateMethods, ObfuscateProperties, ObfuscateFields, ObfuscateEvents, ObfuscateParameters, VirtualFunctions und FlattenNamespaces setzen sie jeweils für ihren Teil außer Kraft.
• Jede andere Funktion ist ausgeschaltet, bis Sie sie einschalten.
• Die Debugsymbole werden neu erzeugt, wenn der Compiler neben der Assembly eine PDB-Datei erzeugt hat (GenerateDebug wird automatisch gesetzt). So bleiben verschleierte Builds debugfähig, und Stacktraces lassen sich decodieren.
• Die Suchverzeichnisse für Assemblys werden aus den Projektreferenzen gebildet, sodass Babel jede Abhängigkeit auflöst, die der Compiler gesehen hat.
• Die Babel-Konfigurationsdatei wird ignoriert (NoConfiguration ist true), sodass der Build nur von dem abhängt, was das Projekt deklariert.
• Eine Datei babelRules.xml im Projektordner wird automatisch übernommen.
• Der Schlüssel für den starken Namen, den MSBuild für das Projekt auflöst (KeyOriginatorFile oder KeyContainerName), wird an Babel übergeben, sodass die verschleierte Assembly wie das Original signiert wird.

So schalten Sie die Umbenennung aus, für ein Testprojekt oder für einen Durchlauf, der nur Zeichenfolgen verschlüsselt:

<PropertyGroup>
  <SymbolsRenaming>false</SymbolsRenaming>
</PropertyGroup>

Verschleierungsregeln

Regeln schließen Symbole von einer Funktion aus oder wenden eine Funktion auf eine Menge von Symbolen an. Es gibt drei Möglichkeiten, sie anzugeben:

• Legen Sie eine Datei babelRules.xml im Projektordner ab: Sie wird automatisch verwendet.
• Referenzieren Sie beliebig viele Regeldateien mit Elementen BabelRules:

<ItemGroup>
  <BabelRules Include="rules\renaming.xml" />
  <BabelRules Include="rules\encryption.xml" />
</ItemGroup>

• Schreiben Sie die Regeln eingebettet in die Eigenschaft XmlRules. Das ist praktisch für eine kleine Gruppe von Regeln, die zum Projekt gehört:

<PropertyGroup>
  <XmlRules>
    <Rules>
      <Rule name="rename public types" feature="renaming" exclude="false">
        <Access>Public</Access>
        <Pattern>*</Pattern>
      </Rule>
    </Rules>
  </XmlRules>
</PropertyGroup>

Das Beispiel Android-Anwendung verwendet eine eingebettete Regel, um öffentliche Typen umzubenennen, und das Beispiel Blazor Web App verwendet eine Regeldatei, um die Klassen hinter Razor-Seiten zu verschleiern. Regeln lassen sich auch mit benutzerdefinierten Attributen an den Code anhängen.

Zeichenfolgenverschlüsselung

StringEncryption schaltet die Zeichenfolgenverschlüsselung ein und wählt den Algorithmus aus, genau wie der Schalter --stringencryption: true verwendet den Standardalgorithmus, während xor, hash, stream oder custom einen bestimmten auswählt. Einen Vergleich finden Sie unter Standardalgorithmen.

<PropertyGroup>
  <StringEncryption>stream</StringEncryption>
</PropertyGroup>

STREAM ★Ultimate ist der bevorzugte Algorithmus für moderne Ziele: Er ist vollständig verwaltet, funktioniert daher mit Trimming, mit NativeAOT und auf Hosts mit FIPS-Vorgaben, und er ist von .NET Framework bis .NET 10 geprüft, einschließlich Android, iOS und .NET MAUI. In Android-, iOS- und MAUI-Projekten führt das Paket Babel bereits nach der Kompilierung und vor dem Verpacken aus. Genau dort muss die Zeichenfolgenverschlüsselung stattfinden, damit die verpackte App die verschlüsselten Zeichenfolgen enthält. Als const deklarierte Zeichenfolgen lassen sich nicht verschlüsseln, siehe Verschlüsselung konstanter Zeichenfolgen.

Kontrollflussverschleierung

ControlFlowObfuscation nimmt dieselbe Schlüssel-Wert-Liste entgegen wie --controlflow, und ControlFlowIterations die Anzahl der Durchläufe (ILIterations wird als Alias akzeptiert):

<PropertyGroup>
  <ControlFlowObfuscation>goto=on;if=on;switch=on;case=on;call=on</ControlFlowObfuscation>
  <ControlFlowIterations>3</ControlFlowIterations>
</PropertyGroup>

Version 12 fügt den Algorithmus Chained State ★Ultimate hinzu, eine abflachende Transformation, die gegen automatische Deobfuskatoren gehärtet ist. Schalten Sie ihn mit chain=on ein, allein oder zusammen mit den anderen Algorithmen:

<PropertyGroup>
  <ControlFlowObfuscation>switch=on;case=on;chain=on</ControlFlowObfuscation>
</PropertyGroup>

Die Abflachung kostet Laufzeit. Halten Sie sie mit Regeln von häufig ausgeführten Methoden fern, wie unter Leistung und Tuning erläutert.

Codeverschlüsselung

MsilEncryption verschlüsselt Methodenrümpfe. true verschlüsselt jede geeignete Methode, während ein regulärer Ausdruck die Verschlüsselung auf die Methoden beschränkt, deren vollständiger Name ihm entspricht:

<PropertyGroup>
  <MsilEncryption>MyApp\.Licensing\..*</MsilEncryption>
</PropertyGroup>

Unter Codeverschlüsselung finden Sie das Laufzeitverhalten, passwortgeschützten Code und die Methoden, die sich nicht verschlüsseln lassen.

Schutz von Werten, Ressourcen und Aufrufen

<PropertyGroup>
  <ValueEncryption>array=true;true</ValueEncryption>
  <ResourceEncryption>true</ResourceEncryption>
  <DynamicProxy>all</DynamicProxy>
  <SuppressIldasm>true</SuppressIldasm>
  <SuppressReflection>true</SuppressReflection>
</PropertyGroup>

Jede Eigenschaft akzeptiert die Werte des entsprechenden Schalters: siehe Wert- und Arrayverschlüsselung, Ressourcenverschlüsselung und Dynamic Proxy.

Manipulationserkennung und Debugging-Schutz

<PropertyGroup>
  <TamperingDetection>true</TamperingDetection>
  <DebuggingProtection>true</DebuggingProtection>
</PropertyGroup>

Auf Desktop-Zielen bildet die Manipulationsprüfung einen Hash über das geladene Abbild im Speicher. In Anwendungen, die als Einzeldatei, getrimmt oder mit AOT veröffentlicht werden, ist sie daher wirkungslos. Das Paket reicht die Einstellung PublishSingleFile des Projekts an Babel weiter, und Babel warnt, wenn die Manipulationserkennung für eine solche Veröffentlichung angefordert wird. Siehe Manipulationserkennung und Debugging-Schutz.

Paketintegrität unter Android und iOS ★Ultimate

Ab Version 12 prüft die Manipulationserkennung auf Zielen mit .NET für Android und iOS (einschließlich .NET MAUI) die Integrität des Pakets statt des Abbilds: unter Android das APK-Signaturzertifikat, unter iOS die Bundle-ID und die Apple-Team-ID. Pinnen Sie die erwarteten Werte mit den Eigenschaften, die in dieser Version hinzugekommen sind:

<!-- Android: SHA-256 fingerprint of the release signing certificate -->
<PropertyGroup Condition="$(TargetFramework.Contains('-android'))">
  <TamperingDetection>true</TamperingDetection>
  <TrustedSigner>2924C53EE9C511E9F26E0720FD8151064F7621681667D7AB1899E551CDB25104</TrustedSigner>
</PropertyGroup>
 
<!-- iOS: bundle identifier and Apple Team ID -->
<PropertyGroup Condition="$(TargetFramework.Contains('-ios'))">
  <TamperingDetection>true</TamperingDetection>
  <TrustedBundle>com.mycompany.myapp</TrustedBundle>
  <TrustedTeam>ABCDE12345</TrustedTeam>
</PropertyGroup>

TrustedSigner akzeptiert mehrere durch Semikolons getrennte Fingerabdrücke, zum Beispiel einen Upload-Schlüssel und den App-Signaturschlüssel von Google Play. Wie Sie die einzelnen Werte ermitteln und was geschieht, wenn ein gepinnter Wert fehlt, ist unter Paketintegrität unter Android (MAUI) und Paketintegrität unter iOS (MAUI) erläutert. Das Beispiel Android-Anwendung zeigt eine vollständige Android-Projektdatei.

Verwaltetes AES für FIPS-Hosts

Die Entschlüsselungsroutinen, die für die Code-, Zeichenfolgen- (XOR und HASH), Wert- und Ressourcenverschlüsselung zur Laufzeit eingefügt werden, verwenden den Kryptografieanbieter der Plattform, und ein Host mit einer defekten FIPS-Konfiguration von OpenSSL kann eine solche Assembly nicht starten. Seit Version 11.8 wählt encryption=aesmanaged stattdessen eine eigenständige verwaltete Entschlüsselungsroutine aus:

<PropertyGroup>
  <MsilEncryption>true</MsilEncryption>
  <Use>encryption=aesmanaged</Use>
</PropertyGroup>

Use akzeptiert jedes Schlüssel-Wert-Paar, das der Schalter --use akzeptiert, durch Semikolons getrennt, zum Beispiel tagassembly=on. Die Vor- und Nachteile der verwalteten Entschlüsselungsroutine beschreibt die Seite FIPS-Konformität.

Assemblys zusammenführen und einbetten

Die Elemente MergeAssembly und EmbedAssembly führen die Assemblys auf, die mit der Ziel-Assembly zusammengeführt oder in sie eingebettet werden. MergeInternalize macht die zusammengeführten öffentlichen Typen intern, und MergeCopyAttributes steuert, ob ihre Attribute auf Assemblyebene kopiert werden:

<ItemGroup>
  <MergeAssembly Include="$(TargetDir)Acme.View.dll" />
  <MergeAssembly Include="$(TargetDir)Acme.ViewModel.dll" />
  <EmbedAssembly Include="$(TargetDir)Framework.Mvvm.dll" />
</ItemGroup>
<PropertyGroup>
  <MergeInternalize>true</MergeInternalize>
</PropertyGroup>

<Target Name="BeforeObfuscate">
  <ItemGroup>
    <MergeAssembly Include="@(ReferencePathWithRefAssemblies)"
                   Condition="'%(Filename)' == 'Acme.View' Or '%(Filename)' == 'Acme.ViewModel'" />
  </ItemGroup>
</Target>

Das Paket entfernt außerdem zusammengeführte und eingebettete Assemblys aus der Datei .deps.json und aus den zu veröffentlichenden Dateien, damit dotnet publish sie nicht doppelt ausliefert. Die Funktion beschreibt die Seite Zusammenführen und Einbetten, die Einzelheiten auf der Buildseite der Abschnitt Veröffentlichen.

Map-Dateien und assemblyübergreifende Umbenennung

GenerateMapOutFile schreibt die XML-Map-Datei der verschleierten Assembly. Sie dient dazu, Stacktraces zu decodieren und die öffentliche Schnittstelle einer Bibliothek über mehrere Assemblys hinweg einheitlich umzubenennen. Elemente MapInFile geben die Map-Dateien bereits verschleierter Assemblys an Babel zurück:

<PropertyGroup>
  <GenerateMapOutFile>true</GenerateMapOutFile>
  <BabelMapOutFile>$(SolutionDir)MapOut\$(TargetFileName).map.xml</BabelMapOutFile>
</PropertyGroup>
<ItemGroup>
  <MapInFile Include="$(SolutionDir)MapOut\Acme.Core.dll.map.xml" />
</ItemGroup>

Siehe XML-Map-Dateien und Assemblyübergreifende Umbenennung. Das Beispiel Unit-Tests verwendet eine Map-Datei, um Tests gegen eine verschleierte Bibliothek auszuführen, und das Beispiel .NET-App veröffentlichen verschleiert die öffentliche Schnittstelle einer NuGet-Abhängigkeit und übergibt deren Map-Datei an die Anwendung.

Optimierungen

<PropertyGroup>
  <DeadCodeElimination>true</DeadCodeElimination>
  <SealClasses>true</SealClasses>
  <EnumRemoval>true</EnumRemoval>
  <ConstRemoval>true</ConstRemoval>
  <DisgregateRemoval>true</DisgregateRemoval>
  <InlineExpansion>true</InlineExpansion>
  <CleanAttributes>true</CleanAttributes>
</PropertyGroup>

Jede Optimierung ist unter Optimierungen beschrieben.

Plugins

Elemente BabelPlugin referenzieren die Plugin-Assemblys, die geladen werden, und PluginsArguments übergibt ihnen Argumente als Schlüssel-Wert-Paare. Das Plugin BabelEncrypt wird im Paket mitgeliefert, im selben Ordner wie die Buildtools:

<ItemGroup>
  <BabelPlugin Include="$(BabelTaskDir)BabelEncrypt.dll" />
</ItemGroup>
<PropertyGroup>
  <PluginsArguments>dictionary=exclusionlist.txt</PluginsArguments>
</PropertyGroup>

Siehe Plugins für Babel Obfuscator und das Encrypt Plugin.

Protokollierung und Diagnose

<PropertyGroup>
  <VerboseLevel>3</VerboseLevel>
  <GenerateLogFile>true</GenerateLogFile>
  <BabelLogFile>$(IntermediateOutputPath)babel.log</BabelLogFile>
  <BabelProvideCommandLineArgs>true</BabelProvideCommandLineArgs>
  <ShowStatistics>true</ShowStatistics>
  <Trace>MyApp\.Services\..*</Trace>
  <BabelWarningsToIgnore>W00008</BabelWarningsToIgnore>
  <BabelWarningsAsErrors>W00000</BabelWarningsAsErrors>
</PropertyGroup>

• VerboseLevel steuert, wie viel vom Babel-Protokoll in die Buildausgabe gelangt. GenerateLogFile und BabelLogFile speichern das vollständige Protokoll in einer Datei.
• BabelProvideCommandLineArgs gibt die Befehlszeile aus, die das Paket an Babel übergibt, und speichert sie im Element @(BabelCommandLineArgs).
• Trace nimmt einen regulären Ausdruck entgegen und erklärt Symbol für Symbol, warum ein Treffer verschleiert wurde oder nicht: der schnellste Weg, Regeln zu debuggen.
• BabelWarningsToIgnore, BabelWarningsAsErrors und BabelWarningsAsInfos nehmen Listen von Warncodes entgegen und ändern, wie diese gemeldet werden.
• MakeBabelProjectFile schreibt ein MSBuild-Projekt, das der aktuellen Konfiguration entspricht. Das ist nützlich, um einen Build mit der Babel-Aufgabe oder dem Befehlszeilentool nachzustellen.

Alle Eigenschaften, die das Paket akzeptiert, sind in der Referenz des Pakets aufgeführt.