linux-ipsec: syntax conventions, part 1

Here's the beginnings of an attempt to clean up our command/output syntax, in reaction to usability problems we found in Raleigh. More later today -- I have to run right now, but promised I'd get this started.

All comments are welcome.

                                                          Henry Spencer
                                                       henry@spsystems.net
                                                     (henry@zoo.toronto.edu)

Henry Spencer

v1, 18 March 1998

This is an attempt to set down some rules for how our interfaces look and behave. I don't expect that everything will conform to it immediately, although I hope we can keep the transition period short. It's not final; comments and criticisms are welcome.

Principles

I've tried to follow a few basic principles here. Syntactic entities should be self-describing as much as possible. Related items of data should be grouped together. Syntaxes using shell metacharacters should be avoided, to simply use of cut-and-paste interfaces. For the same reason, input and output syntax should be identical.

Having precisely the optimal syntax in any particular context is not nearly so important as keeping the syntax consistent so that people don't have to learn separate rules for each context.

Do you need help?

In addition to our free technical library, Pantek provides professional IT services to companies who utilize Open Source software: Learn more about Pantek's Technical Support offerings Place an order for 24/7/365 Technical Support here Learn more about Pantek, who we are, and what we do Chat with a Live Operator Related lists.freeswan.org Links 1998-fall 1998-spring 1998-summer 1998-winter 1999-winter announce briefs bugs design freeswan-list hipsec ietf-sectest users users-admin Request more information about Pantek

Basic Syntax

Octal values, should we have cause to use any, are always written with a leading zero. Decimal values never have a leading zero. Hexadecimal values always have a leading 0x. Input recognizes alphabetic hex digits
(and the x in the 0x prefix) in either case, but output is always in
lowercase.

Attempts to guess the base of an input value are to be avoided, even when it is clear from context (e.g., keys are almost invariably hex), because guessing does not really do the user any favors: a guesser either makes errors on some inputs or rejects them as ambiguous, and the former is unacceptable and the latter can break scripts which have naively come to rely on the guesser. Insisting that the user always specify his intentions explicitly is better.

Precisely which base is used for output depends on circumstances. Values which are bit fields, like key data, should generally be in hex. Most other values -- SPIs, lifetimes, port numbers, etc. -- should be decimal.
(Note that integer values should be output as unsigned numbers unless the
semantics of that particular value dictate that it is signed.) It is important that all, repeat all, output obey the base-syntax conventions, so that it can be re-used as input.

Codes (enumerations selecting, e.g., encryption algorithms) and flags
(where each bit of a bit field has a separate meaning) should consistently
be dealt with as names, not numeric values. Names should always be recognized on input and generated on output. In the event that a value which does not match any known name is encountered on output, hex (with a leading 0x) should be used so that some visible output is produced. When a flags field contains an unknown flag, the rest of the flags should be output as names as usual -- only the unknown one should be produced as hex. If all this is done consistently and correctly, there is no need for output to also include a numeric value, although *debugging* output might continue to do so just in case.

