始めよう

wolfSSHのダウンロードとビルドが終わったら、テストプログラムとサンプルプログラムが自動的に作成されているはずです。

テスト

wolfSSHユニットテスト

wolfSSHのユニットテストはAPIの動作を確認するためのものです。ポジティブ/ネガティブの両テストケースが実行されます。テストはマニュアルで実行することができますが、他の処理の一部（例えばmake check コマンド実行時）として実行される場合もあります。

全てのサンプルプログラムとテストはwolfSSHのホームディレクトリから実行されなければなりません。実行時に必要な各種証明書と鍵をプログラムが見つけることができるようにするためです。

ユニットテストをマニュアルで実行するには次のようにします:

$ ./tests/unit.test

あるいは

$ make check (autoconfが使われている場合)

テストに関する注記事項

レポジトリをクローンした後、テスト用の秘密鍵はユーザーにとってはリードオンリーになっていることを確認してください。そうなっていない場合はssh_clientサンプルプログラムは警告します。

$ chmod 0600 ./keys/gretel-key-rsa.pem ./keys/hansel-key-rsa.pem \
             ./keys/gretel-key-ecc.pem ./keys/hansel-key-ecc.pem

サンプルプログラムechoserverに対しての認証はパスワードあるいは公開鍵を使って行うことができます。パスワードを使う場合は次のコマンドを使ってください:

$ ssh_client -p 22222 USER@localhost

ここでUSERとしてのユーザーとそのパスワードとして次の２つのペアが使えます:

jill:upthehill
jack:fetchapail

公開鍵を使った認証を行う場合には次のコマンドを使います:

$ ssh_client -i ./keys/USER-key-TYPE.pem -p 22222 USER@localhost

ここで、USERの部分にはgretelかhanselが指定できて、TYPEにはrsaかeccを指定します。

echoserverはそのwsUserAuthコールバック関数に偽のアカウント(jack, jill, hansel, とgretel）を用意してあります。後述するシェルサポートが有効になっている場合には、これらの偽アカウントは機能しません。これらのアカウントを使って認証を試みてもサーバーにはシステムのパスワードファイルにこれらのアカウントのおパスワードは存在していないので認証に失敗します。新たなユーザーとパスワードあるいは公開鍵リストをechoserverに追加することができます。追加されたアカウントでは、echoserverによって起動されたシェルにechoserverを起動したユーザー権限でログインすることができます。

サンプルプログラム

wolfSSH echoserver

echoserverサンプルプログラムはwolfSSHのサンプルプログラム中で最も多くの処理をこなすプログラムです。用意されているアカウントを認証することを許された唯一のユーザーであり、入力された文字を繰り返し出力します。後の章で説明するシェルサポートが有効になっている場合には、ユーザーシェルを起動することができます。echoserverの実行にはマシン上での実際のユーザ名とクレデンシャルを検証する為の更新した認証コールバック関数を必要とします。

ターミナルから次のコマンドを事項してください:

$ ./examples/echoserver/echoserver -f

-f オプションはエコーバックだけを行うモードを指定します。別のターミナルを開いて次のコマンドを実行してください:

$ ssh_client jill@localhost -p 22222

パスワードの入力を求められたら"upthehill"と入力してください。サーバーは次のバナーを返信してくるはずです:

    wolfSSH Example Echo Server

ssh_clientにタイプした文字はサーバーからエコーバックされて表示されます。入力した文字が２度スクリーンにエコーバックされたとしたらそれはローカルのエコーバックが有効になっているからです。echoserverは正規のターミナルではないので、CR/LF　改行の変換が期待通りに機能しないかもしれません。

以下の制御文字はechoserverで特別な動作を引き起こします:

CTRL-C:　コネクションを切断
CTRL-E:　セッション状況をプリントアウト
CTRL-F:　新たな鍵交換をトリガー

echoserverサンプルプログラムには以下のコマンドラインオプションが指定できます:

    -1             一回の接続後に終了する
    -e             クライアントからECC公開鍵を受け取る
    -E             ECC秘密鍵を使う
    -f             入力をエコーする
    -p <num>       待ち受けポート番号を指定する（デフォルトは22222) 
    -N             ノンブロッキングソケットを使う
    -d <string>    SFTPコネクションのホームディレクトリを指定する
    -j <file>      接続相手からの公開鍵を受け付ける為にロードする

wolfSSH Client

このクライアントプログラムははSSHサーバーと接続を確立します。簡単モードでは"Hello, wolfSSH!"をサーバーに送信し、サーバーからの応答を表示して終了します。疑似ターミナルオプションではこのクライアントプログラムは実際のクライアントとして機能します。

クライアントサンプルプログラムには以下のコマンドラインオプションが指定できます:

    -h <host>      接続先ホストアドレス（デフォルト 127.0.0.1）
    -p <num>       接続先ポート（デフォルト 22222)
    -u <username>  認証の為のユーザー名（指定必須）
    -P <password>  パスワード（省略した場合はプロンプトが表示される）
    -e             サンプルecc公開鍵を指定
    -i <filename>  ユーザーの秘密鍵ファイル名
    -j <filename>  ユーザーの公開鍵ファイル名
    -x             接続完了後、データ送受信することなく終了
    -N             ノンブロッキングソケットを使う
    -t             疑似ターミナルを使用
    -c <command>   リモートコマンドとpipe stdin/stdout を使用する
    -a             SSH-AGENTの使用を試みる

