Genii Weblog

Civility in critiquing the ideas of others is no vice. Rudeness in defending your own ideas is no virtue.

Tue 20 Jun 2017, 02:19 PM
As software vendors or application developers or anyone else who documents software or processes, we often face the need to come up with an example. The goal of almost any example or documentation is to be simple enough for the uninitiated to grasp while being complex enough to show the possibilities. This is often accomplished with more than one example, so that we can show both how easy it is with one example and how powerful and flexible it is with another.

But there is an interesting question of responsibility raised by examples. Are we responsible for those people who just grab the example and go with it, even if they should be modifying it? A classic, and rather extreme, case might be when your example includes "YourServer" or "YourDB.nsf" or even "Firstname Lastname". While it might lead to an embarrassing support call, the implications of someone actually using such an example verbatim are slight. Most likely, the process or software won't work until they plug in an appropriate value.

There is one class of example which is different. This is the case of somebody using an example with a password or encryption key that is intentionally weak. I read today that 15% of IoT users leave the default password, and we have all known users who use 12345 as a password or key. While it is clearly the responsibility of the user to be more secure, do we have a responsibility to encourage security? It is not a simple question, as even if we do, and use a complex password or key, that password or key is usually static in the documentation, and so inherently insecure.

The following comes from the OpenSSL wiki. It comes with a clear warning not to use that key, which is good, but it intentionally uses one of very few weakest DES keys, which seems an odd choice. Since the user is not meant to type the example exactly, why not use a more random secure key? But if they did, would that be false security since it was static? In a perfect world, the key used in the example might be random and generated on the fly so that every viewer saw a different key. Then, if the example were copied and pasted, a "good" key would be used. But is that really the responsibility of the documentation writer? I don't know.

Inline JPEG image

Copyright 2017 Genii Software Ltd.