RFC 7076

P6R's Secure Shell Public Key Subsystem 🎀

Okay bestie, this is RFC 7076, titled "P6R's Secure Shell Public Key Subsystem" 💖 It was written by M. Joseph and J. Susoy from P6R, Inc 🌸 It's Category Informational, which means it's published for info and isn't an Internet Standards Track spec. It came out in November 2013 as an Independent Submission, ISSN 2070-1721 ✨ The header doesn't list anything it obsoletes or updates, so it's standing on its own 🦋

Abstract

Okay so the Secure Shell (SSH) Public Key Subsystem is a key distribution protocol, and its whole deal is provisioning an SSH server with a user's public keys 🔑 That's it, that's the job 💅 This doc describes a new protocol that builds on RFC 4819 so you can provision keys and certificates onto a server over the SSH transport 🧚

The new protocol lets the client organize keys and certificates into different namespaces on a server 🫶 The server can use those namespaces so a client can configure any application running on it, like SSH, Key Management Interoperability Protocol (KMIP), or Simple Network Management Protocol (SNMP) 🌈

It gives you a server-independent way to add public keys, remove public keys, add certificates, remove certificates, and list the current set of keys and certificates the server knows about, by namespace (so you could list all the public keys in the SSH namespace, iykyk) ✨

Rights to manage keys and certificates in a particular namespace are specific and limited to the authorized user, and they're defined as part of the server's implementation 🔒 The protocol is backward compatible with version 2 from RFC 4819 💜

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 chose to publish it at their discretion and makes no statement about its value for implementation or deployment 🙈 Documents the RFC Editor approves for publication are not a candidate for any level of Internet Standard, see Section 2 of RFC 5741 💀

Info about the current status of this document, any errata, and how to give feedback is at http://www.rfc-editor.org/info/rfc7076 🍓

Copyright Notice

Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. 💜

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication. Please review those documents carefully, because they describe your rights and restrictions with respect to this document 👑

Table of Contents

1. Introduction ....................................................3
2. Terminology .....................................................3
3. Overview of Extensions to the Public Key Subsystem ..............3
   3.1. Extended Status Codes ......................................4
   3.2. The Version Packet .........................................4
   3.3. The Namespace Attribute ....................................4
4. New Operations ..................................................5
   4.1. Adding a Certificate .......................................5
   4.2. Removing a Certificate .....................................6
   4.3. Listing Certificates .......................................6
   4.4. Listing Namespaces .........................................7
5. Extending Public Key Operations .................................8
   5.1. Adding a Public Key ........................................8
   5.2. Removing a Public Key ......................................8
   5.3. Listing Public Keys ........................................9
6. Security Considerations .........................................9
7. IANA Considerations ............................................10
8. References .....................................................10
   8.1. Normative References ......................................10
   8.2. Informative References ....................................10

1. Introduction ✨

Okay so this doc is a new protocol that builds on RFC 4819, and it's used to configure public keys and certificates in an implementation-independent way 🌸 The big new idea is the namespace, which lets the client organize keys and certificates by application or organizational structure 🎀

P6R's Secure Shell Public Key Subsystem is designed to run on top of the Secure Shell transport layer [3] and user authentication protocols [4] 🦋 It gives the client a simple way to manage the public keys and certificates on the server that relate to that client 💖 These keys and certificates are normally used to authenticate the client to a service, but they can also be used for encrypting results back to the client 🔐 Uploaded keys and certificates are meant to configure all protocols running on a server (like SSH, SSL, and KMIP [8]) that use keys and certificates, plus the applications on the server itself 🧚

This document should be read only after reading the Secure Shell Public Key Subsystem [1] document. The new protocol described here builds on and is meant to be backwards compatible with the protocol in [1] 💅

2. Terminology 📖

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 RFC 2119 [2] 🫶

3. Overview of Extensions to the Public Key Subsystem 🌈

The Public Key Subsystem gives you a server-independent way to add public keys, remove public keys, list the current public keys the server knows, add certificates, remove certificates, and list the current set of certificates the server knows 🔑 This secure key distribution mechanism is implemented by a new SSH subsystem named publickey@p6r.com 🧁

