ADCS Open Protocols specifications

Hello S-1-1-0,

Today I want to talk about another area in ADCS I’m contributing to — Open Protocols specifications.

Around 15 years ago, Microsoft moved toward to open source and started a new documentation branch called “Open Specifications”, where Microsoft publishes a very detailed Windows protocols specifications so third party can build compatible clients and servers for Windows products and components. Open Specifications library contains a large stock (hundreds of them!) of technical documents, for example, Windows Protocols. There is a sub-branch for Microsoft Office as well. Main audience is [of course] developers. Microsoft do not actively advertise these documents for some unknown reasons. Why I’m talking about this at all?

In the past, Microsoft maintained two documentation portals: TechNet for IT Pro and administrators and MSDN for developers. TechNet contained documentation about product behaviors without deep development details. MSDN on the other hand contained API documentation and behavior. Around 2015-2016, Microsoft merged both, TechNet and MSDN into a unified Microsoft Docs portal. At that point, Windows XP and Windows Server 2003 reached their last ever possible support. During TechNet/MSDN migration process, Microsoft decided to get rid of all legacy content for potentially unsupported products. And this migration resulted in a disaster when speaking about ADCS articles (I bet many other technologies are affected too). The problem was that a lot of technical documentation was written against Windows XP/Windows Server 2003 and rarely was updated (via “applies to”) to match new versions when behavior is unchanged. ADCS is a very conservative product, once something added, its functionality rarely was changed in newer Windows versions, a brand new functionality was added. This means that a lot of documentation written against deprecated Windows platforms is still valid even for the newest OS (Windows Server 2022, as of this post publishing time). As the result, Microsoft deprecated or otherwise wiped a lot of articles without any chance to be updated. New features to ADCS were added in Windows Server 2008 and Windows Server 2008 R2 which are now out of support and same applies to documentation. They are dead.

Open Specifications is actively maintained and supported by Microsoft and they can act as an alternative up to date documentation for products. Moreover, this documentation provides product version support for particular functionality. ADCS product includes a numerous Open Specification documents for example:

• [MS-WCCE] Windows Client Certificate Enrollment protocol
• [MS-CSRA] Certificate Services Remote Administration protocol
• [MS-CAESO] Certificate Autoenrollment protocol (archived)
• [MS-CRTD] Certificate Templates description
• [MS-XCEP] Enrollment Policy Web service
• [MS-WSTEP] Enrollment Web service
• [MS-OCSPA] Online Responder Administration protocol
• and others

These documents along with carefully salvaged whitepapers as primary documentation are my primary documentation sources when I developed PSPKI module and other proprietary products. Although the ADCS-related protocol specifications are the most comprehensive, they aren’t correct in every single aspect. While working with ADCS, I’m using these protocols along source and time by time I find mismatch between docs and observed behavior. I lost all internal contacts with Windows PKI team and have to look for public boards (and Microsoft MVP status is no helper at all). Filing a doc bug report in public boards/repos is somewhat challenging. You can file it, but whether you will still alive by the time when it is addressed (if ever) — this is a big question. Just an example: it took almost a year for Docs Team to eventually fix this doc bug: IOCSPCAConfiguration::get_ProviderProperties pVal documentation is incorrect. In the meantime it was closed, because the docs team considered it a low-priority issue. Contrary to this, my experience with Open Specification was very different.

I have no idea how Open Specification teams are managed internally, but Microsoft invests heavily into this division from what I see. In every protocol page, there is a list of all protocol historical versions, diffs and errata when available. Windows Protocol support team is a different beast and they own a dedicated forum in Microsoft Q&A where you can submit doc bugs in protocol specifications. Support team (mainly, Jeff McCashland and Obaid Farooqi, kudos to them) responds extremely quickly, within 24hrs. They don’t ask basic/dumb questions, I don’t have to explain WTH I’m talking about, they simply return with technical response (no matter whether my claims are valid or not). their professional level is above of any expectations given my previous experience with other support teams. It is not very humble, but I can tell that I’m the biggest non-MSFT contributor into ADCS protocol specifications.

Some of my recent activities for past 2 years (previous are on retired TechNet forums):

Here is the link to all my contributions in this area on Microsift Q&A: Crypt32 on openspec-windows. I’m really proud to be a part of this, making official docs better, correct, reliable and trustworthy.