File 3903-ssh-Documentation.patch of Package erlang
From e8eb0d78b59f91c75affc9f4b13625500e294c7d Mon Sep 17 00:00:00 2001
From: Hans Nilsson <hans@erlang.org>
Date: Tue, 27 Apr 2021 15:51:50 +0200
Subject: [PATCH 3/4] ssh: Documentation
---
lib/public_key/doc/src/public_key.xml | 19 +++++++++++++
lib/ssh/doc/src/ssh.xml | 41 +++++++++++++++++++++++++--
lib/ssh/doc/src/ssh_file.xml | 39 +++++++++++++++++++++++++
3 files changed, 97 insertions(+), 2 deletions(-)
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
index 46dc54e24b..4f569f2c6d 100644
--- a/lib/public_key/doc/src/public_key.xml
+++ b/lib/public_key/doc/src/public_key.xml
@@ -935,6 +935,12 @@ end
<name name="ssh_decode" arity="2" since="OTP R14B03"/>
<fsummary>Decodes an SSH file-binary.</fsummary>
<desc>
+ <note>
+ <p>This function is deprecated and should not be used in new programs. Use
+ <seemfa marker="ssh:ssh_file#decode/2">ssh_file:decode/2</seemfa>
+ instead.
+ </p>
+ </note>
<p>Decodes an SSH file-binary. In the case of <c>known_hosts</c> or
<c>auth_keys</c>, the binary can include one or more lines of the
file. Returns a list of public keys and their attributes, possible
@@ -967,6 +973,12 @@ end
<name name="ssh_encode" arity="2" since="OTP R14B03"/>
<fsummary>Encodes a list of SSH file entries to a binary.</fsummary>
<desc>
+ <note>
+ <p>This function is deprecated and should not be used in new programs. Use
+ <seemfa marker="ssh:ssh_file#encode/2">ssh_file:encode/2</seemfa>
+ instead.
+ </p>
+ </note>
<p>Encodes a list of SSH file entries (public keys and attributes) to a binary. Possible
attributes depend on the file type, see
<seemfa marker="#ssh_decode/2"> ssh_decode/2 </seemfa>.
@@ -988,6 +1000,13 @@ end
</type>
<desc>
<p>Calculates a ssh fingerprint from a public host key as openssh does.</p>
+ <note>
+ <p>This function is deprecated and should not be used in new programs. Use
+ <seemfa marker="ssh:ssh#hostkey_fingerprint/1">ssh:hostkey_fingerprint/1</seemfa> or
+ <seemfa marker="ssh:ssh#hostkey_fingerprint/2">ssh:hostkey_fingerprint/2</seemfa>
+ instead.
+ </p>
+ </note>
<p>The algorithm in <c>ssh_hostkey_fingerprint/1</c> is md5 to be compatible with older
ssh-keygen commands. The string from the second variant is prepended by the algorithm name
in uppercase as in newer ssh-keygen commands.</p>
diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
index 01db6bd953..377643e69e 100644
--- a/lib/ssh/doc/src/ssh.xml
+++ b/lib/ssh/doc/src/ssh.xml
@@ -229,7 +229,7 @@
<list type="bulleted">
<item><c>PeerName</c> - a string with the name or address of the remote host.</item>
<item><c>FingerPrint</c> - the fingerprint of the Host Key as
- <seemfa marker="public_key:public_key#ssh_hostkey_fingerprint/1">public_key:ssh_hostkey_fingerprint/1</seemfa>
+ <seemfa marker="#hostkey_fingerprint/1">hostkey_fingerprint/1</seemfa>
calculates it.
</item>
</list>
@@ -239,7 +239,7 @@
shall be used to calculate the fingerprint used in the call of the <c>accept_callback()</c>.
The <c>HashALgoSpec</c>
is either an atom or a list of atoms as the first argument in
- <seemfa marker="public_key:public_key#ssh_hostkey_fingerprint/2">public_key:ssh_hostkey_fingerprint/2</seemfa>.
+ <seemfa marker="#hostkey_fingerprint/2">hostkey_fingerprint/2</seemfa>.
If it is a list of hash algorithm names, the <c>FingerPrint</c> argument in the
<c>accept_callback()</c> will be
a list of fingerprints in the same order as the corresponding name in the <c>HashAlgoSpec</c> list.
@@ -1526,6 +1526,43 @@
</desc>
</func>
+ <func>
+ <name since="OTP 24.0">hostkey_fingerprint(HostKey) -> string()</name>
+ <name since="OTP 24.0">hostkey_fingerprint(DigestType, HostKey) -> string()</name>
+ <name since="OTP 24.0">hostkey_fingerprint([DigestType], HostKey) -> [string()]</name>
+ <fsummary>Calculates a ssh fingerprint for a hostkey.</fsummary>
+ <type>
+ <v>HostKey = <seetype marker="public_key:public_key#public_key">public_key:public_key()</seetype></v>
+ <v>DigestType = <seetype marker="public_key:public_key#digest_type">public_key:digest_type()</seetype></v>
+ </type>
+ <desc>
+ <p>Calculates a ssh fingerprint from a public host key as openssh does.</p>
+ <p>The algorithm in <c>hostkey_fingerprint/1</c> is md5 to be compatible with older
+ ssh-keygen commands. The string from the second variant is prepended by the algorithm name
+ in uppercase as in newer ssh-keygen commands.</p>
+ <p>Examples:</p>
+ <code>
+ 2> ssh:hostkey_fingerprint(Key).
+ "f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
+
+ 3> ssh:hostkey_fingerprint(md5,Key).
+ "MD5:f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
+
+ 4> ssh:hostkey_fingerprint(sha,Key).
+ "SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY"
+
+ 5> ssh:hostkey_fingerprint(sha256,Key).
+ "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"
+
+ 6> ssh:hostkey_fingerprint([sha,sha256],Key).
+ ["SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY",
+ "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"]
+ </code>
+ </desc>
+ </func>
+
+
+
</funcs>
</erlref>
diff --git a/lib/ssh/doc/src/ssh_file.xml b/lib/ssh/doc/src/ssh_file.xml
index dadadcc249..0858fd0359 100644
--- a/lib/ssh/doc/src/ssh_file.xml
+++ b/lib/ssh/doc/src/ssh_file.xml
@@ -348,6 +348,45 @@ key :: % encoded key from eg ssh_host_*.pub
</desc>
</func>
+ <func>
+ <name since="OTP 24.0">decode(SshBin, ssh2_pubkey) -> Key</name>
+ <name since="OTP 24.0">decode(SshBin, rfc4716_public_key) -> ResultRfc4716</name>
+ <name since="OTP 24.0">decode(SshBin, openssh_public_key) -> ResultOpenSsh</name>
+ <name since="OTP 24.0">decode(SshBin, public_key) -> ResultRfc4716 | ResultOpenSsh</name>
+ <fsummary>Decodes an SSH binary.</fsummary>
+ <type>
+ <v>SshBin = binary()</v>
+ <v>ResultRfc4716 = [{Key, [{headers,Hdrs}]}] | Error</v>
+ <v>ResultOpenSsh = [{Key, [{comment,string()}]}] | Error</v>
+ <v>Key = <seetype marker="public_key:public_key#public_key">public_key:public_key()</seetype></v>
+ <v>Hdrs = [{Tag::string(), Value::string()}]</v>
+ <v>Error = {error,term()}</v>
+ </type>
+ <desc>
+ <p>Decodes an SSH file-binary.</p>
+ <p>If <c>Type</c> is <c>public_key</c> the binary can be either
+ an RFC4716 public key or an OpenSSH public key.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name since="OTP 24.0">encode(Key, ssh2_pubkey) -> Result</name>
+ <name since="OTP 24.0">encode(KeyAttrsRfc4716, rfc4716_public_key) -> Result</name>
+ <name since="OTP 24.0">encode(KeyAttrsOpenSsh, openssh_public_key) -> Result</name>
+ <fsummary>Encodes a list of SSH file entries to a binary.</fsummary>
+ <type>
+ <v>Key = <seetype marker="public_key:public_key#public_key">public_key:public_key()</seetype></v>
+ <v>Result = binary() | Error</v>
+ <v>KeyAttrsRfc4716 = [{Key, [{headers,Hdrs}]}] | Error</v>
+ <v>KeyAttrsOpenSsh = [{Key, [{comment,string()}]}] | Error</v>
+ <v>Hdrs = [{Tag::string(), Value::string()}]</v>
+ <v>Error = {error,term()}</v>
+ </type>
+ <desc>
+ <p>Encodes a list of SSH file entries (public keys and attributes) to a binary.</p>
+ </desc>
+ </func>
+
</funcs>
</erlref>
--
2.26.2
