## How to add a protocol to the repository

If you know a protocol that you would like to be added to this repository, you can submit it at the following address: florent.jacquemard@lsv.ens-cachan.fr.

You will be notified when the protocol is added. We prefer to moderate contributions, to avoid html errors and also to allow the contributions of interested people who are willing to add a protocol but do not have the time to format their contribution in the language in which our protocols are stored.

We describe below two ways to write a contribution to the security protocol open repository:
• The first method, writing a contribution in plain text, prevents the contributor from the latex formatting but implies more work to the moderator!
• The second method, writing a contribution in latex format, is recommended for latex users.
Please note that in both cases, some fields of the contribution are required, when they are necessary to ensure the coherence of the repository.

### Plain text contributions

The format-free contribution should follow the plan of a protocol description.

In particular, the messages of the protocol may or may not conform to the common syntax, this must be indicated in the contribution.

It is also necessary to add precise bibliographical pointers to the contribution, at least one for the section References. For this purpose, we recommend the bibtex format.

### Contributions in LaTeX

The protocols of the repository are internally stored as LaTeX (.tex) files, and are later converted both to html, postscript, pdf or plain text formats using general tools like hevea, latex, pdflatex and a collection of scripts.

Hence, it is recommended to send contributions in this format, especially for experienced LaTeX users. You may find below the resources necessary to write a LaTeX contribution, and a description of the LaTeX macros used in protocols descriptions.

#### Contents of a formatted contribution

To submit a protocol in latex, you will need to send us two files:
• a latex file protocolName.tex with the protocol description, using the environments and macros presented below,
• a bibtex file splib.bib containing the bibtex entries cited in protocolName.tex.

#### Example files

For the purpose of illustration, we make available to download the latex source of every protocol description of the repository in the page of the protocol (see the header description).

An generic example of .tex file can also be downloaded here, and you can see the result in html at this page. You may also wish to download the following template.tex that you will be able to fill with your contribution.

#### Style file

If you want to check that your contribution can be proceeded in the security protocol open repository, and to have an idea of its final rendering, you can follow the procedure described here.

Note however that this verification is not required for contributing to the security protocols open repository.

#### Preamble

