doc: Add RFC documents

1 files changed, 563 insertions, 0 deletions

diff --git a/doc/rfc/rfc4716.txt b/doc/rfc/rfc4716.txt
new file mode 100644
index 0000000..71f2103
--- /dev/null
+++ b/doc/rfc/rfc4716.txt
@@ -0,0 +1,563 @@
+
+
+
+
+
+
+Network Working Group                                       J. Galbraith
+Request for Comments: 4716                              VanDyke Software
+Category: Informational                                        R. Thayer
+                                                          Canola & Jones
+                                                           November 2006
+
+
+             The Secure Shell (SSH) Public Key File Format
+
+Status of This Memo
+
+   This memo provides information for the Internet community.  It does
+   not specify an Internet standard of any kind.  Distribution of this
+   memo is unlimited.
+
+Copyright Notice
+
+   Copyright (C) The IETF Trust (2006).
+
+Abstract
+
+   This document formally documents an existing public key file format
+   in use for exchanging public keys between different Secure Shell
+   (SSH) implementations.
+
+   In addition, this document defines a standard textual representation
+   for SSH public key fingerprints.
+
+Table of Contents
+
+   1. Introduction ....................................................2
+   2. Conventions Used in This Document ...............................2
+   3. Key File Format .................................................2
+      3.1. Line Termination Characters ................................2
+      3.2. Begin and End Markers ......................................3
+      3.3. Key File Header ............................................3
+           3.3.1. Subject Header ......................................3
+           3.3.2. Comment Header ......................................4
+           3.3.3. Private Use Headers .................................4
+      3.4. Public Key File Body .......................................4
+      3.5. Differences with RFC 1421 PEM Formats ......................4
+      3.6. Examples ...................................................5
+   4. Public Key Fingerprints .........................................6
+   5. IANA Considerations .............................................6
+   6. Security Considerations .........................................7
+   7. References ......................................................8
+      7.1. Normative References .......................................8
+      7.2. Informative References .....................................8
+
+
+
+Galbraith & Thayer           Informational                      [Page 1]
+
+RFC 4716               SSH Public Key File Format          November 2006
+
+
+1.  Introduction
+
+   The SSH protocol supports the use of public/private key pairs in
+   order to perform authentication based on public key cryptography.
+   However, in order to use public key authentication in the SSH
+   protocol, public keys must first be exchanged between client and
+   server.
+
+   This document formally describes an existing public key file format
+   that can be used with any of the common existing file transfer
+   mechanisms in order to exchange public keys.
+
+   The SSH protocol also uses public/private key pairs to authenticate
+   the server.  In this scenario, it is important to verify that the
+   public key provided by the server is indeed the server's public key.
+   This document describes a mechanism for creating a short text string
+   that uniquely represents a particular public key, called
+   fingerprinting.
+
+2.  Conventions Used in This Document
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+   document are to be interpreted as described in [RFC2119].
+
+3.  Key File Format
+
+   In order to implement public key authentication, SSH implementations
+   must share public key files between the client and the server in
+   order to interoperate.
+
+   A key file is a text file, containing a sequence of lines.  Each line
+   in the file MUST NOT be longer than 72 8-bit bytes excluding line
+   termination characters.
+
+3.1.  Line Termination Characters
+
+   Implementations SHOULD generate public key files using their system's
+   local text file representation.
+
+   In the event that public key files are not transferred as text files,
+   implementations SHOULD be prepared to read files using any of the
+   common line termination sequence, <CR>, <LF>, or <CR><LF>.
+
+
+
+
+
+
+
+
+Galbraith & Thayer           Informational                      [Page 2]
+
+RFC 4716               SSH Public Key File Format          November 2006
+
+
+3.2.  Begin and End Markers
+
+   The first line of a conforming key file MUST be a begin marker, which
+   is the literal text:
+
+   ---- BEGIN SSH2 PUBLIC KEY ----
+
+   The last line of a conforming key file MUST be an end marker, which
+   is the literal text:
+
+   ---- END SSH2 PUBLIC KEY ----
+
+3.3.  Key File Header
+
+   The key file header section consists of multiple RFC822-style header
+   fields.  Each field is a line of the following format:
+
+   Header-tag ':' ' ' Header-value
+
+   The Header-tag MUST NOT be more than 64 8-bit bytes and is case-
+   insensitive.  The Header-value MUST NOT be more than 1024 8-bit
+   bytes.  Each line in the header MUST NOT be more than 72 8-bit bytes.
+
+   A line is continued if the last character in the line is a '\'.  If
+   the last character of a line is a '\', then the logical contents of
+   the line are formed by removing the '\' and the line termination
+   characters, and appending the contents of the next line.
+
+   The Header-tag MUST be encoded in US-ASCII.  The Header-value MUST be
+   encoded in UTF-8 [RFC3629].
+
+   A line that is not a continuation line that has no ':' in it is the
+   first line of the base64-encoded body.  (See Section 3.4.)
+
+   The space of header-tags is managed as described in Section 5.
+
+   Compliant implementations MUST ignore headers with unrecognized
+   header-tags.  Implementations SHOULD preserve such unrecognized
+   headers when manipulating the key file.
+
+3.3.1.  Subject Header
+
+   This field is used to store the login-name that the key was generated
+   under.  For example:
+
+   Subject: user
+
+
+
+
+
+Galbraith & Thayer           Informational                      [Page 3]
+
+RFC 4716               SSH Public Key File Format          November 2006
+
+
+3.3.2.  Comment Header
+
+   The comment header contains a user-specified comment.  The comment
+   SHOULD be displayed when using the key.
+
+   It is suggested that this field default to user@hostname for the user
+   and machine used to generate the key.  For example:
+
+   Comment: user@example.com
+
+   Currently, common practice is to quote the Header-value of the
+   Comment by prefixing and suffixing it with '"' characters, and some
+   existing implementations fail if these quotation marks are omitted.
+
+   Compliant implementations MUST function correctly if the quotation
+   marks are omitted.
+
+   Implementations MAY include the quotation marks.  If the first and
+   last characters of the Header-value are matching quotation marks,
+   implementations SHOULD remove them before using the value.
+
+3.3.3.  Private Use Headers
+
+   Headers with header-tags beginning with "x-" are reserved for private
+   use.
+
+3.4.  Public Key File Body
+
+   The body of a public key file is the base64 encoded ([RFC2045])
+   public key data as specified by [RFC4253], Section 6.6:
+
+         string    certificate or public key format identifier
+         byte[n]   key/certificate data
+
+   As with all other lines, each line in the body MUST NOT be longer
+   than 72 8-bit bytes excluding line termination characters.
+
+3.5.  Differences with RFC 1421 PEM Formats
+
+   Implementers should take care to notice that while the format is
+   superficially similar to those specified by PEM [RFC1421] and OpenPGP
+   [RFC2440], it is not identical; most notably:
+
+   o  The other specifications use different BEGIN/END delimiters (five
+      dashes, no space rather than four dashes and a space).
+
+   o  There is no blank line before the start of the base64-encoded
+      contents.
+
+
+
+Galbraith & Thayer           Informational                      [Page 4]
+
+RFC 4716               SSH Public Key File Format          November 2006
+
+
+   o  There is no Cyclic Redundancy Check (CRC) at the end of the
+      base64-encoded block.
+
+   o  Header continuation uses a backslash at the end of the continued
+      line rather than whitespace at the start of the next line.
+
+3.6.  Examples
+
+   The following are some examples of public key files that are
+   compliant (note that the examples all wrap before 72 bytes to meet
+   IETF document requirements; however, they are still compliant.)
+
+   ---- BEGIN SSH2 PUBLIC KEY ----
+   Comment: "1024-bit RSA, converted from OpenSSH by me@example.com"
+   x-command: /home/me/bin/lock-in-guest.sh
+   AAAAB3NzaC1yc2EAAAABIwAAAIEA1on8gxCGJJWSRT4uOrR13mUaUk0hRf4RzxSZ1zRb
+   YYFw8pfGesIFoEuVth4HKyF8k1y4mRUnYHP1XNMNMJl1JcEArC2asV8sHf6zSPVffozZ
+   5TT4SfsUu/iKy9lUcCfXzwre4WWZSXXcPff+EHtWshahu3WzBdnGxm5Xoi89zcE=
+   ---- END SSH2 PUBLIC KEY ----
+
+
+   ---- BEGIN SSH2 PUBLIC KEY ----
+   Comment: This is my public key for use on \
+   servers which I don't like.
+   AAAAB3NzaC1kc3MAAACBAPY8ZOHY2yFSJA6XYC9HRwNHxaehvx5wOJ0rzZdzoSOXxbET
+   W6ToHv8D1UJ/z+zHo9Fiko5XybZnDIaBDHtblQ+Yp7StxyltHnXF1YLfKD1G4T6JYrdH
+   YI14Om1eg9e4NnCRleaqoZPF3UGfZia6bXrGTQf3gJq2e7Yisk/gF+1VAAAAFQDb8D5c
+   vwHWTZDPfX0D2s9Rd7NBvQAAAIEAlN92+Bb7D4KLYk3IwRbXblwXdkPggA4pfdtW9vGf
+   J0/RHd+NjB4eo1D+0dix6tXwYGN7PKS5R/FXPNwxHPapcj9uL1Jn2AWQ2dsknf+i/FAA
+   vioUPkmdMc0zuWoSOEsSNhVDtX3WdvVcGcBq9cetzrtOKWOocJmJ80qadxTRHtUAAACB
+   AN7CY+KKv1gHpRzFwdQm7HK9bb1LAo2KwaoXnadFgeptNBQeSXG1vO+JsvphVMBJc9HS
+   n24VYtYtsMu74qXviYjziVucWKjjKEb11juqnF0GDlB3VVmxHLmxnAz643WK42Z7dLM5
+   sY29ouezv4Xz2PuMch5VGPP+CDqzCM4loWgV
+   ---- END SSH2 PUBLIC KEY ----
+
+
+   ---- BEGIN SSH2 PUBLIC KEY ----
+   Comment: DSA Public Key for use with MyIsp
+   AAAAB3NzaC1kc3MAAACBAPY8ZOHY2yFSJA6XYC9HRwNHxaehvx5wOJ0rzZdzoSOXxbET
+   W6ToHv8D1UJ/z+zHo9Fiko5XybZnDIaBDHtblQ+Yp7StxyltHnXF1YLfKD1G4T6JYrdH
+   YI14Om1eg9e4NnCRleaqoZPF3UGfZia6bXrGTQf3gJq2e7Yisk/gF+1VAAAAFQDb8D5c
+   vwHWTZDPfX0D2s9Rd7NBvQAAAIEAlN92+Bb7D4KLYk3IwRbXblwXdkPggA4pfdtW9vGf
+   J0/RHd+NjB4eo1D+0dix6tXwYGN7PKS5R/FXPNwxHPapcj9uL1Jn2AWQ2dsknf+i/FAA
+   vioUPkmdMc0zuWoSOEsSNhVDtX3WdvVcGcBq9cetzrtOKWOocJmJ80qadxTRHtUAAACB
+   AN7CY+KKv1gHpRzFwdQm7HK9bb1LAo2KwaoXnadFgeptNBQeSXG1vO+JsvphVMBJc9HS
+   n24VYtYtsMu74qXviYjziVucWKjjKEb11juqnF0GDlB3VVmxHLmxnAz643WK42Z7dLM5
+   sY29ouezv4Xz2PuMch5VGPP+CDqzCM4loWgV
+   ---- END SSH2 PUBLIC KEY ----
+
+
+
+Galbraith & Thayer           Informational                      [Page 5]
+
+RFC 4716               SSH Public Key File Format          November 2006
+
+
+   ---- BEGIN SSH2 PUBLIC KEY ----
+   Subject: me
+   Comment: 1024-bit rsa, created by me@example.com Mon Jan 15 \
+   08:31:24 2001
+   AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
+   596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
+   soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=
+   ---- END SSH2 PUBLIC KEY ----
+
+4.  Public Key Fingerprints
+
+   The security of the SSH protocols relies on the verification of
+   public host keys.  Since public keys tend to be very large, it is
+   difficult for a human to verify an entire host key.  Even with a
+   Public Key Infrastructure (PKI) in place, it is useful to have a
+   standard for exchanging short fingerprints of public keys.
+
+   This section formally describes the method of generating public key
+   fingerprints that is in common use in the SSH community.
+
+   The fingerprint of a public key consists of the output of the MD5
+   message-digest algorithm [RFC1321].  The input to the algorithm is
+   the public key data as specified by [RFC4253].  (This is the same
+   data that is base64 encoded to form the body of the public key file.)
+
+   The output of the algorithm is presented to the user as a sequence of
+   16 octets printed as hexadecimal with lowercase letters and separated
+   by colons.
+
+   For example: "c1:b1:30:29:d7:b8:de:6c:97:77:10:d7:46:41:63:87"
+
+5.  IANA Considerations
+
+   Section 3.3 defines a new namespace of "Header-tags".  These are
+   US-ASCII strings of maximum length 64 characters and are
+   case-insensitive.
+
+   IANA has created and maintains a registry of these header-tags.  The
+   registry maps each header-tag to a reference defining the header.
+
+   The initial contents of the registry are as follows:
+
+      subject defined in Section 3.3.1
+
+      comment defined in Section 3.3.2
+
+   Header-tags beginning with "x-" are reserved for private use, as
+   defined in [RFC2434].
+
+
+
+Galbraith & Thayer           Informational                      [Page 6]
+
+RFC 4716               SSH Public Key File Format          November 2006
+
+
+   All other allocations are to be made by IETF consensus, as defined in
+   [RFC2434].
+
+6.  Security Considerations
+
+   The file format described by this document provides no mechanism to
+   verify the integrity or otherwise detect tampering with the data
+   stored in such files.  Given the potential of adversarial tampering
+   with this data, system-specific measures (e.g., Access Control Lists,
+   UNIX permissions, other Discretionary and/or Mandatory Access
+   Controls) SHOULD be used to protect these files.  Also, if the
+   contents of these files are transferred it SHOULD be done over a
+   trusted channel.
+
+   The header data allowed by this file format could contain an
+   unlimited range of information.  While in many environments the
+   information conveyed by this header data may be considered innocuous
+   public information, it may constitute a channel through which
+   information about a user, a key, or its use may be disclosed
+   intentionally or otherwise (e.g., "Comment: Mary E. Jones, 123 Main
+   St, Home Phone:...").  The presence and use of this header data
+   SHOULD be reviewed by sites that deploy this file format.
+
+   The public key fingerprint method presented here relies on the MD5
+   one-way hash function, which is known to have certain weaknesses
+   regarding its collision resistance; however, the particular use made
+   of MD5 here depends solely on its 2nd-preimage resistance, not on its
+   collision resistance.
+
+   MD5 is used here for historical reasons.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith & Thayer           Informational                      [Page 7]
+
+RFC 4716               SSH Public Key File Format          November 2006
+
+
+7.  References
+
+7.1.  Normative References
+
+   [RFC1321]  Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321,
+              April 1992.
+
+   [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+              Extensions (MIME) Part One: Format of Internet Message
+              Bodies", RFC 2045, November 1996.
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
+              10646", STD 63, RFC 3629, November 2003.
+
+   [RFC4253]  Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
+              Transport Layer Protocol", RFC 4253, January 2006.
+
+   [RFC2434]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
+              IANA Considerations Section in RFCs", BCP 26, RFC 2434,
+              October 1998.
+
+7.2.  Informative References
+
+   [RFC1421]  Linn, J., "Privacy Enhancement for Internet Electronic
+              Mail: Part I: Message Encryption and Authentication
+              Procedures", RFC 1421, February 1993.
+
+   [RFC2440]  Callas, J., Donnerhacke, L., Finney, H., and R. Thayer,
+              "OpenPGP Message Format", RFC 2440, November 1998.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith & Thayer           Informational                      [Page 8]
+
+RFC 4716               SSH Public Key File Format          November 2006
+
+
+Authors' Addresses
+
+   Joseph Galbraith
+   VanDyke Software
+   4848 Tramway Ridge Blvd
+   Suite 101
+   Albuquerque, NM  87111
+   US
+
+   Phone: +1 505 332 5700
+   EMail: galb@vandyke.com
+
+
+   Rodney Thayer
+   Canola & Jones
+   650 Castro Street Suite 120-205
+   Mountain View CA 94041
+   US
+
+   Phone: +1 650 704 8389
+   EMail: rodney@canola-jones.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith & Thayer           Informational                      [Page 9]
+
+RFC 4716               SSH Public Key File Format          November 2006
+
+
+Full Copyright Statement
+
+   Copyright (C) The IETF Trust (2006).
+
+   This document is subject to the rights, licenses and restrictions
+   contained in BCP 78, and except as set forth therein, the authors
+   retain all their rights.
+
+   This document and the information contained herein are provided on an
+   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
+   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST,
+   AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
+   THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
+   IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+   PURPOSE.
+
+Intellectual Property
+
+   The IETF takes no position regarding the validity or scope of any
+   Intellectual Property Rights or other rights that might be claimed to
+   pertain to the implementation or use of the technology described in
+   this document or the extent to which any license under such rights
+   might or might not be available; nor does it represent that it has
+   made any independent effort to identify any such rights.  Information
+   on the procedures with respect to rights in RFC documents can be
+   found in BCP 78 and BCP 79.
+
+   Copies of IPR disclosures made to the IETF Secretariat and any
+   assurances of licenses to be made available, or the result of an
+   attempt made to obtain a general license or permission for the use of
+   such proprietary rights by implementers or users of this
+   specification can be obtained from the IETF on-line IPR repository at
+   http://www.ietf.org/ipr.
+
+   The IETF invites any interested party to bring to its attention any
+   copyrights, patents or patent applications, or other proprietary
+   rights that may cover technology that may be required to implement
+   this standard.  Please address the information to the IETF at
+   ietf-ipr@ietf.org.
+
+Acknowledgement
+
+   Funding for the RFC Editor function is currently provided by the
+   Internet Society.
+
+
+
+
+
+
+Galbraith & Thayer           Informational                     [Page 10]
+