The ISARA Radiate Quantum-Safe Library provides a set of cryptographic primitives that let you develop software resistant to attacks by quantum computers. These primitives include:

  • Hash algorithms: SHA2 (Secure Hash Algorithm 2; 256 bit, 384 bit and 512 bit), SHA3 (Secure Hash Algorithm 3; 256 bit and 512 bit)

  • Message authentication codes: (Hash based Message Authentication Code), Poly1305

  • Random number generator: HMAC-DRBG (HMAC Deterministic Random Bit Generator)

  • Key derivation functions: RFC-5869, NIST SP 800-56A Alternative 1 Concatenation, PBKDF2 (Password Based Key Derivation Function 2)

  • Digital signature schemes: Dilithium, HSS (Hierarchical Signature Scheme), Rainbow, SPHINCS+, XMSS (eXtended Merkle Signature Scheme), XMSSMT (multi-tree XMSS)

  • Key agreement schemes: FrodoDH, NewHopeDH, Samwise (an optimized FrodoDH variant), SIDH (Supersingular Isogeny Diffie-Hellman)

  • Key encapsulation mechanisms: Classic McEliece, FrodoKEM, Kyber, NTRUPrime, Saber, SIKE (Supersingular Isogeny Key Exchange)

  • Symmetric cipher: ChaCha20

Changes Since 2.0

New features:

  • Saber, a lattice-based key encapsulation mechanism.

  • New integration samples demonstrating using OpenSSL’s hash implementations, using the Windows CNG with our random number generator API, and using a UNIXy systems' /dev/urandom with our random number generator API. See the individual samples for additional requirements.

  • New Visual Studio projects for building the samples on Windows platforms.

Changed features:

  • The 64-bit x86 libraries now ship in lib (formerly lib_x86_64) to make it easier to compile the samples out of the box. 64-bit ARM libraries are the default on ARM platforms.

  • Added IQR_HSS_2E15_FAST and IQR_HSS_2E15_SMALL variants for HSS.

  • Added lower security variants of Dilithium (IQR_DILITHIUM_80), FrodoKEM (IQR_FRODOKEM_640_AES and IQR_FRODOKEM_640_SHAKE), Kyber (IQR_KYBER_512), SIDH (IQR_SIDH_P434), and SIKE (IQR_SIKE_P434). These are suitable for situations when lower processing time is more important than higher security.

  • Removed HSS height 25 single-tree variants ('IQR_HSS_2E25_FAST' and 'IQR_HSS_2E25_SMALL'); use multi-tree variants or stateless algorithms instead.

  • Optimizations and bug fixes throughout.

  • API headers are more compatible with C implementations conforming to specifications older than C11.

  • iqr_HashRegisterCallbacks() won’t modify the iqr_Context if a hash implementation fails the internal known-answer tests.

  • Fixed a security vulnerability in HSS multi-tree state handling. You’ll need to create new keys if you’re using HSS multi-tree variants from a pre-release of the toolkit.

Contents

The toolkit is organized into several directories:

  • doc — API documentation (doc/library/index.html) and Developer’s Guide (doc/guide/guide.html).

  • include — toolkit headers.

  • one or more lib and lib_<cpu> directories — toolkit static and shared libraries optimized for the given CPU family (for example, lib_skylake would have binaries optimized for the "skylake" architecture). The lib directory has the most-common architecture for the platform (usually x86-64).

  • samples — Sample programs demonstrating how to use the toolkit.

Getting Help

The latest version of the toolkit documentation is available on ISARA’s website:

For information about reporting security issues, please read the SECURITY document.

Using the Toolkit

After unpacking the toolkit archive, you can start using it by adding the following command-line arguments to your compiler:

-I/path/to/isara_toolkit/include \
-L/path/to/isara_toolkit/lib \
-liqr_toolkit

You can specify an architecture-specific lib_cpu instead of lib where cpu is one of the available CPUs in your archive. For example, the linux archive includes some of these versions of the library:

  • lib - 64 bit AMD and Intel CPUs (the default)

  • lib_core2 - Intel Core 2 CPUs

  • lib_sandybridge - Intel Sandybridge CPUs

  • lib_skylake - Intel Skylake CPUs

If you require a version of the library tuned for a specific CPU, please contact ISARA’s sales team.

Building the Samples

To build all of the samples at once:

cd /path/to/isara_toolkit/samples
mkdir build
cd build
cmake ..
make

To build a specific sample:

cd /path/to/isara_toolkit/samples/algorithm/sample_name
mkdir build
cd build
cmake ..
make

For more details and tool requirements, please refer to the Developer’s Guide (doc/guide/guide.html) documentation.

Note
Don’t build the samples on macOS using gcc 8, they will crash before main() due to a problem with -fstack-protector-all. Use clang to produce Mac binaries.

Windows developers can also use the Visual Studio solution and projects found in samples/VisualStudio.

