CryptoIds 0.3.3-prerelease.2

This is a prerelease version of CryptoIds.
dotnet add package CryptoIds --version 0.3.3-prerelease.2                
NuGet\Install-Package CryptoIds -Version 0.3.3-prerelease.2                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CryptoIds" Version="0.3.3-prerelease.2" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add CryptoIds --version 0.3.3-prerelease.2                
#r "nuget: CryptoIds, 0.3.3-prerelease.2"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install CryptoIds as a Cake Addin
#addin nuget:?package=CryptoIds&version=0.3.3-prerelease.2&prerelease

// Install CryptoIds as a Cake Tool
#tool nuget:?package=CryptoIds&version=0.3.3-prerelease.2&prerelease                

CryptoIds

Raison d'etre

Exposing database IDs in a REST API response is generally considered a bad practice. Best practices in API design and security suggest avoiding direct exposure of raw database IDs. Sometimes UUIDs are used instead of database IDs, but they are not always a good solution. UUIDs are hard to index and are not sortable.

Overview

CryptoIds is a C# library designed for ASP.NET Core applications to securely and efficiently obfuscate database IDs. This library is essential for enhancing the security and integrity of APIs by preventing ID enumeration attacks and obscuring the structure of the database.

Features

  • Type Flexibility: Supports any unmanaged type for ID signing and encoding in Base64.

    For more information about unmanaged types, see this article.

    • sbyte, byte, short, ushort, int, uint, long, ulong, nint, nuint, char, float, double, decimal, or bool
    • Any enum type
    • Any pointer type
    • Any user-defined struct type that contains fields of unmanaged types only, such as tuples.
  • Optional Encryption: Provides the option to encrypt IDs. Encrypted IDs appear random, enhancing security.

  • Sortable IDs: When not encrypted, the library ensures that the resulting strings are sortable, maintaining order consistency.

  • ASP.NET Core Integration: Seamless integration with ASP.NET Core for obfuscating IDs in JSON responses and route parameters.

  • Swagger Support: Integrates with Swagger for API documentation, ensuring that ID obfuscation is consistently represented.

  • Multiple Hash Functions: Supports various hash functions for signatures, offering a balance between cryptographic strength and signature length.

  • User-Specific Encryption: Allows encryption based on specific user GUIDs or a shared key, providing flexibility in access control.

Getting Started

Installation

Install the CryptoIds NuGet package from the package manager console:

PM> Install-Package CryptoIds

or using the .NET Core CLI:

> dotnet add package CryptoIds

Usage

1. Configure CryptoIds

CryptoIdContext.Default = CryptoIdContext.CreateFromPassword("Pa55W0rd!", SignatureProviderType.Md5, encrypt: true);

or if you are using ASP.NET Core with Swagger, you can use the following extension method:


builder.Services.AddCryptoIdsWithSwagger("Pa55W0rd!", SignatureProviderType.Md5, encrypt: true);

2. Use it in your controllers:

public class WeatherForecast
{
    public CryptoId<int> Id { get; set; }
    public DateTime Date { get; set; }
    public int TemperatureC { get; set; }
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    public string Summary { get; set; }
}

public Task<> GetWeatherForecastAsync(int id) 
{
    WeatherForecast result = new WeatherForecast();
    
    // ...
    
    result.Id = id;
    return result;
}


[HttpGet("{id}")]
public async Task<ActionResult<WeatherForecast>> Get(CryptoId<int> id)
{
    var weatherForecast = await _weatherForecastService.GetWeatherForecastAsync(id);

    if (weatherForecast == null)
    {
        return NotFound();
    }

    return weatherForecast;
}

3. Enjoy the benefits of obfuscated IDs:

{
    "id": "AqQAAgAAABQAAQAAAAEAAQAAAAI",
    "date": "2021-01-01T00:00:00.0000000Z",
    "temperatureC": -17,
    "temperatureF": 1,
    "summary": "Freezing"
}
    

To summarize, the library lets you replace your Ids of type int with CryptoId<int> and the library will take care of the rest. int and CryptoId<int> are implicitly convertible to each other, so you can use them interchangeably, as long as CryptoIdContext.Default is set.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.