La journalisation dans le monde Microsoft, découvrez l'API EventLog

La journalisation est l'action d'enregistrer dans un journal tout ou partie des évènements qui se produisent dans un système informatique pendant son fonctionnement.

Il est possible de définir deux types de journalisation :

• la journalisation système : ce type de journalisation désigne l'enregistrement chronologique des évènements survenant au niveau des composants du système. Le niveau de cette journalisation peut être paramétré, afin de filtrer les différents évènements selon leur catégorie de gravité ;
• la journalisation applicative : ce type de journalisation désigne l'enregistrement chronologique des opérations de la logique métier pendant le fonctionnement de l'application. Un journal applicatif est lui-même une exigence du métier. Il est donc défini comme une fonctionnalité faisant partie de la logique applicative. Par conséquent, il ne devrait pas être arrêté pendant le fonctionnement de l'application.

Le rôle et les buts de la journalisation sont multiples et souvent liés ou imposés par des contraintes de sécurité.

• Légal : Dans ce cadre, le but de la journalisation est de fournir un élément de preuve juridique. Par exemple, les fournisseurs d'accès à Internet doivent conserver et archiver les journaux concernant les connexions de leurs utilisateurs afin de pouvoir répondre à une requête judiciaire.
• Statistique : La journalisation permet aussi de fournir des informations statistiques concernant l'usage. Un administrateur de serveur WWW par exemple peut légitimement se demander « Quelle est la page WWW de mon site qui est la plus visitée ? », ou encore, « D'où proviennent majoritairement les requêtes ? »
• Analyse : Enfin, la journalisation permet d'analyser un problème et de trouver les enchaînements qui ont provoqué le problème. « Que s'est-il passé sur le réseau à 11H27 juste avant que le serveur DNS ne s'arrête ? », ou encore, « Quelle requête HTTP a bien pu générer un plantage de mon serveur WWW ? »

Comme on peut le voir, les buts de la journalisation sont multiples. Suivant les buts recherchés, le profil des personnes qui liront les journaux sera différent.

Certaines contraintes doivent (ou devraient) s'appliquer à la journalisation.

• Intégrité : L'intégrité de la journalisation ne doit pas pouvoir être remise en cause. Ce qui est archivé dans les journaux doit être ce que l'application ou le système a journalisé. Il ne devrait pas être possible de modifier un élément de la journalisation a posteriori.
• Complétude : L'archivage de la journalisation doit impérativement comporter tous les évènements reçus. Si pour une raison quelconque (surcharge de la machine par exemple), un évènement venait à être perdu, il y aurait incomplétude de la journalisation. Un évènement perdu ou absent peut entrainer une mauvaise analyse d'un problème ou encore la non-prise en compte de la journalisation en tant que preuve juridique valide. Comme il n'est pas toujours possible d'avoir une complétude forte, il faut au moins que le système mis en place puisse détecter la perte ou l'altération d'un ou plusieurs évènements, on parlera dans ce cas-là de complétude faible.
• Cohérence : Afin de faciliter une éventuelle analyse, il est important que les évènements journalisés soient cohérents. Cela veut dire par exemple que la date système de la machine doit être synchronisée afin que la séquence des différents évènements conduisant au problème puisse être ordonnée.
• Utilité : Un évènement de journalisation doit contenir de l'information utile et riche. En effet, Erreur mémoire lors de l'allocation d'un buffer de 112 octets n'est pas très utile pour comprendre un éventuel problème s'il n'est pas couplé avec un message de plus haut niveau du genre : Erreur système lors du traitement de la connexion de l'utilisateur 'Administrateur'.
• Confidentialité : Les informations contenues dans les évènements présentent un certain caractère de confidentialité. Il importe donc que les moyens utilisés pour transporter et archiver ces évènements garantissent cette confidentialité.

Il existe plusieurs méthodes permettant de transporter et d'archiver les différents évènements de journalisation. Le choix et l'usage de ces méthodes sont fonction de l'environnement et de l'application.

