# SymCrypt is the cryptographic library Windows itself runs on > SymCrypt is the core cryptographic function library currently used by Windows, and it is now published under the MIT licence with a SemVer API contract, a FIPS 140 certification path and a build that works on Linux as well as Windows. The README is also unusually candid about who may contribute to it, which is almost nobody outside Microsoft. **microsoft/SymCrypt** — Core cryptographic library for Windows, Azure Linux and other products - Repository: https://github.com/microsoft/SymCrypt - Stars: 896 · Forks: 90 - Language: C - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/microsoft-symcrypt ## From a symmetric-only library to the one Windows uses for everything SymCrypt is described as the core cryptographic function library currently used by Windows, and the history section explains how it got there. The library was started in late 2006 with the first sources committed in February 2007. Initially the goal was limited to implementing symmetric cryptographic operations, hence the name. Starting with Windows 8 it was the primary crypto library for symmetric algorithms. In 2015 the work of adding asymmetric algorithms began, and since the 1703 release of Windows 10, SymCrypt has been the primary crypto library for all algorithms in Windows. That last sentence is the one that matters for an outside adopter. This is not a cryptography library that Microsoft publishes alongside its own; it is the implementation behind the platform's cryptographic behaviour, and it is used by Azure Linux and other products according to the project description. That is the origin of its unusual properties. The code is a single implementation that has to satisfy a hardware certification regime, run on every CPU architecture Windows supports, and stay bit for bit consistent across all of them, because a cryptographic primitive that behaves differently on two machines in the same product is a security defect. The scale is also visible in the repository. Alongside the public source there is a doc/ directory, a gen/ directory for code generation, a modules/ directory, a lib/ and a lib_plus/ directory for the library variants, an inc/ directory for headers, a 3rdparty/ directory, a unittest/ directory, a test/ directory and a SymCRust/ directory, which is the Rust side of the tree. There is a SymCrypt.sln for Visual Studio, a CMakeLists.txt with CMakePresets.json for the other platforms, an msbuild/ directory, a project.mk, and a scripts/ directory holding the build and test helpers. ## Six goals, and every one of them is a constraint The goals section is short, and it is the most useful part of the README for anyone deciding whether this library fits. The README says that, like any engineering project, SymCrypt is a compromise between conflicting requirements, and then lists the goals: ```yaml - Provide safe implementations of the cryptographic algorithms needed by Microsoft products. - Run on all CPU architectures supported by Windows. - Good performance. - Minimize maintenance cost. - Support FIPS 140 certification of products using SymCrypt. - Provide high assurance in the proper functionality of the library. ``` Read as a set, these are not six features. They are six pressures pulling in different directions, and the interesting engineering question is how the library resolves them. Running on all CPU architectures Windows supports means an implementation that cannot assume a particular instruction set, which is a hard constraint on how the assembly level optimisations can be written and how they have to be tested. Good performance then has to be achieved without that freedom, which is why you see architecture specific source files in a project like this rather than one portable implementation. Minimizing maintenance cost and providing high assurance pull against each other in a specific way. A library used inside a certified product cannot be changed casually, so every change has to be validated. A library with a high assurance bar has fewer contributors, and fewer contributors means fewer bugs but also fewer eyes and a slower pace. The FIPS 140 goal adds a third dimension, because the certification process constrains what can be changed and when, and it constrains the entropy sources the library is allowed to use. The safe implementations goal is the baseline, and it is worth reading as a constraint on the other five rather than as a separate promise. ## Building with scripts/build.py, and the submodule you may not be able to clone The documented way to build is the Python build script, scripts/build.py, and the README says you can run it with the --help argument to see which arguments are required and what each one does. For detailed build instructions, including alternative ways to build, it points to BUILD.md in the repository root. The build system is a mix, which is expected for a library that has to build on Windows and on Linux from the same tree. There is a Visual Studio solution, SymCrypt.sln, an msbuild/ directory, a CMakeLists.txt with a CMakePresets.json beside it, a project.mk, and cmake-configs/ and conf/ directories for configuration. A .pipelines/ directory and an .azuredevops/ directory hold the CI definitions, with .github/ for the GitHub side and a CodeQL.yml file for static analysis. Cloning the repository is where a newcomer hits a wall, and the README is upfront about it. In some Linux modules SymCrypt uses Jitterentropy as a source of FIPS-certifiable entropy, so to build those modules you need the jitterentropy-library submodule cloned as well, and the instruction is to run git submodule update --init after cloning. The second submodule is a different situation. The unittest/SymCryptDependencies submodule provides the RSA32 and msbignum implementations, which are used as benchmarks in the unit tests when compiled on Windows. Because of licensing restrictions, Microsoft cannot release these libraries publicly, so the submodule is only cloneable by Microsoft employees with access to the private Azure DevOps repository. The README tells external developers to ignore that submodule. It is only used in the unit tests and does not change the behaviour of the SymCrypt product code. That is an important detail for anyone evaluating the test coverage: the comparison against two independent big number implementations is not available to you, so the local test run is a functional check of SymCrypt against its own expectations rather than a differential test against other implementations. ## The unit test compares SymCrypt against CNG and CAPI on Windows The testing section describes what the SymCrypt unit test does, and the most interesting line is about what it compares against. The unit test runs extensive functional tests on the SymCrypt library. On Windows it also compares results against other implementations such as the Windows APIs CNG and CAPI, and against the older crypto libraries rsa32 and msbignum, if they are available. It also provides detailed performance information. So the testing strategy on Windows is differential, and it is a good one. SymCrypt implements the same primitives that the Windows cryptographic APIs provide, so the platform itself is a second opinion about whether a given computation is right. A disagreement between SymCrypt and CNG is a signal that something needs investigating in one of them, and since the unit test runs on every build, that disagreement surfaces early. The comparison against rsa32 and msbignum extends the same idea to the big number code that those older libraries contain, and the performance information is what lets a change be judged on more than correctness. After a successful build, you can use the scripts/test.py helper script to run the unit tests. The test/ directory in the repository root holds the functional tests, and unittest/ holds the ones that exercise the library more directly, with the SymCryptDependencies submodule sitting inside it. The caveat for an outside adopter is the one above. On Linux, where the private submodule is not available, the differential comparisons against rsa32 and msbignum are simply not there, and the CNG and CAPI comparison is Windows only. You get the functional tests, and you get them running against your own platform and your own compiler, which is still worth having. ## SemVer since 101.0.0, and a strong recommendation to keep updating As of version 101.0.0, SymCrypt uses the version scheme defined by the Semantic Versioning 2.0.0 specification, and the README spells out what that means for a library consumer: ```yaml - Major version changes introduce ABI and/or API breaking changes (including behavior changes) - Minor version changes introduce backwards compatible additional functionality or improvements, and/or bug fixes - Patch version changes introduce backwards compatible bug fixes ``` The initial open source release started at version 100, for compatibility with the previous internal versioning scheme. That is why the current tags look like 103.x, since the major version has moved on from the internal numbering. The versioning is the part of this project that makes it adoptable, because a cryptographic library that changes its API without warning would be unusable. SemVer plus a stated stability policy plus a regression test suite is a contract, and the current release history shows it being kept. The recent tags are v103.13.0 from 2026-09-04, v103.11.0 from 2026-03-31 and v103.8.0 from 2025-01-29, and the last push to the repository was on 2026-08-06. The servicing guidance is unusually direct. The strong recommendation is that distro vendors and application developers regularly update to the latest version of SymCrypt and of the SymCrypt engine, for security fixes and for functionality and performance improvements. The stated reason is that Microsoft maintains a stable API and ABI and has a suite of strong regression tests, and that staying on the current version prevents the need for complex and potentially riskier backports. Read that as a policy statement about how to consume the library. You are meant to be on a current version, and you are meant to update rather than to fork and patch. ## Security reports go to an email address, and outside code contributions are refused Two paragraphs in the README are about who may do what, and both are unusual enough to be worth reading in full. The first is the security process. If you believe you have found a problem that affects the security of the code, you should not create an issue or a pull request, but should email your comments to secure@microsoft.com, with SECURITY.md in the repository root holding more information. A cryptography library that is deployed inside certified products cannot take a vulnerability report through a public issue tracker, because the report itself would be public before a fix is available. The second is the contribution policy, and it is a hard limit. The README says they love to receive comments and suggestions, but cannot accept external code contributions except in specific circumstances from vetted partners with whom there is a pre-arranged agreement. The stated reason is that cryptographic code is considered highly sensitive by many of the large customers, that some very big customers place great value on the assurance of the crypto code used in their organisation, and that restricting the coding to a handful of employees greatly reduces the perceived risk of malicious contributions. That is a coherent position and it is consistent with everything else about the project. The same argument that produces a code base only Microsoft engineers can write produces a code base where a very large customer can get assurance about it. What it means for you is that this is a read and vendor library, not a community project, and that the only realistic way to change it is to report a problem and wait. The project has adopted the Microsoft Open Source Code of Conduct, with a link to the FAQ and an opencode@microsoft.com address for questions about the project, and there is an AGENTS.md and a BRANCHES.md at the repository root, plus a CHANGELOG.md for the per version record. ## MIT, FIPS 140, and a licensing split worth reading The licence is MIT, with LICENSE.txt at the repository root and a separate NOTICE.txt beside it, which is the pattern for a project that includes third party components. The 3rdparty/ directory at the root holds them, and the cgmanifest.json file is a component governance manifest, which is how a large organisation tracks the provenance of what it builds. The FIPS 140 goal from the goals list is the one that shapes the build most concretely, because certification constrains the entropy sources. That is the reason for the Jitterentropy dependency in the Linux modules, since the README describes it as a source of FIPS-certifiable entropy. A library that wants to be usable inside a certified product has to draw randomness from a source that the certification regime accepts, which is a constraint that many otherwise excellent libraries do not meet. For a team outside Microsoft, the practical consequences are these. The code is MIT, so you can read it, vendor it, build it and ship it, and you can audit it, which for a cryptographic library is the point of the exercise. The entropy path is documented enough to understand that the Linux build is not simply calling the system random source. And the project is not a place where your own patches are welcome, so your fork is your own responsibility. The release cadence supports that. The recent tags are v103.13.0, v103.11.0 and v103.8.0, and the guidance is to update regularly rather than to sit on a version. A team that takes that advice ends up with a repeatable upgrade: pull the new tag, run the build, run scripts/test.py, and re-run your own integration tests. The API and ABI stability that Microsoft commits to is what makes that routine rather than a project. ## Conclusion Adopt SymCrypt if you need a primitive level cryptographic library that is already certified for FIPS 140, that you can build and audit yourself, and that behaves identically on Windows, Linux and Azure Linux, and if you are prepared to take on the servicing work that the README asks of you. Do not adopt it if you need a high level cryptographic API, since this is a primitives library, and do not expect to contribute code to it, because the README says external code contributions are not accepted except in specific circumstances from vetted partners. Before you depend on it, read BUILD.md and the versioning rules, run the unit tests against your own platform, and plan to track releases rather than pinning a single version, since Microsoft explicitly recommends updating regularly instead of backporting. ## FAQ ### What is SymCrypt and where is it used? SymCrypt is the core cryptographic function library currently used by Windows, and the project description also names Azure Linux and other products. It has been the primary library for all algorithms in Windows since the 1703 release of Windows 10. ### How do I build SymCrypt? Use the Python build script scripts/build.py, which accepts a --help argument describing the required arguments, and see BUILD.md for detailed and alternative build instructions. If you build the Linux modules you also need the jitterentropy-library submodule, cloned with git submodule update --init. ### Can I contribute code to SymCrypt? Not in practice. The README says external code contributions are not accepted except in specific circumstances from vetted partners with a pre-arranged agreement, because cryptographic code is treated as highly sensitive and restricting coding to a handful of employees reduces the perceived risk of malicious contributions. ### How do I report a security problem in SymCrypt? Do not open an issue or a pull request. The README asks you to email your comments to secure@microsoft.com, and points to SECURITY.md for more information. ### What versioning does SymCrypt use? Since version 101.0.0 it follows Semantic Versioning 2.0.0, with major versions introducing ABI and API breaking changes, minor versions adding compatible functionality, and patch versions carrying compatible fixes. The open source release started at version 100 to match the previous internal scheme. ## Sources - [Issues](https://github.com/microsoft/SymCrypt/issues) - [License: MIT](https://github.com/microsoft/SymCrypt/blob/main/LICENSE) - [microsoft/SymCrypt on GitHub](https://github.com/microsoft/SymCrypt) - [README](https://github.com/microsoft/SymCrypt/blob/main/README.md) - [Releases](https://github.com/microsoft/SymCrypt/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/microsoft-symcrypt