System Requirements

Recommended:

  • Android 7.0 (Nougat) or newer (API level 24 or higher)

  • FreeBSD 11 or newer (64 bit platforms)

  • iOS 12 or newer

  • Linux (Ubuntu 18.04 LTS or newer, CentOS 7 or newer; 64 bit platforms)

  • macOS 10.14 or newer

  • Windows 10 (64 bit platforms)

Minimum:

  • Android 6.0 (Marshmallow) or newer (API level 23 or higher)

  • FreeBSD 11 (64 bit platforms)

  • iOS 8.1 or newer

  • Linux (Ubuntu 14.04 LTS or newer, Debian 8 or newer; 64 bit platforms)

  • macOS 10.10 or newer

  • Windows 10 or newer (64 bit platforms)

Supported CPUs by OS:

  • Android: x86, x86_64, armeabi-v7a, arm64-v8a (default lib)

  • iOS: x86, x86_64, armv7, armv7s, arm64 (default lib)

  • Linux: x86_64 (default lib), core2, sandybridge, skylake, powerpc (32-bit), armv7 (Raspbian 9.4 on Raspberry Pi3)

  • macOS: x86_64 (default lib), core2, sandybridge, skylake

  • Windows: x86_64 (default lib), core2, sandybridge, skylake

Additional CPU-specific builds can also be created on demand; please contact ISARA’s sales team.

Change Log

Changes Since 1.5

Note
All algorithms from NIST’s Post-Quantum Security competition (except Classic McEliece) Round 2, are incompatible with previous versions. You will need to create new keys, signatures, etc. if you’re using these algorithms. This also applies to FrodoDH and SIDH.

New features:

  • iqr_HSSCreateParams() now lets you specify a variant rather than specific layers, height, and Winternitz values. You can still Verify() signatures created with any valid parameter set from the RFC.

  • Samwise, a lattice-based key agreement scheme.

  • SPHINCS+, a stateless hash-based signature system.

  • XMSSMT - A variant of XMSS supporting hyper-trees.

  • You can now create an HSS parameters object from an existing HSS signature object.

  • You can now create an XMSS or XMSSMT parameters object from an existing XMSS or XMSSMT public key object.

  • GetSize() functions now exist for all algorithms.

  • Added a VERIFY_ONLY_STRATEGY tree strategy for HSS/XMSS/XMSSMT applications that only do signature verification.

  • Added the Classic McEliece key encapsulation mechanism.

  • NTRUPrime private keys now include a header with tag and version information. Older versions of these private keys cannot be imported.

  • FreeBSD 11 is now a supported platform on 64 bit x86 architectures.

  • Raspberry Pi (ARMv7) is now a supported 32 bit Linux platform.

  • Rainbow private keys now include a header with tag and version information. Older versions of these private keys cannot be imported.

Changed features:

  • All algorithms from NIST’s Post-Quantum Security competition have been updated to match the changes for Round 2.

  • Dilithium doesn’t require a registered hash function.

  • FrodoDH has been updated so its variants more closely match the FrodoKEM variants in the NIST competition.

  • HSS has been updated to RFC 8554.

  • HSS/XMSS/XMSSMT tree strategies have been renamed.

  • SIDH has been updated so its variants more closely match the SIDH variants from the NIST competition.

  • Internal AES functions will use CPU-native instructions for x86 CPUs that support them.

  • Optimizations to a number of "building block" algorithms (hashing, SHAKE) for specific architectures.

  • Removed libm dependency in samples.

  • Removed the Randomized Hashing functions (iqr_HashSetSalt() etc.).

  • Removed the BLAKE2b hash.

  • Removed SHAKE from the RNG interface.

  • Removed the following iqr_retval.h error values: IQR_EINVPLAINTEXTSIZE, IQR_EINVCIPHERTEXTSIZE, IQR_EINTOVERFLOW, IQR_EDIVBYZERO, IQR_EBADRESULT

  • Removed the ECDH key agreement scheme. It’s not quantum-safe.

  • Removed the LUKE (iqr_luke.h) key agreement scheme.

  • Removed QC-MDPC KEM (iqr_mceliece.h).

Changes Since 1.4

New features:

  • HSS and XMSS now support the BDS tree strategy, resulting is significantly smaller private keys and a separate state at the cost of more processing time during Sign() operations. There’s also a verify-only strategy for efficiently verifying signatures.

  • HSS and XMSS now support detaching subsets of the private key’s state; this lets you split the range of one time signatures. Refer to the Developer’s Guide for details.

  • Rainbow now supports six variants.

  • The library now supports a watchdog callback for long-running operations.

  • Library version information is now exposed in iqr_version.h, and a function has been added to verify that your library matches the headers you’re using. The version sample demonstrates this.

  • Hash: SHA2-384

  • Key agreement scheme: FrodoDH

  • Key encapsulation mechanisms: FrodoKEM, SIKE

  • SIDH now supports both the p503 and p751 variants.

