Version Policy

Keychain follows semantic versioning (https://semver.org/) rules. Each Keychain Core component release is versioned major.minor.patch.

The key version compatibilities are SDK API compatibility and data (ciphertext) compatibility. Others compatibility include pairing (URI) format compatibility, database schema compatibility, and utility API compatibility.

From the 2.3 release line onwards, all Keychain Core packages maintain backward data compatibility. Every subsequent version of the SDK since 2.3 will decrypt and/or verify data that was encrypted and/or signed from a previous version (>=2.3).

A planned future update might break backwards compatibility for pairing due to a change in URI data format.

Version Components

Major

Major releases occur when there are substantial changes in functionality or when new functionality breaks API backwards compatibility. Releases within the same major release line will maintain API compatibility.

Minor

Minor releases add new features, improvements to existing features, and fixes that maintain backwards API compatibility.

Patch

Patch releases fix bugs and maintain backwards API compatibility. Only the latest minor release of a major release line will receive patches. Patch releases happen as needed depending on the urgency of the fix.

Prerelease

Major and minor releases may include prerelease versions (major.minor.patch-rc<N>). Once a release candidate (rc) has been thoroughly tested, the stable release will be published.

Wrapper Versions

Keychain also provides wrappers for Keychain Core in other programming languages, such as Python, C# and Java. The version naming convention for the wrappers is discussed below.

Major

The major version of a wrapper always matches the major version of Keychain Core for which it is targeted.

Minor

The minor version of a wrapper is always less than or equal to the minor version of Keychain Core for which it is targeted. However, newer features or API methods may not be exposed, so some functionality might be missing.

Patch

The patch version of a wrapper is independent of the Keychain Core patch version. It is used to improve the wrapper (in this way it overlaps with minor version role as described in Keychain Core) and fix bugs.

Due to early idiosyncracies in Keychain Core v2.x, where new features were sometimes added on patch instead of minor versions, some wrappers A.B.C are not supported by the equivalent Keychain Core < A.B.D despite having the same major/minor. You should consult the compatibility matrix to find out whether the wrapper version you intend to use is compatible fully, partially, or not at all with the Keychain Core version.

Examples

The table below shows a mixture of Core and Wrapper versions and what the developer can expect for compatibility.

Note that this presumes Core v3 and beyond, on account of the idiosyncratic patch versioning used in v2. For v2 compatibility the first two rows are not guaranteed and the compatibility matrix should be referenced directly instead.

Core Version	Wrapper Version	Compat.
3.4.5	3.4.5	OK (for 3.x and beyond)
3.4.5	3.4.2	OK (for 3.x and beyond)
3.4.5	3.3.7	Partial Compatibility - missing new Core features
3.4.5	3.5.2	NG - wrapper may attempt to invoke API that does not exist. Application may still appear to work
3.4.5	4.1.2	NG - Fully incompatible
3.4.5	2.4.13	NG - Fully incompatible