53 lines
4.1 KiB
Markdown
53 lines
4.1 KiB
Markdown
|
---
|
||
|
|
source_files:
|
||
|
|
- Common/DTS.Common.Security/Encryption.cs
|
||
|
|
generated_at: "2026-04-16T11:36:14.772984+00:00"
|
||
|
|
model: "zai-org/GLM-5-FP8"
|
||
|
|
schema_version: 1
|
||
|
|
sha256: "2d41661347ec3dbc"
|
||
|
|
---
|
||
|
|
|
||
|
|
# Documentation: DTS.Common.Security.Encryption
|
||
|
|
|
||
|
|
## 1. Purpose
|
||
|
|
The `Encryption` static class provides symmetric encryption and decryption utilities for the DTS system. It serves as a wrapper around the `AesCryptoServiceProvider` to securely convert plaintext strings into byte arrays and vice versa. This module centralizes AES encryption logic to ensure consistent cryptographic handling across the application.
|
||
|
|
|
||
|
|
## 2. Public Interface
|
||
|
|
|
||
|
|
### `public static byte[] EncryptStringToBytes(string plainText, byte[] key, byte[] iv)`
|
||
|
|
Encrypts a specified plaintext string into an array of bytes using the AES algorithm.
|
||
|
|
* **Parameters:**
|
||
|
|
* `plainText` (string): The text to encrypt.
|
||
|
|
* `key` (byte[]): The secret key for the symmetric algorithm.
|
||
|
|
* `iv` (byte[]): The initialization vector (IV) for the symmetric algorithm.
|
||
|
|
* **Returns:** A byte array containing the encrypted data.
|
||
|
|
* **Exceptions:** Throws `ArgumentNullException` if `plainText`, `key`, or `iv` are null or empty.
|
||
|
|
|
||
|
|
### `public static string DecryptStringFromBytes(byte[] cipherText, byte[] key, byte[] iv)`
|
||
|
|
Decrypts a specified byte array back into a plaintext string using the AES algorithm.
|
||
|
|
* **Parameters:**
|
||
|
|
* `cipherText` (byte[]): The byte array containing encrypted data.
|
||
|
|
* `key` (byte[]): The secret key used for encryption.
|
||
|
|
* `iv` (byte[]): The initialization vector used for encryption.
|
||
|
|
* **Returns:** The decrypted plaintext string.
|
||
|
|
* **Exceptions:** Throws `ArgumentNullException` if `cipherText`, `key`, or `iv` are null or empty.
|
||
|
|
|
||
|
|
## 3. Invariants
|
||
|
|
* **Null Checks:** All input parameters (`plainText`, `cipherText`, `key`, `iv`) must be non-null and have a length greater than zero. Failure to meet this condition results in an `ArgumentNullException`.
|
||
|
|
* **Algorithm Consistency:** Both methods utilize `AesCryptoServiceProvider` (AES). The key and IV provided to `DecryptStringFromBytes` must match those used in `EncryptStringToBytes` for decryption to succeed.
|
||
|
|
* **Stream Encoding:** The implementation uses `StreamWriter` and `StreamReader` for stream transformations. The specific character encoding is not explicitly defined in the method signatures, relying on the default encoding of the underlying stream writer/reader (typically UTF-8).
|
||
|
|
|
||
|
|
## 4. Dependencies
|
||
|
|
* **Internal Dependencies:** None identified within the provided source.
|
||
|
|
* **External Dependencies:**
|
||
|
|
* `System`: For basic types and exceptions.
|
||
|
|
* `System.IO`: Used for `MemoryStream`, `StreamWriter`, and `StreamReader` to handle data flow during encryption/decryption.
|
||
|
|
* `System.Security.Cryptography`: Used for `AesCryptoServiceProvider` and `CryptoStream` to perform the cryptographic operations.
|
||
|
|
* **Unused Dependencies:** The file imports `System.Collections.Generic`, `System.Linq`, `System.Text`, and `System.Threading.Tasks`, but none of these namespaces appear to be utilized in the current implementation.
|
||
|
|
|
||
|
|
## 5. Gotchas
|
||
|
|
* **Copy-Paste Error in Validation:** In both `EncryptStringToBytes` and `DecryptStringFromBytes`, the validation check for the `iv` parameter throws an exception naming the `key` parameter instead.
|
||
|
|
* *Source Reference:* `if (iv == null || iv.Length <= 0) throw new ArgumentNullException(nameof(key));`
|
||
|
|
* This will report "key" as the null argument in the exception message when the `iv` is actually the invalid parameter, complicating debugging.
|
||
|
|
* **Variable Naming Mismatch:** The `AesCryptoServiceProvider` instance is named `rijAlg` in both methods. This is likely a legacy artifact from a previous implementation using `RijndaelManaged`, which may cause confusion as the code now explicitly uses AES.
|
||
|
|
* **Key/IV Management:** The class provides no mechanism for key or IV generation. Callers are responsible for generating and managing valid AES keys and IVs. Passing invalid key/IV lengths will cause the underlying `AesCryptoServiceProvider` to throw a `CryptographicException`, which is not caught by this wrapper.
|