SCAN Conventions


These documents use the terms "MUST", "SHOULD", and "MAY", and their negated forms, as defined in RFC 2119. These terms apply to crypto algorithm and library implementations that are intended to conform to some subset of SCAN.

In addition, the terms "WILL" and "WILL NOT" specify consistency requirements and policies for SCAN itself. If it is stated that something WILL be true, but it is not actually true, please report it as an error. New SCAN entries or changes to existing entries must satisfy all WILL and WILL NOT constraints.

The term "byte" always refers to an 8-bit byte, or octet. The value of a byte is an integer between 0 and 255 inclusive.

In algorithm descriptions,

Algorithm Interfaces

The inputs and outputs of algorithms (plaintext, ciphertext, keys, input messages, etc.) are normally sequences of bytes. However, in the case of some message digests the input may also be given as a sequence of bits, as explained here.

If it is insufficiently clear from the algorithm specification how the inputs or outputs are to be interpreted as sequences of bytes, the algorithm comments WILL clarify this.

Unless otherwise specified, all hexadecimal-format test vectors that are referenced by SCAN should be assumed to be written from left to right. That is, each test vector represents a sequence of bytes where:

Unless the specification of an algorithm describes any of its inputs or outputs in terms of bit sequences, the order of bits within a byte is not, and does not need to be defined. If you are designing an algorithm, suggestions about byte and bit order, among other issues, are given here.

Categories for References

References WILL be marked as being in one or more of the following categories:

Note that the [Patent] references cannot be guaranteed to include all applicable patents.

Security implications

Unless stated otherwise in the "Security comments:" sections, nothing is implied about the security of an algorithm simply by it having an entry in SCAN. The security comments represent the opinions of the author(s) (or any other people who are quoted) only.

There may be published attacks that are not listed in the security comments or references. If you know of any such attacks, or if you want to dispute something said in these comments, please post to sci.crypt.

References to papers describing cryptanalysis of an algorithm should not be taken as necessarily implying that the algorithm is broken (often, a paper provides support for an algorithm rather than an attack on it, and attacks may or may not be practical).

Algorithm Parameters

Some algorithms have parameters, each of which which WILL be marked as one or more of "write", "read", and "creation". A "write" parameter can be set, and a "read" parameter can be read, after the algorithm object has been created (provided that whichever API is being used supports that).

Any parameters given in parentheses following the algorithm name WILL also be listed as "creation" parameters, and can be specified in the call used to create the algorithm object (in Java, as part of the name passed to getInstance). If there is more than one creation parameter, they are separated by commas, with no whitespace.

For example, the Java code:

will create an object that implements the HMAC message authentication code, with "SHA-1" as the value of HMAC's digest parameter. When a creation parameter refers to an algorithm, that algorithm may itself be parameterized, for example:
An algorithm that depends on one or more other algorithms (as HMAC does in the above examples) is called a "construction".

Adding New Algorithms

If you would like to add an entry to the list, please post it to the Usenet newsgroup sci.crypt, with a subject line that includes "SCAN". The post should give the text of the proposed entry, in the same format as other algorithms of the same type, and ideally should include:

If some of this information isn't available for existing algorithms, post anyway; other people on the newsgroups may know where to find it.

