Commit db95da79 authored by Eric S. Raymond's avatar Eric S. Raymond

Conversion of the Mills HTML docs to asciidoc lands with this commit.

The intent is (a) to make these easier to maintain, and (b) to have just one
master format for all in-tree documentation.  The latter is not yet completely
accomplished, as various manual pages in the source directories are not
yet converted.

The conversion resembles the ancestral HTML pretty closely, using an
adaptation of Dave Mills's stylesheets to retain his look.  The
content has been verified to match by two reviewers.  The sppearance
is very similar, though not identical; asciidoc doesn't allow quite as
much freedom in image placement as raw HTML, and table boxes don't
look quite the same. The look of the command.txt and footer.txt
includes isn't completely right either.
parent 6190ec91
......@@ -38,12 +38,10 @@ clockstuff/:: Directory containing sources for miscellaneous programs
conf/:: Directory containing a motley collection of
configuration files for various systems. For example only.
html/:: Directory containing a complete set of documentation on
building and configuring a NTP server or client. The
documentation is in the form of HTML files suitable for
browsing and contains links to additional documentation
at various web sites. If a browser is unavailable, an
ordinary text editor can be used.
docs/:: Directory containing a complete set of documentation on
building and configuring a NTP server or client. The files
are in asciidoc markup. This replaces the 'html' directory
of precious versions, but html can be generated from it.
include/:: Directory containing include header files used by most
programs in the distribution.
......
......@@ -4,8 +4,6 @@
=== Code ===
* The waf build needs to be landed and solid.
* clock_gettime() is a minor porting issue that may need a shim on
some target platforms. Gary Miller removed a little too quickly some
shims present in NTP classic; these may need to be reverted back in.
......@@ -33,32 +31,37 @@ POSIX types.
build it on a real machines, and live-test it to make sure that
it issues sane corrections and doesn't core-dump or barf.
We need to do that on various platforms. We also need to
live test various refclocks.
live-test various refclocks.
=== Documentation ===
The documentation is a stale, untidy, duplicative mess only partway
converted to asciidoc.
The documentation is a stale, untidy, duplicative mess only most of
the way converted to asciidoc.
* Check completion on the conversion of the HTML docs.
* In the docs subdirectory, include/command.txt is an HTML passthrough
in a not entirely successful attempt to emulate the look of the
Mills HTML documentation this directory was made from. It should be
cleaned up ore replaced.
* The rest of the in-tree documentation must be lifted to asciidoc
* Similarly, includes/footer.txt is a tabular hack made to resemble the
old HTML and should be cleaned up.
* We need to land the whole document conversion in the main repo.
* HTML build from docs/ needs to be part of the stock waf build.
* The rest of the in-tree documentation must be lifted to asciidoc
* A serious content-editing and update pass on the documents.
* Part of d) is the ntp -> ntps name change.
* The format and organization of the NEWS file needs a rethink.
* Phabricator-centered workflow needs to be written up and integrated
with the website content I wrote for us.
* Website needs to be integrated (with a contacts and services page,
among other things) and published.
* Decent build and package-dependency documentation.
=== Remaining procedural issues ===
* The dev changes need to be fed through through Phabricator,
......
These are instructions for the portion of the documentation cleanup that can be
performed by an intern or student hire.
The 'I' referred to in this document is Eric Raymond, aka 'esr'. You will
be working with him on documentation tasks. You can reach him at
esr@thyrsus.com or find him on #icei-ntp.
Things you will need:
1. Command-line access to a Unix machine.
2. Knowledge of how to clone git repositories, and perform basic operations
like checkouts, checkins, pulls, and oushes.
3. Ability to drive a text editor that can handle flat-ASCII documents. Emacs,
vi, nano, joe, or anything in that class will do.
4. Firefox installed. (With a little additional technical knowledge you may be
able to substitute a different preferred browser.)
5. asciidoc installed.
Background of the problem:
The NTP documentation, while exceptionally good at conveying the complex
technicalia of time synchronization, has suffered from neglect and bit-rotted
rather badly. Many of the problems can only be fixed by a technical expert.
Some can be fixed by normal copy-editing, but the material is so dense and
tricky that even apparently simple changes need to be reviewed by an expert.
Complicating the task is that the documentation was written in raw
HTML. The heavy markup of HTML, together with the fact that the
documentation was written with entire long paragraphs as single lines,
makes incremental review very difficult. The first thing we need to
do is fix that.
Accordingly, I have converted the in-tree technical documentation to
a modern, lightweight format called asciidoc that can be rendered
to HTML, man pages, or PDFs and is much more easily reviewed by
human eyeballs. The conversion was mostly done with a program called
pandoc; I then went through and fixed up things that pandoc barfs on,
like tables and certain kinds of compound highlighting.
Your first task is to verify that conversion has not lost or garbled
any of the HTML content. pandoc's HTML parser is weak and I have caught
it silently dropping text from complex HTML; I have fixed what I spotted,
your job is to catch anything I missed.
Once this is done we can start on content changes. For PR/political reasons
we need to have a very clear audit trail of those changes; thus, you will
not be doing them during the content-checking first pass.
How to get started:
1. Clone the issi docs repo from git@icei.org:issi/ntp-doc
2. Go to the ntp/docs subdirectory. A copy of these instructions lives there
in the file INSTRUCTIONS.
3. Type './rebuild' to remake all the HTML files.
4. Choose a .txt file; the first one, 'access.txt", will do. Run
'./compare access'. Leave the ".txt" off the name.
5. Observe that your Firefox instance now has two new tabs. The left-hand
(older) one renders a copy of the original HTML, from a directory named
'html' under 'ntp'. All the files in there are write-locked copies of
HTML from the NTP source tree. The right-hand (newer) one has the
HTML made from asciidoc.
If you have a big enough screen, I find it is helpful to have two
Firefox windows and drag the second tab into the other one.
6. Compare the two. You are looking for textual differences.
When you run 'compare', it rebuilds what it needs.
There is another little script, 'preview', that takes a master name
(without the '.txt') and throws the HTML rendering of it on your
browser.
If you want to make local copies of these with a different browser
substituted for Firefox go ahead. The only requirement is that you
be able to display a specified page by giving it the path to the page
as an argument.
Work product:
The goal is to make the rendered HTML from asciidoc look as much as
possible like the original HTML, *not* (yet) to copy-edit either.
You should report especially on textual differences. If you can fix
these, do it by editing the .txt file, checking in the change, and
pushing it. Doing fixes may require you to learn some asciidoc; that is
OK and can be counted towards your billable time.
You can ignore whitespace differences unless they carry information.
Inter-paragraph breaks and relative paragraph indentation *do* carry
information and you should fix or report differences.
When in doubt, report it.
The visual presentation of the pages does not exactly match. If you
have CSS skills, you may edit the file ntp.css attempting to fix this.
Your work product must include a list of textual defects you found. If
you fix the glitches, your commit messages count as defect reports.
It will save you work in the second pass if you mke a list of spelling
errors and other content glitches that both versions share. Don't fix
them yet; that will happen in the second pass.
That's it.
default:
@rebuild
clean:
rm -f *.html */*.html *~
= Access Control Support =
[cols="10%,90%",frame="none",grid="none",style="verse"]
|==============================
|image:pic/pogo6.gif[]|
http://www.eecis.udel.edu/~mills/pictures.html[from 'Pogo', Walt Kelly]
The skunk watches for intruders and sprays.
Last update: 11-Sep-2010 05:53 UTC
|==============================
== Related Links ==
include::includes/hand.txt[]
include::includes/command.txt[]
include::includes/accopt.txt[]
'''''
== Access Control Support ==
The `ntpd` daemon implements a general purpose access control list (ACL)
containing address/match entries sorted first by increasing address
values and then by increasing mask values. A match occurs when the
bitwise AND of the mask and the packet source address is equal to the
bitwise AND of the mask and address in the list. The list is searched in
order with the last match found defining the restriction flags
associated with the entry.
The ACL is specified as a list of `restrict` commands in the following
format:
`restrict address [mask mask] [flag][...]`
The `address` argument expressed in dotted-quad form is the address of a
host or network. Alternatively, the `address` argument can be a valid
host DNS name. The `mask` argument expressed in IPv4 or IPv6 numeric
address form defaults to all mask bits on, meaning that the `address` is
treated as the address of an individual host. A default entry (address
0.0.0.0, mask 0.0.0.0 for IPv4 and address :: mask :: for IPv6) is
always the first entry in the list. `restrict default`, with no mask
option, modifies both IPv4 and IPv6 default entries. `restrict source`
configures a template restriction automatically added at runtime for
each association, whether configured, ephemeral, or preemptable, and
removed when the association is demobilized.
Some flags have the effect to deny service, some have the effect to
enable service and some are conditioned by other flags. The flags. are
not orthogonal, in that more restrictive flags will often make less
restrictive ones redundant. The flags that deny service are classed in
two categories, those that restrict time service and those that restrict
informational queries and attempts to do run-time reconfiguration of the
server.
An example may clarify how it works. Our campus has two class-B
networks, 128.4 for the ECE and CIS departments and 128.175 for the rest
of campus. Let's assume (not true!) that subnet 128.4.1 homes critical
services like class rosters and spread sheets. A suitable ACL might look
like this:
----------------------------------------------------------------------------------
restrict default nopeer # deny new associations
restrict 128.175.0.0 mask 255.255.0.0 # allow campus access
restrict 128.4.0.0 mask 255.255.0.0 none # allow ECE and CIS access
restrict 128.4.1.0 mask 255.255.255.0 notrust # require authentication on subnet 1
restrict time.nist.gov # allow access
----------------------------------------------------------------------------------
While this facility may be useful for keeping unwanted, broken or
malicious clients from congesting innocent servers, it should not be
considered an alternative to the NTP authentication facilities. Source
address based restrictions are easily circumvented by a determined
cracker.
Default restriction list entries with the flags `ignore, ntpport`, for
each of the local host's interface addresses are inserted into the table
at startup to prevent the server from attempting to synchronize to its
own time. A default entry is also always present, though if it is
otherwise unconfigured; no flags are associated with the default entry
(i.e., everything besides your own NTP server is unrestricted).
'''''
include::includes/footer.txt[]
= Access Control Commands and Options =
[cols="10%,90%",frame="none",grid="none",style="verse"]
|==============================
|image:pic/pogo6.gif[]|
http://www.eecis.udel.edu/~mills/pictures.html[from 'Pogo', Walt Kelly]
The skunk watches for intruders and sprays.
Last update: 13-Nov-2014 03:00 UTC
|==============================
== Related Links ==
include::includes/command.txt[]
include::includes/accopt.txt[]
'''''
== Commands and Options ==
Unless noted otherwise, further information about these ccommands is on
the link:accopt.html[Access Control Support] page.
`discard` [ `average` 'avg' ][ `minimum` 'min' ] [ `monitor` 'prob' ]::
Set the parameters of the rate control facility which protects the
server from client abuse. If the `limited` flag is present in the ACL,
packets that violate these limits are discarded. If, in addition, the
`kod` flag is present, a kiss-o'-death packet is returned. See the
link:rate.html[Rate Management] page for further information. The
options are:
`average` 'avg';;
Specify the minimum average interpacket spacing (minimum average
headway time) in log~2~ s with default 3.
`minimum` 'min';;
Specify the minimum interpacket spacing (guard time) in seconds with
default 2.
`monitor`;;
Specify the probability of being recorded for packets that overflow
the MRU list size limit set by `mru maxmem` or `mru maxdepth`. This
is a performance optimization for servers with aggregate arrivals of
1000 packets per second or more.
`restrict default` ['flag'][...]
`restrict source` ['flag'][...]
`restrict address` [`mask` 'mask'] ['flag'][...]`::
The `address` argument expressed in dotted-quad form is the address of
a host or network. Alternatively, the `address` argument can be a
valid host DNS name. The `mask` argument expressed in IPv4 or IPv6
numeric address form defaults to all mask bits on, meaning that the
`address` is treated as the address of an individual host. A default
entry (address 0.0.0.0, mask 0.0.0.0 for IPv4 and address pass:[::]
mask pass[::] for
IPv6) is always the first entry in the list. `restrict default`,
with no mask option, modifies both IPv4 and IPv6 default entries.
`restrict source` configures a template restriction automatically
added at runtime for each association, whether configured, ephemeral,
or preemptible, and removed when the association is demobilized.
Some flags have the effect to deny service, some have the effect to
enable service and some are conditioned by other flags. The flags. are
not orthogonal, in that more restrictive flags will often make less
restrictive ones redundant. The flags that deny service are classed in
two categories, those that restrict time service and those that
restrict informational queries and attempts to do run-time
reconfiguration of the server. One or more of the following flags may
be specified:
`flake`;;
Discard received NTP packets with probability 0.1; that is, on
average drop one packet in ten. This is for testing and amusement.
The name comes from Bob Braden's _flakeway_, which once did a
similar thing for early Internet testing.
`ignore`;;
Deny packets of all kinds, including `ntpq` and `ntpdc` queries.
`kod`;;
Send a kiss-o'-death (KoD) packet if the `limited` flag is present
and a packet violates the rate limits established by the `discard`
command. KoD packets are themselves rate limited for each source
address separately. If the `kod` flag is used in a restriction which
does not have the `limited` flag, no KoD responses will result.
`limited`;;
Deny time service if the packet violates the rate limits established
by the `discard` command. This does not apply to `ntpq` and `ntpdc`
queries.
`lowpriotrap`;;
Declare traps set by matching hosts to be low priority. The number
of traps a server can maintain is limited (the current limit is 3).
Traps are usually assigned on a first come, first served basis, with
later trap requestors being denied service. This flag modifies the
assignment algorithm by allowing low priority traps to be overridden
by later requests for normal priority traps.
`mssntp`;;
Enable Microsoft Windows MS-SNTP authentication using Active
Directory services. *Note: Potential users should be aware that
these services involve a TCP connection to another process that
could potentially block, denying services to other users. Therefore,
this flag should be used only for a dedicated server with no clients
other than MS-SNTP.*
`nomodify`;;
Deny `ntpq` and `ntpdc` queries which attempt to modify the state of
the server (i.e., run time reconfiguration). Queries which return
information are permitted.
`noquery`;;
Deny `ntpq` and `ntpdc` queries. Time service is not affected.
`nopeer`;;
Deny packets that might mobilize an association unless
authenticated. This includes broadcast, symmetric-active and
manycast server packets when a configured association does not
exist. It also includes `pool` associations, so if you want to use
servers from a `pool` directive and also want to use `nopeer` by
default, you'll want a `"restrict source ..."` line as well that
does _not_ include the `nopeer` directive. Note that this flag does
not apply to packets that do not attempt to mobilize an association.
`noserve`;;
Deny all packets except `ntpq` and `ntpdc` queries.
`notrap`;;
Decline to provide mode 6 control message trap service to matching
hosts. The trap service is a subsystem of the `ntpdc` control
message protocol which is intended for use by remote event logging
programs.
`notrust`;;
Deny packets that are not cryptographically authenticated. Note
carefully how this flag interacts with the `auth` option of the
`enable` and `disable` commands. If `auth` is enabled, which is the
default, authentication is required for all packets that might
mobilize an association. If `auth` is disabled, but the `notrust`
flag is not present, an association can be mobilized whether or not
authenticated. If `auth` is disabled, but the `notrust` flag is
present, authentication is required only for the specified
address/mask range.
`ntpport`;;
This is actually a match algorithm modifier, rather than a
restriction flag. Its presence causes the restriction entry to be
matched only if the source port in the packet is the standard NTP
UDP port (123). A restrict line containing `ntpport` is considered
more specific than one with the same address and mask, but lacking
`ntpport`.
`version`;;
Deny packets that do not match the current NTP version.
Default restriction list entries with the flags `ignore, ntpport`, for
each of the local host's interface addresses are inserted into the
table at startup to prevent the server from attempting to synchronize
to its own time. A default entry is also always present, though if it
is otherwise unconfigured; no flags are associated with the default
entry (i.e., everything besides your own NTP server is unrestricted).
'''''
include::includes/footer.txt[]
# All names and websites particular to the project's name, hosting location,
# and public communications channels indirect through here.
[attributes]
project-shortname=NTP
project-domain=ntp.org
project-website=http://www.ntp.org
project-weblink=http://www.ntp.org[www.ntp.org]
project-fullname=NTP Public Services Project
project-page=NTP Project page
project-bugsite=http://bugs.ntp.org/
project-contact=http://www.ntp.org/contact
project-security-list=security@ntp.org
project-bug-list=bugs@ntp.org
project-bugengine=Bugzilla
project-bugtracker="NTP Public Service Project Bug Tracking System (Bugzilla)"
millshome=http://www.eecis.udel.edu/~mills/
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
= Authentication Support =
[cols="10%,90%",frame="none",grid="none",style="verse"]
|==============================
|image:pic/alice44.gif[]|
http://www.eecis.udel.edu/%7emills/pictures.html[from 'Alice's Adventures in Wonderland', Lewis Carroll]
Our resident cryptographer; now you see him, now you don't.
Last update: 1-Dec-2012 04:44 UTC
|==============================
== Related Links ==
include::includes/hand.txt[]
include::includes/authopt.txt[]
== Table of Contents ==
* link:#auth[Introduction]
* link:#symm[Symmetric Key Cryptography]
* link:#windows[Microsoft Windows Authentication]
* link:#pub[Public Key Cryptography]
'''''
[[auth]]
== Introduction ==
This page describes the various cryptographic authentication provisions
in NTPv4. Authentication support allows the NTP client to verify that
servers are in fact known and trusted and not intruders intending
accidentally or intentionally to masquerade as a legitimate server. A
detailed discussion of the NTP multi-layer security model and
vulnerability analysis is in the white paper
http://www.eecis.udel.edu/~mills/security.html[NTP Security Analysis].
The NTPv3 specification (RFC-1305) defined an authentication scheme
properly described as _symmetric key cryptography_. It used the Data
Encryption Standard (DES) algorithm operating in cipher-block chaining
(CBC) mode. Subsequently, this algorithm was replaced by the RSA Message
Digest 5 (MD5) algorithm commonly called keyed-MD5. Either algorithm
computes a message digest or one-way hash which can be used to verify
the client has the same message digest as the server. The MD5 message
digest algorithm is included in the distribution, so without further
cryptographic support, the distribution can be freely exported.
If the OpenSSL cryptographic library is installed prior to building the
distribution, all message digest algorithms included in the library may
be used, including SHA and SHA1. However, if conformance to FIPS 140-2
is required, only a limited subset of these algorithms can be used. This
library is available from http://www.openssl.org and can be installed
using the procedures outlined in the link:build.html[Building and
Installing the Distribution] page. Once installed, the configure and
build process automatically detects the library and links the library
routines required.
In addition to the symmetric key algorithms, this distribution includes
support for the Autokey public key algorithms and protocol specified in
RFC-5906 "Network Time Protocol Version 4: Autokey Specification". This
support is available only if the OpenSSL library has been installed and
the `--enable-autokey` option is used when the distribution is built.
Public key cryptography is generally considered more secure than
symmetric key cryptography, since the security is based on private and
public values which are generated by each participant and where the
private value is never revealed. Autokey uses X.509 public certificates,
which can be produced by commercial services, the OpenSSL application
program, or the link:keygen.html[`ntp-keygen`] utility program in the
NTP software distribution.
Note that according to US law, NTP binaries including OpenSSL library
components, including the OpenSSL library itself, cannot be exported
outside the US without license from the US Department of Commerce.
Builders outside the US are advised to obtain the OpenSSL library
directly from OpenSSL, which is outside the US, and build outside the
US.
Authentication is configured separately for each association using the
`key` or `autokey` option of the `server` configuration command, as
described in the link:confopt.html[Server Options] page. The
link:keygen.html[ntp-keygen] page describes the files required for the
various authentication schemes. Further details are in the briefings,
papers and reports at the {project-shortname} project page linked from
{project-weblink}.
By default, the client sends non-authenticated packets and the server
responds with non-authenticated packets. If the client sends
authenticated packets, the server responds with authenticated packets if
correct, or a crypto-NAK packet if not.. In the case of unsolicited
packets which might consume significant resources, such as broadcast or
symmetric mode packets, , authentication is required, unless overridden
by a `disable auth` command. In the current climate of targeted
broadcast or "letterbomb" attacks, defeating this requirement would be
decidedly dangerous. In any case, the `notrust `flag, described on the
link:authopt.html[Access Control Options] page, can be used to disable
access to all but correctly authenticated clients..
[[symm]]
== Symmetric Key Cryptography ==
The original NTPv3 specification (RFC-1305), as well as the current
NTPv4 specification (RFC-5905), allows any one of possibly 65,534
message digest keys (excluding zero), each distinguished by a 32-bit key
ID, to authenticate an association. The servers and clients involved
must agree on the key ID, key type and key to authenticate NTP packets.
The message digest is a cryptographic hash computed by an algorithm such
as MD5 or SHA. When authentication is specified, a message
authentication code (MAC) is appended to the NTP packet header. The MAC
consists of a 32-bit key identifier (key ID) followed by a 128- or
160-bit message digest. The algorithm computes the digest as the hash of
a 128- or 160- bit message digest key concatenated with the NTP packet
header fields with the exception of the MAC. On transmit, the message
digest is computed and inserted in the MAC. On receive, the message
digest is computed and compared with the MAC. The packet is accepted
only if the two MACs are identical. If a discrepancy is found by the
client, the client ignores the packet, but raises an alarm. If this
happens at the server, the server returns a special message called a
_crypto-NAK_. Since the crypto-NAK is protected by the loopback test, an
intruder cannot disrupt the protocol by sending a bogus crypto-NAK.
Keys and related information are specified in a keys file, which must be
distributed and stored using secure means beyond the scope of the NTP
protocol itself. Besides the keys used for ordinary NTP associations,
additional keys can be used as passwords for the `ntpq` and `ntpdc`
utility programs. Ordinarily, the `ntp.keys` file is generated by the
`ntp-keygen` program, but it can be constructed and edited using an
ordinary text editor.
Each line of the keys file consists of three fields: a key ID in the
range 1 to 65,534, inclusive, a key type, and a message digest key
consisting of a printable ASCII string less than 40 characters, or a
40-character hex digit string. If the OpenSSL library is installed, the
key type can be any message digest algorithm supported by the library.
If the OpenSSL library is not installed, the only permitted key type is
MD5.
.Figure 1. Typical Symmetric Key File
image:pic/sx5.gif["Typical Symmetric Key File",align="center"]
Figure 1 shows a typical keys file used by the reference implementation
when the OpenSSL library is installed. In this figure, for key IDs in he
range 1-10, the key is interpreted as a printable ASCII string. For key
IDs in the range 11-20, the key is a 40-character hex digit string. The
key is truncated or zero-filled internally to either 128 or 160 bits,
depending on the key type. The line can be edited later or new lines can
be added to change any field. The key can be change to a password, such
as `2late4Me` for key ID 10. Note that two or more keys files can be
combined in any order as long as the key IDs are distinct.