ClosedXML 修改保护（Protection）完全指南：工作簿、工作表与密码哈希原理

后端【免费下载链接】ClosedXMLClosedXML is a .NET library for reading, manipulating and writing Excel 2007 (.xlsx, .xlsm) files. It aims to provide an intuitive and user-friendly interface to dealing with the underlying OpenXML API.项目地址https://gitcode.com/gh_mirrors/cl/ClosedXML点击查看免费下载本文围绕 ClosedXML 的修改保护Modification Protection功能展开讲解如何在 .NET 中通过IXLWorkbook.Protect、IXLWorksheet.Protect等 API 对工作簿结构、工作表内容实施密码保护并深入剖析XLProtectionAlgorithm哈希算法、盐值与SpinCount的底层实现。读完本文你将掌握工作簿/工作表两级保护的完整配置方式、allowedElements参数的正确语义以及解保护与异常处理的实战细节。保护功能概览Excel 提供了一套「修改保护」机制用于防止工作簿数据被意外改动对应 Excel 界面中的Review审阅功能区面板需要特别强调的是这种保护只对“意外修改”有效并非真正的安全防护。从实现上看ClosedXML 只是向 xlsx 文件中写入一个「受保护元素集合的哈希计算结果」任何用户都可以通过直接解压 xlsx 文件、修改其中的 XML 文件来绕过保护。因此不要把该功能当作加密或防篡改手段使用。保护可以在多个层级上生效层级作用范围工作簿级Workbook level用户无法对工作簿执行添加、删除或重命名工作表等结构变更工作表级Worksheet level用户只能通过有限的命令子集修改工作表整张工作表的单元格内容被锁定区域级Range level即使工作表被锁定仍可编辑指定区域内的单元格——要么通过输入密码解锁该区域要么作为组成员获得编辑权限区域级保护在 Excel 中表现为两类对话框一类用于指定「必须输入密码才能编辑的单元格区域」另一类用于指定「无需密码即可编辑区域的成员」密码存储与校验原理密码不会以明文形式存储在 xlsx 文件中。文件中只保存一个盐salt和一个由指定算法计算出的哈希值hash。校验流程为将用户输入的密码与文件中的盐按算法规则组合计算得到哈希结果再与文件中存储的哈希值比对。从 ClosedXML 源码看这一逻辑位于 ClosedXML/Utils/CryptographicAlgorithms.cs 的GetPasswordHash方法中同时文件还额外记录了SpinCount迭代次数默认 100000用于 SHA-512 场景下的迭代加盐哈希。Available API可用的保护 APIClosedXML不会校验锁定元素——无论工作簿保护设置如何所有操作与修改在 ClosedXML 中都是被允许的。也就是说保护信息只是被写入文件供 Excel 等外部程序读取ClosedXML 自身并不会在执行 API 操作时强制拦截。每个Protect方法都提供带「密码 哈希算法」参数的重载。只应使用没有已知碰撞问题的哈希算法即不要用 MD5、CRC32、SHA-1。同时要注意所有可用哈希算法都面向速度设计像 John the Ripper 之类的密码破解工具很可能破解此类密码因此不要依赖该机制提供强密码保护。关于 allowedElements 的易混淆语义API 设计上接受的是「允许修改的元素allowed elements」而非「受保护的元素」这会导致代码读起来有点反直觉wb.Protect(XLWorkbookProtectionElements.None)含义是“不允许任何更改”但代码读起来像是“不保护任何元素”wb.Protect(XLWorkbookProtectionElements.Everything)含义是“允许一切更改”但代码读起来像是“保护所有元素”。官方文档明确建议使用该 API 时显式写出allowedElements参数名以避免歧义。工作簿保护Workbook protectionClosedXML 通过IXLWorkbook.Protect(XLWorkbookProtectionElements)保护工作簿结构。XLWorkbookProtectionElements是一个标记枚举flag enum见 ClosedXML/Excel/Protection/XLWorkbookProtectionElements.cs可以使用位运算组合单个元素成员值含义None0不允许任何结构变更Structure1 0锁定工作簿结构禁止添加、删除、重命名工作表Windows1 1锁定窗口禁止移动、调整大小或关闭工作簿窗口以及隐藏/取消隐藏窗口EverythingStructure \| Windows同时锁定结构与窗口文档建议始终允许XLWorkbookProtectionElements.Windows这也是未指定参数时的默认值。该选项仅被过时版本的 Excel 使用但仍属于标准的一部分——它对应源码 IXLWorkbookProtection.cs 中Protect方法的默认参数XLWorkbookProtectionElements.Windows。创建受保护结构的工作簿var wb new XLWorkbook(); var ws wb.AddWorksheet(); wb.Protect(Pa55w0rD, XLProtectionAlgorithm.Algorithm.SHA512, allowedElements: XLWorkbookProtectionElements.Windows); Assert.IsTrue(wb.IsProtected); Assert.IsTrue(wb.IsPasswordProtected); wb.SaveAs(protect-workbook.xlsx);保存后用户在 Excel 中试图重命名工作表时会看到错误提示而「添加新工作表」的按钮会被置灰表示工作簿结构不可修改底层实现要点从 XLWorkbook.cs 可以看到wb.Protect(...)是委托给内部XLWorkbookProtection实例执行的。Protect(string password, Algorithm algorithm, XLWorkbookProtectionElements allowedElements)的实现见 XLWorkbookProtection.cs会若已处于保护状态直接抛出InvalidOperationException“The workbook structure is already protected”置IsProtected true将空密码归一化为通过CryptographicAlgorithms.GenerateNewSalt生成随机盐SHA-512 需要盐SimpleHash不需要通过CryptographicAlgorithms.GetPasswordHash(algorithm, password, salt, spinCount)计算密码哈希最后记录AllowedElements。写入 xlsx 文件时WorkbookPartWriter.cs 会将PasswordHash、SpinCount、Base64EncodedSalt、算法名分别写入workbookProtection元素的WorkbookPassword、WorkbookSpinCount、WorkbookSaltValue、WorkbookAlgorithmName属性并由LockStructure/LockWindows表达被锁定的结构元素。工作表保护Worksheet protection工作表保护会锁定整张工作表的所有单元格仅允许执行指定的操作集合。同样地API 定义的是allowedElements允许元素而非受保护元素。基础用法var wb new XLWorkbook(); var ws wb.AddWorksheet(); ws.Cell(A1).Value Test; ws.Protect(Pa55w0rD, XLProtectionAlgorithm.Algorithm.SHA512, allowedElements: XLSheetProtectionElements.DeleteRows | XLSheetProtectionElements.SelectEverything | XLSheetProtectionElements.FormatCells); // 也可以从允许列表中移除某个元素 ws.Protection.DisallowElement(XLSheetProtectionElements.DeleteRows); Assert.IsTrue(ws.IsProtected); Assert.IsTrue(ws.IsPasswordProtected); Assert.AreEqual(XLProtectionAlgorithm.Algorithm.SHA512, ws.Protection.Algorithm); Assert.IsFalse(ws.Protection.AllowedElements.HasFlag(XLSheetProtectionElements.DeleteRows)); Assert.IsTrue(ws.Protection.AllowedElements.HasFlag(XLSheetProtectionElements.SelectLockedCells)); Assert.IsTrue(ws.Protection.AllowedElements.HasFlag(XLSheetProtectionElements.FormatCells)); wb.SaveAs(protect-worksheet.xlsx);上述示例中Excel 允许用户修改格式但被禁止的元素如删除行不可用——右键菜单中的删除行选项会被置灰XLSheetProtectionElements 完整枚举XLSheetProtectionElements同样是标记枚举见 ClosedXML/Excel/Protection/XLSheetProtectionElements.cs完整成员如下成员位值含义None0不允许任何操作AutoFilter1 1允许使用自动筛选DeleteColumns1 2允许删除列DeleteRows1 3允许删除行EditObjects1 4允许编辑对象图形等EditScenarios1 5允许编辑方案FormatCells1 6允许设置单元格格式FormatColumns1 7允许设置列格式FormatRows1 8允许设置行格式InsertColumns1 9允许插入列InsertHyperlinks1 10允许插入超链接InsertRows1 11允许插入行PivotTables1 12允许使用数据透视表SelectLockedCells1 13允许选中被锁定单元格SelectUnlockedCells1 14允许选中未锁定单元格Sort1 15允许排序此外还提供了组合常量DeleteEverything DeleteColumns | DeleteRows、FormatEverything FormatCells | FormatColumns | FormatRows、InsertEverything InsertColumns | InsertHyperlinks | InsertRows、SelectEverything SelectLockedCells | SelectUnlockedCells以及覆盖全部位值的Everything。工作表保护的默认allowedElements是XLSheetProtectionElements.SelectEverything见 IXLSheetProtection.cs。底层实现 XLSheetProtection.cs 与工作簿保护结构对称同样包含AllowElement/AllowEverything/AllowNone/DisallowElement/CopyFrom/Unprotect等成员方法其中DisallowElement通过AllowedElements ~element清除位值重复保护会抛出InvalidOperationException。允许编辑区域Allow edit ranges原文档明确说明ClosedXML 目前尚未支持该功能。Excel 中“允许编辑区域”相关的对话框protect-range-dialog.png、protect-range-permissions.png仅用于说明 Excel 原生能力ClosedXML 暂不能写入这类区域级解锁配置。若你的业务需要区域级密码解锁需在 Excel 中手工设置或关注 ClosedXML 后续版本更新。解保护工作簿或工作表Unprotect通过IXLWorkbook.Unprotect/IXLWorksheet.Unprotect方法可以移除工作簿/工作表的保护// 无密码保护时 wb.Unprotect(); ws.Unprotect(); // 有密码保护时 wb.Unprotect(Pa55w0rD); ws.Unprotect(Pa55w0rD);如果保护使用了密码解保护时必须提供有效密码否则会抛出ArgumentException。从源码看XLWorkbookProtection.cs具体行为是若已设置PasswordHash但未传入密码Unprotect()抛出InvalidOperationException“The workbook structure is password protected”工作表保护对应 “The worksheet is password protected”若传入密码但哈希比对失败抛出ArgumentException“Invalid password”校验通过后IsProtected置为false并清空PasswordHash与Base64EncodedSalt。这些行为均有对应测试覆盖见 XLWorkbookProtectionTests.cs 中的CannotUnprotectWithoutPassword、CannotUnprotectIfNoPassword、CanUnprotectWithPassword等用例。哈希算法与测试验证XLProtectionAlgorithm见 ClosedXML/Excel/Protection/XLProtectionAlgorithm.cs中DefaultProtectionAlgorithm默认为SimpleHash当前实际可用的算法只有两个算法说明是否需要盐SimpleHashExcel 传统的 15 位异或位移哈希对应 OpenOffice 文档格式规范 4.18.4结果为大写十六进制否SHA512标准 SHA-512配合随机盐与 100000 次迭代SpinCount计算是源码中 MD2/MD4/MD5/SHA-1/SHA-256 等算法均被注释掉印证了文档“不使用已知碰撞算法”的约束。CryptographicAlgorithms.GetPasswordHashClosedXML/Utils/CryptographicAlgorithms.cs对空密码直接返回空哈希SHA-512 路径先把盐与 UTF-16 编码的密码字节拼接随后按SpinCount循环迭代计算。测试文件 HashAlgorithmTests.cs 给出了确定性验证向量SimpleHash(12345)应等于CA9CSHA512下使用盐aVvPw1DNH3evPqRAd/y3UQ、密码12345、迭代 100000 次哈希应为EqAhyIg/HM0dUrPaENfimFOZp7wlOkJsf/sdGAGHOA9grOv7VLb1ik2vuYohljI9G36e0ea9wnixCK0MMuyQ。此外XLSheetProtectionTests.cs 覆盖了Protect().AllowEverything()、AllowNone()、算法切换SimpleHash → SHA512与跨工作表CopyFrom等场景XLWorkbookProtectionTests还演示了「无密码保护 → 有密码保护」「保护算法动态切换」「跨工作簿CopyFrom复制保护设置含盐、哈希与 SpinCount」「通过IXLProtectable接口统一批量保护/解保护多个对象」等能力。实践建议显式命名参数调用Protect时务必写出allowedElements:避免None/Everything的歧义语义导致误解。算法选择生产环境优先使用XLProtectionAlgorithm.Algorithm.SHA512SimpleHash仅为兼容旧 Excel 行为而保留。定位保护层级工作簿保护用wb.Protect(...)并组合XLWorkbookProtectionElements工作表保护用ws.Protect(...)并组合XLSheetProtectionElements两者可通过IsProtected、IsPasswordProtected、Protection.Algorithm、Protection.AllowedElements查询状态。动态调整保护后仍可通过AllowElement/DisallowElement/AllowEverything/AllowNone增量调整允许列表无需先解保护再重新保护。认知边界ClosedXML 自身不拦截任何修改操作保护仅对 Excel 用户界面生效且可被解包 XML 绕过——它适合“防止误操作”不适合作为安全边界。相关接口与实现文件接口定义见 IXLWorkbookProtection.cs、IXLSheetProtection.cs、IXLElementProtection.cs工作簿与工作表的Protect/Unprotect入口分别位于 XLWorkbook.cs 与 XLWorksheet.cs。赞分享后端【免费下载链接】ClosedXMLClosedXML is a .NET library for reading, manipulating and writing Excel 2007 (.xlsx, .xlsm) files. It aims to provide an intuitive and user-friendly interface to dealing with the underlying OpenXML API.项目地址https://gitcode.com/gh_mirrors/cl/ClosedXML点击查看免费下载相关推荐Rocket Redis快捷键与高效操作10个提升工作效率的实用技巧Rocket Redis快捷键与高效操作10个提升工作效率的实用技巧 Rocket Redis作为一款美观的Redis GUI工具不仅提供了直观的界面管理RApache Fesod 工作簿密码保护实战读写加密 Excel 的完整指南Apache Fesod 工作簿密码保护实战读写加密 Excel 的完整指南 本文基于 Apache FesodIncubating的官方文档 websi后端Nucleus核心原理深度解析配置变更与进程重启的完美解决方案Nucleus核心原理深度解析配置变更与进程重启的完美解决方案 Nucleus是一个基于Model View Presenter模式的Android库专为解移动开发软件架构上一篇Hydrogen v2 Remix 模板的 Vercel 零配置部署指南Shopify 无头电商实战下一篇图像压缩神器Compressor.js浏览器端高效压缩指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考