feat: add func to write encrypt file header.

xiao-77 · xiao-77 · commit 1347c5cb7d84 · 2025-12-06T14:33:20.000+08:00
diff --git a/include/os/osFile.h b/include/os/osFile.h
@@ -146,6 +146,74 @@ bool    lastErrorIsFileNotExist();
 
 int64_t taosWritevFile(TdFilePtr pFile, const TaosIOVec *iov, int iovcnt);
 
+// ============================================================================
+// Encrypted File Operations
+// ============================================================================
+
+// File encryption magic number and constants
+#define TD_ENCRYPT_FILE_MAGIC   "tdEncrypt"
+#define TD_ENCRYPT_FILE_VERSION 1
+#define TD_ENCRYPT_MAGIC_LEN    16
+
+// Database encryption status
+typedef enum {
+  TD_DB_ENCRYPT_STATUS_UNKNOWN = 0,   // Unknown - encryption state uncertain (upgrade scenario)
+  TD_DB_ENCRYPT_STATUS_PLAIN = 1,     // Plain - database files are unencrypted
+  TD_DB_ENCRYPT_STATUS_ENCRYPTED = 2  // Encrypted - database files are fully encrypted
+} ETdDbEncryptStatus;
+
+// DNode encryption status
+typedef enum {
+  TD_DNODE_ENCRYPT_STATUS_PLAIN = 0,     // Plain - config and metadata files are unencrypted
+  TD_DNODE_ENCRYPT_STATUS_ENCRYPTED = 1  // Encrypted - all related files are encrypted
+} ETdDnodeEncryptStatus;
+
+// Encrypt file header structure (plaintext part at file beginning)
+typedef struct {
+  char    magic[TD_ENCRYPT_MAGIC_LEN];  // Magic number "tdEncrypt"
+  int32_t algorithm;                    // Encryption algorithm (e.g., TSDB_ENCRYPT_ALGO_SM4 = 1)
+  int32_t version;                      // File format version
+  int32_t dataLen;                      // Length of encrypted data following header
+  char    reserved[32];                 // Reserved for future use
+} STdEncryptFileHeader;
+
+/**
+ * @brief Write file with encryption header using atomic file replacement
+ *
+ * This function writes data to a file with an encryption header at the beginning.
+ * The caller is responsible for encrypting the data before passing it to this function.
+ * It uses atomic file replacement strategy: writes to temp file, then renames.
+ *
+ * @param filepath Target file path
+ * @param algorithm Encryption algorithm identifier (e.g., TSDB_ENCRYPT_ALGO_SM4)
+ * @param data Data buffer to write (caller should encrypt data if needed, can be NULL for empty file)
+ * @param dataLen Length of data to write (0 for empty file)
+ * @return 0 on success, error code on failure
+ */
+int32_t taosWriteEncryptFileHeader(const char *filepath, int32_t algorithm, const void *data, int32_t dataLen);
+
+/**
+ * @brief Read encryption header from file
+ *
+ * Reads and validates the encryption header from the beginning of a file.
+ *
+ * @param filepath File path to read
+ * @param header Output parameter for header data
+ * @return 0 on success, error code on failure
+ */
+int32_t taosReadEncryptFileHeader(const char *filepath, STdEncryptFileHeader *header);
+
+/**
+ * @brief Check if file has encryption header
+ *
+ * Quickly checks if a file begins with the encryption magic number.
+ *
+ * @param filepath File path to check
+ * @param algorithm Output parameter for algorithm (can be NULL)
+ * @return true if file is encrypted, false otherwise
+ */
+bool taosIsEncryptedFile(const char *filepath, int32_t *algorithm);
+
 #ifdef BUILD_WITH_RAND_ERR
 #define STUB_RAND_NETWORK_ERR(ret)                                        \
   do {                                                                    \
diff --git a/source/os/src/osFile.c b/source/os/src/osFile.c
@@ -1855,3 +1855,206 @@ int64_t taosWritevFile(TdFilePtr pFile, const TaosIOVec *iov, int iovcnt) {
   return (int64_t)totalWritten;
 #endif
 }
+
+// ============================================================================
+// Encrypted File Operations Implementation
+// ============================================================================
+
+/**
+ * Write file with encryption header using atomic file replacement.
+ *
+ * This function writes data to a file with an encryption header at the beginning.
+ * The encryption header contains:
+ * - Magic number "tdEncrypt" for quick identification
+ * - Algorithm identifier (e.g., SM4 = 1)
+ * - File format version
+ * - Length of encrypted data
+ *
+ * Atomic file replacement strategy:
+ * 1. Write to temporary file: filepath.tmp.timestamp
+ * 2. Sync temporary file to disk
+ * 3. Atomically rename temporary file to target filepath
+ * 4. Remove old file if rename succeeds
+ *
+ * This ensures the operation is atomic - no partial writes or corrupted files
+ * even if the process is interrupted.
+ *
+ * @param filepath Target file path
+ * @param algorithm Encryption algorithm identifier
+ * @param data Data buffer to write (can be NULL for empty file with header only)
+ * @param dataLen Length of data to write (0 for empty file)
+ * @return 0 on success, error code on failure
+ */
+int32_t taosWriteEncryptFileHeader(const char *filepath, int32_t algorithm, const void *data, int32_t dataLen) {
+  if (filepath == NULL) {
+    terrno = TSDB_CODE_INVALID_PARA;
+    return terrno;
+  }
+
+  // Validate algorithm
+  if (algorithm < 0) {
+    terrno = TSDB_CODE_INVALID_PARA;
+    return terrno;
+  }
+
+  // Validate data parameters
+  if (dataLen > 0 && data == NULL) {
+    terrno = TSDB_CODE_INVALID_PARA;
+    return terrno;
+  }
+
+  int32_t code = 0;
+  int64_t now = taosGetTimestampMs();
+
+  // Prepare encryption header (plaintext)
+  STdEncryptFileHeader header;
+  memset(&header, 0, sizeof(STdEncryptFileHeader));
+  strncpy(header.magic, TD_ENCRYPT_FILE_MAGIC, TD_ENCRYPT_MAGIC_LEN - 1);
+  header.algorithm = algorithm;
+  header.version = TD_ENCRYPT_FILE_VERSION;
+  header.dataLen = dataLen;
+
+  // Create temporary file for atomic write
+  char tempFile[PATH_MAX];
+  snprintf(tempFile, sizeof(tempFile), "%s.tmp.%ld", filepath, now);
+
+  // Open temp file
+  TdFilePtr pFile = taosOpenFile(tempFile, TD_FILE_CREATE | TD_FILE_WRITE | TD_FILE_TRUNC);
+  if (pFile == NULL) {
+    code = terrno;
+    return code;
+  }
+
+  // Write header (plaintext)
+  int64_t written = taosWriteFile(pFile, &header, sizeof(STdEncryptFileHeader));
+  if (written != sizeof(STdEncryptFileHeader)) {
+    code = (terrno != 0) ? terrno : TSDB_CODE_FILE_CORRUPTED;
+    taosCloseFile(&pFile);
+    taosRemoveFile(tempFile);
+    terrno = code;
+    return code;
+  }
+
+  // Write data if present
+  if (dataLen > 0 && data != NULL) {
+    written = taosWriteFile(pFile, data, dataLen);
+    if (written != dataLen) {
+      code = (terrno != 0) ? terrno : TSDB_CODE_FILE_CORRUPTED;
+      taosCloseFile(&pFile);
+      taosRemoveFile(tempFile);
+      terrno = code;
+      return code;
+    }
+  }
+
+  // Sync to disk
+  code = taosFsyncFile(pFile);
+  if (code != 0) {
+    taosCloseFile(&pFile);
+    taosRemoveFile(tempFile);
+    return code;
+  }
+
+  // Close temp file
+  taosCloseFile(&pFile);
+
+#ifndef WINDOWS
+  // Set file permissions (600 - owner read/write only) for security
+  chmod(tempFile, 0600);
+#endif
+
+  // Atomic replacement - rename temp file to target
+  code = taosRenameFile(tempFile, filepath);
+  if (code != 0) {
+    taosRemoveFile(tempFile);
+    return code;
+  }
+
+  return 0;
+}
+
+/**
+ * Read encryption header from file.
+ *
+ * Reads and validates the encryption header from the beginning of a file.
+ * Checks:
+ * - Magic number matches "tdEncrypt"
+ * - Version is supported
+ *
+ * @param filepath File path to read
+ * @param header Output parameter for header data
+ * @return 0 on success, error code on failure
+ */
+int32_t taosReadEncryptFileHeader(const char *filepath, STdEncryptFileHeader *header) {
+  if (filepath == NULL || header == NULL) {
+    terrno = TSDB_CODE_INVALID_PARA;
+    return terrno;
+  }
+
+  // Open file for reading
+  TdFilePtr pFile = taosOpenFile(filepath, TD_FILE_READ);
+  if (pFile == NULL) {
+    return terrno;
+  }
+
+  // Read header
+  int64_t nread = taosReadFile(pFile, header, sizeof(STdEncryptFileHeader));
+  taosCloseFile(&pFile);
+
+  if (nread != sizeof(STdEncryptFileHeader)) {
+    terrno = TSDB_CODE_FILE_CORRUPTED;
+    return terrno;
+  }
+
+  // Verify magic number
+  if (strncmp(header->magic, TD_ENCRYPT_FILE_MAGIC, strlen(TD_ENCRYPT_FILE_MAGIC)) != 0) {
+    terrno = TSDB_CODE_FILE_CORRUPTED;
+    return terrno;
+  }
+
+  // Verify version (currently only version 1 is supported)
+  if (header->version != TD_ENCRYPT_FILE_VERSION) {
+    terrno = TSDB_CODE_FILE_CORRUPTED;
+    return terrno;
+  }
+
+  return 0;
+}
+
+/**
+ * Check if file has encryption header.
+ *
+ * Quickly checks if a file begins with the encryption magic number.
+ * This is faster than reading the full header when you only need to
+ * know if the file is encrypted.
+ *
+ * @param filepath File path to check
+ * @param algorithm Output parameter for algorithm (can be NULL)
+ * @return true if file is encrypted, false otherwise
+ */
+bool taosIsEncryptedFile(const char *filepath, int32_t *algorithm) {
+  if (filepath == NULL) {
+    terrno = TSDB_CODE_INVALID_PARA;
+    return false;
+  }
+
+  // Check if file exists
+  if (!taosCheckExistFile(filepath)) {
+    return false;
+  }
+
+  // Read header
+  STdEncryptFileHeader header;
+  int32_t              code = taosReadEncryptFileHeader(filepath, &header);
+
+  if (code != 0) {
+    return false;
+  }
+
+  // Return algorithm if requested
+  if (algorithm != NULL) {
+    *algorithm = header.algorithm;
+  }
+
+  return true;
+}
