NaCl.Core

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 82)

🔑 NaCl.Core, a cryptography library for .NET

NaCl.Core Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# NaCl.Core, a cryptography library for .NET

[![Build Status](https://dev.azure.com/idaviddesmet/NaCl.Core/_apis/build/status/NaCl.Core-CI?branchName=master)](https://dev.azure.com/idaviddesmet/NaCl.Core/_build/latest?definitionId=3&branchName=master)
[![CI](https://github.com/daviddesmet/NaCl.Core/actions/workflows/ci.yml/badge.svg)](https://github.com/daviddesmet/NaCl.Core/actions/workflows/ci.yml)
[![Build status](https://ci.appveyor.com/api/projects/status/2k3cxt2e1r2jyinx?svg=true)](https://ci.appveyor.com/project/idaviddesmet/nacl-core)
[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/daviddesmet/NaCl.Core/issues)

## Introduction

**NaCl.Core** is a managed-only cryptography library for [.NET](https://dot.net) which provides modern cryptographic _primitives_.

#### Currently supported:

| Crypto | Description |
|--------|-------------|
| **Salsa20** | A high-speed stream cipher part of the family of 256-bit stream ciphers designed in 2005 and submitted to [eSTREAM](https://www.ecrypt.eu.org/stream/salsa20pf.html), the ECRYPT Stream Cipher Project |
| **ChaCha20** | A high-speed stream cipher based on Salsa20 |
| **XChaCha20** | Based on ChaCha20 IETF with extended nonce (192-bit instead of 96-bit) |
| **Poly1305** | A state-of-the-art secret-key message-authentication code (MAC) based on [RFC8439](https://tools.ietf.org/html/rfc8439) |
| **ChaCha20Poly1305** | An Authenticated Encryption with Associated Data (AEAD) algorithm; IETF variant as defined in [RFC8439](https://tools.ietf.org/html/rfc8439) and in its predecessor [RFC7539](https://tools.ietf.org/html/rfc7539) |
| **XChaCha20Poly1305** | A variant of ChaCha20-Poly1305 that utilizes the XChaCha20 construction in place of ChaCha20; as defined in the [RFC Draft](https://tools.ietf.org/html/draft-arciszewski-xchacha-03) |

## Installation

[![NuGet Version](https://img.shields.io/nuget/v/NaCl.Core)](https://www.nuget.org/packages/NaCl.Core/)
[![CI NuGet](https://img.shields.io/badge/nuget-CI%20builds-4da2db?logo=azure-devops)](https://dev.azure.com/idaviddesmet/NaCl.Core/_packaging?_a=feed&feed=NaCl.Core-CI)

Install the NaCl.Core NuGet package from the .NET CLI using:
```
dotnet add package NaCl.Core
```

or from the NuGet package manager:
```
Install-Package NaCl.Core
```

Or alternatively, you can add the NaCl.Core package from within Visual Studio's NuGet package manager.

Daily NuGet builds of the project are also available in the [Azure Artifacts](https://dev.azure.com/idaviddesmet/NaCl.Core/_packaging?_a=feed&feed=NaCl.Core-CI) feed:

> [https://pkgs.dev.azure.com/idaviddesmet/NaCl.Core/_packaging/NaCl.Core-CI/nuget/v3/index.json](https://pkgs.dev.azure.com/idaviddesmet/NaCl.Core/_packaging/NaCl.Core-CI/nuget/v3/index.json)

## Usage

[![](https://img.shields.io/nuget/dt/NaCl.Core.svg)](https://www.nuget.org/packages/NaCl.Core/)

#### Symmetric Key Encryption

```csharp
// Create the primitive (implements IDisposable for secure key cleanup)
using var aead = new ChaCha20Poly1305(key);

// Use the primitive to encrypt a plaintext
aead.Encrypt(nonce, plaintext, ciphertext, tag, aad);

// ... or to decrypt a ciphertext
aead.Decrypt(nonce, ciphertext, tag, plaintext, aad);
```

> **Note:** All cipher classes (`ChaCha20`, `XChaCha20`, `Salsa20`, `XSalsa20`, `ChaCha20Poly1305`, `XChaCha20Poly1305`) implement `IDisposable`. Call `Dispose()` or use `using` statements to securely zero the key from memory when done.

#### MAC (Message Authentication Code)

```csharp
// Use the primitive to compute a tag
Poly1305.ComputeMac(key, data, tag);

// ... or to verify a tag
Poly1305.VerifyMac(key, data, tag);
```

## Test Coverage

[![codecov](https://codecov.io/gh/daviddesmet/NaCl.Core/branch/master/graph/badge.svg?token=evqDLCtC1K)](https://codecov.io/gh/daviddesmet/NaCl.Core)
[![Azure DevOps tests](https://img.shields.io/azure-devops/tests/idaviddesmet/NaCl.Core/3)](https://dev.azure.com/idaviddesmet/NaCl.Core/_build/latest?definitionId=3)
[![Azure DevOps coverage](https://img.shields.io/azure-devops/coverage/idaviddesmet/NaCl.Core/3)](https://dev.azure.com/idaviddesmet/NaCl.Core/_build/latest?definitionId=3)

- Includes the mandatory RFC [test vectors](https://github.com/daviddesmet/NaCl.Core/tree/master/test/NaCl.Core.Tests).
- [Project Wycheproof](https://github.com/google/wycheproof) by members of Google Security Team, for testing against known attacks (when applicable).

## Performance

Refer to the [benchmarks](https://github.com/daviddesmet/NaCl.Core/tree/master/test/NaCl.Core.Benchmarks) for performance numbers.

Run the benchmarks using:
```bash
dotnet run -c Release
```

```bash
dotnet run -c Release --filter "*ChaCha20IntrinsicsBenchmark*"
```

## Dependency Lock Files

The repository uses [NuGet lock files](https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#locking-dependencies) (`packages.lock.json`, committed per project) to pin the full dependency graph, including transitive packages. CI restores with locked mode enabled, so a build fails if the resolved packages differ from the lock files — protecting against floating transitive versions and dependency-confusion attacks.

Upgrading packages therefore changes slightly:

- Edit the package version in the `.csproj` (or let Dependabot do it), then run `dotnet restore --force-evaluate` from the repository root and commit the updated `packages.lock.json` files together with the `.csproj` change.
- Dependabot PRs update the lock files automatically.
- A plain `dotnet restore` locally never floats versions; it follows the lock files. If it reports `NU1004`, the lock files are out of date — run `dotnet restore --force-evaluate`.

## Learn More

[![License](https://img.shields.io/github/license/daviddesmet/NaCl.Core.svg)](https://github.com/daviddesmet/NaCl.Core/blob/master/LICENSE)

- [ChaCha, a variant of Salsa20](http://cr.yp.to/chacha/chacha-20080128.pdf) by Daniel J. Bernstein.
- [The Poly1305-AES message-authentication code](http://cr.yp.to/mac/poly1305-20050329.pdf) by Daniel J. Bernstein.
- [ChaCha20 and Poly1305 for IETF Protocols](https://tools.ietf.org/html/rfc8439) RFC.
- [Salsa20](https://cr.yp.to/snuffle.html), also known as Snuffle 2005, uses the [Salsa20 core](https://cr.yp.to/salsa20.html) to encrypt data.
- [XSalsa20](https://cr.yp.to/snuffle/xsalsa-20110204.pdf), an extended-nonce Salsa20 variant used in [NaCl](https://nacl.cr.yp.to).
- [XChaCha20-Poly1305](https://tools.ietf.org/html/draft-arciszewski-xchacha-02), an extended-nonce ChaCha20-Poly1305 IETF variant.

NaCl.Core

NaCl.Core Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

NaCl.Core

NaCl.Core Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README