This chapter is sorely needed and is the outcome of work by many documentation experts in various product groups at Microsoft. The chapter is divided into two main parts: security issues in documentation and security issues in error messages. I’m placing the two topics in one chapter because documentation people tend to have input for the text that goes into error messages. Generally, the really bad error messages are those created by developers with no input from user assistance or user education people!
Remember that product design is a process of negotiation and compromise. Security is just one of many factors considered when designing a product, along with ease of deployment, ease of use, manageability, stability, performance, feature set, legacy compatibility, cost and feasibility of implementation, production schedule, and more. The resulting compromises create scenarios in which security will be an issue, and it falls squarely on the documentation people to make sure users understand these trade-offs.
It’s obvious that documenting the security ramifications of using certain product features is important, especially if those features are disabled by default. However, users don’t read the documentation—until they have to. When you have locked down your product to work with minimal privileges and secure defaults, your users will find that many things that "just worked" before won’t work anymore. Faced with this dilemma, they will turn to your documentation, which should be ready to guide them through using and deploying your code in as secure a manner as feasible.
Fundamentally, writing secure documentation means writing good documentation: complete, clear, and concise.
Complete
Where security considerations need to be addressed, whether as a vulnerability in a product or as an administrative consideration, add an appropriate security subtopic or note to alert your reader of the potential concern and ways to handle the concerns. If your product moves unencrypted data across the network or stores a secret in a file, be up front about it so that your users can take appropriate actions to mitigate threats. If a feature’s security concerns are extensive, add a high-level "Security Considerations" subtopic to the feature’s documentation.
Remember that security through obscurity is not security. Intentionally omitting security documentation is not synonymous with mitigating that security vulnerability. Attackers will eventually locate the vulnerability whether or not it’s documented. If the threat is so dire that documenting it would be tantamount to admitting the feature is insecure, the feature is insecure.
Note
From experience, users gravitate to a topic marked Security Considerations in the documentation because all the important advice is in one place.
Clear
Security information should be covered in the appropriate place and at the appropriate level in the table of contents. Be clear and straightforward about your product’s known risks and ramifications. Don’t bury all security-related information in an appendix. Instead, place notices on the security implications of a feature in the documentation of that feature, with a pointer or link to a more complete explanation, if necessary. Ensure that the documentation describes security concerns and tasks at the level an administrator of this feature is expected to be at. Assuming advanced understanding of security for an administrator who knows only the desired application defeats the purpose of clear documentation.
Concise
Give users step-by-step guides to employing your product securely. Don’t give them lots of supplemental information on how public key encryption works or how hash functions can be inverted only in nonpolynomial time. They are usually more interested in the practice than the theory, and numerous excellent references are available for the theory. For completeness, offer references or a bibliography for background or nice-to-know information. In this way the documentation tells them what they need to know now to complete a task and where to get information later for better comprehension of the topic.
During the editorial process, editors and writers should always be aware of their responsibility to proactively encourage trustworthy documentation. Technical writers and editors should be knowledgeable about threat modeling and basic security issues as they write and review material. If they are writing programmer documentation, they should be familiar with all known-to-be-dangerous APIs and query them when they occur in the material.
Always ask your documentation’s technical reviewers if there are known security issues in the product and verify that the new feature or API has been tested for security by the development team. These two items should be part of your standard tech review checklist.
Technical writers and editors should participate in the threat-modeling phase of the product and take note of aspects of the product that might require specialized documentation. Sometimes the product team will decide that the appropriate mitigation for a particular threat is "The product shouldn’t be deployed in that configuration!" or, dare I say it, "The product cannot be deployed in a secure manner!" Every such mitigation should become a very visible note in the appropriate place in your product documentation.
Remember that shipping an insecure default configuration and relying on users to read the documentation to make themselves secure is not a good idea. You should raise an alarm if you notice many threats mitigated by "Read the documentation." While writing screeds of documentation may keep you in work, it’s a disservice to your clients.
Important
Shipping an insecure default configuration and relying on users to read the documentation to make themselves secure is not a good idea.
When documenting a product (or a subsystem of a large product), include a "Security Best Practices" topic that explains how to employ the product (or subsystem) securely as it relates to specific threats. It’s worthwhile having the administrative users of your product think in terms of threats.
The following example addresses the security concerns surrounding the deployment of a mythical SOAP-Server product:
SOAP-Server allows code stored in SOAP scripts on your server to be executed remotely by clients.
By default, SOAP-Server executes your code within the security context of the server process. In some cases, this might be more privilege than you want to grant. (For example, the process can open network sockets.) In other cases, this might be less privilege than is required for successful operation. (For example, the process cannot read arbitrary users’ files.) Always execute your code with the least possible privilege required to accomplish its task. For instructions on how to configure the identity with which a SOAP script executes, see "Configuring the Execution Environment."
Data exchanged between SOAP-Server and a client might in some cases be sensitive and subject to information disclosure threats. If this is the case, consider activating the Encrypt Communications check box for the relevant script. Encrypt Communications uses Transport Layer Security (TLS) technology such that the communication channel between the client and SOAP-Server cannot be monitored. Other technologies, such as Internet Protocol Security (IPSec), can be used instead of or as a complement to this technology to provide additional security.
You might want to restrict access to SOAP scripts to certain clients. SOAP-Server allows you to restrict access based on IP address or identity as verified by an authentication scheme. For instructions on how to enable access restrictions, see "Enabling Access Restrictions" and "Enabling Authentication."
Note: if you authenticate users, you could also have an extra layer of defense by employing access control lists (ACLs) on the SOAP scripts. For information about setting ACLs, search for "Access Control Lists" in the Windows .NET Server on-line help.
Clients access SOAP-Server on port 80 (for unencrypted sessions) or port 443 (for encrypted sessions) using TCP. If you want to make your SOAP scripts accessible only on your LAN, configure your LAN’s firewall to drop TCP packets that originate from outside your LAN where the destination address is the SOAP-Server.
If the SOAP-Server manages sensitive data, you should consider installing only SOAP-Server on the computer, and turning off other nonessential services. This helps reduce the attack surface of the computer and minimizes the number of dependencies on other features over which you may have little control.
It might not be obvious, but this documentation was generated by reviewing a threat model. Here’s a portion of the threat model. Each threat below matches a paragraph above.
The SOAP-Server process runs as the ISOAP_machinename account, which might have more capabilities and privileges than required by some applications, leading to potential elevation of privilege attacks. The threat is low but real.
Data between the client and server is not secured from information disclosure or data-tampering threats. The administration tools allow the user to enable SSL/TLS, but it’s not the default.
For ease-of-use reasons, we do not require authentication to access a SOAP-Server, nor do we restrict access to the system to certain IP or DNS ranges. We simply cannot do this anyway; we don’t know ahead of time what the user’s policy is, and we don’t know whether the user has a firewall. We should consider a setup wizard in the next version to ask the user.
We do not have the bandwidth to test SOAP-Server with every conceivable service and application that could run on a Microsoft Windows .NET Server 2003 computer. For all we know, some service could require a capability that would render a secured SOAP-Server horribly insecure.
Good error messages give notification that a problem occurred, an explanation of why the problem occurred, and a solution so that the user can fix the problem. Good error message text is specific, user-centered, clear, consistent, and courteous. Writing good error messages is hard work, but it’s something that must be done right.
If you have received an error message that’s related to a security feature, chances are good that you found it confusing, it didn’t really help you understand the security problem, and you had no idea how to respond correctly. A good question to ask is, Why are security-related error messages so often bad? By "error messages" I really mean all classes of message boxes, including warnings, confirmations, questions, and status. Much of this information applies to log file entries as well. This portion of the book explores the challenge of writing messages for security-related features. I’ll explain the difficulties in designing good security message text and the information that’s required for a good security message, and I’ll give some tips for designing and presenting security-related messages.
Figure 24-1 shows a typical example of a bad security confirmation message.
This message is a notification and has something resembling an explanation. The user can proceed to view the page by clicking Yes or can avoid some vague security risk by clicking No. Allow me to show you in Figure 24-2 what the user just saw when she read this error message.
So why is the first message bad? The message asks a question that the user cannot possibly answer intelligently. The user has requested that Microsoft Internet Explorer display a page, and this message implicitly advises against loading the page through the wording of the text and by highlighting No as the default choice. The specific security risk that the page poses is not sufficiently explained, so the downside of continuing is unclear. In short, this message is bad because it doesn’t give the user enough information to make a good decision. Consequently, the message fails to be useful.
In general, you want to make error messages as specific and helpful as you can. For security features, specific and helpful information sometimes has an alternative description: information disclosure. Information disclosure occurs when private information is exposed to users who aren’t supposed to see it. It is one of the six main security threats to avoid when designing secure software.
If you pay close attention to error messages, you might have a hard time believing that some of them are too helpful. Let’s work through a basic example.
Suppose you enter the wrong password when logging on to your computer. Even though Windows could determine exactly what is wrong with the password, giving such specific information would disclose information about the password. Because passwords are secure only if kept secret, they should never be revealed or described in any way. Consequently, rather than giving specific information about what is wrong with the password, Windows gives the message shown in Figure 24-3.
This message is a good example of how to give a helpful error message, even when dealing with sensitive data. It presents
A notification that a problem occurred (an incorrect password).
An explanation about why the problem occurred (by implicitly stating that the password was typed incorrectly).
A solution so that the user can fix the problem (by retyping the password, paying special attention to case sensitivity).
And no sensitive data is leaked.
A good security message can give additional helpful information to the user as long as it doesn’t reveal anything private. It’s fair game to disclose general information about Microsoft Windows, the application giving the message, or common user mistakes. In this case, the message reminds the user of a common mistake of typing the password by using the wrong case, such as when the Caps Lock key is pressed.
It is also acceptable to give information that can be readily obtained from other sources, such as thorough documentation or trivial experimentation. Consequently, documented facts such as the permissions or privileges that are required to perform a task are safe. If the user doesn’t have permission to perform a task, the fact that he cannot perform the task reveals this information, so this lack of permission can be explained in an error message without jeopardizing security.
When necessary, a security message can disclose private information on a strict "need to know" basis. Microsoft Internet Information Services (IIS) used to display syntax errors with an error page that showed the problem as well as an excerpt of the offending source code to all users. Such error messages give too much information to attackers. A much better approach is to give this specific information only to those who need to know it (in this case the application developer) and give a generic error message to all other users. IIS now uses this approach.
We can’t blame all bad security messages on trying to prevent information disclosure. Consider the dialog box in Figure 24-4 which is on my list of my most loathed dialogs.
Aside from a default choice of No, this message gives the user no clue what to do next. In fact, it isn’t even clear what the user is being asked to do. As with the first example, this message is asking a question that the user cannot possibly answer intelligently. There is plenty of data here, but what does it all mean? Based on the information presented in this message, why would the user choose Yes? Why would the user choose No?
More Information
I asked my wife what she thought this dialog box means, and she informed me she had no idea. I then asked her which button she would press; once again she had no clue! So I pressed further and told her that clicking No would probably make the task she was about to perform fail and clicking Yes would allow the task to succeed. Based on this information, she said she would click Yes because she wanted her job to complete. As I said, don’t rely on your users making the correct security decision.
If a message is asking the user a security-related question, at the very least it must give the user enough information to make an intelligent decision. This principle is often referred to as informed consent. To make an informed choice about a security issue, the user needs enough information to answer the following questions:
What is this message really asking me to do? How does it relate to the task I am trying to perform?
Is the security issue significant or minor?
If I select the secure choice, what will I not be able to do?
If I select the insecure choice, what is the worst that can happen? What is likely to happen?
If I answer incorrectly, can I fix the problem later? If so, how?
What is the choice recommended by the program? Why?
Resolving a security question without informed consent has no value. Most users know little about security and trust decisions, they just want to get the job done safely; this can be true even for system administrators in all but the largest organizations. When writing security messages, don’t assume that the user is a security expert unless your program is clearly targeted at security experts.
Figure 24-5 shows an improved version of the Root Certificate Store message that helps the user answer most of the questions.
Sure, this is a large message box, but it now clearly explains the question being asked, the security consequences of the action, and what exactly will happen as the result of the decision. There is no benefit to showing anything less.
A problem with informed consent is that it usually requires presenting a lot of information to the user—often too much, in fact. The last example presents the minimum amount of information required, but it still lacks crucial information. Specifically, there is no information on how to validate the certificate, and all the gory details that were presented in the original message are now lost.
The best way to present all the information without overwhelming the user is to use progressive disclosure. The base message should have the essential information required for the user to answer the error message question intelligently. Any supplemental information that the user might need should be made available on demand through a hyperlink, a Details button, a More Information button, or a Help button.
Here in Figure 24-6 is a version that uses progressive disclosure to help the user validate the certificate.
Most messages can be improved by making them more specific. This is certainly true for security messages. Let’s take another look at the first example of a bad security-related confirmation message. Refer to Figure 24-1 before reading on.
As mentioned previously, the message in Figure 24-1 is bad in part because it is completely vague about the security risk at hand. Let’s fix this message by making it more specific, as shown in Figure 24-7.
This version has a specific example of the most common security risk the user might encounter and provides a hyperlink to get more information about the risks and specific advice on how to answer the question.
Yes, it’s more text. Yes, some users aren’t going to read it. But the text isn’t excessive, and the essential information that the user needs to answer the question is offset in bold text to make it easy to scan. If the user is unfamiliar with the concept of the question, the hyperlink is available. Most importantly, the user can clearly understand what the security risk is (disclosure of sensitive information) and has a simple criterion upon which to base an intelligent decision. The question of whether to continue is now worth asking.
Security messages can’t always be expressed in three simple sentences. Being concise is an important goal, but for security messages it should not be the primary goal.
The principle to remember is that security issues already fluster users, and most of the security messages that users are likely to see are variations on this question:
We have found a security issue. Do you wish to proceed securely with impaired functionality or do you want to get your work done?
Users are going to want to get their work done unless presented with an excellent reason not to. Vague statements are rarely motivating, and they totally undermine the value in asking the security question in the first place. Be as specific as you can, without revealing private information.
There is a strong argument for avoiding security-related questions in the first place, because users simply don’t make good trust decisions. But what are the alternatives? One obvious approach is to not ask the question. This is the preferred approach when you are all but certain that you know the right thing for the user to do.
For example, if a user removes a certificate by using the Content tab of the Internet Explorer Internet Options dialog box, a confirmation message could ask if he also wants to remove the associated private key. The Windows security team at Microsoft realized that deleting the private key is always the right thing to do, so they decided not to bother asking. That’s one less bad security message.
Another approach is to use a high-level security policy instead of asking individual low-level security questions. This is the approach used on the Security tab of the Internet Explorer Internet Options dialog box shown in Figure 24-8.
This approach works well because users understand their goals (such as Safe browsing and still functional) far better than they understand security details. Focusing on the user’s goals is an important principle that should be applied to all security messages. Furthermore, having a high-level security policy in place requires less interaction from the user, so the user is less likely to make bad decisions or consciously try to bypass security measures. This goal-based approach could be implemented by other applications as well.
When your team decides that a security message is necessary, be sure to usability test it with your target users early in the development cycle. This step is extremely important because the users’ notions of security are often quite unpredictable. Here are some things to check for:
Did the users understand the context for the message?
Did they understand the message text?
Did they understand the security risk?
Did they obtain all the information required to respond intelligently?
Was the information helpful or confusing?
Did they bother to check any supplemental information?
What decision did they make? Why?
Are they confident that they made the right decision?
Did they understand the consequences of the decision?
Was the decision correct under the circumstances?
When designing security messages, be sure to supply enough information so that users can respond intelligently, but make sure you aren’t revealing any secret information in the message. Use progressive disclosure so that you don’t overwhelm the user with information. Consider design alternatives that might allow you to eliminate the message entirely. Lastly, be sure to usability test your security messages to make sure you’ve got it right.
No doubt as a documentation person you will review product specifications to determine how best to document features in a secure manner. The following list outlines some aspects of the specification that require you to document security ramifications:
The specification outlines customer security holes addressed in a code or design change.
The specification describes architectural details from which an attacker could deduce security holes.
The specification talks about design compromises made to accommodate legacy functionality that could be insecure.
The specification gives multiple ways of doing something but is silent about which of them is more secure.
The specification describes a scenario in which the new feature will not work unless security is downgraded.
The specification assumes that features elsewhere are turned on but does not address security implications.
You should carefully and accurately document the security ramifications of any of these notes.
Although error messages are the majority of the security user interface issues for most applications, many applications have a configuration tab for security settings, and some applications deal primarily with security. Security settings are often challenging to explain, especially to end users, but it is critical that you expend extra effort to make your security settings understandable.
Let’s look at an example. If you’re running Windows XP or Windows 2000, open the Control Panel, choose the Administrative Tools, and finally double-click Local Security Policy. Take a look around and you’ll see lots of settings you can make that can make your system much more (or much less) resistant to an attacker. Open up the folder named Local Policies, and select Security Options. Lots of interesting stuff: what’s it all mean? Say you might want to set Do Not Allow Anonymous Enumeration Of Accounts And Shares under the Network Access section. What implications does changing this have? What could break? What does it really restrict? If I right-click it and choose Help, it directs me to the Security Settings topic. Drilling down into the help system from there leads me to a nicely written help topic that explains the setting.
Another consideration is placing frequently used security settings in an accessible place. If something is important, forcing the user to go through several dialogues and menus to get there means that the feature simply won’t be used. Subject your security features to the same level of usability testing that you do the rest of your application.
Enterprise security usability presents even more challenges. I’ve seen cases where it is quite easy to secure one server, but securing 1000 of them is anywhere from painful to nearly impossible. Features that allow large numbers of systems to be administered easily are going to have to be built in early in the design phase, but this should never be neglected. Consider creating an administration console similar to the Active Directory security policy settings where systems can be grouped and administered uniformly. Additionally, large numbers of systems are frequently administered with small applications and scripts—make sure that you expose remotely accessible interfaces that can be used programmatically.
We’ve managed to create software that most people can use without training—we need to create software that ordinary people can secure. Let’s make security user-friendly.
In this chapter, I covered two important and often overlooked aspects of delivering secure systems to users: the documentation of security features and the error messages presented to users. No matter how good the system is, many decisions about the day-to-day functioning of an application are made based on the information displayed on the screen and documented in Help. If that information is poor or incorrect from a security perspective, it is unlikely the administrators of the application will run the application in a continually secure mode.