Règles XML

Fichiers de règles

Les fichiers de règles de Babel sont des documents XML qui contiennent les informations de configuration servant à personnaliser et à contrôler l’obfuscation. Ils vous permettent de définir précisément quelles fonctionnalités d’obfuscation s’appliquent à quelles parties de votre code, et donc de contrôler finement la protection de vos assemblies.

<Rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Rule name="rule 1" feature="default" exclude="false">
  </Rule>
  <Rule name="rule 2" feature="control flow" exclude="true">
  </Rule>
</Rules>

L’élément Rules peut définir un attribut targetAssembly qui limite à un assembly donné la portée des règles qu’il contient. Si l’attribut targetAssembly n’est pas indiqué, les règles s’appliquent à tous les assemblies traités. Exemple :

<Rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       targetAssembly="ACME.Data">

Élément Rules

L’élément Rules est le conteneur racine qui définit un ensemble de règles à appliquer à l’assembly cible. Il peut contenir plusieurs éléments enfants Rule, chacun décrivant un comportement d’obfuscation différent.

Élément Rule

L’élément Rule définit une règle d’obfuscation Babel qui peut viser une ou plusieurs fonctionnalités de Babel Obfuscator. Chaque règle indique quels éléments de code sont concernés et comment les fonctionnalités d’obfuscation leur sont appliquées.

L’attribut feature définit la fonctionnalité de l’obfuscateur sur laquelle la règle agit. Les attributs name et exclude sont obligatoires, tandis que l’attribut feature est facultatif. S’il n’est pas indiqué, la fonctionnalité prend la valeur « default », qui désigne la fonctionnalité de renommage.

Les fonctionnalités de l’obfuscateur sont des chaînes prédéfinies qui correspondent chacune à une capacité d’obfuscation. Tous les noms de fonctionnalités pris en charge figurent dans les tableaux ci-dessous.

Tableau des fonctionnalités

Les fonctionnalités suivantes peuvent viser tous les types de symboles définis dans un assembly, notamment les types, les méthodes, les propriétés, les champs et les événements :

Les fonctionnalités d’obfuscation suivantes sont propres aux méthodes et ne peuvent s’appliquer qu’à des symboles de méthode :

Tout élément Rule peut contenir des éléments enfants tels que Access, Target, Pattern, HasAttribute, Properties et Description. L’élément Pattern est obligatoire, tous les autres sont facultatifs. Ces éléments enfants ajoutent à la règle des possibilités de filtrage et de configuration. Exemple :

<Rule name="DataWriter" feature="msil encryption" exclude="false">
  <Target>Methods</Target>
  <Pattern>SQLUtils.DataWriter::*</Pattern>
  <Properties>
    <Cache>true</Cache>
    <MinInstructionCount>6</MinInstructionCount>
  </Properties>
  <Description>Encrypt all methods of the DataWriter class.</Description>
</Rule>

Voici la liste complète des éléments enfants possibles de Rule :

Élément Access

Limite la portée de la règle aux symboles dotés des modificateurs de visibilité indiqués. Les valeurs possibles sont All ou toute combinaison de Public, Protected, Internal, Private, FamilyAndAssembly et FamilyOrAssembly. Si cet élément est absent, la valeur par défaut All est utilisée : la règle s’applique alors aux symboles de toute visibilité.

Élément Targets

Limite la portée de la règle à certains types de symboles de code. Les valeurs acceptées sont All ou toute combinaison de Classes, Delegates, Structures, Interfaces, Enums, Events, Methods, Properties, Fields, StaticFields et Resources. Si cet élément est absent, la valeur par défaut All est retenue et la règle s’applique à tous les types de symboles.

Élément Pattern

Dans la définition d’une règle XML de Babel Obfuscator, l’élément Pattern sert à identifier les symboles de l’assembly soumis à l’obfuscation. Il accepte un nom complet de symbole, une expression avec caractères génériques ou une expression régulière, ce qui en fait un mécanisme de filtrage souple pour viser des éléments de code précis.

Expressions avec caractères génériques : pour des critères de sélection plus simples, l’élément Pattern peut contenir des caractères génériques. Le caractère « ? » représente un caractère quelconque, tandis que « * » représente zéro, un ou plusieurs caractères. Vous obtenez ainsi des critères de sélection larges mais maîtrisés, qui permettent de viser facilement des groupes de symboles apparentés sans écrire de motifs complexes.

Expressions régulières : pour un filtrage plus complexe et plus précis, l’élément Pattern accepte les expressions régulières. Dans ce cas, l’attribut isRegEx doit être défini sur « true » pour indiquer que le motif doit être interprété comme une expression régulière et non comme une chaîne littérale ou un motif avec caractères génériques. Il est conseillé de placer l’expression régulière dans une section CDATA pour que le XML soit analysé correctement et que les caractères spéciaux soient bien interprétés. Par exemple :