• Fichier plat : C'est probablement la plus simple des méthodes. Les évènements sont stockés dans un fichier en général au format texte. La gestion de ce fichier (droits du fichier, format d'écriture, durée de rétention …) est entièrement laissée à l'application ou même au système d'exploitation.
• Syslog : C'est la méthode de journalisation historique utilisée dans le monde Unix. Cette méthode comprend un logiciel de collecte et d'archivage (c'est le démon syslogd par exemple), un protocole réseau (défini par le RFC 3164) et une API de programmation permettant de s'interfacer avec le protocole Syslog (voir openlog(), syslog() et closelog()). Plus d'informations sur le protocole Syslog ici.
• Base de données : Les évènements de journalisation sont stockés dans une base de données.
• Le sous-système EventLog : Ce système de journalisation est utilisé dans le monde Microsoft.

Ce document a pour but de présenter la journalisation dans le monde Microsoft et le sous-système EventLog.

Le schéma suivant montre l'architecture simplifiée du système :

Les différentes sources ou applications envoient leurs messages de journalisation EventLog au sous-système. Le sous-système EventLog regarde dans la base de registre le journal associé à la source et enregistre l'évènement dans ce journal.

Par défaut, il existe trois journaux dans lesquels les messages EventLog sont enregistrés. Ces journaux sont :

• Application : il contient les messages EventLog générés par les applications et les services. Par exemple, un journal pourrait enregistrer un message d'erreur. C'est au développeur de l'application de décider les évènements à journaliser. L'emplacement par défaut du fichier d'archivage est %SystemRoot%\System32\Config\AppEvent.evt ;
• Sécurité : il contient les messages EventLog tels que les échecs et les réussites des connexions aussi bien que les évènements relatifs à l'usage des ressources comme l'ouverture, la création ou la destruction de fichiers ou autres objets. Un administrateur peut activer l'audit pour enregistrer ces évènements. L'emplacement par défaut du fichier d'archivage est %SystemRoot%\System32\Config\SecEvent.evt ;
• Système : il contient les messages EventLog générés par les composants du système, comme un problème lors du chargement d'un driver au démarrage. Les évènements journalisés par les composants du système sont prédéterminés. L'emplacement par défaut du fichier d'archivage %SystemRoot%\System32\Config\SysEvent.evt.

D'autres journaux peuvent être créés et utilisés si nécessaire (depuis Windows 2000). Par exemple, depuis Internet Explorer version 7, il existe le journal « Internet Explorer ». Un autre exemple : Windows 2003 Server définit les journaux nommés « Directory Service », « DNS Server » et « File Replication Service ».

Le programme utilisé pour visualiser les messages EventLog est le programme « Event Viewer ». Ce programme est lancé par la commande eventvwr.exe et se trouve normalement dans le répertoire C:\Windows\system32.

Le programme « Event Viewer » permet de visualiser les différents journaux ainsi que les différents messages archivés dans ces journaux :

Ce programme est aussi accessible depuis le panneau de configuration dans les outils d'administration, c'est l'observateur d'évènements. La présence de ce programme à cet endroit montre bien l'importance de la journalisation.

Un message EventLog contient les informations suivantes.

• Le type du message.
• La source du message.
• L'identifiant du message.
• La catégorie du message.
• Le message lui-même.
• Des informations dynamiques facultatives.
• Un buffer de données facultatif.
• La date et l'heure.
• D'autres informations.

III-C-1. Le type du message▲

Il existe six types de messages EventLog. Le programme « Event Viewer » utilise ces types pour déterminer l'icône à utiliser pour afficher la liste des messages EventLog.

• Success : Il s'agit d'un message EventLog qui indique le succès d'une opération.
• Error : Il s'agit d'un message EventLog qui indique un problème significatif comme la perte de données ou de fonctionnalités. Par exemple, si un service ne parvient pas à démarrer, un message de type Error est généré.
• Warning : Il s'agit d'un message EventLog pas forcément significatif, mais qui pourrait indiquer un possible futur problème. Par exemple, quand l'espace disque devient faible, un message de type Warning est généré. En règle générale, si une application peut gérer ce type d'évènements sans perdre de fonctionnalités ou de données, l'évènement peut être classifié comme un EventLog de type Warning.
• Information : Il s'agit d'un message EventLog décrivant la réussite d'une opération pour une application, un service ou un driver. Par exemple, quand un driver réseau se charge avec succès, il est approprié de journaliser un message de type Information. À noter qu'il est généralement inapproprié pour une application utilisateur de générer un tel message à chaque lancement.
• Audit Success : Il s'agit d'un message EventLog qui enregistre le succès d'un accès à un objet dont la sécurité est auditée. Par exemple, la connexion avec succès d'un utilisateur sur le système est journalisée comme un évènement de type Audit Success.
• Audit Failure : Il s'agit d'un message EventLog qui enregistre l'échec d'une tentative d'accès à un objet dont la sécurité est auditée. Par exemple, si un utilisateur tente un accès à un disque réseau et échoue, cette tentative est journalisée comme un évènement de type Audit Failure.

Remarque : le programme « Event Viewer » ne fait pas de différences pour les icônes des types de messages Success, Audit success et Audit failure, il utilise l'icône des messages de type Information.

III-C-2. La source du message▲

La source du message EventLog est le nom du programme ou du service qui a généré cet évènement. C'est souvent le nom de l'application ou le nom d'un composant de cette application si celle-ci est vraiment importante. Une application ou un service peuvent utiliser leur propre nom. Cela peut être MSSQLSERVER ou Tcpip par exemple.

III-C-3. L'identifiant du message▲

L'identifiant du message EventLog est un nombre sur 32 bits qui identifie le message EventLog. Le programme « Event Viewer » affiche cet identifiant.

L'identifiant du message EventLog est un nombre sur 32 bits construit de la manière suivante.

• La partie code : c'est un nombre sur 16 bits qui identifie le message.
• La partie facility : c'est un nombre sur 12 bits. Il peut être utilisé pour identifier le sous-système ou le contexte qui a généré le message EventLog. Cette notion de fonctionnalité est totalement différente du concept de fonctionnalité utilisé par le protocole Syslog.
• La partie reserved bit : c'est un nombre sur 1 bit. Il est réservé pour un usage futur.
• La partie customer bit : c'est un nombre sur 1 bit. Il indique si le message EventLog est généré par le système ou bien par une autre application.
• La partie severity : c'est un nombre sur 2 bits. Il donne le niveau de sévérité du message EventLog. Cette notion de sévérité est totalement différente du concept de sévérité utilisé par le protocole Syslog.

III-C-4. La catégorie du message▲

La catégorie du message EventLog permet d'organiser et d'ajouter de l'information au message EventLog. Cette catégorie est une chaîne de caractères et chaque source de messages EventLog peut définir ses propres catégories. La signification de cette catégorie dépend de la source du message. Le programme « Event Viewer » montre la catégorie du message EventLog.

III-C-5. Le message EventLog▲

La signification et le contenu du message EventLog dépend de la source du message EventLog. Le programme « Event Viewer » montre le texte du message EventLog.

III-C-6. Les informations dynamiques▲

III-C-7. Le buffer de données▲

III-C-8. La date et l'heure▲

III-C-9. Les autres informations▲

Comme souvent pour les systèmes Microsoft, toutes les informations de configuration du sous-système EventLog se situent dans la base de registre.

III-D-1. Clé de registre racine▲

III-D-2. Les différents journaux▲

III-D-3. Les différentes sources▲

Les différentes clés de registres peuvent être vues de la manière suivante :

La reconstitution du message textuel (par le programme « Event Viewer » par exemple) suit un processus rigoureux, mais assez « tortueux ». Cette reconstitution est partiellement décrite dans la documentation du MSDN. Parfois, certains points de ce processus ont été déduits à partir du fonctionnement du programme « Event Viewer ». Si vous trouvez des informations plus complètes ou plus formelles, n'hésitez pas, 19 commentaires, ce document sera mis à jour.

Lorsqu'une application génère un message EventLog, elle fournit entre autres les informations suivantes.

• L'identifiant de la catégorie du message.
• L'identifiant du format de message.
• Un tableau optionnel de paramètres dynamiques.
• Un buffer optionnel de données complémentaires.

Le schéma suivant décrit le cheminement pour recréer le texte localisé complet du message EventLog :

III-F-1. Le nom de la catégorie▲

III-F-2. Le format du message▲

III-F-3. La récupération du format du message▲

III-F-4. Le remplacement des codes d'insertion▲

Les fonctions de l'API Event Logging disponibles pour accéder au sous-système EventLog sont les suivantes :

Toutes ces fonctions sont déclarées dans le fichier include windows.h (en fait, dans winbase.h). Ces fonctions sont implémentées dans la bibliothèque Advapi32.dll (et .lib). Toutes ces fonctions existent en version Unicode (xxxW) et Ansi (xxxA).

La fonction ReportEvent() attend entre autres les paramètres suivants :

• Le type : Il s'agit du code de gravité du message. Il n'y a aucun lien entre le message et son code de gravité. Ce sont le développeur et le projet, qui en fonction du contexte, déterminent le code de gravité. Les valeurs autorisées sont :

  • EVENTLOG_SUCCESS (0x00)
  • EVENTLOG_AUDIT_FAILURE (0x10)
  • EVENTLOG_AUDIT_SUCCESS (0x08)
  • EVENTLOG_ERROR_TYPE (0x01)
  • EVENTLOG_INFORMATION_TYPE (0x04)
  • EVENTLOG_WARNING_TYPE (0x02)
• La catégorie : Il s'agit d'un identifiant (sous forme de nombre) qui permet de qualifier le message en l'accompagnant d'un nom de sous-système par exemple. Ce nombre est l'identifiant d'une ressource chaîne de caractères qui est affichée par le programme « Event Viewer ». Il n'y a aucun lien entre le message et la catégorie, c'est-à-dire qu'un message peut être envoyé une première fois avec une catégorie et une seconde fois avec une autre catégorie sans que cela ne pose un problème. Cette catégorie de messages doit être unique pour une source donnée de messages EventLog. Les identifiants des catégories de messages doivent être séquentiels et commencer à 1. Ce sont le développeur et le projet, qui en fonction du contexte, déterminent la catégorie à utiliser.

• Le message : Il s'agit d'un identifiant (sous forme de nombre) d'une ressource chaîne de caractères qui représente le format d'affichage du message d'erreur. Cet identifiant de message doit être unique pour une source de messages Eventlog donnée. Ce sont le développeur et le projet, qui en fonction du contexte, déterminent le message à utiliser. Cet identifiant de message est constitué de 4 parties :

  • La racine de l'identifiant, c'est un nombre sur 16 bits.
  • La facilité du message, c'est un nombre sur 12 bits. Les facilités 0 à 255 sont normalement réservées par Microsoft et définies dans les fichiers include du SDK Microsoft, les facilités 256 à 4095 sont à la libre disposition des développeurs.
  • Le bit customer. Ce bit indique s'il s'agit d'un message système ou utilisateur.
  • La sévérité du message, c'est un nombre sur 2 bits qui indique la gravité du message. Les valeurs autorisées sont Success (0), Informational (1), Warning (2) et Error (3).
• L'identifiant de sécurité : Il s'agit des informations permettant de connaitre le nom de l'utilisateur qui a généré le message. Cet identifiant peut être absent si cela n'a pas de sens dans le contexte courant (dans le cas d'un service par exemple).
• Les paramètres applicatifs : Il s'agit d'un tableau optionnel de chaînes de caractères fourni par l'application permettant de compléter le message en fonction du contexte. Ces paramètres applicatifs sont déterminés par le développeur et le projet en fonction du contexte du message. Ces paramètres applicatifs doivent être mis en cohérence par rapport à l'information qu'attend le format du message (il est incohérent de passer un nom d'utilisateur si le message doit afficher le chemin de fichier de configuration par exemple).
• Un buffer de données : Il s'agit d'un tableau optionnel d'octets permettant d'ajouter de l'information au message (dump d'une structure par exemple).

