Using the NETCONF Protocol over Secure Shell (SSH)
obsoletes
- rfc-4742 — Using the NETCONF Configuration Protocol over Secure SHell (SSH)
Extracted elements (20)
Running NETCONF as an SSH subsystem (rather than a shell command) avoids the need for clients to recognize shell prompts or skip over extraneous system messages sent at shell start-up, simplifying implementation.
The chunked framing mechanism was introduced in RFC 6242 to replace the EOM-only framing of RFC 4742, which was found to be insecure because ]]>]]> can appear in well-formed XML documents and could be exploited for injection attacks. Chunked framing avoids any content-dependent delimiter.
The ]]>]]> EOM sequence is retained for the initial <hello> message exchange even in RFC 6242, explicitly to avoid breaking backward compatibility with existing RFC 4742 implementations. The associated threat is judged low for this limited use.
The end-of-message framing mechanism is used only for backward compatibility with implementations that do not advertise a base protocol version supporting chunked encoding (i.e., only :base:1.0). When both peers support :base:1.1, chunked framing is used instead.
If the chunk-size value is invalid or an error occurs during decoding of chunked framing, the peer MUST terminate the NETCONF session by closing the corresponding SSH channel. Implementations MUST ensure they are not vulnerable to buffer overrun.
NETCONF servers MUST default to providing access to the 'netconf' SSH subsystem only when the SSH session is established using TCP port 830. Servers SHOULD be configurable to allow access over other ports.
The <hello> message MUST be followed by the character sequence ]]>]]> by both peers, regardless of which framing mechanism is subsequently negotiated. This preserves backward compatibility with RFC 4742 implementations.
The SSH username is passed to the NETCONF message layer without modification. If the username is not representable in XML (i.e., does not comply with NETCONF username requirements in RFC 6241), the SSH session MUST be dropped.
When a NETCONF server processes a <close-session> operation, it SHALL respond and close the SSH session channel. The NETCONF server MUST NOT process any NETCONF messages received after the <close-session> operation.
When using end-of-message framing, the sequence ]]>]]> MUST be sent by both the NETCONF client and the NETCONF server after each message in the NETCONF exchange.
NETCONF is invoked as an SSH subsystem named 'netconf' over an SSH session-type channel. Subsystem support is a feature of SSHv2 only; SSHv1 is not supported. Using a subsystem avoids the need to parse shell prompts or skip extraneous startup messages.
Upon session establishment, both the NETCONF server and client send an XML <hello> element listing capabilities. The server's <hello> includes a <session-id>; both sides may send simultaneously. The <hello> exchange determines which framing mechanism is used for the remainder of the session.
IANA assigned TCP port 830 as the default port for NETCONF over SSH sessions (originally under RFC 4742, updated to reference RFC 6242). IANA also assigned 'netconf' as an SSH Subsystem Name per RFC 4250, updated to reference this document.
Configuration and state data may include sensitive information such as usernames and security keys. NETCONF requires communications channels providing strong encryption for data privacy; the SSH mapping defined here satisfies this requirement.
Defaulting to TCP port 830 enables firewalls and network devices to identify and filter NETCONF over SSH traffic, but also makes it easier for attackers to identify. Allowing the subsystem on other ports without corresponding firewall changes may expose NETCONF to unauthorized access.
The EOM sequence ]]>]]> can legally appear in XML attributes, comments, and processing instructions, contrary to the assumption in RFC 4742. If sent deliberately in RPC messages it can cause operational problems or injection attacks. RFC 6242 limits EOM use to the initial <hello> message and uses chunked framing thereafter to eliminate this attack surface.
The identity of the SSH server MUST be verified and authenticated by the SSH client according to local policy before any password-based authentication data or configuration/state data is exchanged. Likewise, the SSH server MUST verify and authenticate the SSH client before sending any data.
After the <hello> exchange, the framing mechanism is selected: if both peers advertise the :base:1.1 capability, the chunked framing mechanism is used for all subsequent messages; otherwise the legacy end-of-message (]]>]]>) mechanism is used. The transition is one-way at session start.
The chunked framing mechanism encodes each NETCONF message as one or more chunks, each prefixed by LF '#' chunk-size LF, followed by chunk-data octets. The message is terminated by LF '##' LF (end-of-chunks). The chunk-size field is a decimal string with no leading zeros; maximum value is 4294967295.
The end-of-message framing mechanism uses the special character sequence ]]>]]> as a message delimiter appended after each complete XML document (NETCONF message). The SSH transport layer passes data between delimiters to the Messages layer.