Crate ssh2_config

Expand description

§ssh2-config

ssh2-config a library which provides a parser for the SSH configuration file, to be used in pair with the ssh2 crate.

This library provides a method to parse the configuration file and returns the configuration parsed into a structure. The SshConfig structure provides all the attributes which can be used to configure the ssh2 Session and to resolve the host, port and username.

Once the configuration has been parsed you can use the query(&str) method to query configuration for a certain host, based on the configured patterns. Even if many attributes are not exposed, since not supported, there is anyway a validation of the configuration, so invalid configuration will result in a parsing error.

§Get started

First of you need to add ssh2-config to your project dependencies:

ssh2-config = "^0.5"

§Example

Here is a basic example:


use ssh2::Session;
use ssh2_config::{HostParams, ParseRule, SshConfig};
use std::fs::File;
use std::io::BufReader;
use std::path::Path;

let mut reader = BufReader::new(
    File::open(Path::new("./assets/ssh.config"))
        .expect("Could not open configuration file")
);

let config = SshConfig::default().parse(&mut reader, ParseRule::STRICT).expect("Failed to parse configuration");

// Query parameters for your host
// If there's no rule for your host, default params are returned
let params = config.query("192.168.1.2");

// ...

// serialize configuration to string
let s = config.to_string();

§How host parameters are resolved

This topic has been debated a lot over the years, so finally since 0.5 this has been fixed to follow the official ssh configuration file rules, as described in the MAN https://man.openbsd.org/OpenBSD-current/man5/ssh_config.5#DESCRIPTION.

Unless noted otherwise, for each parameter, the first obtained value will be used. The configuration files contain sections separated by Host specifications, and that section is only applied for hosts that match one of the patterns given in the specification. The matched host name is usually the one given on the command line (see the CanonicalizeHostname option for exceptions).

Since the first obtained value for each parameter is used, more host-specific declarations should be given near the beginning of the file, and general defaults at the end.

This means that:

The first obtained value parsing the configuration top-down will be used
Host specific rules ARE not overriding default ones if they are not the first obtained value
If you want to achieve default values to be less specific than host specific ones, you should put the default values at the end of the configuration file using Host *.
Algorithms, so KexAlgorithms, Ciphers, MACs and HostKeyAlgorithms use a different resolvers which supports appending, excluding and heading insertions, as described in the man page at ciphers: https://man.openbsd.org/OpenBSD-current/man5/ssh_config.5#Ciphers.

§Resolvers examples

Compression yes

Host 192.168.1.1
    Compression no

If we get rules for 192.168.1.1, compression will be yes, because it’s the first obtained value.

Host 192.168.1.1
    Compression no

Host *
    Compression yes

If we get rules for 192.168.1.1, compression will be no, because it’s the first obtained value.

If we get rules for 172.168.1.1, compression will be yes, because it’s the first obtained value MATCHING the host rule.


Host 192.168.1.1
    Ciphers +c

If we get rules for 192.168.1.1, ciphers will be c appended to default algorithms, which can be specified in the SshConfig constructor.

§Configuring default algorithms

When you invoke SshConfig::default, the default algorithms are set from openssh source code, which are the following:

ca_signature_algorithms:
    "ssh-ed25519",
    "ecdsa-sha2-nistp256",
    "ecdsa-sha2-nistp384",
    "ecdsa-sha2-nistp521",
    "sk-ssh-ed25519@openssh.com",
    "sk-ecdsa-sha2-nistp256@openssh.com",
    "rsa-sha2-512",
    "rsa-sha2-256",

ciphers:
    "chacha20-poly1305@openssh.com",
    "aes128-ctr,aes192-ctr,aes256-ctr",
    "aes128-gcm@openssh.com,aes256-gcm@openssh.com",

host_key_algorithms:
    "ssh-ed25519-cert-v01@openssh.com",
    "ecdsa-sha2-nistp256-cert-v01@openssh.com",
    "ecdsa-sha2-nistp384-cert-v01@openssh.com",
    "ecdsa-sha2-nistp521-cert-v01@openssh.com",
    "sk-ssh-ed25519-cert-v01@openssh.com",
    "sk-ecdsa-sha2-nistp256-cert-v01@openssh.com",
    "rsa-sha2-512-cert-v01@openssh.com",
    "rsa-sha2-256-cert-v01@openssh.com",
    "ssh-ed25519",
    "ecdsa-sha2-nistp256",
    "ecdsa-sha2-nistp384",
    "ecdsa-sha2-nistp521",
    "sk-ssh-ed25519@openssh.com",
    "sk-ecdsa-sha2-nistp256@openssh.com",
    "rsa-sha2-512",
    "rsa-sha2-256",

