jsch

# Форк JSch-0.1.55

См. оригинальный [README](https://github.com/mwiede/jsch/blob/master/README)

[![GitHub release](https://img.shields.io/github/v/tag/mwiede/jsch.svg)](https://github.com/mwiede/jsch/releases/latest)
[![Maven Central](https://maven-badges.sml.io/sonatype-central/com.github.mwiede/jsch/badge.svg)](https://maven-badges.sml.io/sonatype-central/com.github.mwiede/jsch)
![Java CI with Maven](https://github.com/mwiede/jsch/workflows/Java%20CI%20with%20Maven/badge.svg)

## Почему стоит использовать эту библиотеку?

Как я объяснил в [записи в блоге](http://www.matez.de/index.php/2020/06/22/the-future-of-jsch-without-ssh-rsa/), основные причины таковы:
* OpenSSH по умолчанию отключил ssh-rsa в [релизе 8.8](https://www.openssh.com/txt/release-8.8), и вам нужна библиотека, поддерживающая rsa-sha2-256 и rsa-sha2-512.
* Замена без изменений кода: просто поменяйте координаты зависимости — и всё готово.
* [JSch на SourceForge](https://sourceforge.net/projects/jsch/) больше активно не поддерживается.
* Остаётся в синхронизации с возможностями OpenJDK, поэтому нет необходимости в дополнительных зависимостях.

## Есть ли какая-либо документация?

Немного. Посмотрите примеры кода в папке [examples](https://github.com/mwiede/jsch/tree/master/examples). Также есть несколько вики-страниц, например [Jsch-Configuration](https://github.com/mwiede/jsch/wiki/Jsch-Configuration) и [Jsch-Logging](https://github.com/mwiede/jsch/wiki/Jsch-Logging).

## Версионирование

Вплоть до `0.2.26` версионирование следовало оригинальной схеме jsch; начиная с `2.27.0` мы перешли на [семантическое версионирование](https://semver.org), что говорит о стабильности API библиотеки и её использовании в продакшене.

## Как использовать эту библиотеку в качестве замены `com.jcraft:jsch`

Убедитесь, что в вашем classpath только одна зависимость jsch. Например, можно проверить вывод `mvn dependency:tree`.

### замена прямой maven-зависимости

замените
```xml
<dependency>
    <groupId>com.jcraft</groupId>
    <artifactId>jsch</artifactId>
    <version>0.1.55</version>
</dependency>
```
на
```xml
<dependency>
  <groupId>com.github.mwiede</groupId>
  <artifactId>jsch</artifactId>
  <version>2.28.0</version>
</dependency>
```

### замена jsch как транзитивной maven-зависимости

Если у вас есть артефакт `foo:bar`, содержащий `com.jcraft:jsch` как транзитивную зависимость, вам нужно добавить `com.github.mwiede:jsch` как ещё одну зависимость и исключить зависимость jcraft:
```xml
<dependency>
  <groupId>com.github.mwiede</groupId>
  <artifactId>jsch</artifactId>
  <version>2.28.0</version>
</dependency>
<dependency>
  <groupId>foo</groupId>
  <artifactId>bar</artifactId>
  <exclusions>
        <exclusion>  
          <groupId>com.jcraft</groupId>
          <artifactId>jsch</artifactId>
        </exclusion>
      </exclusions> 
</dependency>
```

*Дополнение*: вы также можете исключить любую из зависимостей `com.jcraft:jsch.agentproxy.jsch`, `com.jcraft:jsch.agentproxy.core` или `com.jcraft:jsch.agentproxy.pageant`, поскольку эти модули были интегрированы в этот форк (см. примечания к релизу [0.1.66](https://github.com/mwiede/jsch/releases/tag/jsch-0.1.66)).

## FAQ
### Какая минимальная версия Java требуется?
  * Java 8. Дополнительные ограничения — в следующем ответе.
### Поддерживаются ли ssh-ed25519, ssh-ed448, curve25519-sha256, curve448-sha512 и chacha20-poly1305@<!-- -->openssh.com?
  * Эта библиотека — [Multi-Release-jar](https://openjdk.org/jeps/238), что означает, что некоторые функции доступны только при использовании более новой версии Java.
    * Чтобы использовать ssh-ed25519 и ssh-ed448, нужна версия Java не ниже 15 или добавьте [Bouncy Castle](https://www.bouncycastle.org/java.html) (bcprov-jdk18on) в classpath.
    * Чтобы использовать curve25519-sha256 и curve448-sha512, нужна версия Java не ниже 11 или добавьте [Bouncy Castle](https://www.bouncycastle.org/java.html) (bcprov-jdk18on) в classpath.
    * Чтобы использовать chacha20-poly1305@<!-- -->openssh.com, необходимо добавить [Bouncy Castle](https://www.bouncycastle.org/java.html) (bcprov-jdk18on) в classpath.
  * Начиная с релиза [0.1.66](https://github.com/mwiede/jsch/releases/tag/jsch-0.1.66), эти алгоритмы можно использовать и со старыми версиями Java, если в classpath добавлен [Bouncy Castle](https://www.bouncycastle.org/java.html) (bcprov-jdk18on).
    * Начиная с релиза [0.1.72](https://github.com/mwiede/jsch/releases/tag/jsch-0.1.72), chacha20-poly1305@<!-- -->openssh.com может использоваться только при добавлении [Bouncy Castle](https://www.bouncycastle.org/java.html) (bcprov-jdk18on) в classpath.
### Почему ключи типа ssh-rsa не работают с этим форком JSch и моим сервером?
  * Начиная с релиза [0.2.0](https://github.com/mwiede/jsch/releases/tag/jsch-0.2.0), алгоритм подписи RSA/SHA1 отключён по умолчанию.
    * SHA1 больше не считается безопасным в криптографическом сообществе, и этот форк JSch стремится сохранять безопасный выбор алгоритмов по умолчанию.
    * Это также соответствует подходу проекта OpenSSH, который отключил подписи RSA/SHA1 по умолчанию, начиная с [релиза OpenSSH 8.8](https://www.openssh.com/txt/release-8.8).
  * Ключи типа ssh-rsa продолжают работать по умолчанию с алгоритмами подписи RSA/SHA256 (rsa-sha2-256) и RSA/SHA512 (rsa-sha2-512), определёнными в [RFC 8332](https://datatracker.ietf.org/doc/html/rfc8332).
  * Если ваш сервер поддерживает только подписи RSA/SHA1 и они необходимы вашему приложению, вам придётся вручную включить их одним из следующих способов (также см. вики-страницу [Jsch-Configuration](https://github.com/mwiede/jsch/wiki/Jsch-Configuration)):
    * Глобально, добавив "ssh-rsa" в свойства `jsch.server_host_key` + `jsch.client_pubkey`.
    * Глобально, выполнив нечто вроде `JSch.setConfig("server_host_key", JSch.getConfig("server_host_key") + ",ssh-rsa")` + `JSch.setConfig("PubkeyAcceptedAlgorithms", JSch.getConfig("PubkeyAcceptedAlgorithms") + ",ssh-rsa")`.
    * Для конкретной сессии, выполнив нечто вроде `session.setConfig("server_host_key", session.getConfig("server_host_key") + ",ssh-rsa")` + `session.setConfig("PubkeyAcceptedAlgorithms", session.getConfig("PubkeyAcceptedAlgorithms") + ",ssh-rsa")`.
    * Добавив "ssh-rsa" в ваш конфигурационный файл OpenSSH с ключевыми словами "HostKeyAlgorithms" + "PubkeyAcceptedAlgorithms", а затем используя класс `OpenSSHConfig`.
### Совместим ли этот форк на 100% с оригинальным JSch? Просто подключение к моему серверу больше не работает!
  * Для совместимости с OpenSSH и повышения безопасности порядок криптоалгоритмов был изменён. Если вы всё ещё хотите использовать старые или устаревшие алгоритмы, необходимо изменить конфигурацию. Примеры см. в [#37](https://github.com/mwiede/jsch/issues/37), [#40](https://github.com/mwiede/jsch/issues/40)
  * Чтобы упростить настройку криптоалгоритмов, начиная с [0.1.65](https://github.com/mwiede/jsch/releases/tag/jsch-0.1.65) при запуске вашего приложения можно задать следующие системные свойства:
    * `jsch.kex`
      * соответствует `JSch.setConfig("kex", "...")`
    * `jsch.server_host_key`
      * соответствует `JSch.setConfig("server_host_key", "...")`
    * `jsch.prefer_known_host_key_types`
      * соответствует `JSch.setConfig("prefer_known_host_key_types", "...")`
    * `jsch.enable_server_sig_algs`
      * соответствует `JSch.setConfig("enable_server_sig_algs", "...")`
    * `jsch.cipher`
      * соответствует `JSch.setConfig("cipher.s2c", "...")` + `JSch.setConfig("cipher.c2s", "...")`
    * `jsch.mac`
      * соответствует `JSch.setConfig("mac.s2c", "...")` + `JSch.setConfig("mac.c2s", "...")`
    * `jsch.compression`
      * соответствует `JSch.setConfig("compression.s2c", "...")` + `JSch.setConfig("compression.c2s", "...")`
    * `jsch.lang`
      * соответствует `JSch.setConfig("lang.s2c", "...")` + `JSch.setConfig("lang.c2s", "...")`
    * `jsch.dhgex_min`
      * соответствует `JSch.setConfig("dhgex_min", "...")`
    * `jsch.dhgex_max`
      * соответствует `JSch.setConfig("dhgex_max", "...")`
    * `jsch.dhgex_preferred`
      * соответствует `JSch.setConfig("dhgex_preferred", "...")`
    * `jsch.compression_level`
      * соответствует `JSch.setConfig("compression_level", "...")`
    * `jsch.preferred_authentications`
      * соответствует `JSch.setConfig("PreferredAuthentications", "...")`
    * `jsch.client_pubkey`
      * соответствует `JSch.setConfig("PubkeyAcceptedAlgorithms", "...")`
    * `jsch.check_ciphers`
      * соответствует `JSch.setConfig("CheckCiphers", "...")`
    * `jsch.check_macs`
      * соответствует `JSch.setConfig("CheckMacs", "...")`
    * `jsch.check_kexes`
      * соответствует `JSch.setConfig("CheckKexes", "...")`
    * `jsch.check_signatures`
      * соответствует `JSch.setConfig("CheckSignatures", "...")`
    * `jsch.fingerprint_hash`
      * соответствует `JSch.setConfig("FingerprintHash", "...")`
    * `jsch.max_auth_tries`
      * соответствует `JSch.setConfig("MaxAuthTries", "...")`

## Другие проекты, использующие JSch

* Jsync https://github.com/fizzed/jsync — предоставляет простой, эффективный, надёжный и полностью на Java инструмент синхронизации файлов и
  каталогов в стиле rsync, который можно использовать программно.
* Blaze https://github.com/fizzed/blaze — способ запускать Java-файлы как скрипты со встроенными мощными возможностями SSH, SFTP и rsync-подобными
  функциями.

## Изменения с момента форка:
См. [ChangeLog.md](https://github.com/mwiede/jsch/blob/master/ChangeLog.md)