Documentation du fichier exécutable .jar AdeptActivateCli.jar

src/AdeptActivate-fr.md

@@ -0,0 +1,215 @@
+### **Aperçu**
+
+Pour pouvoir télécharger des fichiers depuis le Serveur de Contenu Adobe (ACS), 
+l'appareil qui tente le téléchargement doit être enregistré auprès d'Adobe et
+activé. Le programme **AdeptActivateCli.jar** crée les fichiers d'activation
+nécessaires et effectue l'activation Adobe requise. Les fichiers générés sont 
+identiques en format à ceux utilisés par le programme Linux **"libgourou"**.
+
+Un appareil peut être activé de deux manières : il peut être associé à un compte
+Adobe existant, ou il peut être activé de manière anonyme. S'il est associé à un
+compte existant, lié à un identifiant Adobe (Adobe ID) et à un mot de passe,
+il devient possible d'utiliser l'appareil pour accéder au contenu disponible 
+pour d'autres appareils utilisant le même compte, tandis que 
+l'activation anonyme est restreinte aux appareils disposant des fichiers 
+d'activation identiques. Notez que l'inscription à un compte Adobe peut entraîner
+l'envoi d'e-mails marketing de la part d'Adobe.
+
+Pour effectuer une activation anonyme, utilisez l'option de ligne de commande 
+**"-A"**, sinon utilisez les options de ligne de commande **"-u"** (nom 
+d'utilisateur) et **"-p"** (mot de passe) avec un identifiant et un mot de passe
+Adobe existants. Si l'option **"-p"** n'est pas fournie, le programme demandera
+interactivement le mot de passe avant de continuer. L'utilisation soit de l'option
+**"-A"** soit de l'option **"-u"** est obligatoire pour initier le processus.
+
+L'option de ligne de commande **"-D"** est utilisée pour indiquer le répertoire
+(dossier) où les fichiers d'activation seront stockés ; par défaut, ils sont
+stockés dans le répertoire **".config/jadept"** situé dans le répertoire 
+personnel de l'utilisateur. L'option de ligne de commande **"-a"** permet à 
+l'utilisateur de choisir un nom de fichier d'activation différent de celui
+par défaut (**"activation.xml"**).
+
+Si le fichier d'activation existe déjà dans le répertoire de sortie, le 
+programme fera une pause et demandera confirmation explicite avant de
+recréer le fichier d'activation. Les fichiers **"devicesalt"** et **"device.xml"** ne seront pas
+recréés. L'option de ligne de commande **"-f"** entraînera l'écrasement de tout
+fichier d'activation existant sans avertissement.
+
+Pour une explication des autres paramètres de ligne de commande facultatifs,
+voir **"[Options de ligne de commande](#options-de-ligne-de-commande)"** 
+ci-dessous.
+
+### **Utilisation**
+
+> java -jar AdeptActivateCli.jar [-AdefhrvV] [-a <activationFileName>]
+> [--acs <ACSServer>] [-D <outputDir>] [-H <hobbesVersion>]
+> [-p <password>] [-u <username>] [--mac] [--win]
+
+#### **Options de ligne de commande**:
+
+>##### **'-h' ou "--help"**
+>
+> Affiche l'aide du programme (instructions d'utilisation) puis se termine.
+>
+>##### **'-V' ou "--version"**
+>
+> Affiche les informations de version puis se termine.
+> 
+>#### **'-A' ou "--anonymous"**
+>
+> Active l'appareil de manière anonyme. Aucun nom d'utilisateur/mot de passe
+> n'est nécessaire. S'ils sont présents, les paramètres de nom d'utilisateur
+> et de mot de passe seront ignorés.
+>
+>#### **'d' ou "debug"**
+>
+> Entre en mode débogage. Cette option fournit des informations 
+> supplémentaires sur les étapes du processus, y compris les 
+> requêtes HTTP envoyées et les réponses reçues.
+>
+>#### **'-e' ou "--export-private-key"**
+>
+> Exporte la clé privée de l'utilisateur sous forme de fichier **.der**
+> et **.pem**. Les noms de fichiers sont construits en combinant le nom
+> d'utilisateur, un trait d'union et les 12 derniers caractères de l'UUID
+> de l'utilisateur, créé lors des processus de connexion et d'activation
+> (par exemple, "anonymous-4bcd9e763497.pem"). Le fichier .pem contient
+> la clé privée sous forme encodée en Base64, tandis que le fichier .der
+> est une donnée binaire.
+>
+>#### **'-f' ou "--force**
+>
+> Écrase le fichier d'activation existant sans avertissement. Les fichiers
+> de l'appareil (devicesalt, device.xml) ne seront pas écrasés).
+>
+>#### **'-r' ou "--random-serial"**
+>
+> Génère un numéro de série d'appareil aléatoire si le fichier "device.xml"
+> est en cours de création. S'il n'est pas spécifié, le numéro de série de
+> l'appareil est calculé en combinant le nom d'utilisateur du système
+> d'exploitation avec le faux UID de "1000" plus l'adresse MAC de l'appareil
+> cible, en hachant la chaîne résultante, puis en prenant les 10 premiers
+> octets du hachage.
+>
+>#### **'-v' ou "--verbose" (facultatif)**
+>
+>Augmente la verbosité de la journalisation.
+>
+>#### **'-a' ou "--activation-file" <nomFichierActivation> (facultatif)**
+>
+>Le nom de fichier d'activation. S'il n'est pas fourni, le nom 
+> **"activation.xml"** sera utilisé.
+>
+>#### **"--acs" <ServeurACS> (facultatif)**
+>
+> URL du service d'activation du Serveur de Contenu. S'il n'est pas 
+> fourni, **https://adeactivate.adobe.com/adept** sera utilisé.
+>
+>#### **'-D' ou "--adept-directory" <RépertoireSortie>** (facultatif)
+>
+> Le répertoire (dossier) qui contiendra les fichiers devicesalt, 
+> device.xml et le fichier d'activation (typiquement "activation.xml").
+> S'il n'est pas fourni, le chemin **{user.home}/.config/jadept** sera utilisé.
+>
+>#### **'-H' ou "--hobbes-version" &ltversionHobbes>** (facultatif)
+>
+>Définit la version du RMSDK ("hobbes"). S'il n'est pas fourni, 
+> "10.0.4" sera utilisé.
+>
+>#### **'-p' ou "--password" <motDePasse d'Adobe>**
+>
+> Mot de passe de l'AdobeID. S'il n'est par fourni, le programme fera une
+> pause et le demandera. Cette option est ignorée si l'option **'-A'
+> (anonyme)** est spécifié.
+>
+>#### **'-u' ou "--username" <AdobeID>**
+>
+> Un identifiant Adobe (généralement l'adresse e-mail du compte Adobe). 
+> Ignoré si l'option **'-A' (anonyme)** est spécifié, et est *obligatoire*
+> dans le cas contraire.
+>
+>#### **"--mac"**
+>
+> Utilise les emplacements de fichiers par défaut de Macintosh. Cette
+> option est réservée pour une extension future et ne doit pas être utilisée.
+>
+>#### **"--win"**
+>
+> Tente de lire les paramètres Adept à partir du Registre Windows et de 
+> créer les fichiers d'activation correspondants. Ignoré si le programme 
+> ne détecte pas un système d'exploitation Windows. Voir [**Option Win
+**](#option-win).
+
+### **Détails d'Implémentation**
+
+**"AdeptActivate.java"** contient la logique métier principale pour créer les
+fichiers d'activation et pour activer un appareil auprès d'un serveur de contenu.
+
+**"common/Device.java"** gère les informations de l'appareil, y compris la clé
+de chiffrement symétrique privée (AES) de l'appareil (**"devicesalt"**), le 
+numéro de série de l'appareil, l'empreinte numérique de l'appareil et d'autres
+informations d'identification de l'appareil (**"device.xml"**). Une fois créés,
+ces fichiers n'auront probablement jamais besoin d'être recréés. Lors de la
+construction, l'objet Device analyse ses fichiers nécessaires pour peupler ses
+données, ou crée de nouvelles données si les fichiers sont introuvables
+ou corrompus.
+
+**"common/Activation.java"** gère les informations d'activation, y compris
+l'analyse des données d'activation à partir d'un fichier XML existant, 
+l'émission de requêtes HTTP au serveur de contenu pour obtenir des 
+informations d'autorisation de base et le stockage des informations 
+d'activation dans le système de fichiers sous forme de fichier XML.
+
+Les informations récupérées auprès du serveur de contenu comprennent les
+URL pour le serveur d'authentification, le serveur d'activation et le serveur
+d'informations utilisateur, ainsi que les Certificats X509 pour les services
+d'Authentification et d'Activation. Aucune information n'est partagée avec
+le serveur de contenu lors de ces appels réseau initiaux, et les données
+retournées sont actuellement constantes. Cela suggère qu'il serait possible
+d'utiliser des données mises en cache si le réseau n'est pas disponible.
+
+Il existe un certain nombre de classes utilitaires, contenant généralement
+exclusivement des méthodes "static", fournissant des fonctionnalités de support.
+Ces classes comprennent **"CryptoUtils.java"**, qui fournit des
+fonctionnalités cryptographiques pour le chiffrement et le déchiffrement
+symétriques (AES) et asymétriques (RSA), **"XMLUtils.java"**, qui fournit des
+méthodes pour extraire des données à partir d'objets XML Document et créer des
+représentations textuelles de ces objets, et **"HttpUtils.java"**, qui fournit
+des méthodes pour envoyer et recevoir des messages depuis des serveurs 
+distants en utilisant le protocole HTTP. Cette dernière classe diffère des 
+autres en ce que ses méthodes ne sont pas statiques, et la classe doit être
+instanciée avant utilisation. Cette différence permet de créer une classe 
+simulée (mock), étendant **"HttpUtils"**, spécifiquement pour des besoins de
+tests unitaires et d'intégration sans dépendance sur une réseau réelle.
+
+**AdeptActivateCli.java** implémente l'interface Runnable et utilise la
+bibliothèque **picocli** pour fournir une interface de ligne de commande 
+pour AdeptActivate.java. AdeptActivateCli analyse valide et applique les
+options de ligne de commande, y compris la définition des valeurs par défaut.
+Il appelle ensuite les méthodes de AdeptActivate.java pour effectuer
+l'activation réelle ; ainsi, AdeptActivate.java pourrait
+être utilisé sans AdeptActivateCli pour créer une application non
+pilotée par la ligne de commande.
+
+Après avoir validé les paramètres de la ligne de commande, l'objet 
+**"AdeptActivateCli"** instancie un objet Device et un objet Activation, 
+puis appelle les méthodes AdeptActivate.signIn() et 
+AdeptActivate.activateDevice() pour compléter le processus d'activation 
+et stocker les informations d'identification de l'utilisateur et le jeton
+d'activation du serveur de contenu.
+
+#### **Option Win**
+
+Le paramètre de ligne de commande **"--win"** mérite une attention particulière.
+Ce paramètre est pertinent **uniquement** lors de l'exécution sur des appareils 
+Windows qui ont déjà été enregistrés et activés par des applications officielles
+d'Adobe, telles qu'Adobe Digital Editions (ADE) ou l'application Libby. 
+Lorsque ces exigences sont remplies, AdeptActivateCli remplace les objets
+génériques **Activation** et **Device** par des objets spécialisés : un 
+objet **ADEActivation** et un objet **ADEDevice**. Ces classes étendent
+leurs classes respectives, mais chargent leurs données à partir des 
+informations stockées par ADE dans le Registre Windows. Elles n'effectuent
+aucun appel réseau si les entrées de registre requises ne peuvent pas être 
+trouvées. Lors de l'enregistrement des données (sauvegarde), les méthodes
+non surchargées sont utilisées, ce qui génère des fichiers compatibles avec 
+"**libgourou**" dans le répertoire de sortie.