SSH and SFTP client library for React Native

SSH and SFTP client library for React Native on iOS and Android.

Installation

npm install @dylankenneally/react-native-ssh-sftp

iOS

Update your Podfile to use the jim-lake's fork of NMSSH. Note that we use the forked version to give us a required later version of libssh. Your Podfile is located in your React Native project at ./ios/Podfile.

target '[your project's name]' do
  pod 'NMSSH', :git => 'https://github.com/jim-lake/NMSSH.git' # <-- add this line
  # ... rest of your target details ...
end

And then run pod install in your ./ios directory.

cd ios
pod install
cd -

Tip

Adding a postinstall script to your package.json file to run pod install after npm install is a good idea. The pod-install package is a good way to do this.

{
  "scripts": {
    "postinstall": "npx pod-install",
  }
}

Having OpenSSL issues on iOS?

If you are using Flipper to debug your app, it will already have a copy of OpenSSL included. This can cause issues with the version of OpenSSL that NMSSH uses. You can disable flipper by removing/commenting out the flipper_configuration => flipper_config, line in your Podfile.

Android

No additional steps are needed for Android.

Linking

This project has been updated to use React Native v73 (the latest at the time of writing, Jan 2024) - which means that manual linking is not required.

Usage

All functions that run asynchronously where we have to wait for a result returns Promises that can reject if an error occurred.

Note

On iOS, this package currently doesn't support the simulator, you will need to have your app running on a physical device. If you would like to know more about this, see this issue. I'd welcome a PR to resolve this.

New API (Recommended)

The new API separates connection and authentication into distinct operations, allowing for more flexible authentication workflows.

Connect to a host

import SSHClient from '@dylankenneally/react-native-ssh-sftp';

const client = await SSHClient.connect("10.0.0.10", 22, "user");

Authenticate with password

await client.authenticateWithPassword("password");

Authenticate with private key

const privateKey = "-----BEGIN RSA...";
await client.authenticateWithKey(privateKey);

// With passphrase
await client.authenticateWithKey(privateKey, "passphrase");

Authenticate with sign callback

const publicKey = "ssh-rsa AAAAB3NzaC1yc2EA......";
const signCallback = async (data) => {
  // Your signing implementation
  return signature;
};

await client.authenticateWithSignCallback(publicKey, signCallback);

Check authentication status

if (client.isAuthenticated()) {
  // Client is ready for operations
}

Multiple authentication attempts

const client = await SSHClient.connect("10.0.0.10", 22, "user");

try {
  await client.authenticateWithPassword("password1");
} catch (error) {
  // Try different method
  await client.authenticateWithKey(privateKey);
}

Legacy API (Deprecated)

The legacy API combines connection and authentication in a single call. These methods are deprecated but still supported for backward compatibility.

Create a client using password authentication

import SSHClient from '@dylankenneally/react-native-ssh-sftp';

SSHClient.connectWithPassword(
  "10.0.0.10",
  22,
  "user",
  "password"
).then(client => {/*...*/});

Create a client using public key authentication

import SSHClient from 'react-native-ssh-sftp';

SSHClient.connectWithKey(
  "10.0.0.10",
  22,
  "user",
  privateKey="-----BEGIN RSA...",
  passphrase
).then(client => {/*...*/});

Public key authentication is also supported

{privateKey: '-----BEGIN RSA......'}
{privateKey: '-----BEGIN RSA......', publicKey: 'ssh-rsa AAAAB3NzaC1yc2EA......'}
{privateKey: '-----BEGIN RSA......', publicKey: 'ssh-rsa AAAAB3NzaC1yc2EA......', passphrase: 'Password'}

Close client

client.disconnect();

Execute SSH command

const command = 'ls -l';
client.execute(command)
  .then(output => console.warn(output));

Shell

Start shell

• Supported ptyType: vanilla, vt100, vt102, vt220, ansi, xterm

const ptyType = 'vanilla';
client.startShell(ptyType)
  .then(() => {/*...*/});

Read from shell

client.on('Shell', (event) => {
  if (event)
    console.warn(event);
});

Write to shell

const str = 'ls -l\n';
client.writeToShell(str)
  .then(() => {/*...*/});

Close shell

client.closeShell();

SFTP

Connect SFTP

client.connectSFTP()
  .then(() => {/*...*/});

List directory

const path = '.';
client.sftpLs(path)
  .then(response => console.warn(response));

Create directory

client.sftpMkdir('dirName')
  .then(() => {/*...*/});

Rename file or directory

client.sftpRename('oldName', 'newName')
  .then(() => {/*...*/});

Remove directory

client.sftpRmdir('dirName')
  .then(() => {/*...*/});

Remove file

client.sftpRm('fileName')
  .then(() => {/*...*/});

Download file

client.sftpDownload('[path-to-remote-file]', '[path-to-local-directory]')
  .then(downloadedFilePath => {
    console.warn(downloadedFilePath);
  });

// Download progress (setup before call)
client.on('DownloadProgress', (event) => {
  console.warn(event);
});

// Cancel download
client.sftpCancelDownload();

Upload file

client.sftpUpload('[path-to-local-file]', '[path-to-remote-directory]')
  .then(() => {/*...*/});

// Upload progress (setup before call)
client.on('UploadProgress', (event) => {
  console.warn(event);
});

// Cancel upload
client.sftpCancelUpload();

Close SFTP

client.disconnectSFTP();

Example app

You can find a very simple example app for the usage of this library here.

Testing

The example app includes end-to-end (e2e) tests using Detox.

Prerequisites

iOS:

• Xcode and iOS Simulator
• applesimutils (install via brew tap wix/brew && brew install applesimutils)

Android:

• Android Studio and Android SDK
• Android emulator with AVD named Pixel_3a_API_36_ARM

Running Tests

cd example

# Install dependencies
npm install

# iOS
npm run e2e:build:ios
npm run e2e:test:ios

# Android
npm run e2e:build:android
npm run e2e:test:android

Current Test Status:

• iOS: ✅ All 18 E2E tests passing with full Detox integration
• Android: ✅ E2E tests working with Android instrumentation testing
  • Note: Uses UiAutomator for UI automation instead of Detox

Credits

This package wraps the following libraries, which provide the actual SSH/SFTP functionality:

• NMSSH for iOS
• JSch for Android (from Matthias Wiedemann fork)

This package is a fork of Emmanuel Natividad's react-native-ssh-sftp package. The fork chain from there is as follows:

1. Gabriel Paul "Cley Faye" Risterucci
2. Bishoy Mikhael
3. Qian Sha