Changed features:

  • The signature scheme formerly known as LMS is now HSS, and is compatible with the IETF draft. Currently only one level of hyper-tree is supported.

  • HSS implementation updated to version 13 of the IETF draft specification.

  • XMSS is now compatible with the IETF RFC.

  • HSS and XMSS now manage their own state rather than requiring the user to manage an index. This state needs to be stored safely after every Sign() operation (or every Detach() operation if you’re splitting state).

  • Rainbow key generation is now significantly faster.

  • Several algorithms have been updated to be compatible with the NIST competition submissions: Dilithium, Rainbow

  • Several algorithms have been updated to be compatible with the NIST competition submissions: Dilithium, Kyber, NTRUPrime, Rainbow

  • The NIST SP 800-56A Alternative 1 KDF is now known as NIST SP 800-56C Option 1 due to a new release of that specification.

  • Clarified that the McEliece QC-MDPC KEM is CPA secure but not CCA2 secure.

Changes Since 1.3

New features:

  • Digital signature scheme: XMSS

Changed features:

  • Significantly faster SIDH implementation.

  • LMS implementation updated to version 8 of the IETF draft specification.

  • KDF APIs marked "Deprecated"; they’ll receive a "generic" KDF API (to allow streaming) in a future toolkit release.

Changes Since 1.2

New features:

  • Digital signature schemes: Dilithium, Rainbow

  • Hash: BLAKE2b (256 bit and 512 bit)

  • Key agreement schemes: ECDH, SIDH

  • Key encapsulation mechanisms: Kyber, McEliece QC-MDPC, NTRUPrime

  • FIPS 140 certification (Implementation Under Test as of 2017-07-07)

  • LMS now supports a tree height of 25.

  • iqr_HashRegisterCallbacks() performs a known-answer test for BLAKE2b, SHA2, and SHA3 to make sure the specified implementation works as expected.

Changed features:

  • Tuned assembly language versions of some functions on supported processors. (ChaCha20 and SHA2-256 on x86-64 platforms.)

  • LMS now requires at least 64 bytes of digest for signing operations.

  • LMS implementation updated to version 7 of the IETF draft specification.

  • The I value ("identifier") in LMS parameters is now entirely internal, you don’t need to specify it when creating LMS parameter objects.

  • Samples re-organized and now build with single cmake instead of a shell script.

  • KDF APIs marked "Deprecated"; they’ll receive a "generic" KDF API (to allow streaming) in a future toolkit release.

Removed features:

  • McEliece QC-MDPC has been removed as an asymmetric encryption scheme.

  • The "BoringSSL" variant of NewHope has been removed, as it no longer exists in the wild.

  • The iqr_LMSGetRemainingSignatureCount() function has been removed.

Changes Since 1.1

  • NewHope’s iqr_NewHopeGetResponderPublicKeyAndSecret and LUKE’s iqr_LUKEGetResponderPublicKeyAndSecret now have proper camel case.

  • HMAC now responds properly to error conditions.

  • LMS samples updated to support Height 15 trees.

Changes Since 1.0

  • LMS APIs marked "Deprecated" as they’ll be changing due to the latest IETF draft.

  • Hash implementations now have initialize() and cleanup() methods.

  • MACs (HMAC and Poly1305) now use a generic API similar to Hashes.

  • LMS IETF parameters and XDR encodings have been removed; they belong in a higher-level library. Removed iqr_LMSCreateParamsIETF() and iqr_LMSGetIETFTypes().

  • iqr_LMSGetSignatureSize() was changed to iqr_LMSGetSignatureComponentSizes(), which is slightly different.

  • iqr_LMSSign() and iqr_LMSVerify() APIs changed to reflect the removal of XDR encoding.

  • LUKE and NewHope algorithms now have a simplified Responder API.

  • The RNG in iqr_Context has been removed, along with the iqr_RNGRegisterCallbacks() function. iqr_RNGCreate() now takes a callback structure directly.

  • FreeBSD (versions 10 and 11) is now a supported platform.

  • Windows is now a supported platform.

The ISARA Radiate Quantum-Safe Library is licensed for use:

Copyright © 2015-2020, ISARA Corporation, All Rights Reserved.

The code and other content set out herein is not in the public domain, is considered a trade secret and is confidential to ISARA Corporation. Use, reproduction or distribution, in whole or in part, of such code or other content is strictly prohibited except by express written permission of ISARA Corporation. Please contact ISARA Corporation at info@isara.com for more information.

Sample code (and only the sample code) is covered by the Apache 2.0 license:

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Trademarks

ISARA Radiate™ is a trademark of ISARA Corporation.

Patent Information

Portions of this software are covered by Japanese Patent 6,644,894.