MUST 和 MUST NOT

关于编写文档

亲爱的 KV，

我加入了一家小型安全初创公司，并被委派编写我们的内部安全流程。问题是我不是作家，我是一名软件工程师，每当我开始尝试编写关于我们流程的内容时，我要么盯着空白屏幕直到感到沮丧并转移视线去做其他事情，要么我只是最终写了很多句子，后来似乎没有多大意义。我确信一定有一个模板可以让我从中入手，以便将我脑海中的所有内容以有用的方式写下来，但我不确定该在哪里寻找。例如，我想要一种方法来向人们描述他们应该和不应该对我们的软件做什么，以及必须如何使用它，以便它提供他们期望的安全属性。当我尝试写关于这方面的内容时，我看到的是一团乱麻般的文字。

困惑的

亲爱的困惑的，

通常我会回复说，完成大量写作的唯一方法是进行为期三天的狂欢，然后在清醒之前，坐在键盘前，将你的内心和灵魂倾注到你的文本缓冲区中，保存你的工作，然后在阅读你写的内容之前再进行一次狂欢。这可能行不通，但狂欢应该会非常有趣。

实际上，我打算向您推荐一份超过 20 年历史的文件，RFC 2119。KV 之前提到过 RFC（请求评论文档）；这是一系列可以追溯到 1970 年代初的文件，其中描述了互联网协议和许多其他协议。对于那些不熟悉这些文档的人来说，它们总是使用少量关键词来指定协议的哪些部分是必需的或可选的：

关键词 “MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY” 和 “OPTIONAL”？ [引用 RFC 2119]

这些词的含义在两页 ASCII 码中进行了编纂，ASCII 码是现在一种古老的文本通信标准。这些关键词以大写形式作为它们唯一的强调形式。事实证明，为了清晰地沟通，没有必要使用花哨的格式；实际上，花哨的格式通常会分散人们对您想要传达的信息的注意力。

不，我不仅仅是建议您使用这样的语言；我认为您 MUST 按照书面形式使用这些术语，然后引用 RFC。通过引用一份众所周知且写得很好的文档，并可能用它来敲打他们，让一群人理解您的意思，可以为您节省大量时间和麻烦。文档越长，争论的内容就越多，挑剔的地方也就越多。减少挑剔可以节省大量时间。

当您计划在安全文档中使用这些术语时，请注意：这些词语必须谨慎使用，并发挥最大的效果。一长串的 MUST 和 MUST NOT 将会是乏味和无聊的，并且会分散读者的注意力。注意力不集中的读者会犯错误，在这种情况下，他们会犯安全错误，而这正是您的文档试图帮助他们避免的错误类型。让我再分享 RFC 中的一段话

这些术语经常用于指定具有安全影响的行为。不实施 MUST 或 SHOULD，或者做一些规范说 MUST NOT 或 SHOULD NOT 做的事情，其安全影响可能非常微妙。文档作者应花时间详细说明不遵循建议或要求的安全影响，因为大多数实施者将不会从制定规范的经验和讨论中获益。规范。

这段话的意思是，“解释清楚！” 对于那些没有深入研究计算机安全或一般安全艺术和科学的人来说，没有背景或解释材料的声明是毫无用处的。同时像攻击者和防御者一样思考需要一种特殊的思维方式，而大多数人无法做到这一点；因此，如果您希望阅读文档的人遵循您的指导，那么您必须带领他们从无知走向知识。只有这样，您才能期望他们正确地实施您的指导，无论是在熟悉还是——尤其是在不熟悉的情况下。

微软的协议文档计划：大规模互操作性测试
与 Nico Kicillof、Wolfgang Grieskamp 和 Bob Binder 的讨论
https://queue.org.cn/detail.cfm?id=1996412

下一个大事件
Kode Vicious
https://queue.org.cn/detail.cfm?id=1317398

重新思考稳健性原则
寻求中间立场
Eric Allman，Sendmail
https://queue.org.cn/detail.cfm?id=1999945

Kode Vicious，凡人称之为 George V. Neville-Neil，为乐趣和利润从事网络和操作系统代码工作。他还教授各种与编程相关的课程。他的兴趣领域是代码探险、操作系统和重写您的糟糕代码（好吧，也许不是最后一个）。他获得了马萨诸塞州波士顿东北大学计算机科学学士学位，并且是、Usenix 协会和 IEEE 的成员。Neville-Neil 与 Marshall Kirk McKusick 和 Robert N. M. Watson 合著了 FreeBSD 操作系统设计与实现 （第二版）。他是一位狂热的自行车爱好者和旅行者，目前居住在纽约市。

最初发表于 Queue 第 17 卷，第 2 期——
在数字图书馆中评论这篇文章

更多相关文章

Catherine Hayes, David Malone - 质疑评估非加密哈希函数的标准
尽管加密和非加密哈希函数无处不在，但在它们的设计方式上似乎存在差距。针对各种安全需求，存在许多用于加密哈希的标准，但在非加密方面，存在一定的民间传说，尽管哈希函数历史悠久，但尚未得到充分探索。虽然针对真实世界数据集的均匀分布很有意义，但在面对具有特定模式的数据集时，这可能是一个挑战。

Nicole Forsgren, Eirini Kalliamvakou, Abi Noda, Michaela Greiler, Brian Houck, Margaret-Anne Storey - DevEx in Action
随着领导者寻求在财政紧缩和人工智能等变革性技术的背景下优化软件交付，DevEx（开发者体验）在许多软件组织中越来越受到关注。技术领导者直观地接受良好的开发者体验能够实现更有效的软件交付和开发者幸福感。然而，在许多组织中，旨在改善 DevEx 的拟议举措和投资难以获得支持，因为业务利益相关者质疑改进的价值主张。

João Varajão, António Trigo, Miguel Almeida - 低代码开发生产力
本文旨在通过展示使用基于代码、低代码和极端低代码技术进行的实验室实验结果，研究生产力差异，从而为该主题提供新的见解。低代码技术已清楚地显示出更高的生产力水平，为低代码在短期/中期内主导软件开发主流提供了有力的论据。本文报告了程序和协议、结果、局限性以及未来研究的机会。

Ivar Jacobson, Alistair Cockburn - 用例至关重要
虽然软件行业是一个快节奏且令人兴奋的世界，其中不断开发新的工具、技术和技巧来为商业和社会服务，但它也很健忘。在其快速前进的过程中，它容易受到时尚的突发奇想的影响，并且可能会忘记或忽略某些它面临的永恒问题的经过验证的解决方案。用例，最早于 1986 年引入并在后来普及，就是那些经过验证的解决方案之一。