kex_algorithms:
    "sntrup761x25519-sha512",
    "sntrup761x25519-sha512@openssh.com",
    "mlkem768x25519-sha256",
    "curve25519-sha256",
    "curve25519-sha256@libssh.org",
    "ecdh-sha2-nistp256",
    "ecdh-sha2-nistp384",
    "ecdh-sha2-nistp521",
    "diffie-hellman-group-exchange-sha256",
    "diffie-hellman-group16-sha512",
    "diffie-hellman-group18-sha512",
    "diffie-hellman-group14-sha256",
    "ssh-ed25519-cert-v01@openssh.com",
    "ecdsa-sha2-nistp256-cert-v01@openssh.com",
    "ecdsa-sha2-nistp384-cert-v01@openssh.com",
    "ecdsa-sha2-nistp521-cert-v01@openssh.com",
    "sk-ssh-ed25519-cert-v01@openssh.com",
    "sk-ecdsa-sha2-nistp256-cert-v01@openssh.com",
    "rsa-sha2-512-cert-v01@openssh.com",
    "rsa-sha2-256-cert-v01@openssh.com",
    "ssh-ed25519",
    "ecdsa-sha2-nistp256",
    "ecdsa-sha2-nistp384",
    "ecdsa-sha2-nistp521",
    "sk-ssh-ed25519@openssh.com",
    "sk-ecdsa-sha2-nistp256@openssh.com",
    "rsa-sha2-512",
    "rsa-sha2-256",
    "chacha20-poly1305@openssh.com",
    "aes128-ctr,aes192-ctr,aes256-ctr",
    "aes128-gcm@openssh.com,aes256-gcm@openssh.com",
    "chacha20-poly1305@openssh.com",
    "aes128-ctr,aes192-ctr,aes256-ctr",
    "aes128-gcm@openssh.com,aes256-gcm@openssh.com",
    "umac-64-etm@openssh.com",
    "umac-128-etm@openssh.com",
    "hmac-sha2-256-etm@openssh.com",
    "hmac-sha2-512-etm@openssh.com",
    "hmac-sha1-etm@openssh.com",
    "umac-64@openssh.com",
    "umac-128@openssh.com",
    "hmac-sha2-256",
    "hmac-sha2-512",
    "hmac-sha1",
    "umac-64-etm@openssh.com",
    "umac-128-etm@openssh.com",
    "hmac-sha2-256-etm@openssh.com",
    "hmac-sha2-512-etm@openssh.com",
    "hmac-sha1-etm@openssh.com",
    "umac-64@openssh.com",
    "umac-128@openssh.com",
    "hmac-sha2-256",
    "hmac-sha2-512",
    "hmac-sha1",
    "none,zlib@openssh.com",
    "none,zlib@openssh.com",

mac:
    "umac-64-etm@openssh.com",
    "umac-128-etm@openssh.com",
    "hmac-sha2-256-etm@openssh.com",
    "hmac-sha2-512-etm@openssh.com",
    "hmac-sha1-etm@openssh.com",
    "umac-64@openssh.com",
    "umac-128@openssh.com",
    "hmac-sha2-256",
    "hmac-sha2-512",
    "hmac-sha1",

pubkey_accepted_algorithms:
    "ssh-ed25519-cert-v01@openssh.com",
    "ecdsa-sha2-nistp256-cert-v01@openssh.com",
    "ecdsa-sha2-nistp384-cert-v01@openssh.com",
    "ecdsa-sha2-nistp521-cert-v01@openssh.com",
    "sk-ssh-ed25519-cert-v01@openssh.com",
    "sk-ecdsa-sha2-nistp256-cert-v01@openssh.com",
    "rsa-sha2-512-cert-v01@openssh.com",
    "rsa-sha2-256-cert-v01@openssh.com",
    "ssh-ed25519",
    "ecdsa-sha2-nistp256",
    "ecdsa-sha2-nistp384",
    "ecdsa-sha2-nistp521",
    "sk-ssh-ed25519@openssh.com",
    "sk-ecdsa-sha2-nistp256@openssh.com",
    "rsa-sha2-512",
    "rsa-sha2-256",

If you want you can use a custom constructor SshConfig::default_algorithms to set your own default algorithms.

Structs§

Algorithms: List of algorithms to be used. The algorithms can be appended to the default set, placed at the head of the list, excluded from the default set, or set as the default set.
DefaultAlgorithms: Default algorithms for ssh.
Host: Describes the rules to be used for a certain host
HostClause: Describes a single clause to match host
HostParams: Describes the ssh configuration. Configuration is describes in this document: http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5 Only arguments supported by libssh2 are implemented
ParseRule: The parsing mode
SshConfig: Describes the ssh configuration. Configuration is described in this document: http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5

Enums§

SshParserError: Ssh config parser error

Type Aliases§

SshParserResult

Crate ssh2_configCopy item path