OpenKMS v1.0.2 — nugetz
pkg
basistheory/ OpenKMS v1.0.2 .NET 6.0
OpenKMS SDK
Get Started dotnet CLI PackageReference Package Manager
$ dotnet add package OpenKMSReadme Open KMS SDK
The OpenKMS .NET SDK for .NET 6+.
Installation
Using the .NET Core command-line interface (CLI) tools :
dotnet add package OpenKMS
Using the NuGet Command Line Interface (CLI) :
nuget install OpenKMS
Using the Package Manager Console :
Install-Package OpenKMS
Documentation
OpenKMS is an encryption abstraction based on the Json Web Encryption (JWE) ,
Json Web Algorithm (JWA) , and Json Web Key (JWK) specifications.
The IEncryptionService interface exposes methods for encrypt and decrypt operations.
public interface IEncryptionService
{
Task<JsonWebEncryption> EncryptAsync(byte[] plaintext, string? scheme, CancellationToken cancellationToken = default);
Task<JsonWebEncryption> EncryptAsync(string plaintext, string? scheme, CancellationToken cancellationToken = default);
Task<byte[]> DecryptAsync(JsonWebEncryption encryption, CancellationToken cancellationToken = default);
Task<string> DecryptStringAsync(JsonWebEncryption encryption, CancellationToken cancellationToken = default);
}
Encryption schemes are used to register encryption handlers and pre-configure options (e.g. KeyType, KeySize, Algorithm) used when calling
EncryptAsync
// IServiceCollection services;
services.AddEncryption(o =>
{
o.DefaultScheme = "default";
}).AddScheme<AesEncryptionOptions, AesEncryptionHandler, AzureKeyVaultEncryptionOptions, AzureKeyVaultEncryptionHandler>("default",
contentEncryptionOptions => {
contentEncryptionOptions.EncryptionAlgorithm = EncryptionAlgorithm.A256CBC_HS512;
contentEncryptionOptions.KeySize = 256;
contentEncryptionOptions.KeyType = KeyType.OCT;
},
keyEncrptionOptions => {
keyEncrptionOptions.KeySize = 4096;
keyEncrptionOptions.KeyType = KeyType.RSA;
keyEncrptionOptions.KeyName = "<key_name>";
keyEncrptionOptions.EncryptionAlgorithm = EncryptionAlgorithm.RSA_OAEP;
}
);
Provide handler implementations for:
Task<EncryptResult> EncryptAsync(byte[], byte[]?, CancellationToken)Task<byte[]> DecryptAsync(JsonWebKey, byte[], byte[]?, byte[]?, byte[]?, CancellationToken)bool CanDecrypt(JsonWebKey) Provide options implementations for:
IList<EncryptionAlgorithm> ValidEncryptionAlgorithmsDictionary<KeyType, int?[]> ValidKeyTypeSizesEncryptionAlgorithm EncryptionAlgorithmKeyType KeyTypeint? KeySize
Usage
Dependency Injection To configure an instance of IEncryptionService that can be used throughout your project, call AddEncryption when registering services:
// program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddEncryption()
.AddScheme<TContentEncryptionOptions, TContentHander, TKeyEncryptionOptions, TKeyHandler>("<scheme_name>",
contentEncrptionOptions => { ... },
keyEncryptionOptions => { ... }
); // calls can be chained to .AddScheme<> to register more encryption schemes!
To inject an instance of IEncryptionHandler into your class for data encryption and/or decryption,
add a constructor dependency for IEncryptionService.
public class MyAwesomeService() {
private readonly IEncryptionService _encryptionService;
private readonly IPersonRepository _repository;
public MyAwesomeService(IEncryptionService encryptionService, IPersonRepository repository) {
_encryptionService = encryptionService;
_repository = repository;
}
public async Task SavePerson(Person person, CancellationToken cancellationToken = default) {
JsonWebEncryption encryptedName = await _encryptionService.EncryptAsync(
person.Name,
"<scheme_name>",
cancellationToken);
person.Name = null;
person.NameEncrypted = encryptedName.ToCompactSerializationFormat();
await _repository.SavePersonAsync(person, cancellationToken);
}
public async Task<Person> GetPersonById(string personId, CancellationToken cancellationToken = default) {
var foundPerson = await _repository.GetPersonAsync(personId, cancellationToken);
JsonWebEncryption encryptedName = JsonWebEncryption.FromCompactSerializationFormat(person.NameEncrypted);
var decryptedName = await _encryptionService.DecryptAsync(encryptedName, cancellationToken);
person.Name = Encoding.UTF8.GetString(decryptedName);
person.NameEncrypted = null;
return person;
}
}
Development The provided scripts with the SDK will check for all dependencies, start docker, build the solution, and run all tests.
Dependencies
Build the SDK and run Tests Run the following command from the root of the project:
make verify