IV-C-1. Format du fichier▲

;// This is a single-line comment.
 
;/* This is a block comment.
;   It spans multiple lines.
;*/

MessageIdTypedef = DWORD

SeverityNames =
   (
      Sev_Success       = 0x0
      Sev_Information   = 0x1
      Sev_Warning       = 0x2
      Sev_Error         = 0x3
   )

FacilityNames =
   (
      FACILITY_NULL                    =  0
      FACILITY_RPC                     =  1
      FACILITY_DISPATCH                =  2
      FACILITY_STORAGE                 =  3
      FACILITY_ITF                     =  4
   )

LanguageNames =
    (
        LANGUE_FRA   = 0x040c:Messages_0x040c
        LANGUE_ENG   = 0x0809:Messages_0x0809
    )

Outputbase = 10

MessageId       = 1000
MessageId       = +1
MessageId       =
MessageId       = +0

MessageId1      = 1000
Facility        = FACILITY_NULL
...
MessageId2      = 1200
Facility        = FACILITY_MBN
...
MessageId3      = +1
Facility        = FACILITY_NULL
...
MessageId4      = +1
Facility        = FACILITY_MBN
...

Severity      = Sev_Success
Severity      = Sev_Information

Facility      = FACILITY_MBN
Facility      = FACILITY_NULL