3.1. Extended Status Codes 🚦

The status code gives the status in a more machine-readable format (suitable for localization). It can have these 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 failure codes mean what their names say 💀 Check Security Considerations for how to use the failure code SSH_PUBLICKEY_ACTION_NOT_AUTHORIZED 🔥

3.2. The Version Packet 🎟️

Both sides MUST start a connection by sending a version packet that says which version of the protocol they're using 🫶

     string "version"
     uint32 protocol-version-number

This document defines version 3 of the new protocol 💜 Version 3 is used so it stays backward compatible with the protocol from RFC 4819 [1] 🦋

3.3. The Namespace Attribute 🗂️

The "namespace" attribute is added as an extension to what RFC 4819 describes 🌸 Its purpose is to organize uploaded keys and certificates into groups, where each group represents an application or organizational structure 🍓 This attribute is a string that should not be longer than 300 characters, and it MUST be specified in UTF-8 format [5] 💅

This new protocol uses the "ssh" namespace to manipulate public keys on an SSH server, and it should be considered the default namespace when none is provided 🔑

By convention, namespaces used for protocols are lowercase strings of the protocol's standard abbreviation. For example, "ssl" should be the namespace for the Secure Sockets Layer protocol 🔐 Namespaces for applications should contain the product and vendor's name 🧚 To help figure out which namespaces already exist on a server, a new operation called "list-namespaces" is defined in Section 4 ✨

4. New Operations 🎀

P6R's Public Key Subsystem extends the functionality from RFC 4819 with these operations: add-certificate, remove-certificate, list-certificates, and list-namespaces 👑

4.1. Adding a Certificate 💖

If the client wants 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 the server knows where to save the certificate 🌈 Only one namespace attribute can be used per add-certificate request 🙈 The same user can save the same certificate into multiple namespaces, but that has to be done with several separate add-certificate requests 🦋

If the namespace in an add-certificate request doesn't already exist on a server, this operation creates it ✨ But if the user isn't 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 give the user an option to overwrite the certificate 🔄 If the overwrite field is true and the specified key already exists in the given namespace but can't be overwritten, the server MUST return SSH_PUBLICKEY_ACCESS_DENIED 🚫

But a user may not be authorized to add a certificate to the specified namespace 🙅‍♀️ If the user doesn't have permission to add a certificate, 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 is detailed in Section 6.6, "Public Key Algorithms", of the SSH Transport Protocol document [3], and X.509 certificates are encoded in a DER format [6] [7] inside a certificate blob 🌸

4.2. Removing a Certificate 🗑️

If the client wants 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 the server knows where to delete the certificate from 🫶 Only one namespace attribute can be used per remove-certificate request 🍓 The server MUST attempt to remove the certificate from the appropriate location 🧹

But a user may not be authorized to remove a certificate from the specified namespace 🙈 If the user doesn't have permission to remove the certificate, the server MUST return SSH_PUBLICKEY_ACTION_NOT_AUTHORIZED 🔐

Examples of possible "certificate format names" are "X509", "pgp-sign-rsa", and "pgp-sign-dss" 🧚

---

4.3. Listing Certificates 📜✨

Okay so if the client wants to list the known certificates, it sends this bestie:

string    "list-certificates"

The server replies with zero or more of these responses:

string    "certificate"
string    certificate format name
string    certificate blob
uint32    attribute-count
 string    attrib-name
 string    attrib-value
repeated attribute-count times

There is no requirement that the responses come back in any particular order 🌀 Some servers might send them in a certain order, but client implementations should not rely on responses being in any order. Don't build your whole life around it, babe 💅

This response MUST include at least the "namespace" attribute so a client can tell which namespace the certificate lives in 🏠 Only one namespace attribute can be used per list-certificate request.

Once the last "certificate" response has been sent, a status packet MUST be sent 📦

---

4.4. Listing Namespaces 🗂️💖

If the client wants to know which namespaces exist on the server, it sends:

string    "list-namespaces"

The server replies with zero or more of these responses:

string    "namespace"
string    namespace name

Not every namespace is visible to every authenticated user 👀 So in that case, the responding server will return only a subset of the existing namespaces. Check Security Considerations below, it's giving serious vibes 🔐

After the last "namespace" response, a status packet MUST be sent 📦✨

---

5. Extending Public Key Operations 🔑🦋

In addition to the new operations, this document describes extensions to the operations already defined in RFC 4819. So we're upgrading the old stuff too 💅

5.1. Adding a Public Key 🌸

If the client wants to add a public key, it 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 the client can save the public key into a specific namespace 🎯 The same user can save the same key into multiple namespaces, but that takes a separate add request for each one.

If the namespace in an add public key request doesn't already exist on the server, this operation creates it ✨ But if the user isn't authorized to create a namespace, the server MUST return SSH_PUBLICKEY_CANNOT_CREATE_NAMESPACE. Not allowed, bestie 🙅‍♀️

5.2. Removing a Public Key 🗑️

If the client wants to remove a public key, it 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 lets attributes be added to a remove request 🎀 This request MAY include one "namespace" attribute so the client can remove the public key from a specific namespace.

5.3. Listing Public Keys 🔍💜

If the client wants to list the known public keys, it sends:

string    "list"
uint32    attribute-count
 string    attrib-name
 string    attrib-value
 bool      critical
repeated attribute-count times

This extension lets attributes be added to a list request too ✨ This request MAY include one "namespace" attribute so the client can list the public keys from a specific namespace.

The server replies with zero or more of these 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 the client can tell which namespace each key lives in 🧚

---

6. Security Considerations 🔐💀

Okay bestie, read this part twice 😭 This protocol assumes it runs over a secure channel and that the endpoints of that channel have been authenticated. So it assumes it's already protected from network-level attacks by something outside itself 🛡️

This protocol gives you a way to upload key and certificate material and manipulate it inside a server application. It is the server implementation's job to enforce any access controls needed to limit what a particular user can do with the data in a namespace. For example, one user might be allowed to only list the contents of a namespace, but not add or remove keys or certificates to or from it 🙅‍♀️ The server MUST return SSH_PUBLICKEY_ACTION_NOT_AUTHORIZED when a user's action goes against its defined access controls. No exceptions, no vibes-based permissions 🚫

This protocol requires the client to assume that the server will correctly implement and observe the attributes applied to keys 🥺 Implementation errors on the server could make clients authorize keys and certificates for access they weren't meant to have, or apply fewer restrictions than were intended. Scary, I know 👻 So please, test your servers 🫶

---

7. IANA Considerations 📋🌈

Although Section 3.1 defines four new status codes, these live in the 'Private Use' range of IANA's Publickey Subsystem Status Codes registry, as defined by Section 6.6.1 ("Conventions") in [1]. So no IANA actions are required for this document 🎉

---

8. References 📚💅

8.1. Normative References 🧠

[1] Galbraith, J., Van Dyke, J., and J. Bright, "Secure Shell Public Key Subsystem", RFC 4819, March 2007.

[2] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.

[3] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Transport Layer Protocol", RFC 4253, January 2006.

[4] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Authentication Protocol", RFC 4252, January 2006.

[5] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.

[6] 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", RFC 5280, May 2008.

[7] 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).

8.2. Informative References 🌷

[8] OASIS, "Key Management Interoperability Protocol (KMIP) 1.1", January 2013, http://docs.oasis-open.org/kmip/spec/v1.1/os/kmip-spec-v1.1-os.html.

---

Authors' Addresses 💌

Mark Joseph, PhD
P6R, Inc
1840 41st Ave
Suite 102-139
Capitola, CA 95010
US

Phone: +1 888 452 2580 (x702)
EMail: mark@p6r.com


Jim Susoy
P6R, Inc
1840 41st Ave
Suite 102-139
Capitola, CA 95010
US

Phone: +1 888 452 2580 (x701)
EMail: jim@p6r.com