Flags fields with more than one bit set are written with the flag names separated by commas. White space after commas is ignored on input; output does not include any white space (so that a flags field will go in a single command argument without quoting). Flag order is not significant on input, and on output it should be consistent in all places where a given set of flag bits is being output. In the absence of any specific reason to do otherwise, I suggest working from right to left in a flags field (because new flags tend to be added on the left and it's probably best if new names appear on the end in the output). [I am not convinced that this particular order is best -- comments? Is there significant left-to-right existing practice that we should conform to? I do think it is desirable to recommend a specific default order.]

Code/flag names should always contain either a hyphen or at least one non-hexadecimal letter. Attempts to allow ad-hoc shortening of names by guessing the expansion are to be avoided, for the same reason as for base guessing: when new names are added and old short versions thus become ambiguous, the guesser has a choice between making errors and rejecting some formerly-valid inputs, and neither is satisfactory. Desirable abbreviations should be defined as separate names. Abbreviations for flag bits may include multiple bits, to allow common combinations to be set conveniently, but output should always use the individual bit names.

Code/flag names are case-insensitive on input. Output should always use lowercase.

Do you need more help?

In addition to our free technical library, Pantek provides professional IT services to companies who utilize Open Source software: Learn more about Pantek's Technical Support offerings Place an order for 24/7/365 Technical Support here Learn more about Pantek, who we are, and what we do Chat with a Live Operator Related lists.freeswan.org Links 1998-fall 1998-spring 1998-summer 1998-winter 1999-winter announce briefs bugs design freeswan-list hipsec ietf-sectest users users-admin Request more information about Pantek

[I am tempted to suggest that there should be a /proc/net/ipsec/names or something like that, so that applications can read the kernel's code/flag names and their definitions from there rather than having to have an independent compiled-in list. (The kernel has to have its own list so it can use them in /proc.) Is this a good idea, in the long run?]

IPv4 Addresses Etc.

A single IPv4 address can be written on input as a DNS name, a dotted-quad address (four decimal numbers, without leading zeros, separated by single dots), or a hex number (with leading 0x or 0X) (heaven knows why anyone would want this for addresses, but see below). Output should always be in dotted-quad format. Parsing software should be aware that DNS names can begin with a digit, and that there are even some existing DNS names with all-numeric components, e.g. "1776.com". It is acceptable to reject a DNS name whose first component looks like a hex number.

An IPv4 subnet mask syntactically is like an address, with the addition that if it is written as a single decimal number, that stands for a 32-bit value with that many high-order bits on. On output, this notation should be used unless the mask cannot be written that way.

An IPv4 subnet is written as an address and a mask separated by a slash (/). Note that either part of this can be in any of the acceptable forms, e.g. one could have a DNS name as address and a hex number as mask. It is an error for any of the 0 bits in the mask to be 1 in the address.

A range of IPv4 addresses is written as two addresses separated by a pair of dots (..). This may not be the best notation, but it's easy to write and avoids problems with some alternatives (e.g., hyphens can occur in DNS names).

It will probably be necessary to store and manipulate IPv4 addresses in host order, not network order, so that range inclusion can be tested efficiently.

Port numbers, protocol numbers, etc. may be input either as numbers
(preferably decimal) or as names taken from the appropriate name list
(e.g. /etc/services for ports). Output should be by name when possible,
by decimal number when not (name list unavailable or number not in list).

Can we help you?

In addition to our free technical library, Pantek provides professional IT services to companies who utilize Open Source software: Learn more about Pantek's Technical Support offerings Place an order for 24/7/365 Technical Support here Learn more about Pantek, who we are, and what we do Chat with a Live Operator Related lists.freeswan.org Links 1998-fall 1998-spring 1998-summer 1998-winter 1999-winter announce briefs bugs design freeswan-list hipsec ietf-sectest users users-admin Request more information about Pantek

Tuples

For a number of purposes, it is desirable to group individual values into syntactic entities that can be manipulated as a whole. An obvious example is grouping a destination address and an SPI together to identify an SA; a less obvious one is grouping a key and an IV together to specify setup parameters for an encryption algorithm.

A tuple is formed out of values by separating them by color (:) or newline. (Why would you want to use newline? Read on...)

An empty value within a tuple (a : following another : or at the end of the tuple) indicates the use of a default value, determined by context and not necessarily zero. (For example, the default value of an IPv4 subnet mask should probably be 32.) Trailing colons can be omitted.

[I am not entirely happy with the use of colon here. I would have preferred to use slash. But that makes life very difficult when a subnet is part of a tuple -- especially if the subnet could also be written as an address range -- and the use of slash in subnet notation is too well established to mess with. I couldn't make it work with slash, although I'm still thinking about it.]

If a command argument (etc.) is written as @ immediately followed by a string, that means that the real argument is the contents of the file named by the string. This is provided so that sensitive information like keys can be read by a route which is not open to inspection by "ps" and similar programs. Note that this is why newlines are accepted as value delimiters within tuples, so that bulky information can be split over multiple lines in such a file.

Wildcards

Given the special significance of "*" to the shells, "any" should be used when a way to write a wildcard value is needed.

Can't find what you're looking for?

In addition to our free technical library, Pantek provides professional IT services to companies who utilize Open Source software: Learn more about Pantek's Technical Support offerings Place an order for 24/7/365 Technical Support here Learn more about Pantek, who we are, and what we do Chat with a Live Operator Related lists.freeswan.org Links 1998-fall 1998-spring 1998-summer 1998-winter 1999-winter announce briefs bugs design freeswan-list hipsec ietf-sectest users users-admin Request more information about Pantek

The IPSEC drafts use "opaque" in some places to refer to values that are hidden by encryption. While "opaque" should be accepted in such contexts, "hidden" is a better way of expressing the concept, and is our preferred way of writing this. [I have doubts about supporting two different ways of writing this, but "opaque" is just too damn cryptic. Comments?]