SymbolicName    = EVENT_STARTED_BY_1
SymbolicName    = EVENT_BACKUP
SymbolicName    = CATEGORY_ONE

;#ifndef __MESSAGES_EventMessageFile_H__
;#define __MESSAGES_EventMessageFile_H__
;
;// Ligne de compilation : mc.exe -u$(InputDir)\$(InputName).mc"
;//     -u indique un fichier Unicode
;
 
MessageIdTypedef = DWORD
 
Outputbase = 16
 
LanguageNames =
    (
        LANGUE_FRA   = 0x040c:Messages_0x040c
        LANGUE_ENG   = 0x0809:Messages_0x0809
    )
 
FacilityNames =
   (
      FACILITY_NULL                    =  0
      FACILITY_RPC                     =  1
      FACILITY_DISPATCH                =  2
      FACILITY_STORAGE                 =  3
      FACILITY_ITF                     =  4
      FACILITY_WIN32                   =  7
      FACILITY_WINDOWS                 =  8
      FACILITY_SSPI                    =  9
      FACILITY_SECURITY                =  9
      FACILITY_CONTROL                 = 10
      FACILITY_CERT                    = 11
      FACILITY_INTERNET                = 12
      FACILITY_MEDIASERVER             = 13
      FACILITY_MSMQ                    = 14
      FACILITY_SETUPAPI                = 15
      FACILITY_SCARD                   = 16
      FACILITY_COMPLUS                 = 17
      FACILITY_AAF                     = 18
      FACILITY_URT                     = 19
      FACILITY_ACS                     = 20
      FACILITY_DPLAY                   = 21
      FACILITY_UMI                     = 22
      FACILITY_SXS                     = 23
      FACILITY_WINDOWS_CE              = 24
      FACILITY_HTTP                    = 25
      FACILITY_USERMODE_COMMONLOG      = 26
      FACILITY_USERMODE_FILTER_MANAGER = 31
      FACILITY_BACKGROUNDCOPY          = 32
      FACILITY_CONFIGURATION           = 33
      FACILITY_STATE_MANAGEMENT        = 34
      FACILITY_METADIRECTORY           = 35
      FACILITY_WINDOWSUPDATE           = 36
      FACILITY_DIRECTORYSERVICE        = 37
      FACILITY_GRAPHICS                = 38
      FACILITY_SHELL                   = 39
      FACILITY_TPM_SERVICES            = 40
      FACILITY_TPM_SOFTWARE            = 41
      FACILITY_UI                      = 42
      FACILITY_PLA                     = 48
      FACILITY_FVE                     = 49
      FACILITY_FWP                     = 50
      FACILITY_WINRM                   = 51
      FACILITY_NDIS                    = 52
      FACILITY_USERMODE_HYPERVISOR     = 53
      FACILITY_CMI                     = 54
      FACILITY_USERMODE_VIRTUALIZATION = 55
      FACILITY_USERMODE_VOLMGR         = 56
      FACILITY_BCD                     = 57
      FACILITY_USERMODE_VHD            = 58
      FACILITY_SDIAG                   = 60
      FACILITY_WEBSERVICES             = 61
      FACILITY_WINDOWS_DEFENDER        = 80
      FACILITY_OPC                     = 81
      FACILITY_XPS                     = 82
      FACILITY_RAS                     = 83
      FACILITY_MBN                     = 84
   )
 
SeverityNames =
   (
      Sev_Success      = 0x0
      Sev_Information  = 0x1
      Sev_Warning      = 0x2
      Sev_Error        = 0x3
   )
 
 
;////////////////////////////////////////
;// Events
;//
 
MessageId       = 1000
SymbolicName    = EVENT_STARTED_BY_1
Facility        = FACILITY_MBN
Severity        = Sev_Success
Language        = LANGUE_FRA
Succès : L'application '%P02' (%2) a été démarrée par l'utilisateur%1"
.
Language        = LANGUE_ENG
Success : The program '%P02' (%2) has been started by user%1"
.
 
MessageId       = +0
SymbolicName    = EVENT_STARTED_BY_2
Facility        = FACILITY_NULL
Severity        = Sev_Information
Language        = LANGUE_FRA
Information : L'application '%P02' (%2) a été démarrée par l'utilisateur%1"
.
Language        = LANGUE_ENG
Information : The program '%P02' (%2) has been started by user%1"
.
 
MessageId       = +0
SymbolicName    = EVENT_STARTED_BY_3
Facility        = FACILITY_NULL
Severity        = Sev_Warning
Language        = LANGUE_FRA
Warning : L'application '%P02' (%2) a été démarrée par l'utilisateur%1"
.
Language        = LANGUE_ENG
Warning : The program '%P02' (%2) has been started by user%1"
.
 
MessageId       = +0
SymbolicName    = EVENT_STARTED_BY_4
Facility        = FACILITY_NULL
Severity        = Sev_Error
Language        = LANGUE_FRA
Error : L'application '%P02' (%2) a été démarrée par l'utilisateur%1"
.
Language        = LANGUE_ENG
Error : The program '%P02' (%2) has been started by user%1"
.
 
MessageId       = +1
SymbolicName    = EVENT_BACKUP
Facility        = FACILITY_NULL
Severity        = Sev_Information
Language        = LANGUE_FRA
Vous devriez sauvegarder vos données régulièrement !
.
Language        = LANGUE_ENG
You should regulary backup your data!
.
 
;
;#endif  //__MESSAGES_EventMessageFile_H__
;

IV-C-2. Construction du fichier de ressources▲

