{"id":26777228,"url":"https://github.com/timothymeadows/argon2.netcore","last_synced_at":"2026-02-24T00:08:54.092Z","repository":{"id":96219374,"uuid":"282560228","full_name":"TimothyMeadows/Argon2.NetCore","owner":"TimothyMeadows","description":"Implementation of Argon2 key derivation function designed by Alex Biryukov, Daniel Dinu, and Dmitry Khovratovich. Optimized for PinnedMemory and .NET Core.","archived":false,"fork":false,"pushed_at":"2020-08-13T20:11:34.000Z","size":15,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-01T05:34:39.772Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimothyMeadows.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-07-26T02:23:57.000Z","updated_at":"2022-04-14T13:50:26.000Z","dependencies_parsed_at":"2024-05-04T23:35:31.536Z","dependency_job_id":null,"html_url":"https://github.com/TimothyMeadows/Argon2.NetCore","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/TimothyMeadows/Argon2.NetCore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyMeadows%2FArgon2.NetCore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyMeadows%2FArgon2.NetCore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyMeadows%2FArgon2.NetCore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyMeadows%2FArgon2.NetCore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimothyMeadows","download_url":"https://codeload.github.com/TimothyMeadows/Argon2.NetCore/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyMeadows%2FArgon2.NetCore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273094228,"owners_count":25044440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-29T04:49:16.361Z","updated_at":"2026-02-24T00:08:54.085Z","avatar_url":"https://github.com/TimothyMeadows.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Argon2.NetCore\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![NuGet](https://img.shields.io/nuget/v/Argon2.NetCore.svg)](https://www.nuget.org/packages/Argon2.NetCore/)\n\n`Argon2.NetCore` is a .NET implementation of the Argon2 password/key derivation function (PHC winner) by Alex Biryukov, Daniel Dinu, and Dmitry Khovratovich. This package is optimized to work with [`PinnedMemory`](https://github.com/TimothyMeadows/PinnedMemory) so sensitive material can stay in pinned buffers for better memory-handling control.\n\n---\n\n## Installation\n\n```bash\ndotnet add package Argon2.NetCore\n```\n\n```powershell\nInstall-Package Argon2.NetCore\n```\n\nNuGet package page:\nhttps://www.nuget.org/packages/Argon2.NetCore/\n\n---\n\n## Quick start\n\n```csharp\nusing System;\nusing System.Security.Cryptography;\nusing Argon2.NetCore;\nusing PinnedMemory;\n\nvar salt = new byte[16];\nvar secret = new byte[32];\nRandomNumberGenerator.Fill(salt);\nRandomNumberGenerator.Fill(secret);\n\nusing var keyPin = new PinnedMemory\u003cbyte\u003e(secret, false);\nusing var argon2 = new Argon2(keyPin, salt)\n{\n    // Argon2i (IndependentAddressing) by default.\n    // Set DependentAddressing for Argon2d.\n    Addressing = Argon2.AddressType.IndependentAddressing,\n\n    HashLength = 32,\n    MemoryCost = 65536, // 64 MiB (value is KiB)\n    TimeCost = 3,\n    Lanes = 4,\n    Threads = 2\n};\n\n// Optional: include additional context bytes in the hash input.\nvar message = new byte[] { 0x63, 0x61, 0x77 }; // \"caw\"\nargon2.UpdateBlock(message, 0, message.Length);\n\nusing var hash = new PinnedMemory\u003cbyte\u003e(new byte[argon2.GetLength()]);\nargon2.DoFinal(hash, 0);\n\nConsole.WriteLine(Convert.ToHexString(hash.ToArray()));\n```\n\nAdditional sample code is available in `Argon2.NetCore.Examples/Program.cs`.\n\n---\n\n## Constructor\n\n```csharp\nArgon2(PinnedMemory\u003cbyte\u003e key, byte[] salt, byte[] associatedData = null)\n```\n\n### Parameters\n\n- `key`: secret key / password bytes (required).\n- `salt`: unique random salt bytes (required, minimum 8 bytes).\n- `associatedData`: optional associated bytes mixed into derivation.\n\n---\n\n## Configuration options\n\nSet these on the `Argon2` instance before calling `DoFinal`.\n\n- `Addressing`\n  - `IndependentAddressing` (`Argon2i` behavior; default)\n  - `DependentAddressing` (`Argon2d` behavior)\n- `HashLength` (`int`)\n  - Number of output bytes.\n  - Minimum value: `4`.\n- `MemoryCost` (`int`)\n  - Memory cost in **KiB**.\n  - Example: `65536` = 64 MiB.\n- `TimeCost` (`int`)\n  - Number of iterations/passes over memory.\n- `Lanes` (`int`)\n  - Number of lanes (parallelism level).\n- `Threads` (`int`)\n  - Number of worker threads used by the implementation.\n\n---\n\n## API reference\n\n- `int GetLength()`\n  - Returns currently configured output length.\n- `void Update(byte input)`\n  - Appends one byte to the message input.\n- `void UpdateBlock(byte[] input, int inOff, int len)`\n  - Appends part of a byte array to the message input.\n- `void UpdateBlock(PinnedMemory\u003cbyte\u003e input, int inOff, int len)`\n  - Appends a pinned byte buffer to the message input.\n- `void DoFinal(PinnedMemory\u003cbyte\u003e output, int outOff)`\n  - Computes derived output and writes to the provided pinned output buffer.\n- `void Reset()`\n  - Resets internal state for another run while retaining key/salt.\n- `void Dispose()`\n  - Clears key/salt state and frees resources.\n\n---\n\n## Best practices\n\n### 1. Always use a unique, random salt\n\n- Use at least 16 bytes of cryptographically secure randomness.\n- Never reuse a salt for different secrets when avoiding correlation matters.\n\n### 2. Tune cost parameters for your environment\n\n- Start from:\n  - `MemoryCost`: 64 MiB to 256 MiB (`65536` to `262144` KiB)\n  - `TimeCost`: `2` to `4`\n  - `Lanes`: number of physical cores (or a smaller operational cap)\n- Benchmark in production-like conditions and target a derivation time that balances security and user latency.\n\n### 3. Prefer Argon2i-style addressing when side-channel concerns matter\n\n- `IndependentAddressing` (default) maps to Argon2i-style memory addressing and is generally safer for password hashing scenarios.\n- Use `DependentAddressing` only when you specifically need Argon2d-style behavior.\n\n### 4. Handle secrets as pinned memory where possible\n\n- Keep password/key data in `PinnedMemory\u003cbyte\u003e` while hashing.\n- Dispose of `Argon2` and pinned buffers promptly to reduce lifetime of sensitive data.\n\n### 5. Size output intentionally\n\n- 32 bytes is a common default for key derivation.\n- Use larger output (for example 64 bytes) only when your protocol needs it.\n\n### 6. Store metadata alongside derived values\n\nWhen persisting hashes, store:\n\n- Algorithm identifier (`Argon2` variant/addressing mode)\n- `MemoryCost`, `TimeCost`, `Lanes`, `HashLength`\n- Salt\n- Hash output\n\nThis ensures future verification and migration remain possible.\n\n### 7. Validate operational limits\n\n- Very high memory/thread settings can exhaust container/host resources.\n- Use load testing to verify worst-case concurrency and avoid denial-of-service through excessive KDF pressure.\n\n---\n\n## Notes\n\n- `DoFinal` requires an output buffer large enough for `HashLength` at the given offset.\n- `salt` must be at least 8 bytes.\n- Parameter validation throws exceptions for invalid values (e.g., non-positive costs/lanes/threads).\n\n---\n\n\n## SIMD acceleration\n\n`Argon2.NetCore` now includes SIMD-aware optimizations in the Argon2 block/memory hot paths while preserving compatibility and deterministic output:\n\n- **Vectorized block XOR/copy-XOR paths** in the internal `Block` implementation (`Copy`, `Xor`, `CopyXor`) using `System.Numerics.Vector\u003culong\u003e` where hardware acceleration is available.\n- **Faster `FillBlock` / `FillBlockWithXor` setup** by using a single `CopyXor` operation for `refBlock ^ prevBlock` instead of separate copy and XOR passes.\n- **Optimized `LoadBlock` / `StoreBlock` transforms** on little-endian runtimes using `MemoryMarshal.Cast\u003cbyte, ulong\u003e` bulk conversion with endian-safe fallback logic.\n- **Scalar fallback behavior remains intact**, so functionality is preserved on platforms without SIMD acceleration.\n\nThese changes are designed to mirror the performance-oriented approach used in `Blake2b.NetCore` while keeping Argon2 algorithm behavior unchanged.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimothymeadows%2Fargon2.netcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimothymeadows%2Fargon2.netcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimothymeadows%2Fargon2.netcore/lists"}