Skip to content

Commit 81ef8c2

Browse files
dorsseldorssel
committed
Finish documentation
+semver: major
1 parent 706d1ba commit 81ef8c2

File tree

5 files changed

+73
-48
lines changed

5 files changed

+73
-48
lines changed

‎Directory.Build.props‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,9 @@ SPDX-License-Identifier: MIT
4848
<!-- NuGet metadata -->
4949
<Title>$(Product)</Title>
5050
<Authors>$(Company)</Authors>
51-
<Description>Provides types for additional cryptographic algorithms: AES-CTR, AES-CMAC, and SIV-AES.</Description>
51+
<Description>Provides types for additional cryptographic algorithms: AES-CTR, AES-CMAC, SIV-AES, AES-CMAC-PRF-128, and PBKDF-AES-CMAC-PRF-128.</Description>
52+
<PackageProjectUrl>https://dorssel.github.io/dotnet-aes-extra/</PackageProjectUrl>
53+
<PackageTags>cryptography aes-ctr aes-cmac siv-aes aes-siv aes-cmac-prf-128 pbkdf2-aes-cmac-prf-128 nist-sp-800-38a nist-sp-800-38b rfc-4493 rfc-5297 rfc-4615 rfc-8018</PackageTags>
5254
<PackageLicenseExpression>MIT</PackageLicenseExpression>
5355
<PackageReadmeFile>README.md</PackageReadmeFile>
5456
<UseFullSemVerForNuGet>false</UseFullSemVerForNuGet>

‎Documentation/index.md‎

Lines changed: 13 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -4,59 +4,25 @@ SPDX-FileCopyrightText: 2025 Frans van Dorsselaer
44
SPDX-License-Identifier: MIT
55
-->
66

7-
# This is the **HOMEPAGE**
7+
# dotnet-aes-extra
88

9-
## Under construction
9+
The library leverages the AES implementation of .NET; it does not contain the AES primitive itself.
10+
Instead, it adds modes of AES that are not in available in .NET / .NET Core / .NET Framework.
1011

11-
> [!NOTE]
12-
> Information the user should notice even if skimming.
12+
The library exposes its objects modeled after default .NET classes, so its usage is straightforward.
1313

14-
<!-- new blockquote -->
14+
The @"Dorssel.Security.Cryptography?text=API" includes both the classic `byte[]` as well as the modern `Span<byte>` overloads.
1515

16-
> [!TIP]
17-
> Optional information to help a user be more successful.
16+
There are two builds of the library included in th package, one for .NET Standard 2.0 and one for .NET 8 (or higher).
17+
The public @"Dorssel.Security.Cryptography?text=API" is the same for both, but internally the builds slightly differ:
1818

19-
<!-- new blockquote -->
19+
- The .NET Standard build depends on `Microsoft.Bcl.AsyncInterfaces` and `Microsoft.Bcl.Memory` for `ValueTask` and `Span` support.
2020

21-
> [!IMPORTANT]
22-
> Essential information required for user success.
21+
- The .NET 8 build uses `CryptographicOperations` for `ZeroMemory` and `FixedTimeEquals`,
22+
whereas the .NET Standard build uses an internal implementation backported from the original .NET 8 code.
2323

24-
<!-- new blockquote -->
24+
- The .NET 8 build supports trimming.
2525

26-
> [!CAUTION]
27-
> Negative potential consequences of an action.
26+
## Example
2827