La chaîne de construction des ressources de messages EventLog est la suivante :

Le sous-système EventLog présente tout de même quelques limitations :

• Il n'est pas prévu nativement de pouvoir transférer les messages EventLog vers un concentrateur de messages de logs. Les seules possibilités sont la sauvegarde des différents journaux dans un fichier de sauvegarde ou alors la lecture des messages générés à l'aide de la fonction ReadEventLog() qui permet de se connecter à une machine distante par protocole Netbios. Cette fonctionnalité nécessite toutefois que la machine qui récupère les messages ait un compte sur la machine distante (machines dans un même domaine ou alors login/password sur la machine distante).
• Les messages ne peuvent être générés que sur la machine locale, car les ressources messages sont situées dans des DLL (ou exe) sur la machine qui génère le message. Une machine distante qui récupèrerait le message (par ReadEventLog() ou alors par une copie du journal des évènements) devrait avoir les mêmes DLL (ou exe) en local ou alors devrait pouvoir lire les fichiers à distance (par protocole Netbios).

Le choix qui a été fait pour ce projet à des fins purement didactiques est de réaliser une DLL pour chacune des familles de messages (catégories, messages et paramètres). Il est probable que dans un vrai projet, au moins les catégories et les messages seraient regroupés dans une seule DLL (avec peut-être aussi les paramètres).

Le programme utilise 3 DLL qui contiennent chacune les messages :

• EventCategorieFile.dll : cette DLL contient les ressources sous forme de chaîne de caractères des noms des différentes catégories en français et en anglais. Cette DLL définit 3 catégories dont les identifiants commencent à 1 et finissent à 3.
• EventMessageFile.dll : cette DLL contient les ressources sous forme de chaîne de caractères des formats d'affichage des différents messages en français et en anglais. Cette DLL définit 5 messages. Il est absolument impératif que les identifiants des messages commencent après le dernier identifiant de catégories. Si cette dernière règle n'est pas respectée, l'affichage des messages dans le programme « Event Viewer » sera incohérent.
• EventParameterFile.dll : cette DLL contient les ressources sous forme de chaîne de caractères des paramètres fixes des différents messages en langue neutre. Cette DLL définit un paramètre fixe dont l'identifiant est arbitrairement fixé à 5002. Il n'y a aucune contrainte sur le choix des identifiants des messages des paramètres.

Ces 3 DLL sont référencées dans la base de registre respectivement dans les clés de registre CategoryMessageFile, EventMessageFile et ParameterMessageFile.

Ce programme a été développé sur une machine Windows 7 professional en utilisant le « SDK Windows® Software Development Kit (SDK) for Windows 7 and .NET Framework 3.5 Service Pack 1 ».

Les différents binaires constituants ce projet sont :

• Le programme EventLogWriter.exe peut être récupéré ici.
• La DLL EventCategorieFile.dll peut être récupérée ici.
• La DLL EventMessageFile.dll peut être récupérée ici.
• La DLL EventParameterFile.dll peut être récupérée ici.

Ces 4 fichiers doivent être mis impérativement dans le même répertoire (et pas dans la racine d'un disque).

Le projet complet au format Visual Studio 2005 peut être téléchargé ici.

Le programme doit être appelé une première fois avec les privilèges d'administrateur. Ces privilèges sont nécessaires pour créer les différentes clés dans la base de registre.

Les clés qui vont être créées sont :

Le fonctionnement du programme est le suivant :

• Il commence par appeler la fonction _add_event_source() qui enregistre le programme TestApp comme source de messages EventLog dans le journal Application. C'est pour cela que les privilèges d'administrateur sont nécessaires la première fois.
• Ensuite le programme appelle la fonction _log_event(). Cette fonction va ouvrir une connexion avec le sous-système EventLog et ensuite envoyer 7 messages EventLog avec des caractéristiques différentes.
• La fonction _GetSid() est utilisée pour récupérer le SID (Security Identifier) de l'utilisateur actuellement connecté et le transmettre dans le message EventLog.

V-D-1. Le fichier EventLogWritter.cpp▲

// EventLogConsole.cpp : définit le point d'entrée pour l'application console.
//
 
#ifndef _WIN32_WINNT      // Autorise l'utilisation des fonctionnalités spécifiques à Windows XP ou version ultérieure.                   
#define _WIN32_WINNT 0x0501   // Attribuez la valeur appropriée à cet élément pour cibler d'autres versions de Windows.
#endif                  
 
#define _CRT_SECURE_NO_DEPRECATE
#define _CRT_NON_CONFORMING_SWPRINTFS
 
#include <Windows.h>
#include <stdio.h>
#include "MessageFile.h"
#include "CategorieFile.h"
#include "ParameterFile.h"
 
// quelques types bien utiles
typedef wchar_t MCR_CHAR;
typedef const wchar_t * MCR_CSTR;
typedef unsigned char MCR_U1;
typedef unsigned long MCR_U4;
 
static void _GetSID(SID * Sid)
{
   // Open the access token associated with the calling process.
HANDLE hToken = NULL;
   OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &hToken);
 
   // get the size of the memory buffer needed for the SID
DWORD dwBufferSize = 0;
   GetTokenInformation(hToken, TokenUser, NULL, 0, &dwBufferSize);
 
PTOKEN_USER pTokenUser = (PTOKEN_USER)malloc(dwBufferSize);
   memset(pTokenUser, 0, dwBufferSize);
 
   // Retrieve the token information in a TOKEN_USER structure.
   GetTokenInformation(hToken, TokenUser, pTokenUser, dwBufferSize, &dwBufferSize);
 
   // copy the SID structure
   memcpy(Sid, pTokenUser->User.Sid, sizeof(*Sid));
 
   // free everything
   free(pTokenUser);
   CloseHandle(hToken);
}
 
