This library adoptsThe Bouncy Castle Cryptography Library For .NETto wan24-Crypto and extendsthe wan24-Crypto
library with these algorithms:
Algorithm | ID | Name |
---|---|---|
Asymmetric | ||
CRYSTALS-Kyber | 2 | CRYSTALSKYBER |
CRYSTALS-Dilithium | 3 | CRYSTALSDILITHIUM |
FALCON | 4 | FALCON |
SPHINCS+ | 5 | SPHINCSPLUS |
FrodoKEM | 6 | FRODOKEM |
NTRUEncrypt | 7 | NTRUENCRYPT |
Ed25519 | 8 | ED25519 |
Ed448 | 9 | ED448 |
X25519 | 10 | X25519 |
X448 | 11 | X448 |
XEd25519 | 12 | XED25519 |
XEd448 | 13 | XED448 |
Streamlined NTRU Prime | 14 | SNTRUP |
BIKE | 15 | BIKE |
HQC | 16 | HQC |
Picnic | 17 | PICNIC |
Symmetric | ||
ChaCha20 | 1 | CHACHA20 |
XSalsa20 | 2 | XSALSA20 |
AES-256-GCM AEAD (128 bit MAC) | 3 | AES256GCM |
Serpent 256 CBC (ISO10126 padding) | 5 | SERPENT256CBC |
Serpent 256 GCM AEAD (128 bit MAC) | 6 | SERPENT256GCM |
Twofish 256 CBC (ISO10126 padding) | 7 | TWOFISH256CBC |
Twofish 256 GCM AEAD (128 bit MAC) | 8 | TWOFISH256GCM |
Main goals of this extension library are to make wan24-Crypto
usable on allplatforms and extend its algorithms by PQC algorithms and other non-PQCalgorithms, which are not available from .NET, but implemented in the BouncyCastle library.
How to get it
This library is available asNuGet package.
Usage
In case you don't use the wan24-Core
bootstrapper logic, you need toinitialize the Bouncy Castle extension first, before you can use it:
wan24.Crypto.BC.Bootstrap.Boot();
This will register the algorithms to the wan24-Crypto
library.
wan24-Crypto
algorithm replacement
Some algorithms of the wan24-Crypto
library are not available on someplatforms, that's why they need to be replaced in order to be used:
wan24-Crypto | wan24-Crypto-BC |
---|---|
AsymmetricEcDiffieHellmanAlgorithm | AsymmetricBcEcDiffieHellmanAlgorithm |
AsymmetricEcDsaAlgorithm | AsymmetricBcEcDsaAlgorithm |
EncryptionAes256CbcAlgorithm | EncryptionBcAes256CbcAlgorithm |
HashShake128Algorithm | HashBcShake128Algorithm |
HashShake256Algorithm | HashBcShake256Algorithm |
HashSha3_256Algorithm | HashBcSha3_256Algorithm |
HashSha3_384Algorithm | HashBcSha3_384Algorithm |
HashSha3_512Algorithm | HashBcSha3_512Algorithm |
MacHmacSha3_256Algorithm | MacBcHmacSha3_256Algorithm |
MacHmacSha3_384Algorithm | MacBcHmacSha3_384Algorithm |
MacHmacSha3_512Algorithm | MacBcHmacSha3_512Algorithm |
To replace all of them:
BouncyCastle.ReplaceNetAlgorithms();
NOTE: The Shake128/256 replacements don't support variable output lengthand use the default output length of the wan24-Crypto
implementationsinstead. The NetShake128/256HashAlgorithmAdapter
can't be replaced for thisreason.
In order to override the .NET default SHA3 hash and HMAC algorithms, you cancall:
BouncyCastle.RegisterNetAlgorithms();
This will use Bouncy Castle SHA3 implementations for the .NET implemented SHA3hash algorithms:
Name | Type |
---|---|
SHA3-256 | HashBcSha3_256.SHA3_256 |
SHA3-384 | HashBcSha3_384.SHA3_384 |
SHA3-512 | HashBcSha3_512.SHA3_512 |
HMACSHA3-256 | MacBcHmacSha3_256.HMACSHA3_256 |
HMACSHA3-384 | MacBcHmacSha3_384.HMACSHA3_384 |
HMACSHA3-512 | MacBcHmacSha3_512.HMACSHA3_512 |
This step is required, if you want to ensure that whenever a .NET crypto typeor any 3rd party crypto type requests a SHA3 hash or HMAC instance using thestatic HashAlgorithm.Create("NAME")
or KeyedHashAlgorithm.Create("NAME")
methods.
Use as default algorithms
To set Bouncy Castle defaults as wan24-Crypto
defaults:
BouncyCastle.SetDefaults();
Per default the current wan24-Crypto
default will be set as counteralgorithms to HybridAlgorithmHelper
.
Current Bouncy Castle default algorithms are:
Usage | Algorithm |
---|---|
Key exchange | NTRUEncrypt |
Signature | CRYSTALS-Dilithium |
Encryption | Serpent 256 bit CBC |
PAKE encryption | Serpent 256 bit GCM |
Post quantum safety
These asymmetric algorithms are designed for post quantum cryptography:
- CRYSTALS-Kyber (key exchange)
- CRYSTALS-Dilithium (signature)
- FALCON (signature)
- SPHINCS+ (signature)
- FrodoKEM (key exchange)
- NTRUEncrypt (key exchange)
- Streamlined NTRU Prime (key exchange)
- BIKE (key exchange)
- HQC (key exchange)
- Picnic (signature)
Normally you want to use them in hybrid mode and use classical algorithms ofthe wan24-Crypto
package as counter algorithm. To do this per default:
// Enable the post quantum algorithms as (counter-)defaultsCryptoHelper.ForcePostQuantumSafety();
This will use these algorithms as (counter) algorithms for asymmetriccryptography, in case you didn't define other post quantum algorithms already:
- NTRUEncrypt (key exchange)
- CRYSTALS-Dilithium (signature)
The counter algorithm will come in effect, if you use asymmetric keys forencryption:
// Create options having a counter private keyCryptoOptions options = EncryptionHelper.GetDefaultOptions();options.SetCounterPrivateKey(yourNtruPrivateKey);// Encrypt using the options and your normal private keybyte[] cipherData = rawData.Encrypt(yourNormalPrivateKey, options);rawData = cipherData.Decrypt(yourNormalPrivateKey, options);
And for signature:
// Create options having a counter private keyCryptoOptions options = AsymmetricHelper.GetDefaultSignatureOptions();options.SetCounterPrivateKey(yourDilithiumPrivateKey);// Sign using the options and your normal private keySignatureContainer signature = dataToSign.Sign(yourNormalPrivateKey, options: options);
Algorithm parameters used
Algorithm | Parameters |
---|---|
CRYSTALS-Kyber, CRYSTALS-Dilithium | non-AES |
SPHINCS+ | Haraka simple* |
FrodoKEM | AES* |
Picnic | Full |
NOTE: CRYSTALS-Kyber and CRYSTALS-Dilithium AES parameters and SPHINCS+robust parameters are deprecated! SPHINCS+ Haraka parameters are removed fromthe FIPS standard, so wan24-Crypto-BC
will switch to Shake parametersinstead. Also the FrodoKEM Shake parameters will be used in the next majorrelease, which will require to renew existing keys, which use the AESparameters from the current version of this library.
WARNING The PQC standards are in development at the moment, so futureincompatible changes are very likely and will be handled in a new majorrelease of this library.
Random data provider
The RandomDataProvider
is a RandomDataGenerator
which provides added seeddata to OnSeed(Async)
attached event handlers. It uses the ChaCha20Rng
incombination with RND
of wan24-Crypto
to produce cryptographic securerandom data (CSRNG). An instance may be set as RND.Generator
singletonrandom data generator for all consumers (like key generators etc.).
RandomDataProvider
can be customized by extending the type. Pregnant methodsare virtual and can be overridden. Since the type is a HostedServiceBase
, itcan be used in modern .NET app environments. And since it implements theIRandomGenerator
interface of Bouncy Castle, it can be used as secure randomdata source for all Bouncy Castle algorithms (like key generators) also.
By calling the CreateFork(Async)
method, you can create an attachedinstance, which will be initialized with a random seed generated by the parentinstance and consumes the provided seeds from the parent automatically.
NOTE: Don't forget to dispose an unused RandomDataProvider
instance!
CAUTION: There is a patent (US10402172B1) which comes into play, if youplan to create a Random or Entropy as a Service (R/EaaS) application,especially when using QRNG entropy. Read that document carefully to avoiddisappointments.
Stream cipher RNG
The StreamCipherRng
uses any stream cipher to encrypt the generated randombytes of an underlaying PRNG using a random key. The result is a CSRNG. Thesestream ciphers are available with wan24-Crypto-BC
, but you could use anyother stream cipher (but not AEAD implementations!) also:
Stream cipher | RNG |
---|---|
ChaCha20 | ChaCha20Rng |
XSalsa20 | XSalsa20Rng |
If you didn't specify an underlaying PRNG, Bouncy Castle'sVmpcRandomGenerator
will be used and seeded using 256 bytes from RND
.
The final CSRNG implements IRandomGenerator
for use with Bouncy Castle, andalso ISeedableRng
for use with RND
(as seed consumer, for example).
NOTE: A StreamCipherRng
needs to be disposed after use!
You can use the resulting CSRNG as default RNG for RND
:
ChaCha20Rng csrng = new();// Enable automatic seedingRND.SeedConsumer = csrng;// Use as default CSRNGRND.FillBytes = csrng.GetBytes;RND.FillBytesAsync = csrng.GetBytesAsync;
NOTE: When setting the RND.FillBytes(Async)
callbacks, they may not beused, if /dev/random
was preferred. To disable /dev/random
, setRND.UseDevRandom
and RND.RequireDevRandom
to false
also.
NOTE: Currently only stream ciphers are supported, because the cipher RNGimplementation doesn't buffer pre-generated random data.
X/Ed448-Goldilocks and X/Ed25519
Just a short note on Curve448: Private and public keys have a different keysize: The private key has 456 bit, while the public key has 448 bit. Both keysizes are supported for key generation and result in the same key sizes forthe private (456 bit) and the public (448 bit) key. The private key of a keypair will always identify with 456 bit, while the public key will alwaysidentify with 448 bit - no matter which key size was chosen for key pairgeneration.
The Ed448 signature is context based, but currently only an empty byte arrayis being used as context data. Instead of a context you should use the purposefree text, which can be given to the signature methods of wan24-Crypto
.
XEd25519 and XEd448 convert the private Ed25519/448 key to X25519/448 for keyexchange. The private key stores only the Ed25519/448 information, while thepublic key stores both, the Ed25519/448 and the X25519/448 informations (andtherefor require a custom serialization format). You can derive Ed25519/448private keys from a XEd25519/448 private key, and XEd25519/448 private keysfrom a Ed25519/448 private key.
Using the ToX25519/448PrivateKey
extension methods for theEd25519/448PrivateKeyParameters
a conversion to X25519/448 is possible now(if you want to use the Bouncy Castle API directly).
WARNING: Different Ed25519/448 keys may convert to equal X25519/448 keys,so be aware of possible collisions!