7076
INFORMATIONAL
P6R's Secure Shell Public Key Subsystem
Authors: M. Joseph, J. Susoy
Date: November 2013
Stream: INDEPENDENT
Abstract
The Secure Shell (SSH) Public Key Subsystem protocol defines a key distribution protocol that is limited to provisioning an SSH server with a user's public keys. This document describes a new protocol that builds on the protocol defined in RFC 4819 to allow the provisioning of keys and certificates to a server using the SSH transport.
The new protocol allows the calling client to organize keys and certificates in different namespaces on a server. These namespaces can be used by the server to allow a client to configure any application running on the server (e.g., SSH, Key Management Interoperability Protocol (KMIP), Simple Network Management Protocol (SNMP)).
The new protocol provides a server-independent mechanism for clients to add public keys, remove public keys, add certificates, remove certificates, and list the current set of keys and certificates known by the server by namespace (e.g., list all public keys in the SSH namespace).
Rights to manage keys and certificates in a particular namespace are specific and limited to the authorized user and are defined as part of the server's implementation. The described protocol is backward compatible to version 2 defined by RFC 4819.
RFC 7076
INFORMATIONAL
Independent Submission M. Joseph
Request for Comments: 7076 J. Susoy
Category: Informational P6R, Inc
ISSN: 2070-1721 November 2013
<span class="h1">P6R's Secure Shell Public Key Subsystem</span>
Abstract
The Secure Shell (SSH) Public Key Subsystem protocol defines a key
distribution protocol that is limited to provisioning an SSH server
with a user's public keys. This document describes a new protocol
that builds on the protocol defined in <a href="./rfc4819">RFC 4819</a> to allow the
provisioning of keys and certificates to a server using the SSH
transport.
The new protocol allows the calling client to organize keys and
certificates in different namespaces on a server. These namespaces
can be used by the server to allow a client to configure any
application running on the server (e.g., SSH, Key Management
Interoperability Protocol (KMIP), Simple Network Management Protocol
(SNMP)).
The new protocol provides a server-independent mechanism for clients
to add public keys, remove public keys, add certificates, remove
certificates, and list the current set of keys and certificates known
by the server by namespace (e.g., list all public keys in the SSH
namespace).
Rights to manage keys and certificates in a particular namespace are
specific and limited to the authorized user and are defined as part
of the server's implementation. The described protocol is backward
compatible to version 2 defined by <a href="./rfc4819">RFC 4819</a>.
Status of This Memo
This document is not an Internet Standards Track specification; it is
published for informational purposes.
This is a contribution to the RFC Series, independently of any other
RFC stream. The RFC Editor has chosen to publish this document at
its discretion and makes no statement about its value for
implementation or deployment. Documents approved for publication by
the RFC Editor are not a candidate for any level of Internet
Standard; see <a href="./rfc5741#section-2">Section 2 of RFC 5741</a>.
<span class="grey">Joseph & Susoy Informational [Page 1]</span><span id="page-2" ></span>
<span class="grey"><a href="./rfc7076">RFC 7076</a> P6R's Secure Shell Public Key Subsystem November 2013</span>
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
<a href="https://www.rfc-editor.org/info/rfc7076">http://www.rfc-editor.org/info/rfc7076</a>.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and the IETF Trust's Legal
Provisions Relating to IETF Documents
(<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document.
Table of Contents
<a href="#section-1">1</a>. Introduction ....................................................<a href="#page-3">3</a>
<a href="#section-2">2</a>. Terminology .....................................................<a href="#page-3">3</a>
<a href="#section-3">3</a>. Overview of Extensions to the Public Key Subsystem ..............<a href="#page-3">3</a>
<a href="#section-3.1">3.1</a>. Extended Status Codes ......................................<a href="#page-4">4</a>
<a href="#section-3.2">3.2</a>. The Version Packet .........................................<a href="#page-4">4</a>
<a href="#section-3.3">3.3</a>. The Namespace Attribute ....................................<a href="#page-4">4</a>
<a href="#section-4">4</a>. New Operations ..................................................<a href="#page-5">5</a>
<a href="#section-4.1">4.1</a>. Adding a Certificate .......................................<a href="#page-5">5</a>
<a href="#section-4.2">4.2</a>. Removing a Certificate .....................................<a href="#page-6">6</a>
<a href="#section-4.3">4.3</a>. Listing Certificates .......................................<a href="#page-6">6</a>
<a href="#section-4.4">4.4</a>. Listing Namespaces .........................................<a href="#page-7">7</a>
<a href="#section-5">5</a>. Extending Public Key Operations .................................<a href="#page-8">8</a>
<a href="#section-5.1">5.1</a>. Adding a Public Key ........................................<a href="#page-8">8</a>
<a href="#section-5.2">5.2</a>. Removing a Public Key ......................................<a href="#page-8">8</a>
<a href="#section-5.3">5.3</a>. Listing Public Keys ........................................<a href="#page-9">9</a>
<a href="#section-6">6</a>. Security Considerations .........................................<a href="#page-9">9</a>
<a href="#section-7">7</a>. IANA Considerations ............................................<a href="#page-10">10</a>
<a href="#section-8">8</a>. References .....................................................<a href="#page-10">10</a>
<a href="#section-8.1">8.1</a>. Normative References ......................................<a href="#page-10">10</a>
<a href="#section-8.2">8.2</a>. Informative References ....................................<a href="#page-10">10</a>
<span class="grey">Joseph & Susoy Informational [Page 2]</span><span id="page-3" ></span>
<span class="grey"><a href="./rfc7076">RFC 7076</a> P6R's Secure Shell Public Key Subsystem November 2013</span>
<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
This document describes a new protocol that builds on the protocol
defined in <a href="./rfc4819">RFC 4819</a> that can be used to configure public keys and
certificates in an implementation-independent fashion. The concept
of a namespace is added to the protocol's operations; it allows the
client to organize keys and certificates by application or
organizational structure.
P6R's Secure Shell Public Key Subsystem has been designed to run on
top of the Secure Shell transport layer [<a href="#ref-3" title=""The Secure Shell (SSH) Transport Layer Protocol"">3</a>] and user authentication
protocols [<a href="#ref-4" title=""The Secure Shell (SSH) Authentication Protocol"">4</a>]. It provides a simple mechanism for the client to
manage the public keys and certificates on the server related to that
client. These keys and certificates are normally used for
authentication of the client to a service, but they can be used for
encrypting results back to the client as well. Uploaded keys and
certificates are meant to be able to configure all protocols running
on a server (e.g., SSH, SSL, KMIP [<a href="#ref-8" title=""Key Management Interoperability Protocol (KMIP) 1.1"">8</a>]) that use keys and
certificates, as well as the applications that run on a server.
This document should be read only after reading the Secure Shell
Public Key Subsystem [<a href="#ref-1" title=""Secure Shell Public Key Subsystem"">1</a>] document. The new protocol described in
this document builds on and is meant to be backwards compatible with
the protocol described in [<a href="#ref-1" title=""Secure Shell Public Key Subsystem"">1</a>].
<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Terminology</span>
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 <a href="./rfc2119">RFC 2119</a> [<a href="#ref-2" title=""Key words for use in RFCs to Indicate Requirement Levels"">2</a>].
<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. Overview of Extensions to the Public Key Subsystem</span>
The Public Key Subsystem provides a server-independent mechanism for
clients to add public keys, remove public keys, list the current
public keys known by the server, add certificates, remove
certificates, and list the current set of certificates known by the
server. This secure key distribution mechanism is implemented by a
new SSH subsystem with the name of "[email protected]".
<span class="grey">Joseph & Susoy Informational [Page 3]</span><span id="page-4" ></span>
<span class="grey"><a href="./rfc7076">RFC 7076</a> P6R's Secure Shell Public Key Subsystem November 2013</span>
<span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a>. Extended Status Codes</span>
The status code gives the status in a more machine-readable format
(suitable for localization) and can have the following values:
SSH_PUBLICKEY_CERTIFICATE_NOT_FOUND 192
SSH_PUBLICKEY_CERTIFICATE_NOT_SUPPORTED 193
SSH_PUBLICKEY_CERTIFICATE_ALREADY_PRESENT 194
SSH_PUBLICKEY_ACTION_NOT_AUTHORIZED 195
SSH_PUBLICKEY_CANNOT_CREATE_NAMESPACE 196
The meaning of the failure codes is as implied by their names. See
Security Considerations for the use of the failure code:
SSH_PUBLICKEY_ACTION_NOT_AUTHORIZED.
<span class="h3"><a class="selflink" id="section-3.2" href="#section-3.2">3.2</a>. The Version Packet</span>
Both sides MUST start a connection by sending a version packet that
indicates the version of the protocol they are using.
string "version"
uint32 protocol-version-number
This document defines version 3 of the new protocol. We are using
version 3 so that it can be backward compatible with the protocol
defined by <a href="./rfc4819">RFC 4819</a> [<a href="#ref-1" title=""Secure Shell Public Key Subsystem"">1</a>].
<span class="h3"><a class="selflink" id="section-3.3" href="#section-3.3">3.3</a>. The Namespace Attribute</span>
The "namespace" attribute is added as an extension to what was
described in <a href="./rfc4819">RFC 4819</a>. The purpose of this attribute is to be able
to organize the uploaded keys and certificates into groups where each
group represents an application or organization structure. This
attribute is a string that should not be longer than 300 characters
and MUST be specified in UTF-8 format [<a href="#ref-5" title=""UTF-8, a transformation format of ISO 10646"">5</a>].
This new protocol uses the "ssh" namespace for the manipulation of
public keys in an SSH server and should be considered as the default
namespace when none is provided.
As a convention, namespaces used for protocols are lowercase strings
of the protocol's standard abbreviation. For example, "ssl" should
be the namespace used for the Secure Sockets Layer protocol.
Namespaces for applications should contain the product and vendor's
name. To help determine what namespaces already exist on a server, a
new operation "list-namespaces" is defined in <a href="#section-4">Section 4</a>.
<span class="grey">Joseph & Susoy Informational [Page 4]</span><span id="page-5" ></span>
<span class="grey"><a href="./rfc7076">RFC 7076</a> P6R's Secure Shell Public Key Subsystem November 2013</span>
<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. New Operations</span>
P6R's Public Key Subsystem extends the functionality defined in <a href="./rfc4819">RFC</a>
<a href="./rfc4819">4819</a> with the following operations: add-certificate,
remove-certificate, list-certificates, and list-namespaces.
<span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a>. Adding a Certificate</span>
If the client wishes to add a certificate, the client sends:
string "add-certificate"
string certificate format name
string certificate blob
boolean overwrite
uint32 attribute-count
string attrib-name
string attrib-value
bool critical
repeated attribute-count times
This request MUST include at least the "namespace" attribute so that
the server knows where to save the certificate. Only one namespace
attribute can be used per an add-certificate request. It is possible
for the same user to save the same certificate into multiple
namespaces, but this must be done with several separate
add-certificate requests.
If the namespace appearing in an add-certificate request does not
already exist on a server, then it is created by this operation.
However, if the user is not authorized to create a namespace, the
server MUST return SSH_PUBLICKEY_CANNOT_CREATE_NAMESPACE.
If the overwrite field is false and the specified certificate already
exists in the given namespace, the server MUST return
SSH_PUBLICKEY_CERTIFICATE_ALREADY_PRESENT. If the server returns
this, the client SHOULD provide an option to the user to overwrite
the certificate. If the overwrite field is true and the specified
key already exists in the given namespace but cannot be overwritten,
the server MUST return SSH_PUBLICKEY_ACCESS_DENIED.
However, a user may not be authorized to add a certificate to the
specified namespace. If the user does not have permission to add a
certificate, then the server MUST return
SSH_PUBLICKEY_ACTION_NOT_AUTHORIZED.
Examples of possible "certificate format names" are: "X509",
"pgp-sign-rsa", and "pgp-sign-dss". The format of the public key and
certificate blobs are detailed in <a href="#section-6.6">Section 6.6</a>, "Public Key
<span class="grey">Joseph & Susoy Informational [Page 5]</span><span id="page-6" ></span>
<span class="grey"><a href="./rfc7076">RFC 7076</a> P6R's Secure Shell Public Key Subsystem November 2013</span>
Algorithms", of the SSH Transport Protocol document [<a href="#ref-3" title=""The Secure Shell (SSH) Transport Layer Protocol"">3</a>], where X.509
certificates are to be encoded using a DER format [<a href="#ref-6" title=""Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile"">6</a>] [<a href="#ref-7" title=" Information technology -- ASN.1 encoding rules: Specification of Basic Encoding Rules (BER)">7</a>] in a
certificate blob.
<span class="h3"><a class="selflink" id="section-4.2" href="#section-4.2">4.2</a>. Removing a Certificate</span>
If the client wishes to remove a certificate, the client sends:
string "remove-certificate"
string certificate format name
string certificate blob
uint32 attribute-count
string attrib-name
string attrib-value
repeated attribute-count times
This request MUST include at least the "namespace" attribute so that
the server knows from where to delete the certificate. Only one
namespace attribute can be used per remove-certificate request. The
server MUST attempt to remove the certificate from the appropriate
location.
However, a user may not be authorized to remove a certificate from
the specified namespace. If the user does not have permission to
remove the certificate, then the server MUST return
SSH_PUBLICKEY_ACTION_NOT_AUTHORIZED.
Examples of possible "certificate format names" are: "X509",
"pgp-sign-rsa", and "pgp-sign-dss".
<span class="h3"><a class="selflink" id="section-4.3" href="#section-4.3">4.3</a>. Listing Certificates</span>
If the client wishes to list the known certificates, the client
sends:
string "list-certificates"
The server will respond with zero or more of the following responses:
string "certificate"
string certificate format name
string certificate blob
uint32 attribute-count
string attrib-name
string attrib-value
repeated attribute-count times
<span class="grey">Joseph & Susoy Informational [Page 6]</span><span id="page-7" ></span>
<span class="grey"><a href="./rfc7076">RFC 7076</a> P6R's Secure Shell Public Key Subsystem November 2013</span>
There is no requirement that the responses be in any particular
order. Whilst some server implementations may send the responses in
some order, client implementations should not rely on responses being
in any order.
This response MUST include at least the "namespace" attribute so that
a client can tell in which namespace the certificate resides. Only
one namespace attribute can be used per list-certificate request.
Following the last "certificate" response, a status packet MUST be
sent.
<span class="h3"><a class="selflink" id="section-4.4" href="#section-4.4">4.4</a>. Listing Namespaces</span>
If the client wishes to know existing namespaces on the server, it
sends:
string "list-namespaces"
The server will respond with zero or more of the following responses:
string "namespace"
string namespace name
It is possible that not all namespaces will be visible to every
authenticated user. In this case, the responding server will return
a subset of existing namespaces. See Security Considerations below.
Following the last "namespace" response, a status packet MUST be
sent.
<span class="grey">Joseph & Susoy Informational [Page 7]</span><span id="page-8" ></span>
<span class="grey"><a href="./rfc7076">RFC 7076</a> P6R's Secure Shell Public Key Subsystem November 2013</span>
<span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. Extending Public Key Operations</span>
In addition to adding new operations, this document describes
extensions to the operations defined in <a href="./rfc4819">RFC 4819</a>.
<span class="h3"><a class="selflink" id="section-5.1" href="#section-5.1">5.1</a>. Adding a Public Key</span>
If the client wishes to add a public key, the client sends:
string "add"
string public key algorithm name
string public key blob
boolean overwrite
uint32 attribute-count
string attrib-name
string attrib-value
bool critical
repeated attribute-count times
This request MAY include one "namespace" attribute so that a client
can save the public key into a specific namespace. It is possible
for the same user to save the same key into multiple namespaces, but
this requires multiple add requests.
If the namespace appearing in an add public key request does not
already exist on a server, then it is created by this operation.
However, if the user is not authorized to create a namespace the
server MUST return SSH_PUBLICKEY_CANNOT_CREATE_NAMESPACE,
<span class="h3"><a class="selflink" id="section-5.2" href="#section-5.2">5.2</a>. Removing a Public Key</span>
If the client wishes to remove a public key, the client sends:
string "remove"
string public key algorithm name
string public key blob
uint32 attribute-count
string attrib-name
string attrib-value
bool critical
repeated attribute-count times
This extension allows attributes to be added to a remove request.
This request MAY include one "namespace" attribute so that a client
can remove the public key from a specific namespace.
<span class="grey">Joseph & Susoy Informational [Page 8]</span><span id="page-9" ></span>
<span class="grey"><a href="./rfc7076">RFC 7076</a> P6R's Secure Shell Public Key Subsystem November 2013</span>
<span class="h3"><a class="selflink" id="section-5.3" href="#section-5.3">5.3</a>. Listing Public Keys</span>
If the client wishes to list the known public keys, the client sends:
string "list"
uint32 attribute-count
string attrib-name
string attrib-value
bool critical
repeated attribute-count times
This extension allows attributes to be added to a list request. This
request MAY include one "namespace" attribute so that a client can
list the public keys from a specific namespace.
The server will respond with zero or more of the following responses:
string "publickey"
string public key algorithm name
string public key blob
uint32 attribute-count
string attrib-name
string attrib-value
repeated attribute-count times
This response MAY include the "namespace" attribute so that a client
can tell in which namespace the key resides.
<span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. Security Considerations</span>
This protocol assumes that it is run over a secure channel and that
the endpoints of the channel have been authenticated. Thus, this
protocol assumes that it is externally protected from network-level
attacks.
This protocol provides a mechanism that allows key and certificate
material to be uploaded and manipulated into a server application.
It is the responsibility of the server implementation to enforce
access controls that may be required to limit any particular user's
access to the data in a namespace. For example, one user may be
allowed to list only the contents of a namespace but not add or
remove keys or certificates to/from it. The server MUST return
SSH_PUBLICKEY_ACTION_NOT_AUTHORIZED when a user's action goes against
its defined access controls.
<span class="grey">Joseph & Susoy Informational [Page 9]</span><span id="page-10" ></span>
<span class="grey"><a href="./rfc7076">RFC 7076</a> P6R's Secure Shell Public Key Subsystem November 2013</span>
This protocol requires the client to assume that the server will
correctly implement and observe attributes applied to keys.
Implementation errors in the server could cause clients to authorize
keys and certificates for access they were not intended to have, or
to apply fewer restrictions than were intended.
<span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>. IANA Considerations</span>
Although <a href="#section-3.1">Section 3.1</a> defines four new status codes, these are in the
'Private Use' range of IANA's Publickey Subsystem Status Codes
registry as defined by <a href="#section-6.6.1">Section 6.6.1</a> ("Conventions") in [<a href="#ref-1" title=""Secure Shell Public Key Subsystem"">1</a>]. No IANA
actions are required for this document.
<span class="h2"><a class="selflink" id="section-8" href="#section-8">8</a>. References</span>
<span class="h3"><a class="selflink" id="section-8.1" href="#section-8.1">8.1</a>. Normative References</span>
[<a id="ref-1">1</a>] Galbraith, J., Van Dyke, J., and J. Bright, "Secure Shell Public
Key Subsystem", <a href="./rfc4819">RFC 4819</a>, March 2007.
[<a id="ref-2">2</a>] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>, March 1997.
[<a id="ref-3">3</a>] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Transport
Layer Protocol", <a href="./rfc4253">RFC 4253</a>, January 2006.
[<a id="ref-4">4</a>] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
Authentication Protocol", <a href="./rfc4252">RFC 4252</a>, January 2006.
[<a id="ref-5">5</a>] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD
63, <a href="./rfc3629">RFC 3629</a>, November 2003.
[<a id="ref-6">6</a>] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R.,
and W. Polk, "Internet X.509 Public Key Infrastructure
Certificate and Certificate Revocation List (CRL) Profile", <a href="./rfc5280">RFC</a>
<a href="./rfc5280">5280</a>, May 2008.
[<a id="ref-7">7</a>] ITU-T Recommendation X.690 (2002) | ISO/IEC 8825-1:2002,
Information technology -- ASN.1 encoding rules: Specification of
Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and
Distinguished Encoding Rules (DER).
<span class="h3"><a class="selflink" id="section-8.2" href="#section-8.2">8.2</a>. Informative References</span>
[<a id="ref-8">8</a>] OASIS, "Key Management Interoperability Protocol (KMIP) 1.1",
January 2013, <<a href="http://docs.oasis-open.org/kmip/spec/v1.1/os/kmip-spec-v1.1-os.html">http://docs.oasis-open.org/kmip/spec/v1.1/os/</a>
<a href="http://docs.oasis-open.org/kmip/spec/v1.1/os/kmip-spec-v1.1-os.html">kmip-spec-v1.1-os.html</a>>.
<span class="grey">Joseph & Susoy Informational [Page 10]</span><span id="page-11" ></span>
<span class="grey"><a href="./rfc7076">RFC 7076</a> P6R's Secure Shell Public Key Subsystem November 2013</span>
Authors' Addresses
Mark Joseph, PhD
P6R, Inc
1840 41st Ave
Suite 102-139
Capitola, CA 95010
US
Phone: +1 888 452 2580 (x702)
EMail: [email protected]
Jim Susoy
P6R, Inc
1840 41st Ave
Suite 102-139
Capitola, CA 95010
US
Phone: +1 888 452 2580 (x701)
EMail: [email protected]
Joseph & Susoy Informational [Page 11]
Annotations
Select text to annotate