// nécessite les privilèges d'administration
// lancer le programme la première fois en tant qu'admin
static void _add_event_source(MCR_CSTR pszName, const MCR_U4 dwCategoryCount)
{
HKEY      hRegKey = NULL; 
MCR_CHAR szPath[ MAX_PATH ];
 
   swprintf( szPath, L"SYSTEM\\CurrentControlSet\\Services\\EventLog\\Application\\%s", pszName );
 
   // Create the event source registry key
   RegCreateKey( HKEY_LOCAL_MACHINE, szPath, &hRegKey );
 
   // Name of the PE module that contains the message resource
   GetModuleFileName( NULL, szPath, MAX_PATH );
 
   // remove the last '\'
   *wcsrchr(szPath, '\\') = 0;
 
   // Register EventMessageFile
   MCR_CHAR szFile[ MAX_PATH ];
   swprintf( szFile, L"%s\\%s", szPath, L"EventMessageFile.dll" );
   RegSetValueEx(   hRegKey, L"EventMessageFile", 0, REG_EXPAND_SZ,
                  (LPBYTE)szFile,
                  (MCR_U4)(wcslen( szFile ) + 1) * sizeof szFile[0] ); 
 
   // Register ParameterMessageFile
   swprintf( szFile, L"%s\\%s", szPath, L"EventParameterFile.dll" );
   RegSetValueEx(   hRegKey, L"ParameterMessageFile", 0, REG_EXPAND_SZ,
                  (LPBYTE)szFile,
                  (MCR_U4)(wcslen( szFile ) + 1) * sizeof szFile[0] ); 
 
 
   // Register CategoryMessageFile
   swprintf( szFile, L"%s\\%s", szPath, L"EventCategorieFile.dll" );
   RegSetValueEx(   hRegKey, L"CategoryMessageFile", 0, REG_EXPAND_SZ,
                  (LPBYTE)szFile,
                  (MCR_U4)(wcslen( szFile ) + 1) * sizeof szFile[0] ); 
 
   // Register supported event types
   MCR_U4 dwTypes = EVENTLOG_ERROR_TYPE | EVENTLOG_WARNING_TYPE | EVENTLOG_INFORMATION_TYPE; 
   RegSetValueEx( hRegKey, L"TypesSupported", 0, REG_DWORD, (LPBYTE) &dwTypes, sizeof dwTypes );
 
   // Register category count
   RegSetValueEx( hRegKey, L"CategoryCount", 0, REG_DWORD, (LPBYTE)&dwCategoryCount, sizeof dwCategoryCount );
 
   RegCloseKey( hRegKey );
}
 
static void _log_event(MCR_CSTR pszName)
{
   // Open the eventlog
   HANDLE hEventLog = RegisterEventSource( NULL, pszName );
 
   // get the sid of the user
SID sid;
   _GetSID(&sid);
   PSID psid = &sid;
 
   // make dynamic parameters array
   MCR_CSTR aInsertions[] = { L"Paramètre 1", L"Paramètre 2" };
 
   // buffer parameters
   MCR_U1 buffer[64];
   for(MCR_U1 boucle = 0; boucle != sizeof(buffer); boucle++)
      buffer[boucle] = ' ' + boucle;
 
   ReportEvent(hEventLog,                  // Handle to the eventlog
               EVENTLOG_SUCCESS,             // Type of event
               CATEGORY_TWO,               // Category (could also be 0)
               EVENT_STARTED_BY_1,         // Event id
               psid,                       // User's sid (NULL for none)
               2,                          // Number of insertion strings
               sizeof(buffer),             // Number of additional bytes
               aInsertions,                // Array of insertion strings
               buffer                      // Pointer to additional bytes
               );
 
   // And another one
   ReportEvent(hEventLog,                  // Handle to the eventlog
               EVENTLOG_INFORMATION_TYPE,  // Type of event
               CATEGORY_TWO,               // Category (could also be 0)
               EVENT_STARTED_BY_2,         // Event id
               psid,                       // User's sid (NULL for none)
               2,                          // Number of insertion strings
               sizeof(buffer),             // Number of additional bytes
               aInsertions,                // Array of insertion strings
               buffer                      // Pointer to additional bytes
               );
 
   ReportEvent(hEventLog,                  // Handle to the eventlog
               EVENTLOG_WARNING_TYPE,       // Type of event
               CATEGORY_TWO,               // Category (could also be 0)
               EVENT_STARTED_BY_3,         // Event id
               psid,                       // User's sid (NULL for none)
               2,                          // Number of insertion strings
               sizeof(buffer),             // Number of additional bytes
               aInsertions,                // Array of insertion strings
               buffer                      // Pointer to additional bytes
               );
 
   ReportEvent(hEventLog,                  // Handle to the eventlog
               EVENTLOG_ERROR_TYPE,          // Type of event
               CATEGORY_TWO,               // Category (could also be 0)
               EVENT_STARTED_BY_4,         // Event id
               psid,                       // User's sid (NULL for none)
               2,                          // Number of insertion strings
               sizeof(buffer),             // Number of additional bytes
               aInsertions,                // Array of insertion strings
               buffer                      // Pointer to additional bytes
               );
 
   ReportEvent(hEventLog,                  // Handle to the eventlog
               EVENTLOG_AUDIT_SUCCESS,       // Type of event
               CATEGORY_TWO,               // Category (could also be 0)
               EVENT_STARTED_BY_1,         // Event id
               psid,                       // User's sid (NULL for none)
               2,                          // Number of insertion strings
               sizeof(buffer),             // Number of additional bytes
               aInsertions,                // Array of insertion strings
               buffer                      // Pointer to additional bytes
               );
 
   ReportEvent(hEventLog,                  // Handle to the eventlog
               EVENTLOG_AUDIT_FAILURE,       // Type of event
               CATEGORY_ONE,               // Category (could also be 0)
               EVENT_STARTED_BY_2,         // Event id
               psid,                       // User's sid (NULL for none)
               2,                          // Number of insertion strings
               sizeof(buffer),             // Number of additional bytes
               aInsertions,                // Array of insertion strings
               buffer                      // Pointer to additional bytes
               );
 
   ReportEvent(hEventLog,                  // Handle to the eventlog
               EVENTLOG_SUCCESS,       // Type of event
               CATEGORY_ONE,               // Category (could also be 0)
               EVENT_BACKUP,                // Event id
               NULL,                       // User's sid (NULL for none)
               2,                          // Number of insertion strings
               0,                          // Number of additional bytes
               aInsertions,                // Array of insertion strings
               NULL                        // Pointer to additional bytes
               );
 
   // Close eventlog
   DeregisterEventSource( hEventLog );
}
 
