INI file-format reverse engineering

This place is intended to provide details of the INI file format and INI file APIs as supported by Microsoft.

What is the INI file format?

Basically it's a key-value-store with a few limitations. The intended use looks like this:

[section1]
key1=value1
;next line defines key2
key2=value2
[section2]
;keys can repeat in another section
key1=value1
key2=value2

Straight-forward you may think. But it is a file format that has no specification - which is unfortunate. You can read more on Wikipedia. I will dissect the statements from there as soon as I have enough evidence.

File formats without a real specification seem to be popular again recently (like JSON, Markdown), after we went through a period of potentially over-specified file formats (like XML, of course with DTD only).

Why?

At least to my experience (working full time for three companies), there are still a lot of applications out there that store configuration information in INI files.

Parsing INI files seems trivial and I have written at least three INI file parsers in my life already - and probably none of them was 100% compatible to the INI file format of the Windows API - at least when it comes to humans editing the file in a text editor. They all "worked", sort of.

So, before I implement the next INI file parser, I want to make sure I understand what Microsoft does and provide a compatible implementation, and maybe a configurable one in order to be able to convert files from one INI dialect into another.

How?

For the moment I'll follow the law of the instrument and make progress using the tools I'm familiar with. As there are

• Visual Studio
• .NET Framework
• Unit Tests

This approach should quickly give me some insights.

Later, I could try a few things I'm not overly comfortable with, like

• C++

• Reverse Engineering using disassembly in WinDbg

• Reverse Engineering using IDA Free

at which point I'd certainly appreciate someone of the RCE community. At least I hope that I have found enough evidence before, so that I can always confirm my reverse engineering against the results of the unit tests.

What's the problem?

The problem? Many problems ;-)

Documentation

Analysis of GetPrivateProfileString()

Analysis of WritePrivateProfileString()

Analysis of Comments

Analysis of Registry Redirection

References

• English Wikipedia about the INI-file
• Question "Did INI files work in a different way on Windows 3.x than today?" on Retrocomputing
• Raymond Chen in "The old new thing": Why are INI files deprecated in favor of the Registry? Raymond Chen is a Microsoft employee writing a lot of blog posts
• Michael S. Kaplan in "Unicode INI function; Unicode INI file?" Michael S. Kaplan was a Microsoft employee writing blog posts until he died

Top questions on Stack Overflow regarding INI files:

• Reading/writing an INI file
• Do Standard INI files allow comments?
• What is the easiest way to parse an INI File in C++? (closed as off-topic, because "easiest" is opinion based, the Microsoft way might not be the easiest, but probably quite compatible)

Methods for reading INI files, focusing on the "private" ones. The non-private ones will only read from c:\windows\win.ini:

• Reading text

  • GetPrivateProfileString() [MSDN]
  • GetPrivateProfileStringA() [MSDN]
  • GetPrivateProfileStringW() [MSDN]

• Reading structs

  • GetPrivateProfileStruct() [MSDN]
  • GetPrivateProfileStructA() [MSDN]
  • GetPrivateProfileStructW() [MSDN]

• Reading numbers

  • GetPrivateProfileInt() [MSDN]
  • GetPrivateProfileIntA() [MSDN]
  • GetPrivateProfileIntW() [MSDN]

• Reading sections

  • GetPrivateProfileSection() [MSDN]
  • GetPrivateProfileSectionA() [MSDN]
  • GetPrivateProfileSectionW() [MSDN]
  • GetPrivateProfileSectionNames() [MSDN]
  • GetPrivateProfileSectionNamesA() [MSDN]
  • GetPrivateProfileSectionNamesW() [MSDN]

The Registry key that maps INI files is at

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\IniFileMapping

Implementations

Of course, people have implemented INI parsers already. My implementations are not published, luckily :-)

• NuGet: INI-Parser License: MIT
• NuGet: Peanut Butter.INI License: BSD 3-clause
• CodeProject: An INI file handling class using C# License: unclear. Problems: has a limit of 254 characters for reading.
• Bytes: Reading and parsing an INI file in C#. License: unclear. Problems: does not strip spaces from the values
• Multipedros: Confing.dll has a SimpleIni and a Ini class. License: FreeBSD
• Github: Madmilkman.ini License: MIT.
• Github: simpleini. License: MIT.
• SourceForge: libini License: unclear.
• Github: inih License: New BSD.
• Github: inipp License: MIT.
• Maybe a dozen implementations answering this Stack Overflow question

Giving back to the community

As a result of my research I came across a few things and I can hopefully give back to the community, to whomever is interested. I left my traces here:

• Stack Overflow: Do Standard INI files allow comments?
• Stack Overflow: How do WritePrivateProfileStringA() and Unicode go together?
• Stack Overflow: Why does File.ReadAllText() also recognize UTF-16 encodings?
• Stack Overflow: What are the differences in functionality when INI files are mapped to the Registry?
• Super User: What's the largest REG_SZ value that Regedit can edit?