Skip to content

Getting started

Install

dotnet add package CryptoService.Sdk --version 0.0.41

The package targets net10.0 and has no dependency beyond the base class library. It is on NuGet from 0.0.40; the snippet names the version main prepares, so use the newest published one until it is out, or reference src/CryptoService.Sdk/CryptoService.Sdk.csproj from a clone.

A server

The SDK calls crypto-server; Development shows how to build and start the pinned one on loopback. The examples below read its address from CRYPTO_SERVICE_URL and its API key from CRYPTO_SERVICE_API_KEY.

The first call

using CryptoService.Sdk;

await using var client = new CryptoServiceClient(new CryptoServiceClientOptions
{
    BaseUrl = new Uri(Environment.GetEnvironmentVariable("CRYPTO_SERVICE_URL") ?? "http://127.0.0.1:3000"),
    ApiKey = Environment.GetEnvironmentVariable("CRYPTO_SERVICE_API_KEY"),
});

KeyPairResult recipient = await client.MlKemGenerateKeyPairAsync();
MlKemEncapsulateResult sender = await client.MlKemEncapsulateAsync(
    new MlKemEncapsulateRequest { PublicKey = recipient.PublicKey });
SharedSecretResult received = await client.MlKemDecapsulateAsync(
    new MlKemDecapsulateRequest { KeyId = recipient.KeyId, Ciphertext = sender.Ciphertext });

The secret key never leaves the server: the client holds a keyId.

With IHttpClientFactory

The client takes an HttpClient, so it registers as a typed client. Give the factory the SDK's handler so redirects stay refused:

services.AddSingleton(new CryptoServiceClientOptions { BaseUrl = new Uri("https://crypto.internal.example"), ApiKey = key });
services.AddHttpClient<CryptoServiceClient>()
    .ConfigurePrimaryHttpMessageHandler(CryptoServiceClient.CreateHandler);

IHttpClientFactory lives in Microsoft.Extensions.Http, a package of your application; the SDK does not depend on it.

Errors

try
{
    await client.SignAsync(new SignRequest { KeyId = "k_AAAAAAAAAAAAAAAAAAAAAA", Message = "x" });
}
catch (CryptoApiException error)
{
    // error.StatusCode == 404, error.Problem.Type == "urn:crypto-service:problem:key-not-found"
}
catch (CryptoTransportException error) when (error.TimedOut)
{
    // the attempt timed out, or the deadline passed
}

See ADR 0003 for the full model.