<Pattern isRegEx="true"><![CDATA[^Properties.*]]></Pattern> 

Format du nom complet

Dans le motif d’une règle XML de Babel Obfuscator, le format du nom complet d’un symbole dépend du type de symbole visé. Cette distinction garantit une obfuscation précise et efficace pour les différents types de symboles, tout en restant claire et cohérente.

Types (classes, structures, énumérations, interfaces) : le format habituel est NamespaceName.TypeName, une notation directe pour les déclarations de type simples.

Types imbriqués : pour les types imbriqués (types définis à l’intérieur d’autres types), le format utilise une barre oblique comme séparateur : NamespaceName.TypeName/NestedTypeName. Cette notation distingue clairement les types imbriqués de leurs types parents et conserve la relation hiérarchique.

Types génériques : la notation des types génériques commence par NamespaceName.TypeName, suivi des arguments de type générique entre chevrons :

NamespaceName.TypeName<GenericArgumentList>

GenericArgumentList : cet élément n’est pas un motif indépendant, il fait partie intégrante du motif des types génériques. Il définit la liste des arguments de type générique, séparés par des virgules, chacun étant indiqué avec son espace de noms complet et son nom de type :

NamespaceName.TypeName1,NamespaceName.TypeName2,...,NamespaceName.TypeNameN

Méthodes : le format habituel des méthodes comprend l’espace de noms, le nom du type, le nom de la méthode, la liste des paramètres et, éventuellement, le type de retour :

NamespaceName.TypeName::MethodName(ParameterList):ReturnType

La présence de ReturnType dans le motif est facultative, et il peut être omis dans la plupart des cas.

Propriétés : le format des propriétés suit cette structure :

NamespaceName.TypeName::PropertyName:PropertyType

En général, le type de la propriété n’a pas besoin de figurer dans le motif et peut être omis.

Événements : le format des événements s’écrit ainsi :

NamespaceName.TypeName::EventName:EventHandlerType

Ce format comprend à la fois le nom de l’événement et le type de gestionnaire qui lui est associé.

Champs : les champs suivent le format :

NamespaceName.TypeName::FieldName:FieldType

Comme pour les propriétés, le type du champ est en général facultatif et n’est pas nécessaire dans la plupart des motifs.

ParameterList : cet élément ne concerne que le motif des méthodes. Il donne les noms de type complets des paramètres, séparés par des virgules :

NamespaceName.TypeName1,NamespaceName.TypeName2,...,NamespaceName.TypeNameN

Ces motifs servent à indiquer précisément quelles parties du code Babel Obfuscator doit viser. La syntaxe exacte peut varier légèrement selon le contexte et les besoins de votre stratégie d’obfuscation. Des motifs exacts garantissent que les règles d’obfuscation ne touchent que les symboles voulus.

Élément HasAttribute

Indique une liste de noms complets de types d’attributs personnalisés, séparés par des virgules. Si le symbole cible porte au moins l’un de ces attributs, la règle lui est appliquée. Cet élément permet de filtrer selon les attributs pour cibler précisément la règle.

Cet élément accepte l’attribut facultatif onEnclosingType. Défini sur « true », il indique que l’attribut personnalisé doit être recherché sur le type englobant du symbole cible et non sur le symbole lui-même :

<HasAttribute onEnclosingType="true">System.SerializableAttribute</HasAttribute>

Cette configuration correspond aux symboles, tels que les méthodes, les propriétés, les champs et les événements, qui appartiennent à un type portant l’attribut SerializableAttribute.

Élément HasBase

Indique une liste de noms complets de types de base, séparés par des virgules. La règle correspond à un symbole de type si le type cible dérive de l’un de ces types de base. Cet élément permet de filtrer selon l’héritage pour appliquer la règle.

Cet élément accepte l’attribut facultatif onEnclosingType. Défini sur « true », il indique que Babel doit effectuer la recherche dans la hiérarchie du type englobant des symboles cibles, ce qui vous permet d’appliquer des règles selon la structure d’héritage des types conteneurs.

Élément Namespace

Limite la règle aux symboles d’un espace de noms donné. La règle est ainsi filtrée au niveau de l’espace de noms.

<Namespace>ACME.Data</Namespace>

La règle s’applique à tous les symboles définis dans l’espace de noms ACME.Data et dans ses sous-espaces de noms.

Élément Properties

L’élément Properties définit une collection d’éléments XML enfants qui personnalisent le comportement de la fonctionnalité visée par la règle. Chaque fonctionnalité d’obfuscation prend en charge des propriétés propres, qui en contrôlent le fonctionnement et ajustent la manière dont elle traite les symboles correspondants.