int wmain(int /*argc*/, wchar_t * /*argv*/ [])
{
   // register the source EventLog
   // should be done during the setup procedure by the setup
   // but in this sample, will be done every times
   _add_event_source(L"TestApp", LAST_CATEGORY);
 
   _log_event(L"TestApp");
 
   return 0;
}

V-D-2. Le fichier CategoryFile.mc▲

;#ifndef __MESSAGES_EventCategorieFile_H__
;#define __MESSAGES_EventCategorieFile_H__
;
;// Ligne de compilation : mc.exe -u "$(InputDir)\$(InputName).mc"
;//     -u indique un fichier Unicode
;
 
MessageIdTypedef = DWORD
 
Outputbase = 10
 
LanguageNames =
    (
        LANGUE_FRA   = 0x040c:Messages_0x040c
        LANGUE_ENG   = 0x0809:Messages_0x0809
    )
 
;////////////////////////////////////////
;// Eventlog categories
;//
;// Categories always have to be the first entries in a message file!
;//
 
MessageId       = +1
SymbolicName    = CATEGORY_ONE
Language        = LANGUE_FRA
Première catégorie d'évènements
.
Language        = LANGUE_ENG
First category of events
.
 
MessageId       = +1
SymbolicName    = CATEGORY_TWO
Language        = LANGUE_FRA
Seconde catégorie d'évènements
.
Language        = LANGUE_ENG
Second category of events
.
 
MessageId       = +1
SymbolicName    = LAST_CATEGORY
Language        = LANGUE_FRA
Repère pour la dernière catégorie d'évènements
.
Language        = LANGUE_ENG
Tag for the last category of events
.
 
;
;#endif  //__MESSAGES_EventCategorieFile_H__
;

V-D-3. Le fichier MessageFile.mc▲

;#ifndef __MESSAGES_EventMessageFile_H__
;#define __MESSAGES_EventMessageFile_H__
;
;// Ligne de compilation : mc.exe -u "$(InputDir)\$(InputName).mc"
;//     -u indique un fichier Unicode
;
 
MessageIdTypedef = DWORD
 
Outputbase = 16
 
LanguageNames =
    (
        LANGUE_FRA   = 0x040c:Messages_0x040c
        LANGUE_ENG   = 0x0809:Messages_0x0809
    )
 
FacilityNames =
   (
      FACILITY_NULL                    =  0
      FACILITY_RPC                     =  1
      FACILITY_DISPATCH                =  2
      FACILITY_STORAGE                 =  3
      FACILITY_ITF                     =  4
      FACILITY_WIN32                   =  7
      FACILITY_WINDOWS                 =  8
      FACILITY_SSPI                    =  9
      FACILITY_SECURITY                =  9
      FACILITY_CONTROL                 = 10
      FACILITY_CERT                    = 11
      FACILITY_INTERNET                = 12
      FACILITY_MEDIASERVER             = 13
      FACILITY_MSMQ                    = 14
      FACILITY_SETUPAPI                = 15
      FACILITY_SCARD                   = 16
      FACILITY_COMPLUS                 = 17
      FACILITY_AAF                     = 18
      FACILITY_URT                     = 19
      FACILITY_ACS                     = 20
      FACILITY_DPLAY                   = 21
      FACILITY_UMI                     = 22
      FACILITY_SXS                     = 23
      FACILITY_WINDOWS_CE              = 24
      FACILITY_HTTP                    = 25
      FACILITY_USERMODE_COMMONLOG      = 26
      FACILITY_USERMODE_FILTER_MANAGER = 31
      FACILITY_BACKGROUNDCOPY          = 32
      FACILITY_CONFIGURATION           = 33
      FACILITY_STATE_MANAGEMENT        = 34
      FACILITY_METADIRECTORY           = 35
      FACILITY_WINDOWSUPDATE           = 36
      FACILITY_DIRECTORYSERVICE        = 37
      FACILITY_GRAPHICS                = 38
      FACILITY_SHELL                   = 39
      FACILITY_TPM_SERVICES            = 40
      FACILITY_TPM_SOFTWARE            = 41
      FACILITY_UI                      = 42
      FACILITY_PLA                     = 48
      FACILITY_FVE                     = 49
      FACILITY_FWP                     = 50
      FACILITY_WINRM                   = 51
      FACILITY_NDIS                    = 52
      FACILITY_USERMODE_HYPERVISOR     = 53
      FACILITY_CMI                     = 54
      FACILITY_USERMODE_VIRTUALIZATION = 55
      FACILITY_USERMODE_VOLMGR         = 56
      FACILITY_BCD                     = 57
      FACILITY_USERMODE_VHD            = 58
      FACILITY_SDIAG                   = 60
      FACILITY_WEBSERVICES             = 61
      FACILITY_WINDOWS_DEFENDER        = 80
      FACILITY_OPC                     = 81
      FACILITY_XPS                     = 82
      FACILITY_RAS                     = 83
      FACILITY_MBN                     = 84
   )
 
