OpenKMS 1.0.2
See the version list below for details.
dotnet add package OpenKMS --version 1.0.2
NuGet\Install-Package OpenKMS -Version 1.0.2
<PackageReference Include="OpenKMS" Version="1.0.2" />
paket add OpenKMS --version 1.0.2
#r "nuget: OpenKMS, 1.0.2"
// Install OpenKMS as a Cake Addin #addin nuget:?package=OpenKMS&version=1.0.2 // Install OpenKMS as a Cake Tool #tool nuget:?package=OpenKMS&version=1.0.2
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;
}
);
To derive a new encryption handler implementation, extend the EncryptionHandler<TOptions> and EncryptionHandlerOptions abstract classes.
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> ValidEncryptionAlgorithms
Dictionary<KeyType, int?[]> ValidKeyTypeSizes
EncryptionAlgorithm EncryptionAlgorithm
KeyType KeyType
int? 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
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net6.0
- Microsoft.Extensions.Options (>= 6.0.0)
- Microsoft.IdentityModel.Tokens (>= 6.22.0)
NuGet packages (4)
Showing the top 4 NuGet packages that depend on OpenKMS:
Package | Downloads |
---|---|
OpenKMS.Azure.KeyVault
OpenKMS Azure KeyVault encryption service provider |
|
OpenKMS.Aes
OpenKMS library for AES Encryption Algorithms |
|
OpenKMS.EntityFrameworkCore
Package Description |
|
OpenKMS.AWS.KeyManagementService
Package Description |
GitHub repositories
This package is not used by any popular GitHub repositories.