29-
<!-- new blockquote -->
30-
31-
> [!WARNING]
32-
> Dangerous certain consequences of an action.
33-
34-
<!-- new blockquote -->
35-
36-
> [!TODO]
37-
> This needs to be done.
38-
39-
Refer to [Markdown](http://daringfireball.net/projects/markdown/) for how to write markdown files.
40-
41-
## Quick Start Notes
42-
43-
1. Add images to the *images* folder if the file is referencing an image.
44-
45-
## MathJax example
46-
47-
Inline: $\sqrt{3x-1}+(1+x)^2$
48-
49-
Or paragraph:
50-
51-
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
52-
53-
## Mermaid example
54-
55-
```mermaid
56-
flowchart LR
57-
58-
A[Hard] -->|Text| B(Round)
59-
B --> C{Decision}
60-
C -->|One| D[Result 1]
61-
C -->|Two| E[Result 2]
62-
```
28+
[!code-csharp[](../Example/Program.cs)]

‎Example/Example.csproj‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!--
3+
SPDX-FileCopyrightText: 2025 Frans van Dorsselaer
4+
5+
SPDX-License-Identifier: MIT
6+
-->
7+
<Project Sdk="Microsoft.NET.Sdk">
8+
9+
<PropertyGroup>
10+
<TargetFramework>$(MainTargetFramework)</TargetFramework>
11+
<OutputType>Exe</OutputType>
12+
</PropertyGroup>
13+
14+
<ItemGroup>
15+
<ProjectReference Include="..\AesExtra\AesExtra.csproj" />
16+
</ItemGroup>
17+
18+
</Project>

‎Example/Program.cs‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// SPDX-FileCopyrightText: 2025 Frans van Dorsselaer
2+
//
3+
// SPDX-License-Identifier: MIT
4+
5+
using Dorssel.Security.Cryptography;
6+
using System.Security.Cryptography;
7+
8+
// example data
9+
const int AesBlockSizeInBytes = 16;
10+
var plaintext = new byte[] { 1, 2, 3 };
11+
var key = RandomNumberGenerator.GetBytes(32);
12+
var iv = RandomNumberGenerator.GetBytes(AesBlockSizeInBytes);
13+
var salt = RandomNumberGenerator.GetBytes(8);
14+
var associatedData = new byte[] { 4, 5 };
15+
16+
// AES-CTR (use like .NET's Aes)
17+
using var aesCtr = new AesCtr(key);
18+
var ciphertextCtr = aesCtr.TransformCtr(plaintext, iv);
19+
20+
// AES-CMAC (use like .NET's HMACSHA256)
21+
using var aesCmac = new AesCmac(key);
22+
var tagCmac = aesCmac.ComputeHash(plaintext);
23+
24+
// SIV-AES (use like .NET's AesGcm)
25+
using var aesSiv = new AesSiv(key);
26+
var ciphertextSiv = new byte[AesBlockSizeInBytes + plaintext.Length];
27+
aesSiv.Encrypt(plaintext, ciphertextSiv, associatedData);
28+
29+
// AES-CMAC-PRF-128 (use like .NET's HKDF)
30+
var derivedKey = AesCmacPrf128.DeriveKey(key, plaintext);
31+
32+
// PBKDF2-AES-CMAC-PRF-128 (use like .NET's Rfc2898DeriveBytes)
33+
var passwordBasedDerivedKey = AesCmacPrf128.Pbkdf2("password", salt, 1000, 32);

‎dotnet-aes-extra.sln‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "UnitTests8", "UnitTests8\Un
2525
EndProject
2626
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Documentation", "Documentation\Documentation.csproj", "{D6E6BF39-629B-4A1D-B888-B0A8A32B99D1}"
2727
EndProject
28+
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Example", "Example\Example.csproj", "{337891B4-3C05-4F3E-B1B9-7B570AB109DB}"
29+
EndProject
2830
Global
2931
GlobalSection(SolutionConfigurationPlatforms) = preSolution
3032
Debug|Any CPU = Debug|Any CPU
@@ -45,6 +47,10 @@ Global
4547
{2110E495-3D1F-4720-A3E8-F18DC50CDAD6}.Release|Any CPU.Build.0 = Release|Any CPU
4648
{D6E6BF39-629B-4A1D-B888-B0A8A32B99D1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
4749
{D6E6BF39-629B-4A1D-B888-B0A8A32B99D1}.Release|Any CPU.ActiveCfg = Release|Any CPU
50+
{337891B4-3C05-4F3E-B1B9-7B570AB109DB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
51+
{337891B4-3C05-4F3E-B1B9-7B570AB109DB}.Debug|Any CPU.Build.0 = Debug|Any CPU
52+
{337891B4-3C05-4F3E-B1B9-7B570AB109DB}.Release|Any CPU.ActiveCfg = Release|Any CPU
53+
{337891B4-3C05-4F3E-B1B9-7B570AB109DB}.Release|Any CPU.Build.0 = Release|Any CPU
4854
EndGlobalSection
4955
GlobalSection(SolutionProperties) = preSolution
5056
HideSolutionNode = FALSE

0 commit comments

Comments
 (0)