SeverityNames =
   (
      Sev_Success      = 0x0
      Sev_Information  = 0x1
      Sev_Warning      = 0x2
      Sev_Error        = 0x3
   )
 
 
;////////////////////////////////////////
;// Events
;//
 
MessageId     = 1000
SymbolicName  = EVENT_STARTED_BY_1
Facility      = FACILITY_NULL
Severity      = Sev_Success
Language      = LANGUE_FRA
Succès : L'application '%P01' (%1) a été démarrée par l'utilisateur "%2"
.
Language      = LANGUE_ENG
Success : The program '%P01' (%1) has been started by user "%2"
.
 
MessageId     = +0
SymbolicName  = EVENT_STARTED_BY_2
Facility      = FACILITY_NULL
Severity      = Sev_Information
Language      = LANGUE_FRA
Information : L'application '%P01' (%2) a été démarrée par l'utilisateur "%1"
.
Language      = LANGUE_ENG
Information : The program '%P01' (%2) has been started by user "%1"
.
 
MessageId     = +0
SymbolicName  = EVENT_STARTED_BY_3
Facility      = FACILITY_NULL
Severity      = Sev_Warning
Language      = LANGUE_FRA
Warning : L'application '%P01' (%1) a été démarrée par l'utilisateur "%2"
.
Language      = LANGUE_ENG
Warning : The program '%P01' (%1) has been started by user "%2"
.
 
MessageId     = +0
SymbolicName  = EVENT_STARTED_BY_4
Facility      = FACILITY_NULL
Severity      = Sev_Error
Language      = LANGUE_FRA
Error : L'application '%P01' (%2) a été démarrée par l'utilisateur "%1"
.
Language      = LANGUE_ENG
Error : The program '%P01' (%2) has been started by user "%1"
.
 
MessageId     = +1
SymbolicName  = EVENT_BACKUP
Facility      = FACILITY_NULL
Severity      = Sev_Information
Language      = LANGUE_FRA
Vous devriez sauvegarder vos données régulièrement !
.
Language      = LANGUE_ENG
You should regulary backup your data!
.
 
;
;#endif  //__MESSAGES_EventMessageFile_H__
;

V-D-4. Le fichier ParameterFile.mc▲

;#ifndef __MESSAGES_EventParameterFile_H__
;#define __MESSAGES_EventParameterFile_H__
;
;// Ligne de compilation : mc.exe -u "$(InputDir)\$(InputName).mc"
;//     -u indique un fichier Unicode
;
 
MessageIdTypedef = DWORD
 
Outputbase = 10
 
LanguageNames =
    (
        NEUTRAL = 0x0000:Messages_0x0000
    )
 
MessageId     = 5001
SymbolicName  = PARAMETER_5001
Language      = NEUTRAL
'Test %P02'
.
 
MessageId     = 5002
SymbolicName  = PARAMETER_5002
Language      = NEUTRAL
EventLogWritter.exe
.
 
;
;#endif  //__MESSAGES_EventParameterFile_H__
;

Le programme EventLogReader.exe lit les évènements EventLog du journal Application au fur et à mesure qu'ils sont générés. La génération d'évènements se fera en utilisant le programme EventLogWriter.exe présenté au paragraphe précédent.

Ce programme a été développé sur une machine Windows 7 professional en utilisant le « SDK Windows® Software Development Kit (SDK) for Windows 7 and .NET Framework 3.5 Service Pack 1 ».

Le programme EventLogReader.exe peut être récupéré ici.

Le projet complet au format Visual Studio 2005 peut être téléchargé ici.

Le programme commence d'abord par calculer le numéro du dernier évènement présent dans le journal avec les fonctions GetOldestEventLogRecord() et GetNumberOfEventLogRecords(). Ensuite, il détermine l'index du dernier évènement (Number of event log + Oldest event log - 1) pour se positionner juste après cet évènement (avec la fonction ReadEventLog(EVENTLOG_SEEK_READ | EVENTLOG_FORWARDS_READ).

Ensuite, il crée un objet évènement avec la fonction CreateEvent(). Cet objet est ensuite donné en paramètre au sous-système EventLog par la fonction NotifyChangeEventLog() afin d'être prévenu lors de l'arrivée d'un nouvel évènement EventLog.

Le programme fait ensuite une attente bloquante sur cet objet évènement et dès qu'il est libéré, le programme lit le journal des évènements avec la fonction ReadEventLog(). Cet appel pouvant retourner 1 ou plusieurs évènements simultanément, il y a une boucle de lecture/extraction des différents évènements EventLog.

Ensuite, chaque évènement EventLog est analysé et affiché par la fonction _analyse().

Remarque : la fonction NotifyChangeEventLog() est utilisée, car elle permet une attente passive. Toutefois, cette fonction ne peut pas être utilisée pour interroger le sous-système EventLog d'une autre machine. Dans ce cas, il faudra passer par une attente active avec temporisation, lecture et analyse s'il y a de nouveaux évènements EventLog.

Ce chapitre présente les quelques références (en anglais pour la plupart) qui m'ont servi pour comprendre le fonctionnement du sous-système EventLog et pour rédiger ce document.

• Message Compiler (MC.exe)
• Message Text Files
• Language Identifier Constants and Strings
• Client Processing of Event Descriptions and Other Localizable Strings
• FormatMessage Function
• Event Viewer
• L'API Event Logging
• L'API Windows Event Log
• Security Descriptor Definition Language

Je tiens à remercier 3DArchi et renaud26 pour leurs conseils avisés lors de la relecture de ce tutoriel.