You can write whatever you like before `\`begin`{`document`}`. However, be aware that not all latex commands are supported by hevea, which is used for html formatting.

#### Document

Between `\`begin`{`document`}` and `\`end`{`document`}`, comes the protocol description, in a protocol environment. The description is formatted, each section being defined by a latex environment. The environments should appear in the order in which they are listed below.

NB: Some environments are optional but every environment, except remark, must occur at most once in the document.

#### Environment protocol(mandatory)

This environment is opened by the following command, with 6 parameters:
`\`begin`{`protocol`}``{`title`}``{`author`}``{`date`}``{`editor`}``{`submitted`}``{`last change`}`
The mandatory parameters must have a non empty value, the optional parameters can be empty but the braces `{``}` must always be written. For instance, in `\`begin`{`protocol`}``{`title`}``{`author`}``{`date`}``{``}``{``}``{``}`, the editor's name, the date of submission and the date of last change are omitted.

The parameters which are dates must by given in the format `dd/mm/aaaa`, or `mm/aaaa`, or `aaaa`.
`{`title`}` (mandatory)
The name of the protocol. This name will be printed at the beginning of the documents concerning the protocol (html, ps, pdf...) and will also figure in the first column of the protocol index.
NB: the parameter `{`title`}` must contain no latex commands (beginning with backslash).

`{`author`}` (mandatory)
The list of the names of the authors of the protocol.

`{`date`}` (optional)
The date of the first publication of the protocol.

`{`editor`}` (optional)
The name of the person submitting the protocol.

`{`submitted`}` (optional)
The date of the submission.

`{`last change`}` (optional)
The date of the last change on the submission. This parameter is for the moderator of the repository and hence should be either empty or equal to `{`submitted`}` in submissions.

#### Command `\`crossref

Reference to another protocol, of the form:
`\`crossref`{`label`}`
The parameter `{`label`}` is the prefix of the file name of a protocol of the repository. The labels definitions can be found in the file all.aux, in the following form:
```\newlabel{filename}{{title}{0}}
```
Where:
`{`filename`}`
is the label
`{`title`}`
is the title given in the first parameter of the environment protocol. Its value will be the text of the reference link in the html version of the protocol.

#### Environment abstract(mandatory)

Between `\`begin`{`abstract`}` and `\`end`{`abstract`}`, should be written a short description of the protocol goals (authentication, key exchange...) and of the protocol needs in term of cryptographic functionalities (symmetric or public keys algorithms, one-way functions, server...).

#### Protocol specification

The protocol messages can be specified in one of the two following environments, corresponding to two formats:
• in the environment verbcore, the protocol specification is give verbatim,
• in the environment core, the protocol specification must follow a particular syntax defined below.
NB: Every protocol latex file must contain one of the environments verbcore and core, and must not contain both. Moreover, there must be no more than one environment verbcore or core in a protocol tex file. Otherwise, the construction of downloadable files will fail.

#### Environment verbcore(mandatory)

In this environment, the protocol specification can be written in a free format, and will be printed verbatim in both html and postscript/pdf versions.

This environment has been defined to permit the contributer to write protocol specification that do not fit in the syntax for the environment core, described below. It is recommended to use the environment core as long as possible.

#### Environment core(mandatory)

This environment contains the specification of the protocol messages, in a syntax that will produce the format defined here. One processed, the protocol messages will follow the syntax defined in the page describing the protocols format.

The section core is composed of the two subsections declarations and messages.

#### Environment declarations(optional)

According to the syntax defined below, the contents of protocol messages shall be build using 3 constructors (tuple, crypt and apply) and protocols variables. These variables can be typed in the protocol specification, up to the submitter, and in this case, the type declarations are given in this environment declarations, using the command `\`dcl.

#### Command `\`dcl

This command is used to write a type declaration for protocol variables:
`\`dcl`{`v1,...,vn`}``{`type`}`
`{`v1,...,vn`}`
v1,... ,vn are identifiers that occur in the protocol messages or as sender or receiver of messages (also called protocol principals).
`{`type`}`
the value of type must conform the syntax described here.
Note that there are no restrictions on the basic types names.

#### Environment messages(mandatory)

This environment contains a sequence commands `\`msg (protocol message) and commands `\`action.

#### Command `\`msg

This command is used to specify a protocol message, and shall be called with the following parameters:
`\`msg`{`label`}``{`sender`}``{`receiver`}``{`contents`}`
`{`label`}`
the label of the rule is any alphanumerical string that is not a protocol identifier declared in the environment declarations.
`{`sender`}`
the sender is an identifier declared in the environment declarations.
`{`receiver`}`
the sender is an identifier declared in the environment declarations.
`{`contents`}`
the message body must conform to the messages syntax.
NB: The parameters contents are printed verbatim, hence, do not write latex commands except those described below in these parameters, in particular, do not use math mode.

The commands `\`crypt and `\`tuple can be used to write the message `{`contents`}`.

Every command `\`msg produces a line in the protocol specification. If you want to write the contents of a message on several lines, you can use a sequence of `\`msg commands of the following form:
`\`msg`{`label`}``{`sender`}``{`receiver`}``{`first line of contents`}`
`\`msg`{``}``{``}``{``}``{`second line of contents`}`
...
Some intermediate instructions like conditional branching or variables affectations, can be inserted between two messages with the command `\`action, in order to clarify some actions taken during the protocol execution.

#### Command `\`crypt

This command ciphers, i.e. terms associated with the non-terminal cipher in the syntax definition. It is used as follows:
`\`crypt`{`message`}``{`key`}`
Nested occurrences of the command `\`crypt are allowed in both parameters `{`message`}` and `{`key`}`.

#### Command `\`tuple

As described in the syntax definition, the tuple must be written by default without parentheses, and their elements, separated by commas, are assumed to left associated.

Explicit parentheses for tuples must be written as follows:
`\`tuple`{`commas separated elements`}`

#### Command `\`action

This command can optionally be inserted between two messages to describe actions taken by the receiver of a message, a conditional branching etc. It is called by:
`\`action`{`text`}`
where the syntax for the `{`text`}` is free.

#### Environment remark(optional)

This environment can be added after any other environment to write an additional comment. This comment will be highlighted in the final documents with a title of the same size as the others sections.

#### Environment explanation(optional)

This section contains some additional information about the protocol variables, the initial conditions, the treatment of received messages and the construction of new message by principals, the flow control of the protocol execution... and in general anything that can explain that is not explicit in the protocol specification.

Some equational axioms for functional identifiers can also be given here.

For sake of clarity, the explanations must refer to the protocol identifiers contained in the environment messages (and optionally declared in the environment declarations). We recommand to change the font for these identifiers using the command `\`code.

#### Command `\`code

`\`code`{`text`}`
The contents of the `{`text`}` parameter are printed in the font used in the protocol specification (in typewriter style).

#### Environment property(optional)

The requirements that have to be fulfilled by the protocol, written in natural language.

#### Environment references(mandatory)

This environment must contain a citation (with command `\`cite) of the the paper in which the protocol has been first published and also optionally tutorials or surveys presenting the the protocol.

The papers studying the protocol must not be cited here, but rather in the environments proofs and attacks.

#### Command `\`cite

This is a standard latex command.
`\`cite[note]`{`label`}`
The parameter `{`label`}` must correspond to an entry in the bibtex file included in the contribution (see above).

#### Environment proofs(optional)

We can have here citations (with `\`cite) of the works providing a formal proof of correctness of the protocol, or at least of one of the requirements cited above.

#### Environment attacks(optional)

We cite here the works which demonstrated a vulnerability of the protocol, with respect to one of the requirement cited in the environment property.

Sometimes, one (or several) scenarios of attack can be found here. A scenario is a sequence of messages, possibly involving 2 or more interlaced sessions of the protocol, written in the same syntax as the protocol specification, i.e. inside an environment messages with commands `\`msg.

Following the syntax in use in the Clark and Jacob survey [CJ97], we use two special constructors for the sender and receiver names in order to describe a specific action of a malicious agent (the intruder I):
• the eaves dropping by the intruder I of a message:
`\`msg`{`label`}``{`sender`}``{`I(receiver)`}``{`message contents`}`
• the sending of a message by the intruder I, with impersonation of another principal sender:
`\`msg`{`label`}``{`I(sender)`}``{`receiver`}``{`message contents`}`

#### Environment see(optional)

This optional environment can contain references to other protocols of the repository, written with the command `\`crossref.

## Citations

[CJ97]
John Clark and Jeremy Jacob. A survey of authentication protocol literature : Version 1.0., November 1997. http://www-users.cs.york.ac.uk/ jac/papers/drareview.ps.gz

This document was translated from LATEX by HEVEA.