|
Packit Service |
31306d |
/**
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@mainpage
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
This is the online reference for developing with the libssh library. It
|
|
Packit Service |
31306d |
documents the libssh C API and the C++ wrapper.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@section main-linking Linking
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
We created a small howto how to link libssh against your application, read
|
|
Packit Service |
31306d |
@subpage libssh_linking.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@section main-tutorial Tutorial
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
You should start by reading @subpage libssh_tutorial, then reading the documentation of
|
|
Packit Service |
31306d |
the interesting functions as you go.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@section main-features Features
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
The libssh library provides:
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
- Key Exchange Methods: curve25519-sha256, curve25519-sha256@libssh.org, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group1-sha1, diffie-hellman-group14-sha1
|
|
Packit Service |
31306d |
- Public Key Algorithms: ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-rsa, rsa-sha2-512, rsa-sha2-256,ssh-dss
|
|
Packit Service |
31306d |
- Ciphers: aes256-ctr, aes192-ctr, aes128-ctr, aes256-cbc (rijndael-cbc@lysator.liu.se), aes192-cbc, aes128-cbc, 3des-cbc, blowfish-cbc, none
|
|
Packit Service |
31306d |
- Compression Schemes: zlib, zlib@openssh.com, none
|
|
Packit Service |
31306d |
- MAC hashes: hmac-sha1, hmac-sha2-256, hmac-sha2-512, hmac-md5, none
|
|
Packit Service |
31306d |
- Authentication: none, password, public-key, keyboard-interactive, gssapi-with-mic
|
|
Packit Service |
31306d |
- Channels: shell, exec (incl. SCP wrapper), direct-tcpip, subsystem, auth-agent-req@openssh.com
|
|
Packit Service |
31306d |
- Global Requests: tcpip-forward, forwarded-tcpip
|
|
Packit Service |
31306d |
- Channel Requests: x11, pty, exit-status, signal, exit-signal, keepalive@openssh.com, auth-agent-req@openssh.com
|
|
Packit Service |
31306d |
- Subsystems: sftp(version 3), OpenSSH Extensions
|
|
Packit Service |
31306d |
- SFTP: statvfs@openssh.com, fstatvfs@openssh.com
|
|
Packit Service |
31306d |
- Thread-safe: Just don't share sessions
|
|
Packit Service |
31306d |
- Non-blocking: it can be used both blocking and non-blocking
|
|
Packit Service |
31306d |
- Your sockets: the app hands over the socket, or uses libssh sockets
|
|
Packit Service |
31306d |
- OpenSSL or gcrypt: builds with either
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@section main-additional-features Additional Features
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
- Client and server support
|
|
Packit Service |
31306d |
- SSHv2 and SSHv1 protocol support
|
|
Packit Service |
31306d |
- Supports Linux, UNIX, BSD, Solaris, OS/2 and Windows
|
|
Packit Service |
31306d |
- Automated test cases with nightly tests
|
|
Packit Service |
31306d |
- Event model based on poll(2), or a poll(2)-emulation.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@section main-copyright Copyright Policy
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
libssh is a project with distributed copyright ownership, which means we prefer
|
|
Packit Service |
31306d |
the copyright on parts of libssh to be held by individuals rather than
|
|
Packit Service |
31306d |
corporations if possible. There are historical legal reasons for this, but one
|
|
Packit Service |
31306d |
of the best ways to explain it is that it’s much easier to work with
|
|
Packit Service |
31306d |
individuals who have ownership than corporate legal departments if we ever need
|
|
Packit Service |
31306d |
to make reasonable compromises with people using and working with libssh.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
We track the ownership of every part of libssh via git, our source code control
|
|
Packit Service |
31306d |
system, so we know the provenance of every piece of code that is committed to
|
|
Packit Service |
31306d |
libssh.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
So if possible, if you’re doing libssh changes on behalf of a company who
|
|
Packit Service |
31306d |
normally owns all the work you do please get them to assign personal copyright
|
|
Packit Service |
31306d |
ownership of your changes to you as an individual, that makes things very easy
|
|
Packit Service |
31306d |
for us to work with and avoids bringing corporate legal departments into the
|
|
Packit Service |
31306d |
picture.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
If you can’t do this we can still accept patches from you owned by your
|
|
Packit Service |
31306d |
employer under a standard employment contract with corporate copyright
|
|
Packit Service |
31306d |
ownership. It just requires a simple set-up process first.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
We use a process very similar to the way things are done in the Linux Kernel
|
|
Packit Service |
31306d |
community, so it should be very easy to get a sign off from your corporate
|
|
Packit Service |
31306d |
legal department. The only changes we’ve made are to accommodate the license we
|
|
Packit Service |
31306d |
use, which is LGPLv2 (or later) whereas the Linux kernel uses GPLv2.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
The process is called signing.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
How to sign your work
|
|
Packit Service |
31306d |
----------------------
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
Once you have permission to contribute to libssh from your employer, simply
|
|
Packit Service |
31306d |
email a copy of the following text from your corporate email address to:
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
contributing@libssh.org
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@verbatim
|
|
Packit Service |
31306d |
libssh Developer's Certificate of Origin. Version 1.0
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
By making a contribution to this project, I certify that:
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
(a) The contribution was created in whole or in part by me and I
|
|
Packit Service |
31306d |
have the right to submit it under the appropriate
|
|
Packit Service |
31306d |
version of the GNU General Public License; or
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
(b) The contribution is based upon previous work that, to the best of
|
|
Packit Service |
31306d |
my knowledge, is covered under an appropriate open source license
|
|
Packit Service |
31306d |
and I have the right under that license to submit that work with
|
|
Packit Service |
31306d |
modifications, whether created in whole or in part by me, under
|
|
Packit Service |
31306d |
the GNU General Public License, in the appropriate version; or
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
(c) The contribution was provided directly to me by some other
|
|
Packit Service |
31306d |
person who certified (a) or (b) and I have not modified it.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
(d) I understand and agree that this project and the contribution are
|
|
Packit Service |
31306d |
public and that a record of the contribution (including all
|
|
Packit Service |
31306d |
metadata and personal information I submit with it, including my
|
|
Packit Service |
31306d |
sign-off) is maintained indefinitely and may be redistributed
|
|
Packit Service |
31306d |
consistent with the libssh Team's policies and the requirements of
|
|
Packit Service |
31306d |
the GNU GPL where they are relevant.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
(e) I am granting this work to this project under the terms of the
|
|
Packit Service |
31306d |
GNU Lesser General Public License as published by the
|
|
Packit Service |
31306d |
Free Software Foundation; either version 2.1 of
|
|
Packit Service |
31306d |
the License, or (at the option of the project) any later version.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
https://www.gnu.org/licenses/lgpl-2.1.html
|
|
Packit Service |
31306d |
@endverbatim
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
We will maintain a copy of that email as a record that you have the rights to
|
|
Packit Service |
31306d |
contribute code to libssh under the required licenses whilst working for the
|
|
Packit Service |
31306d |
company where the email came from.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
Then when sending in a patch via the normal mechanisms described above, add a
|
|
Packit Service |
31306d |
line that states:
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@verbatim
|
|
Packit Service |
31306d |
Signed-off-by: Random J Developer <random@developer.example.org>
|
|
Packit Service |
31306d |
@endverbatim
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
using your real name and the email address you sent the original email you used
|
|
Packit Service |
31306d |
to send the libssh Developer’s Certificate of Origin to us (sorry, no
|
|
Packit Service |
31306d |
pseudonyms or anonymous contributions.)
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
That’s it! Such code can then quite happily contain changes that have copyright
|
|
Packit Service |
31306d |
messages such as:
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@verbatim
|
|
Packit Service |
31306d |
(c) Example Corporation.
|
|
Packit Service |
31306d |
@endverbatim
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
and can be merged into the libssh codebase in the same way as patches from any
|
|
Packit Service |
31306d |
other individual. You don’t need to send in a copy of the libssh Developer’s
|
|
Packit Service |
31306d |
Certificate of Origin for each patch, or inside each patch. Just the sign-off
|
|
Packit Service |
31306d |
message is all that is required once we’ve received the initial email.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
Have fun and happy libssh hacking!
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
The libssh Team
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@section main-rfc Internet standard
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@subsection main-rfc-secsh Secure Shell (SSH)
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
The following RFC documents described SSH-2 protcol as an Internet standard.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
- RFC 4250,
|
|
Packit Service |
31306d |
The Secure Shell (SSH) Protocol Assigned Numbers
|
|
Packit Service |
31306d |
- RFC 4251,
|
|
Packit Service |
31306d |
The Secure Shell (SSH) Protocol Architecture
|
|
Packit Service |
31306d |
- RFC 4252,
|
|
Packit Service |
31306d |
The Secure Shell (SSH) Authentication Protocol
|
|
Packit Service |
31306d |
- RFC 4253,
|
|
Packit Service |
31306d |
The Secure Shell (SSH) Transport Layer Protocol
|
|
Packit Service |
31306d |
- RFC 4254,
|
|
Packit Service |
31306d |
The Secure Shell (SSH) Connection Protocol
|
|
Packit Service |
31306d |
- RFC 4255,
|
|
Packit Service |
31306d |
Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints
|
|
Packit Service |
31306d |
(not implemented in libssh)
|
|
Packit Service |
31306d |
- RFC 4256,
|
|
Packit Service |
31306d |
Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)
|
|
Packit Service |
31306d |
- RFC 4335,
|
|
Packit Service |
31306d |
The Secure Shell (SSH) Session Channel Break Extension
|
|
Packit Service |
31306d |
- RFC 4344,
|
|
Packit Service |
31306d |
The Secure Shell (SSH) Transport Layer Encryption Modes
|
|
Packit Service |
31306d |
- RFC 4345,
|
|
Packit Service |
31306d |
Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer Protocol
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
It was later modified and expanded by the following RFCs.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
- RFC 4419,
|
|
Packit Service |
31306d |
Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer
|
|
Packit Service |
31306d |
Protocol
|
|
Packit Service |
31306d |
- RFC 4432,
|
|
Packit Service |
31306d |
RSA Key Exchange for the Secure Shell (SSH) Transport Layer Protocol
|
|
Packit Service |
31306d |
(not implemented in libssh)
|
|
Packit Service |
31306d |
- RFC 4462,
|
|
Packit Service |
31306d |
Generic Security Service Application Program Interface (GSS-API)
|
|
Packit Service |
31306d |
Authentication and Key Exchange for the Secure Shell (SSH) Protocol
|
|
Packit Service |
31306d |
(only the authentication implemented in libssh)
|
|
Packit Service |
31306d |
- RFC 4716,
|
|
Packit Service |
31306d |
The Secure Shell (SSH) Public Key File Format
|
|
Packit Service |
31306d |
(not implemented in libssh)
|
|
Packit Service |
31306d |
- RFC 5647,
|
|
Packit Service |
31306d |
AES Galois Counter Mode for the Secure Shell Transport Layer Protocol
|
|
Packit Service |
31306d |
(the algorithm negotiation implemented according to openssh.com)
|
|
Packit Service |
31306d |
- RFC 5656,
|
|
Packit Service |
31306d |
Elliptic Curve Algorithm Integration in the Secure Shell Transport Layer
|
|
Packit Service |
31306d |
- RFC 6594,
|
|
Packit Service |
31306d |
Use of the SHA-256 Algorithm with RSA, DSA, and ECDSA in SSHFP Resource Records
|
|
Packit Service |
31306d |
(not implemented in libssh)
|
|
Packit Service |
31306d |
- RFC 6668,
|
|
Packit Service |
31306d |
SHA-2 Data Integrity Verification for the Secure Shell (SSH) Transport Layer Protocol
|
|
Packit Service |
31306d |
- RFC 7479,
|
|
Packit Service |
31306d |
Using Ed25519 in SSHFP Resource Records
|
|
Packit Service |
31306d |
(not implemented in libssh)
|
|
Packit Service |
31306d |
- RFC 8160,
|
|
Packit Service |
31306d |
IUTF8 Terminal Mode in Secure Shell (SSH)
|
|
Packit Service |
31306d |
(not handled in libssh)
|
|
Packit Service |
31306d |
- RFC 8270,
|
|
Packit Service |
31306d |
Increase the Secure Shell Minimum Recommended Diffie-Hellman Modulus Size to 2048 Bits
|
|
Packit Service |
31306d |
- RFC 8308,
|
|
Packit Service |
31306d |
Extension Negotiation in the Secure Shell (SSH) Protocol
|
|
Packit Service |
31306d |
(only the "server-sig-algs" extension implemented)
|
|
Packit Service |
31306d |
- RFC 8332,
|
|
Packit Service |
31306d |
Use of RSA Keys with SHA-256 and SHA-512 in the Secure Shell (SSH) Protocol
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
There are also drafts that are being currently developed and followed.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
- draft-ietf-curdle-ssh-kex-sha2-10
|
|
Packit Service |
31306d |
Key Exchange (KEX) Method Updates and Recommendations for Secure Shell (SSH)
|
|
Packit Service |
31306d |
- draft-miller-ssh-agent-03
|
|
Packit Service |
31306d |
SSH Agent Protocol
|
|
Packit Service |
31306d |
- draft-ietf-curdle-ssh-curves-12
|
|
Packit Service |
31306d |
Secure Shell (SSH) Key Exchange Method using Curve25519 and Curve448
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
Interesting cryptography documents:
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
- PKCS #11, PKCS #11 reference documents, describing interface with smartcards.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@subsection main-rfc-sftp Secure Shell File Transfer Protocol (SFTP)
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
The protocol is not an Internet standard but it is still widely implemented.
|
|
Packit Service |
31306d |
OpenSSH and most other implementation implement Version 3 of the protocol. We
|
|
Packit Service |
31306d |
do the same in libssh.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
-
|
|
Packit Service |
31306d |
draft-ietf-secsh-filexfer-02.txt,
|
|
Packit Service |
31306d |
SSH File Transfer Protocol
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
@subsection main-rfc-extensions Secure Shell Extensions
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
The OpenSSH project has defined some extensions to the protocol. We support some of
|
|
Packit Service |
31306d |
them like the statvfs calls in SFTP or the ssh-agent.
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
-
|
|
Packit Service |
31306d |
OpenSSH's deviations and extensions
|
|
Packit Service |
31306d |
-
|
|
Packit Service |
31306d |
OpenSSH's pubkey certificate authentication
|
|
Packit Service |
31306d |
-
|
|
Packit Service |
31306d |
chacha20-poly1305@openssh.com authenticated encryption mode
|
|
Packit Service |
31306d |
-
|
|
Packit Service |
31306d |
OpenSSH private key format (openssh-key-v1)
|
|
Packit Service |
31306d |
|
|
Packit Service |
31306d |
*/
|