Recursive AI
onecryptoDocs

Getting started with OneCrypto

OneCrypto 0.1.0-preview.1Markdown

All onecrypto docs

Install OneCrypto 0.1.0-preview.1 for .NET 10, load a key and certificate file with one call, and sign and verify with the key. OneCrypto is cryptography for .NET (not cryptocurrency), written from the specifications on the base class library alone.

Before you use it

  • Not audited. This library has not been independently audited. It is a preview: the API can change between previews.
  • Path validation is a preview. The RFC 5280 certificate path validator “has had an internal review; its follow-ups are still landing, so don’t rely on it for trust decisions yet.”
  • Constant time, where stated. Timing tests cover the secret data of specific primitives; no constant-time claim is made for key handling yet, nor for Argon2id, Argon2d, scrypt or bcrypt-pbkdf. The exact list: Conformance.

Install

The package targets net10.0, so you need the .NET 10 SDK, and dotnet add package needs --prerelease or the exact version.

Terminal
dotnet new console -o OneCryptoStart
cd OneCryptoStart
dotnet add package RecursiveAI.OneCrypto --version 0.1.0-preview.1

One package is on NuGet: RecursiveAI.OneCrypto. It holds ASN.1 and PEM, X.509 certificates, requests, CRLs and OCSP, CMS, RFC 3161 time-stamps, PKCS#8, PKCS#12 and OpenSSH keys, Crypto.Load, CryptoPolicy, the key interfaces, the certificate authority, time-stamp authority and OCSP responder handlers, and the primitives .NET lacks: Ed25519, Ed448, X25519, X448, OCB, EAX, AES key wrap, Argon2, scrypt, bcrypt-pbkdf and Camellia. It depends on nothing but .NET. OpenPGP, AdES and PAdES signatures, age and minisign files, SSH signatures, PKCS#11 and cloud keys are separate packages that are planned, not published.

A first program

Make a certificate and key with OpenSSL and pack them into a .pfx, as a server or a signing service would have:

Terminal
openssl req -x509 -newkey ed25519 -nodes -days 30 -subj "/CN=demo" \
  -keyout key.pem -out cert.pem
openssl pkcs12 -export -inkey key.pem -in cert.pem -passout pass:demo -out demo.pfx

Put this in Program.cs and run dotnet run:

C#
using System.Text;
using RecursiveAI.OneCrypto;
using RecursiveAI.OneCrypto.Keys;
 
// One call for any key or certificate file: PEM, DER, PKCS#8, PKCS#12, OpenSSH
using LoadedItems file = Crypto.Load("demo.pfx", _ => "demo");
Certificate cert = file.Certificates[0];
LoadedPrivateKey key = file.PrivateKeys[0];
Console.WriteLine($"{file.Format}: {cert.Subject}, key {key.Algorithm}");
 
// Sign with the private key, verify with the certificate's public key
byte[] data = Encoding.UTF8.GetBytes("hello");
ISigningKey signer = key.Signing!;
byte[] signature = signer.Sign(data, signer.DefaultSpec);
SignatureSpec spec = signer.DefaultSpec;
SignatureVerification check = spec.Verify(cert.PublicKey, data, signature);
Console.WriteLine($"{spec}, {signature.Length}-byte signature: {check.Status}");
Text
PKCS#12: CN=demo, key Ed25519
Ed25519, 64-byte signature: Valid

.NET can’t load an Ed25519 key or certificate at all; OneCrypto signs with it here. Crypto.Load decides the format from the content, asks the callback for a password only when something is encrypted, and returns typed lists: Certificates, PrivateKeys, PublicKeys, Crls, SshPublicKeys and more. Dispose the result to zero the private keys.

Where things are

  • Primitives are in RecursiveAI.OneCrypto.Primitives: Ed25519, X25519, Argon2, Scrypt and the rest, as span one-shots and key objects.
  • Formats are in the root namespace and RecursiveAI.OneCrypto.Pkcs: Certificate, SignedData, EnvelopedData, AuthEnvelopedData, PrivateKeyInfo, Pkcs12File.
  • Keys are in RecursiveAI.OneCrypto.Keys: ISigningKey, IDecryptionKey, IAgreementKey, SignatureSpec, PrivateKey.
  • Which algorithms work where: .NET’s own cryptography is used first; the library’s own code fills only the gaps listed in Platform availability. Anything else throws AlgorithmNotSupportedException naming the algorithm and platform.

Next

  • Cookbook: Ed25519, X25519, Argon2, PEM, PKCS#12, SSH keys and CMS, each a complete program checked against OpenSSL or ssh-keygen.
  • Conformance: what is tested, against what, the speed table with its three exceptions, and the constant-time evidence.
  • Changelog.