64 lines
4.1 KiB
Markdown
64 lines
4.1 KiB
Markdown
|
---
|
||
|
|
source_files:
|
||
|
|
- Common/DTS.Common.Security/Encryption.cs
|
||
|
|
generated_at: "2026-04-16T14:14:38.025149+00:00"
|
||
|
|
model: "zai-org/GLM-5-FP8"
|
||
|
|
schema_version: 1
|
||
|
|
sha256: "2d41661347ec3dbc"
|
||
|
|
---
|
||
|
|
|
||
|
|
# Documentation: DTS.Common.Security.Encryption
|
||
|
|
|
||
|
|
## 1. Purpose
|
||
|
|
This module provides symmetric encryption and decryption utilities for string data within the `DTS.Common.Security` namespace. It exists to securely transform plaintext strings into byte arrays and vice versa using the Advanced Encryption Standard (AES) algorithm. It serves as a stateless wrapper around `AesCryptoServiceProvider` to facilitate data confidentiality.
|
||
|
|
|
||
|
|
## 2. Public Interface
|
||
|
|
|
||
|
|
### Class: `Encryption`
|
||
|
|
**Type:** `static`
|
||
|
|
|
||
|
|
### Method: `EncryptStringToBytes`
|
||
|
|
**Signature:** `public static byte[] EncryptStringToBytes(string plainText, byte[] key, byte[] iv)`
|
||
|
|
|
||
|
|
Encrypts a given string into an array of bytes using AES.
|
||
|
|
* **Parameters:**
|
||
|
|
* `plainText` (`string`): The data to encrypt.
|
||
|
|
* `key` (`byte[]`): The secret key for symmetric encryption.
|
||
|
|
* `iv` (`byte[]`): The initialization vector.
|
||
|
|
* **Returns:** `byte[]` containing the encrypted data.
|
||
|
|
* **Behavior:** Validates inputs, initializes an `AesCryptoServiceProvider`, and writes the encrypted data to a `MemoryStream` using a `CryptoStream`.
|
||
|
|
|
||
|
|
### Method: `DecryptStringFromBytes`
|
||
|
|
**Signature:** `public static string DecryptStringFromBytes(byte[] cipherText, byte[] key, byte[] iv)`
|
||
|
|
|
||
|
|
Decrypts a byte array back into a string using AES.
|
||
|
|
* **Parameters:**
|
||
|
|
* `cipherText` (`byte[]`): The encrypted data.
|
||
|
|
* `key` (`byte[]`): The secret key used for encryption.
|
||
|
|
* `iv` (`byte[]`): The initialization vector used for encryption.
|
||
|
|
* **Returns:** `string` containing the decrypted plaintext.
|
||
|
|
* **Behavior:** Validates inputs, initializes an `AesCryptoServiceProvider`, and reads the decrypted data from a `MemoryStream` using a `CryptoStream`.
|
||
|
|
|
||
|
|
## 3. Invariants
|
||
|
|
* **Null/Empty Checks:** All parameters (`plainText`, `key`, `iv`, `cipherText`) must be non-null and have a length greater than 0. If these conditions are not met, an `ArgumentNullException` is thrown.
|
||
|
|
* **Symmetric Keys:** The `key` and `iv` provided to `DecryptStringFromBytes` must be identical to those used in `EncryptStringToBytes` to produce the original plaintext.
|
||
|
|
* **Encoding:** Text encoding relies on the default behavior of `StreamWriter` and `StreamReader` (typically UTF-8) wrapping the crypto streams.
|
||
|
|
* **Algorithm:** The encryption algorithm is implicitly set to the default mode and padding of `AesCryptoServiceProvider` (typically CBC mode with PKCS7 padding), as these properties are not explicitly set in the source.
|
||
|
|
|
||
|
|
## 4. Dependencies
|
||
|
|
* **Internal Dependencies:** None.
|
||
|
|
* **External Dependencies:**
|
||
|
|
* `System`
|
||
|
|
* `System.IO` (for `MemoryStream`, `StreamReader`, `StreamWriter`)
|
||
|
|
* `System.Security.Cryptography` (for `AesCryptoServiceProvider`, `CryptoStream`)
|
||
|
|
* `System.Text` (implicitly used by Stream readers/writers)
|
||
|
|
|
||
|
|
## 5. Gotchas
|
||
|
|
* **Incorrect Exception Parameter Name:** In both `EncryptStringToBytes` and `DecryptStringFromBytes`, the validation logic for the `iv` parameter throws an exception naming `key` instead:
|
||
|
|
```csharp
|
||
|
|
if (iv == null || iv.Length <= 0) throw new ArgumentNullException(nameof(key));
|
||
|
|
```
|
||
|
|
This will mislead developers debugging null IV issues.
|
||
|
|
* **Comment/Code Mismatch:** The XML comments and inline comments refer to `RijndaelManaged`, but the actual code instantiates `AesCryptoServiceProvider`. While AES is a subset of Rijndael, the types are different. The variable name `rijAlg` is also misleading given the type.
|
||
|
|
* **Implicit Crypto Settings:** The code does not explicitly set the `Mode` (e.g., CBC, ECB) or `Padding` properties of the `AesCryptoServiceProvider`. It relies entirely on the framework's default values. This can be fragile if code is ported to environments with different defaults, though .NET defaults are consistent (CBC/PKCS7).
|
||
|
|
* **Unused Imports:** The file imports `System.Collections.Generic`, `System.Linq`, and `System.Threading.Tasks`, none of which are used in the provided implementation.
|