wolfSSH portfwd

portfwdサンプルプログラムはSSHサーバーと接続を確立し、ローカルポートフォワーディングのための待ち受けポートをリスンするかあるいはリスンしているリスナーに対してリモートポートフォワーディングを要求します。接続確立の後はプログラムは終了します。

portfwd サンプルプログラムには以下のコマンドラインオプションが指定できます:

    -h <host>      接続先SSHサーバーアドレス（デフォルト 127.0.0.1）
    -p <num>       接続先SSHサーバーポート（デフォルト 22222）
    -u <username>  ユーザー名(指定必須)
    -P <password>  パスワード（省略した場合はプロンプトが表示される）
    -F <host>      フォーワード元ホストアドレス（デフォルト 0.0.0.0）
    -f <num>       フォーワード元ホストポート（指定必須）
    -T <host>      フォーワード先ホストアドレス(デフォルト host)
    -t <num>       フォーワード先ホストポート（指定必須）

wolfSSH scpclient

scpclientとwolfscpはSSHサーバーと接続を確立し、指定されたファイルをローカルマシンにコピー、あるいはローカルマシンのファイルをサーバーにコピーします。

scpclientサンプルプログラムには以下のコマンドラインオプションが指定できます:

    -H <host>      接続先SSHサーバーアドレス（デフォルト 127.0.0.1）
    -p <num>       接続先SSHサーバーポート（デフォルト 22222）
    -u <username>  ユーザー名(指定必須)
    -P <password>  パスワード（省略した場合はプロンプトが表示される）
    -L <from>:<to> ローカルマシンのfromからサーバーのtoへコピーする
    -S <from>:<to> サーバーのfromからローカルマシンのtoへコピーする

wolfSSH sftpclient

sftpclient, wolfsftpはSSHサーバーと接続を確立し、ディレクトリ移動、ファイル取得、ファイル配置、ディレクトリ追加・削除等を実行します。

sftpclientサンプルプログラムには以下のコマンドラインオプションが指定できます:

    -h <host>      接続先SSHサーバーアドレス（デフォルト 127.0.0.1）
    -p <num>       接続先SSHサーバーポート（デフォルト 22222）
    -u <username>  ユーザー名(指定必須)
    -P <password>  パスワード（省略した場合はプロンプトが表示される）
    -d <path>      ローカルマシンのデフォルトのパスを設定
    -N             ノンブロッキングソケットを使う
    -e             ECC公開鍵を使ってユーザー認証を行う
    -l <filename>  ローカルファイル名
    -r <filename>  リモートファイル名
    -g             ローカルファイルをリモートファイルとして送信
    -G             リモートファイルをローカルファイルとして受信

wolfSSHサーバー

serverはプレースホルダーとして存在しています。

SCP

wolfSSHはscpの為のサーバー側サポート（サーバーへのファイルコピーとサーバーからのファイルのコピーの両方）を含んでいます。単一ファイルのコピーとディレクトリ単位の再帰的コピーの両方をデフォルトの送信コールバックあるいは受信コールバックでサポートしています。

wolfSSHをscpサポート機能を有効にしてコンパイルするには,--enable-scp ビルドオプションを指定するかあるいはWOLFSSL_SCPマクロ定義を指定してください：

$ ./configure --enable-scp
$ make

wolfSSHサンプルサーバープログラムは単一のscpリクエストを受け付けるように設定されていてwolfSSHライブラリをビルドする際にデフォルトでビルドされます。サンプルサーバーを起動するには以下を実行してください:

$ ./examples/server/server

標準scpコマンド群はクライアント側で利用されます。以下はその使用例です。ここで、scpは使用しているsshクライアントを表します。

単一ファイルをサーバーに送信する場合で既定のユーザー"jill"を使うとすると:

$ scp -P 22222 <local_file> jill@127.0.0.1:<remote_path>

同じ単一ファイルをサーバーに送信する場合で、今度はタイムスタンプを使いバーバスモードを使うとすると:

$ scp -v -p -P 22222 <local_file> jill@127.0.0.1:<remote_path>

あるディレクトリを再帰的にサーバーに送信する場合には：

$ scp -P 22222 -r <local_dir> jill@127.0.0.1:<remote_dir>

単一ファイルをサーバーからローカルマシンにコピーするには:

$ scp -P 22222 jill@127.0.0.1:<remote_file> <local_path>

サーバーのあるディレクトリを再帰的に受信する場合には：

$ scp -P 22222 -r jill@127.0.0.1:<remote_dir> <local_path>

シェルサポート

wolfSSHのechoserverサンプルプログラムはログインを試みるユーザーの為にシェルを起動することができます。この機能はLinuxとmacOSでのみテスト済みです。echoserver.cファイルはユーザー認証コールバック内にユーザーのクレデンシャルを保持するように変更が必要です。あるいはユーザー認証コールバックは提供されたパスワードを検証するように変更する必要があります。

wolfSSHをシェルサポート機能付きでビルドする場合には--enable-shellオプションを指定するかあるいはWOLFSSH_SHELLマクロ定義を指定します：

$ ./configure --enable-shell
$ make

デフォルトでechoserverはシェルを実行しようと試みます。エコーバックの機能をテストしたい場合にはコマンドラインオプションで-fを指定してください:

$ ./examples/echoserver/echoserver -f