sci.crypt should also be used to discuss corrections and additions to existing entries. (I prefer to handle these on newsgroups rather than via email, as it is important to get other cryptographers' comments about changes.)

Algorithm status and stability

Each SCAN entry (not including alleged algorithms) is classified and colour-coded as one of:

 • Blue - stable
 ? Green - provisional
× Red - experimental

The symbols '•', '?' and '×' give the same information as the colour-coding. (If you don't see blue, green and red text above, or if '•' or '×' display as boxes, see the browser problems section below.)

During the early stages of the development of SCAN, there have been a number of incompatible changes to algorithms (all of which are clearly marked in the comments for the relevant entries).

However, when SCAN version 1.1 is published, the policy from then on WILL be that once an algorithm has been accepted as stable, it can never change - not even if the change is apparently backward-compatible. Any revisions WILL be handled by assigning a new algorithm name. Also, a stable algorithm WILL NOT be able to change its status to provisional or experimental. There will be absolutely no exceptions to this policy.

Note that this does not mean that the entry describing the algorithm cannot be modified, e.g. to add new papers, clarifications, or security comments. Also, stable algorithms can still be generalised by adding extra creation parameters. For instance, a block cipher named "Foo" could be generalised to "Foo[(rounds)]", where (rounds) indicates the number of rounds to be used.

Provisional and experimental algorithms, on the other hand, can be removed from SCAN or changed incompatibly at any time. An algorithm is marked as provisional either because some required information (most commonly test vectors) is missing, or because the document(s) that define the algorithm have draft or similar status. I will attempt to avoid incompatible changes to provisional algorithms, but it is always possible that when the missing information is found, it may expose a problem that requires a change.

For experimental algorithms, no effort to avoid incompatible changes is implied.

The rationale for forbidding even backward-compatible revisions (apart from generalisations) to stable algorithms is as follows: the JCA API (and any other API that may be adopted for languages other than Java) makes use of a list of security providers configured by the user or administrator, in order from most preferred to least preferred. When an algorithm name is looked up without specifying an exact provider, the first provider in preference order that supports the algorithm is used. If compatible changes were allowed, an implementation of an old revision of an algorithm might 'mask' an implementation of a newer revision by a provider later in the preference order, which is obviously not desirable.

Note that some of the citations in the "References:" sections are to draft standards. Where an algorithm is said to be "as defined in" a particular draft standard, the algorithm definition may change as the standard changes. Implementation or design based on these drafts is at the risk of developers (and users). Some of the referenced standards have a specific requirement that advertisements and documentation should not attempt to claim compliance with the standard until it has been finalized.

A SCAN entry that depends on a draft document as a [Def] or [Test] reference WILL NOT be marked as stable. If a reference gives a particular version number of a draft document, that means that the given version was the last one for which the specification of the particular algorithm has been checked. It does not mean that later drafts should not be used when implementing the algorithm.

All stable algorithms WILL have test vectors, unless the algorithm is simple enough that there is clearly no need for test vectors.

Alleged Algorithms

At the end of each category page (e.g. MessageDigest, Mac, etc.) there is a list of "alleged algorithms", most of which are linked to either an on-line reference, or a page number in the Handbook of Applied Cryptography (HAC) or Applied Cryptography, 2nd edition (AC2).

These lists are purely informational. The entries typically will not include any details of any parameters that would be needed, and in some cases may not even be sufficient to identify the algorithm.

Please note that alleged algorithms may be:

in (almost :-) any combination. You have been warned.

Of course, I'm still interested in comments or corrections for these sections, as with any other part of SCAN.

Provisional Algorithm Names

I don't think anyone was using provisional algorithm names, and the "Other alleged algorithms" lists (see above) now allow algorithms to be minimally documented even if they do not meet the criteria for a proper SCAN entry. Therefore, the convention using DNS domains that was previously described here should not be used.

Just in case, the guarantee that standard names WILL NOT contain a colon (':') character still applies.

ASN.1 Object Identifiers

Where there is an ASN.1 OBJECT IDENTIFIER for an algorithm, the dotted-decimal form of the identifier can be used implicitly as an alias. These aliases WILL be the only names that match 'oid' from the following ABNF syntax (which is a subset of that given in Section 2.15 of RFC 1778):

    oid       = number *("." number)
    number    = "0" | (leaddigit 1*digit)
    digit     = "0"-"9"
    leaddigit = "1"-"9"
Note that other names may start with a digit, but WILL NOT match the syntax above.

Names as Programming Language Identifiers

Most programming languages have fairly restrictive syntaxes for identifiers; typically some superset of:

    identifier = letter *(letter | digit | "_")
    letter     = "a"-"z" | "A"-"Z"
    digit      = "0"-"9"
An identifier satisfying this syntax can be derived for each basic name (not including parameters) as follows: New names and aliases WILL be chosen so that this procedure always works, and is reversible (by replacing "_" by "-") to give a valid alias.

Conventions for symmetric ciphers

The information that was in this section has moved to the symmetric ciphers page.

Browser problems

To see SCAN as intended:

Viewing PDF and Postscript files

Most of the on-line references are in PDF and/or PostScript format. Versions of the Acrobat ReaderTM PDF viewer for several operating systems are available from Adobe's site:

Get Acrobat Reader

To view PostScript files, you will need GNU or Aladdin Ghostscript, and either Ghostview or GSview, all of which are available from here. Note that in at least some versions of Netscape, compressed PostScript files (with filetypes ending .ps.Z or .ps.gz), seem to be downloaded incorrectly when the link to a file is clicked on directly. If you encounter this bug, it can be worked around by right-clicking on the link, selecting "Save Link As..." to save the compressed file, and decompressing it manually (on Windows, use a decompression utility that understands .Z and .gz formats, such as Winzip).

Alternatively, the TOM Conversion Server is a very useful service for converting documents between different formats (you may find that the file upload option works if the URL conversion option does not).

Valid HTML 4.0 Valid CSS Copyright and trademark information