<Rule name="DataWriter" feature="msil encryption" exclude="false">
  <Target>Methods</Target>
  <Pattern>ACME.Data.DataWriter::*</Pattern>
  <Properties>
    <Cache>true</Cache>
    <MinInstructionCount>6</MinInstructionCount>
  </Properties>
  <Description>Encrypts code in the DataWriter class.</Description>
</Rule>

Cette règle configure la fonctionnalité msil encryption en définissant les propriétés Cache et MinInstructionCount pour toutes les méthodes de la classe DataWriter.

Voici la liste complète des éléments de propriété pris en charge par chaque fonctionnalité d’obfuscation :

agent

cleanup attributes

control flow

(*) Ces options génèrent de l’IL non vérifiable. Si votre assembly doit s’exécuter dans un environnement de confiance partielle ou passer la validation PEVerify, ne les activez pas.

renaming

string encryption

merge

msil encryption

optimizations

Élément Description

Fournit un texte qui décrit le rôle et le comportement de la règle. Cette description apparaît dans le journal d’obfuscation, ce qui aide à comprendre l’effet de chaque règle lorsque vous examinez le déroulement de l’obfuscation.

Configurer les règles

Vous pouvez transmettre des fichiers de règles à Babel Obfuscator depuis la ligne de commande, la tâche MSBuild Babel ou Babel Desktop. Choisissez la méthode adaptée à votre build.

Ligne de commande

babel myapp.exe --rules babelRules.xml

L’option --rules peut être indiquée plusieurs fois sur la ligne de commande pour ajouter d’autres fichiers de règles XML. Vous pouvez ainsi répartir les règles dans des fichiers distincts et les combiner selon vos besoins.

Tâche MSBuild Babel

<ItemGroup>
  <RuleFile Include="babelRules.xml" />
</ItemGroup>
 
<Babel RulesFiles="@(RuleFile)" />

L’option RulesFiles de Babel Obfuscator accepte une liste de fichiers de règles XML, que vous pouvez définir avec l’élément ItemGroup dans votre fichier de projet MSBuild. Vous pouvez ainsi indiquer plusieurs fichiers de règles et les gérer facilement dans la structure du projet. Chaque fichier de règles du groupe d’éléments est traité comme une entrée distincte de Babel Obfuscator et peut définir des règles et des paramètres d’obfuscation différents pour différentes parties de votre base de code.

Outre les fichiers de règles XML externes, vous pouvez placer la définition des règles XML directement dans le fichier de projet à l’aide de l’attribut XmlRules de la tâche Babel, comme ci-dessous :

<PropertyGroup>
  <XmlRules>
    <Rules targetAssembly="Acme, Version=1.0.0.0, Culture=neutral, PublicKeyToken=f66185f16ea61c16">
      <Rule name="rule1" feature="msil encryption" exclude="false">
        <Target>Methods</Target>
        <Pattern>Acme.Engine*</Pattern>
        <Description>Enable MSIL Code Encryption in Acme Engine</Description>
      </Rule>
    </Rules>
    <Rules targetAssembly="Acme.Entities, Version=1.0.0.0, Culture=neutral, PublicKeyToken=f66185f16ea61c16">
      <Rule name="rule2" feature="control flow" exclude="true">
        <Target>Methods</Target>
        <Pattern>Acme.Entities.*</Pattern>
        <Description>Disable Control Flow Obfuscation for EF classes</Description>
      </Rule>
    </Rules>
  </XmlRules>
</PropertyGroup>
 
<Babel XmlRules="$(XmlRules)" />

Lorsque Babel Obfuscator traite plusieurs assemblies cibles dans un projet, l’attribut targetAssembly des règles XML vous permet d’indiquer à quel assembly cible un ensemble de règles s’applique. Cet attribut désigne un assembly par son nom complet, avec la version, la culture et le jeton de clé publique. Si l’attribut targetAssembly est omis, les règles s’appliquent à tous les assemblies cibles définis dans le projet.

Babel Desktop

Pour utiliser des fichiers de règles XML externes, sélectionnez l’assembly cible sur le canevas du projet et ajoutez les fichiers à RulesFiles, dans le groupe Fichiers et dépendances du panneau des propriétés.

Pour écrire des règles XML intégrées, ouvrez la vue Règles XML de l’assembly sélectionné (l’onglet Règles XML du panneau des propriétés, ou Paramètres > Assembly sélectionné > Règles XML). L’éditeur valide les règles par rapport au schéma XML de Babel et signale les erreurs avec leur ligne et leur colonne ; il peut aussi ouvrir et enregistrer des documents de règles sous forme de fichiers XML.

Les règles intégrées sont stockées dans le fichier de projet, dans la propriété XmlRules de la tâche Babel, comme dans l’exemple MSBuild ci-dessus. Elles sont donc enregistrées et versionnées avec la configuration du projet. Voir Projets d’obfuscation pour savoir comment utiliser les projets dans Babel Desktop.