diff --git a/wolfSSH/Makefile b/wolfSSH/Makefile index d077ace6..9f12b7ee 100644 --- a/wolfSSH/Makefile +++ b/wolfSSH/Makefile @@ -16,7 +16,10 @@ SOURCES = chapter01.md \ chapter11.md \ chapter12.md \ chapter13.md \ - chapter14.md + chapter14.md \ + chapter15.md \ + chapter16.md \ + chapter17.md ifeq ($(DOC_LANG),JA) PDF = wolfSSH-Manual-jp.pdf diff --git a/wolfSSH/mkdocs-ja.yml b/wolfSSH/mkdocs-ja.yml index e5d3c006..8712d94b 100644 --- a/wolfSSH/mkdocs-ja.yml +++ b/wolfSSH/mkdocs-ja.yml @@ -17,7 +17,10 @@ nav: - "11. サポートとコンサルティング": chapter11.md - "12. wolfSSHのアップデート": chapter12.md - "13. APIリファレンス": chapter13.md - - "14. wolfSSL SFTP API リファレンス": chapter14.md + - "14. SFTP API リファレンス": chapter14.md + - "15. SCP API リファレンス": chapter15.md + - "16. その他のAPIリファレンス": chapter16.md + - "17. プリプロセッサ ガードマクロ": chapter17.md theme: name: null custom_dir: ../mkdocs-material/material diff --git a/wolfSSH/mkdocs.yml b/wolfSSH/mkdocs.yml index c541b857..42d7748c 100644 --- a/wolfSSH/mkdocs.yml +++ b/wolfSSH/mkdocs.yml @@ -17,7 +17,10 @@ nav: - "11. Support and Consulting": chapter11.md - "12. wolfSSH Updates": chapter12.md - "13. API Reference": chapter13.md - - "14. wolfSSL SFTP API Reference": chapter14.md + - "14. SFTP API Reference": chapter14.md + - "15. SCP API Reference": chapter15.md + - "16. Additional API Reference": chapter16.md + - "17. Preprocessor Guard Macros": chapter17.md theme: name: null custom_dir: ../mkdocs-material/material diff --git a/wolfSSH/src-ja/chapter01.md b/wolfSSH/src-ja/chapter01.md index ae5c48b4..c8c0bc66 100644 --- a/wolfSSH/src-ja/chapter01.md +++ b/wolfSSH/src-ja/chapter01.md @@ -1,49 +1,41 @@ # イントロダクション +このマニュアルは組み込み用 wolfSSH ライブラリの技術ガイドとして書かれています。wolfSSH のビルド方法と使い始め方を説明し、ビルドオプション、機能、サポートなどの概要を提供します。 -このマニュアルは組み込み用wolfSSHライブラリの技術解説書としてお読みいただけるように書かれています。wolfSSHをビルドして起動することから始まり、ビルドオプション、機能、サポートなどの概要を提供します。 - -wolfSSHはC言語で書かれたSSH（セキュアシェル）サーバー実装で、wolfSSLから利用可能なwolfCryptを使用します。さらに、マルチプラットフォームで使用できるようにゼロから構築されています。また、SSHv2仕様に準拠しています。 +wolfSSH は C 言語で書かれた SSH（セキュアシェル）サーバーの実装で、wolfSSL からも利用可能な wolfCrypt ライブラリを使用します。さらに、wolfSSH はマルチプラットフォームで利用できるようにゼロから構築されています。この実装は SSH v2 仕様に基づいています。 ## プロトコル概要 -SSHは２つの通信端点に多重化されたデータストリームを提供する一連の階層化されたプロトコルです。一般的には、サーバー上のシェルへの接続を保護するために利用されます。ですが、ファイルを安全にコピーしたり、Xディスプレイプロトコルをトンネリングするのにも利用されています。 - -## wolfSSHをお勧めする理由 +SSH は、2 つのピア間で多重化されたデータストリームを提供する階層化されたプロトコル群です。一般的には、サーバー上のシェルへの接続を保護するために利用されます。ただし、2 台のマシン間でファイルを安全にコピーしたり、X ディスプレイプロトコルをトンネリングしたりするためにもよく利用されます。 -wolfSSHはANSI Cで記述された軽量のSSHv2サーバーライブラリで、サイズが軽量でありスピード、機能セットに富んでいる点から、組み込み機器、リアルタイムOSおよびリソース制約のある環境をターゲットにしています。wolfSSHは業界標準のSSH v2をサポートし、さらに先進的なアルゴリズム（ChaCha20, Poly1305, NTRU とSHA-3)も提供しています。wolfSSHを支えているのはwolfCrypt暗号化ライブラリで、このライブラリはFIPS140-2認証（認証#2425）を受けています。より詳細はwolfCrypt FIPS FAQを参照されるかあるいはfacts@wolfssl.comまでお知らせください。 +## wolfSSH をお勧めする理由 +wolfSSH ライブラリは ANSI C で記述された軽量な SSHv2 サーバーライブラリで、そのサイズの小ささ、速度、機能セットから、主に組み込み機器、RTOS、リソース制約のある環境をターゲットにしています。ロイヤリティフリーの価格設定と優れたクロスプラットフォームサポートにより、標準的な動作環境でも広く利用されています。wolfSSH は業界標準の SSH v2 をサポートしています。wolfSSH は wolfCrypt ライブラリによって支えられています。wolfCrypt 暗号ライブラリのあるバージョンは FIPS 140-3 認証（認証番号 #4718）および FIPS 140-2 認証（認証番号 #3389）を取得しています。追加情報については、wolfCrypt FIPS FAQ を参照するか、fips@wolfssl.com までお問い合わせください。 -### 機能（特徴） +### 機能 +- SSH v2.0（サーバーおよびクライアント） -- SSH v2.0 (サーバー機能) +- 最小フットプリントサイズ 33kB -- 最小フットプリント：33kB +- 実行時メモリ使用量 1.4KB〜2KB（設定可能な受信バッファは含まず） -- 実行時メモリ消費量：1.4KB ~ 2KB (受信バッファは含まず) +- 複数のハッシュ関数: SHA-1、SHA-2（SHA-256、SHA-384、SHA-512） -- ハッシュ関数: SHA-1, SHA-2 (SHA-256, SHA-384, SHA-512), BLAKE2b, Poly +- ブロック暗号および認証付き暗号: AES-CBC、AES-CTR、AES-GCM -- 暗号アルゴリズム：Block, Stream, and Authenticated Ciphers: AES (CBC, CTR, GCM, CCM), Camellia, ChaCha +- 鍵交換オプション: DHE および ECDHE（曲線 NISTP256、NISTP384、NISTP521） -- 公開鍵オプション: RSA, DH, EDH, NTRU +- 公開鍵認証オプション: RSA および ECDSA（曲線 NISTP256、NISTP384、NISTP521） -- ECDH と ECDSA で次の楕円曲線をサポート: NISTP256, NISTP384, NISTP, Curve25519, Ed +- ユーザー認証のサポート（パスワード、keyboard-interactive、公開鍵認証） -- クライアント認証をサポート(RSA key, password) +- シンプルな API -- シンプルなAPI +- PEM および DER 形式の X.509 証明書サポート -- PEM and DER certificate support +- ハードウェア暗号サポート: Intel AES-NI サポート、Intel AVX1/2、RDRAND、RDSEED、Cavium NITROX サポート、STM32F2/F4 ハードウェア暗号サポート、Freescale CAU / mmCAU / SEC、Microchip PIC32MZ -- ハードウエア暗号サポート: - - Intel AES-NI support - - Intel AVX1/2 - - RDRAND - - RDSEED - - Cavium NITROX - - STM32F2/F4 ハードウエア暗号 - - Freescale CAU / mmCAU / SEC - - Microchip PIC32MZ +- Hybrid ECDH-P256 Kyber-Level1 によるポスト量子ハイブリッド鍵交換 +- SFTP、SCP、SSH-AGENT、ローカルおよびリモートポートフォワーディングのサポート diff --git a/wolfSSH/src-ja/chapter02.md b/wolfSSH/src-ja/chapter02.md index 76774981..1797979d 100644 --- a/wolfSSH/src-ja/chapter02.md +++ b/wolfSSH/src-ja/chapter02.md @@ -1,102 +1,81 @@ -# wolfSSHのビルド +# wolfSSH のビルド -wolfSSHはポータビリティを念頭において開発されているので多くのシステム上に移植するのは容易にできるはずです。ですが、もし移植上で問題がありましたら https://www.wolfssl.com/forums を参照されるか support@wolfssl.com へ質問をお寄せください。 +wolfSSH はポータビリティを念頭において開発されているので、多くのシステム上で概ね容易にビルドできるはずです。もしビルドで問題がありましたら、遠慮なくサポートフォーラム https://www.wolfssl.com/forums を通じてサポートをお求めいただくか、support@wolfssl.com へ直接ご連絡ください。 +この章では、Linux、un\*x 系（BSD、macOS）、および Windows 環境で wolfSSH をビルドする方法を説明し、非標準環境でのビルドに関するガイダンスも提供します。入門ガイドとサンプルは第 3 章に用意しています。 -この章ではwolfSSHを*nix システム（あるいはその派生システム）やWindows上でビルドする方法を説明します。また、上記以外のシステムにおいてのビルド方法のガイダンスも提供します。次章では「サンプルプログラムを使って始めてみよう」を用意しています。 - -autoconf/automakeシステムを使ってビルドする際にはwolfSSHは単一のMakefileによってすべてのコンポーネントとサンプルプログラムをビルドできます。Makefileを繰り返し使用する場合に比べてシンプルで早いです。 +autotools システムを使ってビルドする際には、wolfSSH は単一の Makefile によってライブラリのすべての部分とサンプルをビルドします。これは Makefile を再帰的に使用する場合に比べてシンプルかつ高速です。 ## ソースコードの入手 -最新バージョンのコードを入手する場合には次のGitHubサイトからダウンロードできます：
- [https://github.com/wolfSSL/wolfSSH](https://github.com/wolfSSL/wolfSSH) +最新の最新版は、次の GitHub サイトからダウンロードできます: [https://github.com/wolfSSL/wolfssh](https://github.com/wolfSSL/wolfssh)。 - “Download ZIP” ボタンをクリックするかターミナルを開いて次のコマンドを実行してください:
- +“Download ZIP” ボタンをクリックするか、ターミナルで次のコマンドを実行してください: ``` $ git clone https://github.com/wolfSSL/wolfssh.git ``` - ## wolfSSH が依存するモジュール -wolfSSHはwolfCryptに依存しているので、wolfSSLのコンフィギュレーションが必要となっています。wolfSSLはここからダウンロードできます:
-https://github.com/wolfSSL/wolfssl - -最も簡潔なwolfSSHの構成のためのwolfSSLのコンフィギュレーションを行うにはwolfSSLのルートフォルダから以下のコマンドを実行します:
- +wolfSSH は wolfCrypt に依存しているため、wolfSSL のコンフィギュレーションが必要です。wolfSSL はここからダウンロードできます: [https://github.com/wolfSSL/wolfssl](https://github.com/wolfSSL/wolfssl)。wolfSSH に必要な最も簡潔な wolfSSL の構成は、既定のビルドです。これは wolfSSL のルートフォルダから次のコマンドでビルドできます: ``` -$ ./autogen.sh (GitHubからクローンした場合にのみ実行が必要) -$ ./configure --enable-ssh +$ ./autogen.sh (GitHub からクローンした場合にのみ実行が必要) +$ ./configure --enable-wolfssh $ make check $ sudo make install ``` +wolfSSH の鍵生成機能を利用するには、wolfSSL を keygen 付きでコンフィギュレーションする必要があります: +``` +--enable-keygen +``` +wolfSSL コードの大部分が不要な場合は、crypto only オプションで wolfSSL をコンフィギュレーションできます: +``` +--enable-cryptonly +``` -wolfSSHの鍵生成機能を利用する場合には `--enable-keygen` を追加してください。 -また、もしwolfSSLのコードが必要ない場合には `--enable-cryptonly` を追加してください。 - -上記により、wolfSSHの実行に必要なwolfSSLライブラリがインストールされます。 - -## ＊nixシステム上でのwolfSSHのビルド - -Linux, ＊BSD, OS X, Solaris ＊nix類似のシステム上でビルドを行う場合には、autoconfシステムを利用します。wolfSSHのビルドには以下のコマンドを実行します:
+## autotools でのビルド +Linux、BSD、macOS、Solaris、その他の un\*x 系環境でビルドする場合は、autotools システムを使用します。wolfSSH をビルドするには次のコマンドを実行します: ``` -$ ./autogen.sh (GitHubからクローンした場合にのみ実行が必要) +$ ./autogen.sh (GitHub からクローンした場合にのみ実行が必要) $ ./configure $ make $ make install ``` - -configureコマンドにはオプションを追加することができます。追加可能なオプションとその用途は以下のコマンドで参照することができます:
- +configure コマンドにはビルドオプションを追加できます。利用可能な configure オプションとその用途の一覧は、次のコマンドで参照できます: ``` $ ./configure --help ``` - -wolfSSHのビルドには以下を実行してください: - +wolfSSH をビルドするには次を実行します: ``` $ make ``` - -wolfSSHのビルドが正常に終了したことを確認する為に、以下のコマンドを実行して、全てのテストがパスすることを確認してください: - +wolfSSH が正しくビルドされたことを確認するために、次のコマンドで全てのテストがパスしたかどうかを確認してください: ``` $ make check ``` -以下を実行してwolfSSHをインストールします: - +wolfSSH をインストールするには次を実行します: ``` $ make install ``` -インストールにはスーパーユーザー権限が必要なので、場合によっては以下の様に'sudo'コマンドを前置して実行する必要があるかもしれません: - +インストールにはスーパーユーザー権限が必要な場合があり、その場合は sudo を付けてインストールを実行してください: ``` $ sudo make install ``` - -場合によっては、wolfssh/src以下のwolfSSHライブラリだけをビルドし、その他のアイテム（サンプルプログラムやテスト）を除外したいかもしれません。その場合にはwolfSSHのルートフォルダから以下のコマンドを実行してください: - +wolfssh/src/ にある wolfSSH ライブラリのみをビルドし、追加のアイテム（サンプルとテスト）はビルドしたくない場合は、wolfSSH のルートフォルダから次のコマンドを実行できます: ``` $ make src/libwolfssh.la ``` +## Windows 上でのビルド -## Windows上でのwolfSSHのビルド - -Visual Studioプロジェクトファイルは以下で取得できます: -https://github.com/wolfSSL/wolfssh/blob/master/ide/winvs/wolfssh.sln - +Visual Studio のプロジェクトファイルは *ide\\winvs* ディレクトリにあります。 -ソリューションファイル'wolfssh.sln'はwolfSSH,そのサンプルプログラムとテストプログラムをビルドするように構成されています。DebugビルドとReleaseビルドの構成をスタティックリンクライブラリとダイナミック（32/64ビット）ライブラリの両形式で提供しています。user_settings.hはwolfSSLのコンフィギュレーションで必要となります。 - - -このプロジェクトファイルではwolfSSHとwolfSSLのソースフォルダ階層が隣同士に配置されていることを前提にしています。また、それらのルートフォルダにはバージョン番号が含まれていないフォルダ名となっていることを前提としています。つまり、次のようなフォルダ構成です: +ソリューションファイル 'wolfssh.sln' により、wolfSSH とそのサンプルおよびテストプログラムをビルドできます。このソリューションは、スタティックおよびダイナミックの 32 ビットまたは 64 ビットライブラリの Debug ビルドと Release ビルドの両方を提供します。wolfSSL のビルドをコンフィギュレーションするには user_settings.h を使用してください。 +このプロジェクトは、wolfSSH と wolfSSL のソースディレクトリが隣り合わせにインストールされ、そのフォルダ名にバージョン番号が含まれていないことを前提としています: ``` Projects\ @@ -104,96 +83,70 @@ wolfssh\ wolfssl\ ``` -`wolfssh\ide\winvs\user_settings.h`ファイルはwolfSSLに対する設定も既に含んだ適切な内容となっています。このファイルを忘れずに`wolfssh\ide\winvs`フォルダから`wolfssl\IDE\WIN`フォルダにコピーしてください。もし、一方の内容を変更した場合には、 -その内容を他方にもコピーして下さい。 - -`WOLFCRYPT_ONLY`マクロ定義はwolfSSLコードをビルド対象から除外し、wolfCryptのアルゴリズム部分のみをビルドするの為に指定してあります。もし、wolfSSLコードもビルドする場合にはこの定義を削除してください。 +`wolfssh\ide\winvs\user_settings.h` ファイルには、wolfSSL を適切な設定でコンフィギュレーションするための設定が含まれています。このファイルは `wolfssh\ide\winvs` ディレクトリから `wolfssl\IDE\WIN` へコピーする必要があります。一方のコピーを変更した場合は、両方のコピーを変更しなければなりません。`WOLFCRYPT_ONLY` オプションは wolfSSL ファイルのビルドを無効にし、wolfCrypt アルゴリズムのみをビルドします。wolfSSL も残すには、このオプションを削除してください。 +### Windows 上でのビルドに使用するユーザーマクロ -### Windows上でのビルドに使用するユーザーマクロ定義 - - - -ソリューションではwolfSSLライブラリとヘッダーファイルのロケーションを指定するためにユーザーマクロを利用します。wolfssl64ソリューションでは全てのパスは既定のビルド出力先に設定されます。ユーザーマクロ'wolfCryptDir'はライブラリを検索するためのベースパスとして使用します。初期値として、`..\..\..\..\wolfssl`に設定されています。その後、例えば追加のインクルードファイル検索パスが追加される場合には、`$(wolfCryptDir)`に対して追加を行います。 - -wolfCryptDirパスはプロジェクトファイルからの相対位置で表せなければなりません。 - +このソリューションでは、wolfSSL ライブラリとヘッダーの場所を示すためにユーザーマクロを使用します。すべてのパスは wolfssl64 ソリューションの既定のビルド出力先に設定されています。ユーザーマクロ wolfCryptDir は、ライブラリを検索するためのベースパスとして使用されます。初期値は `..\..\..\..\wolfssl` に設定されています。そして、例えば API テストプロジェクトの追加インクルードディレクトリの値は `$(wolfCryptDir)` に設定されています。 +wolfCryptDir パスは、プロジェクトファイルからの相対パスでなければなりません。プロジェクトファイルはすべて 1 つ下のディレクトリにあります。 ``` wolfssh/wolfssh.vcxproj unit-test/unit-test.vcxproj ``` - -そのほかのユーザーマクロは異なるビルドターゲットのためのディレクトリを表すために使用されます。例えば、 `wolfCryptDllRelease64` は次のフォルダを表します: - - +その他のユーザーマクロは、異なるビルド向けの wolfSSL ライブラリが見つかるディレクトリです。したがって、ユーザーマクロ 'wolfCryptDllRelease64' は初期値として次のように設定されています: ``` $(wolfCryptDir)\x64\DLL Release ``` - -このパスはechoserverサンプルプログラムのデバッグ環境設定で64-bit DLLリリースビルド版の出力先を表現するのに次の様に使われます: - +この値は、echoserver の 64 ビット DLL Release ビルドのデバッグ環境で次のように設定して使用されます: ``` PATH=$(wolfCryptDllRelease64);%PATH% ``` +デバッガーから echoserver を実行すると、そのディレクトリで wolfSSL DLL が見つかります。 -echoserverプログラムをデバッガーを使って実行する際にはこの設定によってwolfSSL DLLがこのディレクトリから見つかります。 - - -## その他の環境上でのビルド - -公式にはサポートしていませんが、wolfSSHを非標準の環境でビルドしたいお客様、特に組み込み機器向け環境でのビルドをご希望の方々をできるだけお手伝いしようとしています。以下はその際に理解しておいていただきたい点です: - -1. ソースとヘッダーファイルはwolfSSHダウンロードパッケージの階層構造に存在する必要があります。 -2. いくつかのビルドシステムではwolfSSHヘッダーファイルの格納場所を明示的に指定することを求める場合があります。その格納場所は/wolfsshディレクトリなので通常はディレクトリをインクルードファイルパスに追加することで解決します。 -3. wolfSSHはコンフィギュレーションで指定されない限りリトルエンディアンをデフォルトにしています。ユーザーが使用している非標準環境ではconfigureコマンドを使用していない場合で、ビッグエンディアンシステムに指定する場合にはBIG_ENDIAN_ORDERマクロ定義が必要となります。 -4. ライブラリをビルドしてみて何か問題が生じた場合にはwolfSSLにお知らせください。サポートが必要な場合には、support@wolfssl.com 宛てにご連絡ください。 +## 非標準環境でのビルド +公式にはサポートしていませんが、非標準環境、特に組み込みおよびクロスコンパイル環境で wolfSSH をビルドしたいユーザーをできるだけお手伝いしようとしています。以下は、その際に理解しておいていただきたい点です: +1. ソースファイルとヘッダーファイルは、wolfSSH ダウンロードパッケージにある階層構造のまま維持する必要があります。 +2. 一部のビルドシステムでは、wolfSSH ヘッダーファイルの場所を明示的に知る必要があるため、それを指定しなければならない場合があります。それらは /wolfssh ディレクトリにあります。通常、 ディレクトリをインクルードパスに追加することでヘッダーの問題を解決できます。 +3. wolfSSH は、configure プロセスがビッグエンディアンを検出しない限り、リトルエンディアンシステムを既定とします。非標準環境でビルドするユーザーは configure プロセスを使用していないため、ビッグエンディアンシステムを使用する場合は BIG_ENDIAN_ORDER を定義する必要があります。 +4. ライブラリをビルドしてみて、何か問題が生じた場合はお知らせください。サポートが必要な場合は、support@wolfssl.com までご連絡ください。 ## クロスコンパイル +組み込みプラットフォームの多くのユーザーは、自身の環境向けにクロスコンパイルを行います。ライブラリをクロスコンパイルする最も簡単な方法は、configure システムを使用することです。configure システムは Makefile を生成し、それを使って wolfSSH をビルドできます。 -組み込み機器開発環境ではクロスコンパイルを行います。そのための簡単な方法はライブラリをコンフィギュアシステムを使ってクロスコンパイルを行うことです。コンフィギュアシステムはMakefileを一つ生成し、それを使ってwolfSSHをビルドします。 - -クロスコンパイルを行う際には、次の様にコンフィギュアを行うホストを指定する必要があります: - +クロスコンパイルを行う際には、次のようにコンフィギュレーションするホストを指定する必要があります: ``` $ ./configure --host=arm-linux ``` - -さらにコンパイラ、リンカー等も指定する必要があるでしょう： - +また、使用したいコンパイラやリンカーなどを指定する必要がある場合もあります: ``` -$ ./configure --host=arm-linux CC=arm-linux-gcc AR=arm-linux-ar RANLIB=arm-linux +$ ./configure --host=arm-linux CC=arm-linux-gcc AR=arm- +linux-ar +RANLIB=arm-linux ``` - -クロスコンパイル用にwolfSSHを正しくコンフィギュレーションできた後は、標準のautoconf作法にしたがってビルドとライブラリのインストールを行います: +クロスコンパイル用に wolfSSH を正しくコンフィギュレーションできた後は、標準の autoconf の作法にしたがってライブラリのビルドとインストールを行えるはずです: ``` $ make $ sudo make install ``` - -ここでご紹介した以外のTipsをお持ちでしたらぜひ facts@wolfssl.comまで お知らせください。 +wolfSSH のクロスコンパイルに関する追加の Tips やフィードバックがありましたら、facts@wolfssl.com までお知らせください。 ## カスタムディレクトリへのインストール -wolfSSLをカスタムディレクトリへインストールする場合には次のようにしてください: - +wolfSSL のカスタムインストールディレクトリを設定するには、次のようにします: ``` -$ ./configure --prefix=`~`/wolfSSL +$ ./configure --prefix=~/wolfSSL $ make $ make install ``` - -上記コマンドによってライブラリを ”~/wolfSSL/lib” に、インクルードファイルを ”~/wolfssl/include” に配置するように指定します。wolfSSHをカスタムディレクトリに配置する場合には次の様にしてください: - - +これにより、ライブラリは ~/wolfSSL/lib に、インクルードは ~/wolfssl/include に配置されます。wolfSSH のカスタムインストールディレクトリを設定し、カスタムの wolfSSL ライブラリおよびインクルードディレクトリを指定するには、次のようにします: ``` -$ ./configure --prefix=`~`/wolfssh --libdir=`~`/wolfssl/lib --includedir=`~`/wolfssl/include +$ ./configure --prefix=~/wolfssh --libdir=~/wolfssl/lib --includedir=~/wolfssl/include $ make $ make install ``` - -上記パスがご自分の実際のディレクトリとマッチすることを確認して下さい。 +上記のパスが実際の場所と一致していることを確認してください。 diff --git a/wolfSSH/src-ja/chapter03.md b/wolfSSH/src-ja/chapter03.md index f3516a65..a7883ee4 100644 --- a/wolfSSH/src-ja/chapter03.md +++ b/wolfSSH/src-ja/chapter03.md @@ -1,104 +1,86 @@ # 始めよう -wolfSSHのダウンロードとビルドが終わったら、テストプログラムとサンプルプログラムが自動的に作成されているはずです。 - +wolfSSHのダウンロードとビルドが終わったら、ライブラリの使い方を示す自動テストプログラムとサンプルプログラムが用意されています。 ## テスト ### wolfSSHユニットテスト -wolfSSHのユニットテストはAPIの動作を確認するためのものです。ポジティブ/ネガティブの両テストケースが実行されます。テストはマニュアルで実行することができますが、他の処理の一部（例えばmake check コマンド実行時）として実行される場合もあります。 +wolfSSHのユニットテストはAPIの動作を確認するためのものです。ポジティブ/ネガティブの両テストケースが実行されます。テストはマニュアルで実行することができますが、makeやmake checkコマンドなど他の自動化された処理の一部として実行される場合もあります。 -全てのサンプルプログラムとテストはwolfSSHのホームディレクトリから実行されなければなりません。実行時に必要な各種証明書と鍵をプログラムが見つけることができるようにするためです。 +全てのサンプルプログラムとテストはwolfSSHのホームディレクトリから実行されなければなりません。実行時に必要な各種証明書と鍵をテストツールが見つけることができるようにするためです。 ユニットテストをマニュアルで実行するには次のようにします: - ``` $ ./tests/unit.test ``` - あるいは - ``` $ make check (autoconfが使われている場合) ``` ### テストに関する注記事項 -レポジトリをクローンした後、テスト用の秘密鍵はユーザーにとってはリードオンリーになっていることを確認してください。そうなっていない場合はssh_clientサンプルプログラムは警告します。 - +レポジトリをクローンした後、テスト用の秘密鍵はユーザーにとってリードオンリーになっていることを確認してください。そうなっていない場合は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 +$ ssh -p 22222 USER@localhost ``` -ここでUSERとしてのユーザーとそのパスワードとして次の２つのペアが使えます: - +ここで_USER_としてのユーザーとそのパスワードとして次の２つのペアが使えます: ``` jill:upthehill jack:fetchapail ``` 公開鍵を使った認証を行う場合には次のコマンドを使います: - ``` -$ ssh_client -i ./keys/USER-key-TYPE.pem -p 22222 USER@localhost +$ ssh -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を起動したユーザー権限でログインすることができます。 +ここで、_USER_の部分にはgretelかhanselが指定でき、TYPEにはrsaかeccを指定します。 +echoserverはそのwsUserAuthコールバック関数に複数の偽のアカウント(jack, jill, hansel, とgretel）を用意してあります。後述するシェルサポートが有効になっている場合には、これらの偽アカウントは機能しません。これらのアカウントはシステムのパスワードファイルに存在しないためです。ユーザー認証は成功しますが、システム上にこれらのアカウントが存在しないためサーバー側でエラーになります。echoserverのパスワードリストあるいは公開鍵リストに自分自身のユーザー名を追加することができます。追加されたアカウントでは、echoserverによって起動されたシェルにechoserverを起動したユーザーの権限でログインすることができます。 ## サンプルプログラム ### wolfSSH echoserver -echoserverサンプルプログラムはwolfSSHのサンプルプログラム中で最も多くの処理をこなすプログラムです。用意されているアカウントを認証することを許された唯一のユーザーであり、入力された文字を繰り返し出力します。後の章で説明するシェルサポートが有効になっている場合には、ユーザーシェルを起動することができます。echoserverの実行にはマシン上での実際のユーザ名とクレデンシャルを検証する為の更新した認証コールバック関数を必要とします。 - -ターミナルから次のコマンドを事項してください: - +echoserverサンプルプログラムはwolfSSHのサンプルプログラム中で最も多くの処理をこなすプログラムです。もともとは用意されたアカウントのいずれかで認証を行い、入力された文字を繰り返し出力するだけのものでした。後のセクションで説明するシェルサポートを有効にすると、ユーザーシェルを起動することができます。その場合、マシン上の実際のユーザー名と、そのクレデンシャルを検証するために更新されたユーザー認証コールバック関数が必要になります。echoserverはSCPおよびSFTP接続も扱うことができます。ターミナルから次を実行してください: ``` -$ ./examples/echoserver/echoserver -f + $ ./examples/echoserver/echoserver -f ``` - `-f` オプションはエコーバックだけを行うモードを指定します。 - 別のターミナルを開いて次のコマンドを実行してください: +`-f` オプションはエコーバックだけを行うモードを有効にします。別のターミナルから次を実行してください: ``` -$ ssh_client jill@localhost -p 22222 + $ ssh jill@localhost -p 22222 ``` -パスワードの入力を求められたら"upthehill"と入力してください。サーバーは次のバナーを返信してくるはずです: - - +パスワードの入力を求められたら"upthehill"と入力してください。サーバーは次のバナーをクライアントに送信します: ``` wolfSSH Example Echo Server ``` -ssh_clientにタイプした文字はサーバーからエコーバックされて表示されます。入力した文字が２度スクリーンにエコーバックされたとしたらそれはローカルのエコーバックが有効になっているからです。echoserverは正規のターミナルではないので、CR/LF　改行の変換が期待通りに機能しないかもしれません。 +クライアントにタイプした文字はサーバーからスクリーンにエコーバックされます。文字が２度エコーバックされたとしたら、それはクライアントのローカルエコーが有効になっているからです。echoserverは正規のターミナルとして振る舞ってはいないので、CR/LFの変換が期待通りに機能しないことがあります。 以下の制御文字はechoserverで特別な動作を引き起こします: -- CTRL-C:　コネクションを切断 -- CTRL-E:　セッション状況をプリントアウト -- CTRL-F:　新たな鍵交換をトリガー +- CTRL-C: コネクションを切断します。 +- CTRL-E: いくつかのセッション統計をプリントアウトします。 +- CTRL-F: 新たな鍵交換をトリガーします。 echoserverサンプルプログラムには以下のコマンドラインオプションが指定できます: - ``` -1 一回の接続後に終了する -e クライアントからECC公開鍵を受け取る -E ECC秘密鍵を使う -f 入力をエコーする - -p 待ち受けポート番号を指定する（デフォルトは22222) + -p 待ち受けポート番号を指定する（デフォルトは22222） -N ノンブロッキングソケットを使う -d SFTPコネクションのホームディレクトリを指定する -j 接続相手からの公開鍵を受け付ける為にロードする @@ -106,10 +88,9 @@ echoserverサンプルプログラムには以下のコマンドラインオプ ### wolfSSH Client -このクライアントプログラムははSSHサーバーと接続を確立します。簡単モードでは"Hello, wolfSSH!"をサーバーに送信し、サーバーからの応答を表示して終了します。疑似ターミナルオプションではこのクライアントプログラムは実際のクライアントとして機能します。 +このクライアントはSSHサーバーとの接続を確立します。最も単純なモードでは"Hello, wolfSSH!"という文字列をサーバーに送信し、その応答を表示して終了します。疑似ターミナルオプションを使うと、このクライアントは実際のクライアントとして機能します。 クライアントサンプルプログラムには以下のコマンドラインオプションが指定できます: - ``` -h 接続先ホストアドレス（デフォルト 127.0.0.1） -p 接続先ポート（デフォルト 22222) @@ -118,16 +99,16 @@ echoserverサンプルプログラムには以下のコマンドラインオプ -e サンプルecc公開鍵を指定 -i ユーザーの秘密鍵ファイル名 -j ユーザーの公開鍵ファイル名 - -x 接続完了後、データ送受信することなく終了 + -x 接続成功後、データの読み書きをせずに終了 -N ノンブロッキングソケットを使う -t 疑似ターミナルを使用 - -c リモートコマンドとpipe stdin/stdout を使用する + -c リモートコマンドを実行し stdin/stdout をパイプする -a SSH-AGENTの使用を試みる ``` ### wolfSSH portfwd -portfwdサンプルプログラムはSSHサーバーと接続を確立し、ローカルポートフォワーディングのための待ち受けポートをリスンするかあるいはリスンしているリスナーに対してリモートポートフォワーディングを要求します。接続確立の後はプログラムは終了します。 +portfwdサンプルプログラムはSSHサーバーとの接続を確立し、ローカルポートフォワーディングのための待ち受けリスナーを設定するか、あるいはリモートポートフォワーディングのためのリスナーを要求します。接続確立の後、プログラムは終了します。 portfwd サンプルプログラムには以下のコマンドラインオプションが指定できます: ``` @@ -143,107 +124,227 @@ portfwd サンプルプログラムには以下のコマンドラインオプシ ### wolfSSH scpclient -scpclientとwolfscpはSSHサーバーと接続を確立し、指定されたファイルをローカルマシンにコピー、あるいはローカルマシンのファイルをサーバーにコピーします。 -wolfSSHのサンプルプログラムを使用する際は、絶対パスを使用する必要があり、ディレクトリは`/`で終わる必要があります。 +scpclient、すなわちwolfscpはSSHサーバーとの接続を確立し、指定されたファイルをサーバーへ、あるいはサーバーからローカルマシンへコピーします。wolfSSHのサンプルプログラムを使用する際は、絶対パスを使用する必要があり、ディレクトリは`/`で終わる必要があります。 scpclientサンプルプログラムには以下のコマンドラインオプションが指定できます: - ``` -H 接続先SSHサーバーアドレス（デフォルト 127.0.0.1） -p 接続先SSHサーバーポート（デフォルト 22222） -u ユーザー名(指定必須) -P パスワード（省略した場合はプロンプトが表示される） - -L : ローカルマシンのfromからサーバーのtoへコピーする - -S : サーバーのfromからローカルマシンのtoへコピーする + -L : ローカルマシンからサーバーへコピーする + -S : サーバーからローカルマシンへコピーする ``` -# wolfSSH sftpclient - -sftpclient, wolfsftpはSSHサーバーと接続を確立し、ディレクトリ移動、ファイル取得、ファイル配置、ディレクトリ追加・削除等を実行します。 - +### wolfSSH sftpclient +sftpclient、すなわちwolfsftpはSSHサーバーとの接続を確立し、ディレクトリ移動、ファイルの取得と配置、ディレクトリの作成と削除などを実行できるようにします。 sftpclientサンプルプログラムには以下のコマンドラインオプションが指定できます: - ``` -h 接続先SSHサーバーアドレス（デフォルト 127.0.0.1） -p 接続先SSHサーバーポート（デフォルト 22222） -u ユーザー名(指定必須) -P パスワード（省略した場合はプロンプトが表示される） - -d ローカルマシンのデフォルトのパスを設定 + -d ローカルマシンのデフォルトのパスを設定する -N ノンブロッキングソケットを使う - -e ECC公開鍵を使ってユーザー認証を行う + -e ECCユーザー認証を使う -l ローカルファイル名 -r リモートファイル名 - -g ローカルファイルをリモートファイルとして送信 - -G リモートファイルをローカルファイルとして受信 + -g ローカルファイルをリモートファイルとして送信する + -G リモートファイルをローカルファイルとして受信する ``` ### wolfSSHサーバー -serverはプレースホルダーとして存在しています。 +このツールはプレースホルダーです。 ## SCP -wolfSSHはscpの為のサーバー側サポート（サーバーへのファイルコピーとサーバーからのファイルのコピーの両方）を含んでいます。単一ファイルのコピーとディレクトリ単位の再帰的コピーの両方をデフォルトの送信コールバックあるいは受信コールバックでサポートしています。 +wolfSSHはscpの為のサーバー側サポートを含んでおり、サーバーへのファイルコピーとサーバーからのファイルコピーの両方をサポートしています。単一ファイルのコピーとディレクトリ単位の再帰的コピーの両方が、デフォルトの送信・受信コールバックでサポートされています。 -wolfSSHをscpサポート機能を有効にしてコンパイルするには,`--enable-scp` ビルドオプションを指定するかあるいは`WOLFSSL_SCP`マクロ定義を指定してください： +wolfSSHをscpサポート付きでコンパイルするには、`--enable-scp` ビルドオプションを指定するか、あるいは`WOLFSSL_SCP`を定義してください: +``` + $ ./configure --enable-scp + $ make +``` + + +wolfSSLサンプルサーバープログラムは単一のscpリクエストを受け付けるように設定されており、wolfSSHライブラリのコンパイル時にデフォルトでコンパイルされます。サンプルサーバーを起動するには次を実行してください: + + $ ./examples/server/server + +クライアント側では標準のscpコマンドが使用できます。以下はその使用例です。ここで`scp`は使用しているsshクライアントを表します。 + +既定のサンプルユーザー"jill"を使って単一ファイルをサーバーに送信するには: + + $ scp -P 22222 jill@127.0.0.1: + +同じ単一ファイルをサーバーに送信するが、今度はタイムスタンプ付きでバーバスモードを使うには: + + $ scp -v -p -P 22222 jill@127.0.0.1: + +あるディレクトリを再帰的にサーバーへコピーするには: + $ scp -P 22222 -r jill@127.0.0.1: +単一ファイルをサーバーからローカルクライアントへコピーするには: + + $ scp -P 22222 jill@127.0.0.1: + +あるディレクトリをサーバーからローカルクライアントへ再帰的にコピーするには: + + $ scp -P 22222 -r jill@127.0.0.1: + +## SFTP + +wolfSSHはSFTPバージョン3のサーバー側およびクライアント側サポートを提供します。これにより、ファイルシステムを管理するための暗号化された接続を設定することができます。 + +wolfSSHをSFTPサポート付きでコンパイルするには、`--enable-sftp` ビルドオプションを指定するか、あるいは`WOLFSSH_SFTP`を定義してください: + +``` + $ ./configure --enable-sftp + $ make ``` -$ ./configure --enable-scp + +APIの完全な使用方法と実装の詳細については、wolfSSHユーザーマニュアルを参照してください。 + +作成されるSFTPクライアントはexamples/sftpclient/ディレクトリに配置され、サーバーはwolfSSHと同じechoserverを使って実行されます。 + +``` + src/wolfssh$ ./examples/sftpclient/wolfsftp +``` + +サポートされているコマンドの完全な一覧は、接続後に"help"と入力することで確認できます。 + +``` + wolfSSH sftp> help + + Commands : + cd change directory + chmod change mode + get pulls file(s) from server + ls list current directory + mkdir creates new directory on server + put push file(s) to server + pwd list current path + quit exit + rename renames remote file + reget resume pulling file + reput resume pushing file + interrupt get/put cmd +``` +別のシステムに接続する例は次のようになります: + +``` + src/wolfssh$ ./examples/sftpclient/wolfsftp -p 22 -u user -h 192.168.1.111 +``` + +## シェルサポート + +wolfSSHのサンプルechoserverは、ログインを試みるユーザーの為にシェルをforkできるようになりました。この機能は現在のところLinuxとmacOSでのみテストされています。echoserver.cファイルは、ユーザー認証コールバック内にユーザーのクレデンシャルを保持するように変更するか、あるいは提供されたパスワードを検証するようにユーザー認証コールバックを変更する必要があります。 + +wolfSSHをシェルサポート付きでコンパイルするには、--enable-shellビルドオプションを指定するか、あるいはWOLFSSH_SHELLを定義してください: +``` +$ ./configure --enable-shell $ make ``` -wolfSSHサンプルサーバープログラムは単一のscpリクエストを受け付けるように設定されていてwolfSSHライブラリをビルドする際にデフォルトでビルドされます。サンプルサーバーを起動するには以下を実行してください: +デフォルトでechoserverはシェルを起動しようとします。エコーテストの動作を使うには、echoserverにコマンドラインオプション-fを指定してください: +``` +$ ./examples/echoserver/echoserver -f +``` + +## Post-Quantum -$ ./examples/server/server +wolfSSHはポスト量子アルゴリズムのKyberをサポートするようになりました。これはNIST提出のLevel 1パラメータセットを使用し、wolfSSHとの統合を通じてliboqsによって実装されています。これはP-256 ECC曲線上のECDHEとハイブリッド化されています。 -標準scpコマンド群はクライアント側で利用されます。以下はその使用例です。ここで、`scp`は使用しているsshクライアントを表します。 +liboqsを使用できるようにするためには、システム上でliboqsをビルドしインストールしておく必要があります。liboqsの0.7.0リリースをサポートしています。次のリンクからダウンロードできます: -単一ファイルをサーバーに送信する場合で既定のユーザー"jill"を使うとすると: ``` -$ scp -P 22222 jill@127.0.0.1: + https://github.com/open-quantum-safe/liboqs/archive/refs/tags/0.7.0.tar.gz ``` -同じ単一ファイルをサーバーに送信する場合で、今度はタイムスタンプを使いバーバスモードを使うとすると: +展開後、次の手順で十分です: ``` -$ scp -v -p -P 22222 jill@127.0.0.1: + $ cd liboqs-0.7.0 + $ mkdir build + $ cd build + $ cmake -DOQS_USE_OPENSSL=0 .. + $ make all + $ sudo make install ``` -あるディレクトリを再帰的にサーバーに送信する場合には： + +wolfSSHでP-256 ECC曲線上のECDHEとハイブリッド化されたKyber Level1のサポートを有効にするには、configure時に`--with-liboqs`ビルドオプションを使用してください: ``` -$ scp -P 22222 -r jill@127.0.0.1: + $ ./configure --with-liboqs ``` -単一ファイルをサーバーからローカルマシンにコピーするには: +この機能が有効になっていると、wolfSSHのクライアントとサーバーはP-256 ECC曲線上のECDHEとハイブリッド化されたKyber Level1を使うように自動的にネゴシエートします。 ``` -$ scp -P 22222 jill@127.0.0.1: + $ ./examples/echoserver/echoserver -f + + $ ./examples/client/client -u jill -P upthehill ``` -サーバーのあるディレクトリを再帰的に受信する場合には： +クライアント側では、次のような出力が表示されます: ``` -$ scp -P 22222 -r jill@127.0.0.1: +Server said: Hello, wolfSSH! ``` -## シェルサポート +OpenQuantumSafeのOpenSSHフォークとの相互運用性を確認したい場合は、echoserverを実行している間にそのフォークをビルドして実行できます。次のリンクからリリースをダウンロードしてください: -wolfSSHのechoserverサンプルプログラムはログインを試みるユーザーの為にシェルを起動することができます。この機能はLinuxとmacOSでのみテスト済みです。echoserver.cファイルはユーザー認証コールバック内にユーザーのクレデンシャルを保持するように変更が必要です。あるいはユーザー認証コールバックは提供されたパスワードを検証するように変更する必要があります。 +``` + https://github.com/open-quantum-safe/openssh/archive/refs/tags/OQS-OpenSSH-snapshot-2021-08.tar.gz +``` -wolfSSHをシェルサポート機能付きでビルドする場合には--enable-shellオプションを指定するかあるいはWOLFSSH_SHELLマクロ定義を指定します： +ビルドと実行には次の手順で十分です: ``` -$ ./configure --enable-shell -$ make + $ tar xmvf openssh-OQS-OpenSSH-snapshot-2021-08.tar.gz + $ cd openssh-OQS-OpenSSH-snapshot-2021-08/ + $ ./configure --with-liboqs-dir=/usr/local + $ make all + $ ./ssh -o"KexAlgorithms +ecdh-nistp256-kyber-512-sha256" \ + -o"PubkeyAcceptedAlgorithms +ssh-rsa" \ + -o"HostkeyAlgorithms +ssh-rsa" \ + jill@localhost -p 22222 ``` -デフォルトでechoserverはシェルを実行しようと試みます。エコーバックの機能をテストしたい場合にはコマンドラインオプションで-fを指定してください: +注記: プロンプトが表示されたら、パスワード"upthehill"を入力してください。 + +1行のテキストを入力してEnterを押すと、その行がエコーバックされます。接続を終了するにはCTRL-Cを使用してください。 + + +## Certificate Support + +wolfSSHはユーザーを認証する際に、単なる公開鍵の代わりにX.509証明書を受け付けることができます。 + +wolfSSHをX.509サポート付きでコンパイルするには、`--enable-certs`ビルドオプションを指定するか、あるいは`WOLFSSH_CERTS`を定義してください: ``` -$ ./examples/echoserver/echoserver -f + $ ./configure --enable-certs + $ make +``` + +ユーザーの証明書を検証するためのCAルート証明書を提供するには、echoserverにコマンドラインオプション`-a`を指定してください: + +``` + $ ./examples/echoserver/echoserver -a ./keys/ca-cert-ecc.pem +``` + +echoserverとクライアントには"john"という名前の偽のユーザーが用意されており、その証明書が認証に使用されます。 + +サンプル証明書john-cert.derを使ったechoserver/client接続の例は次のようになります: + +``` + $ ./examples/echoserver/echoserver -a ./keys/ca-cert-ecc.pem -K john:./keys/john-cert.der + + $ ./examples/client/client -u john -J ./keys/john-cert.der -i ./keys/john-key.der ``` diff --git a/wolfSSH/src-ja/chapter05.md b/wolfSSH/src-ja/chapter05.md index 93bd5bc4..af47c18a 100644 --- a/wolfSSH/src-ja/chapter05.md +++ b/wolfSSH/src-ja/chapter05.md @@ -29,7 +29,8 @@ ID の署名とユーザー認証要求メッセージを提供します。サ ユーザ認証コールバック関数プロトタイプは次の通りです： ``` -int UserAuthCb(byte authType , const WS_UserAuthData* authData , void* ctx ); +int UserAuthCb(byte authType , const WS_UserAuthData* +authData , void* ctx ); ``` この関数プロトタイプのタイプは： @@ -52,7 +53,7 @@ WOLFSSH_USERAUTH_PUBLICKEY パラメータ authData　は認証データへのポインタです。 -WS_UserAuthData　の詳細は5.4を参照してください。 +WS_UserAuthData　の詳細は5.4を参照してください。 パラメータ **ctx** はアプリケーション定義のコンテキストです。 wolfSSH はコンテキスト 内のデータについては何の知識も持たず何も操作しません。コールバック関数へのコンテキストポイ @@ -64,6 +65,7 @@ WS_UserAuthData　の詳細は5.4を参照してください。 ``` WOLFSSH_USERAUTH_PASSWORD +WOLFSSH_USERAUTH_KEYBOARD WOLFSSH_USERAUTH_PUBLICKEY ``` @@ -79,9 +81,11 @@ invalid username invalid password invalid public key ``` - -ライブラリはクライアントに成功または失敗のみを示し、下記の特定の失敗タイプはロギングに -のみ使用されます。 +サーバーはクライアントに _成功_ または _失敗_ を示し、特定の失敗タイプはロギングに +のみ使用されます。コールバックがライブラリに返せる特別な成功と失敗の応答として +_partial-success_（部分的成功）があります。これは、その認証タイプは成功したが、完 +全に認証するには別の認証タイプがまだ必要であることを意味します。サーバーは partial-success +フラグをセットしたユーザー認証失敗メッセージをクライアントに送信します。 ``` WOLFSSH_USERAUTH_SUCCESS @@ -89,13 +93,14 @@ WOLFSSH_USERAUTH_FAILURE WOLFSSH_USERAUTH_INVALID_USER WOLFSSH_USERAUTH_INVALID_PASSWORD WOLFSSH_USERAUTH_INVALID_PUBLICKEY +WOLFSSH_USERAUTH_PARTIAL_SUCCESS +WOLFSSH_USERAUTH_SUCCESS_ANOTHER ``` ## コールバック関数のデータタイプ クライアントデータは、`WS_UserAuthData` という構造体でコールバック関数に渡され -ます。 メッセージ内のデータへのポインタが含まれています。 このフィールドには共通フィールドとUNIONフィールドをメンバに持っています。メソッド固有のフィールドは、ユーザー認証データ内のUNIONフィールドにあります。 - +ます。 メッセージ内のデータへのポインタが含まれています。 この構造体には共通フィールドを持ちます。メソッド固有のフィールドは、ユーザー認証データ内の構造体の union にあります。 ``` typedef struct WS_UserAuthData { @@ -103,10 +108,11 @@ typedef struct WS_UserAuthData { byte* username ; word32 usernameSz ; byte* serviceName ; - word32 serviceNameSz ; n + word32 serviceNameSz ; union { WS_UserAuthData_Password password ; WS_UserAuthData_PublicKey publicKey ; + WS_UserAuthData_Keyboard keyboard ; } sf; } WS_UserAuthData; ``` @@ -119,7 +125,6 @@ password フィールドと passwordSz フィールドは、クライアント クライアントから提供された場合は設定されますが、パラメータ hasNewPassword、newPassword、および newPasswordSz は使用されません。 現時点でクライアントにパスワードを変更するように指示するメカニズムはありません。 - ``` typedef struct WS_UserAuthData_Password { uint8_t* password ; @@ -130,6 +135,50 @@ typedef struct WS_UserAuthData_Password { } WS_UserAuthData_Password; ``` +### Keyboard-Interactive + +Keyboard-Interactive モードでは、サーバーからクライアントへ任意の数のプロンプトと +レスポンスをやり取りできます。情報を格納する構造体は次の通りです： + +```c +typedef struct WS_UserAuthData_Keyboard { + word32 promptCount; + word32 responseCount; + word32 promptNameSz; + word32 promptInstructionSz; + word32 promptLanguageSz; + byte* promptName; + byte* promptInstruction; + byte* promptLanguage; + word32* promptLengths; + word32* responseLengths; + byte* promptEcho; + byte** responses; + byte** prompts; +} WS_UserAuthData_Keyboard; +``` + +クライアント側では、認証中に `promptName` と `promptInstruction` が認証に関する情 +報をユーザーに示します。 `promptLanguage` フィールドは API の非推奨部分であり、無 +視されます。 + +`promptCount` はプロンプトがいくつあるかを示します。 `prompts` はプロンプトの配列 +を保持し、`promptLengths` は `prompts` 内の各プロンプトの長さを保持する配列です。 +`promptEcho` は、各プロンプトのレスポンスをユーザーが入力する際にエコー表示するか +どうかを示すブール値の配列です。 + +逆に、`responseCount` は与えられるレスポンスの数を設定します。 `responses` と +`responseLengths` はプロンプトに対するレスポンスデータを保持します。 + +サーバーは `wolfSSH_SetKeyboardAuthPrompts()` コールバックを使用してプロンプトを設 +定できます。 `WS_CallbackKeyboardAuthPrompts` コールバックは `promptCount`、 +`prompts`、`promptLengths`、`promptEcho` を設定する必要があります。 その他の +`prompt*` 項目はオプションです。 + +サーバーは、後続のリクエスト/レスポンスのラウンドを実行するために、 +`WS_CallbackUserAuth` コールバックから `WOLFSSH_USERAUTH_SUCCESS_ANOTHER` を返す必 +要があります。 + ### 公開鍵 wolfSSH は複数の公開鍵アルゴリズムをサポートします。 publicKeyType メンバは、使用されているアルゴリズム名を指します。 diff --git a/wolfSSH/src-ja/chapter06.md b/wolfSSH/src-ja/chapter06.md index 7670286d..a3b01a33 100644 --- a/wolfSSH/src-ja/chapter06.md +++ b/wolfSSH/src-ja/chapter06.md @@ -2,68 +2,56 @@ 以下の関数を使って、ユーザー認証コールバック関数の設定を行います。 - ## ユーザ認証コールバック関数の設定 ``` -void wolfSSH_SetUserAuth(WOLFSSH_CTX* ctx , WS_CallbackUserAuthcb); +void wolfSSH_SetUserAuth(WOLFSSH_CTX* ctx , WS_CallbackUserAuth +cb ); ``` +コールバック関数は、wolfSSH セッションオブジェクトを作成するために使用される wolfSSL CTX オブジェクトに設定されます。この CTX を使用するすべてのセッションは同じコールバック関数を使用します。このコンテキストは、コールバック関数のコンテキストと混同しないでください。 -コールバック関数は、wolfSSH セッションオブジェクトを作成するために使用される -WOLFSSH_CTX オブジェクトに設定されます。 この CTX を使用するすべてのセッション -は同じコールバック関数を使用します。 このコンテキストは、コールバック関数のコン -テキストと混同しないでください。 +## ユーザ認証コールバックコンテキストデータの設定 +``` +void wolfSSH_SetUserAuthCtx(WOLFSSH* ssh , void* ctx ); +``` +それぞれの wolfSSH セッションはそれ自身のユーザ認証コンテキストデータを持っているか、あるいはいくつかを共有することもできます。wolfSSH ライブラリはこのコンテキストデータの内容について何も感知しません。データの作成、解放、および必要に応じた排他制御の提供は、アプリケーションの責任です。コールバックはライブラリからこのコンテキストデータを受け取ります。 -## ユーザ認証コールバックコンテクストデータの設定 +## ユーザ認証コールバックコンテキストデータの取得 ``` -void wolfSSH_SetUserAuthCtx(WOLFSSH* ssh , void* ctx); +void* wolfSSH_GetUserAuthCtx(WOLFSSH* ssh ); ``` -それぞれの wolfSSH セッションはそれ自身のユーザ認証コンテキストデータを持ってい -るか、あるいはいくつかを共有することもできます。 wolfSSH ライブラリはこのコンテ -キストデータの内容について何も感知しません。 データの作成、解放、および必要に応 -じた排他制御の提供は、アプリケーションの責任です。 コールバックはライブラリから -このコンテキストデータを受け取ります。 +提供された wolfSSH セッションに保存されたユーザ認証コンテキストデータへのポインターを返します。これはセッションを作成するために使用される wolfSSH のコンテキストデータと混同しないよう注意してください。 -## ユーザ認証コールバックコンテクストデータの取得 +## キーボード認証プロンプトコールバック関数の設定 ``` -void* wolfSSH_GetUserAuthCtx(WOLFSSH* ssh); +void wolfSSH_SetKeyboardAuthPrompts(WOLFSSH_CTX* ctx, WS_CallbackKeyboardAuthPrompts cb); ``` -提供された wolfSSH セッションに保存されたユーザ認証コンテキストデータへのポイン -タを返します。 これはセッションを作成するために使用される wolfSSH のコンテキスト -データと混同しないよう注意してください。 -## Echoserver サンプルプログラムのユーザ認証 +サーバーは、クライアントが Keyboard-Interactive モードで認証できるように、クライアントに提示するプロンプトを指定する必要があります。このコールバックにより、サーバーはクライアントに送信するプロンプトを設定できます。 + +これが設定されていない場合、明示的に有効化しようとしても、サーバー上で Keyboard-Interactive モードは無効になります。 -サンプルの echoserver は、パスワードと公開鍵を使用してサンプルユーザーとの認証コ -ールバックを実装しています。 コールバックの例と wsUserAuth は、wolfSSH コンテキ -ストに設定されています: +## Echoserver サンプルプログラムのユーザ認証 +サンプルの echoserver は、パスワードと公開鍵を使用してサンプルユーザーとの認証コールバックを実装しています。コールバックの例である wsUserAuth は、wolfSSH コンテキストに設定されています: ``` wolfSSH_SetUserAuth(ctx, wsUserAuth); ``` - -パスワードファイルの例（passwd.txt）は、コロンで区切られたユーザー名とパスワー -ドの単純なリストです。 このファイル内に存在するデフォルトは次のとおりです: +パスワードファイルの例（passwd.txt）は、それぞれコロンで区切られたユーザー名とパスワードの単純なリストです。このファイル内に存在するデフォルトは次のとおりです。 ``` jill:upthehill jack:fetchapail ``` - -公開鍵ファイルは、ssh-keygen を実行して得た公開鍵出力を 2 つ連結したものです。 - +公開鍵ファイルは、ssh-keygen を 2 回実行して得た公開鍵出力を連結したものです。 ``` ssh-rsa AAAAB3NzaC1yc...d+JI8wrAhfE4x hansel ssh-rsa AAAAB3NzaC1yc...UoGCPIKuqcFMf gretel ``` +すべてのユーザー認証データは、ユーザー名と、パスワードまたは公開鍵 blob の SHA-256 ハッシュのペアをリンクリスト形式で格納されています。 -すべてのユーザー認証データは、ユーザー名と、パスワードまたは公開鍵blob のSHA-256 ハッシュのペアをリンクリスト形式で格納されています。 - -設定ファイル内の公開鍵blob は Base64エンコードされており、ハッシュ前にデコードされます。 ユーザ名 - ハッシュペアのリストへのポインタは新しい wolfSSH セッションに保存されます。 - +設定ファイル内の公開鍵 blob は Base64 エンコードされており、ハッシュ前にデコードされます。ユーザ名 - ハッシュペアのリストへのポインターは新しい wolfSSH セッションに保存されます: ``` wolfSSH_SetUserAuthCtx(ssh, &pwMapList); ``` - -コールバック関数は、最初に authType が公開鍵かパスワードかを調べ、そうでない場合は一般ユーザー認証失敗エラーコードを返します。次に、authData を介して渡された公開鍵またはパスワードをハッシュします。ユーザー名をリスト中から検索し見つけられない場合は無効ユーザーエラーコードを返します。ユーザー名が見つかった場合には、渡された公開鍵またはパスワードの計算ハッシュとペアに格納されているハッシュを比較します。一致した場合、関数は成功を返します。それ以外の場合、無効なパスワードまたは公開鍵 -のエラーコードを返します。 +コールバック関数は、最初に authType が公開鍵かパスワードかを調べ、そうでない場合は一般ユーザー認証失敗エラーコードを返します。次に、authData を介して渡された公開鍵またはパスワードをハッシュします。ユーザー名をリスト中から検索し、見つけられない場合は無効ユーザーエラーコードを返します。ユーザー名が見つかった場合には、渡された公開鍵またはパスワードの計算ハッシュとペアに格納されているハッシュを比較します。一致した場合、関数は成功を返します。それ以外の場合、無効なパスワードまたは公開鍵のエラーコードを返します。 diff --git a/wolfSSH/src-ja/chapter07.md b/wolfSSH/src-ja/chapter07.md index f35e3864..d961ae9e 100644 --- a/wolfSSH/src-ja/chapter07.md +++ b/wolfSSH/src-ja/chapter07.md @@ -4,42 +4,34 @@ wolfSSLは既にwolfSSHの使用のためにビルドが済んでいると仮定しています。wolfSSLのビルド方法については２章を参照してください。 -SFTPサポート機能を有効にしてwolfSSHをビルドする場合には、autotoolsを使ったビルドのビルドでは--enable-sftpオプションを指定します。autotoolsを使わない場合にはWOLFSSH_SFTPマクロ定義を指定します。コマンドラインは次のようになります: - - +SFTPサポート機能を有効にしてwolfSSHをビルドする場合には、autotoolsを使ったビルドでは--enable-sftpオプションを指定します。autotoolsを使わない場合にはWOLFSSH_SFTPマクロ定義を指定します。コマンドラインは次のようになります: ``` -$ ./configure --enable-sftp && make +./configure --enable-sftp && make ``` - -リード・ライトをハンドリングするためのバッファサイズはデフォルトで1024バイトです。この値はアプリケーションがより少ないリソース消費に抑えたい場合やより大きなバッファが必要な場合には変更することができます。サイズ変更は`WOLFSSH_MAX_SFTP_RW`マクロを定義して行います。設定例は: +リード・ライトをハンドリングするためのバッファサイズはデフォルトで1024バイトです。この値はアプリケーションがより少ないリソース消費に抑えたい場合やより大きなバッファが必要な場合には変更することができます。デフォルトサイズの変更は、コンパイル時に`WOLFSSH_MAX_SFTP_RW`マクロを定義して行います。設定例は次のとおりです: ``` -$ ./configure --enable-sftp C_EXTRA_FLAGS="WOLFSSH_MAX_SFTP_RW=2048" +./configure --enable-sftp +C_EXTRA_FLAGS=’WOLFSSH_MAX_SFTP_RW=2048 ``` ## wolfSSH SFTP アプリケーションの使用 -SFTPサーバーとクライアントアプリケーションはwoflSSHにバンドルされています。両アプリケーションともautotoolsを使ってwolfSSHライブラリをSFTPサポートを有効にしてビルドする際に同時にビルドされて生成されます。クライアントアプリケーションはwolfsftp/clientフォルダに存在しておりwolfsftpと呼ばれます。 +SFTPサーバーとクライアントアプリケーションはwolfSSHにバンドルされています。両アプリケーションともautotoolsを使ってwolfSSHライブラリをSFTPサポートを有効にしてビルドする際に同時にビルドされて生成されます。サーバーアプリケーションはexamples/echoserverフォルダに存在しておりechoserverと呼ばれます。クライアントアプリケーションはwolfsftp/clientフォルダに存在しておりwolfsftpと呼ばれます。 サーバーの起動例を示します。起動するとSFTPクライアントからの接続を待ち受けます: - ``` -$ ./examples/echoserver/echoserver +./examples/echoserver/echoserver ``` - -ここで、コマンドはルートwolfSSHディレクトリから実行します。サーバーはSSHとSFTPコマンドの両方を処理することができます。 +ここで、コマンドはルートwolfSSHディレクトリから実行します。サーバーはSSHとSFTPの両方の接続を処理することができます。 一方、クライアントを起動するには特定のユーザー名を与えて起動します: - ``` $ ./wolfsftp/client/wolfsftp -u ``` +テストを実行するためのデフォルトの“username:password”は“jack:fetchapail” または “jill:upthehill”です。デフォルトのポートは22222です。 -デフォルトの“username:password”は“jack:fetchapail” または “jill:upthehill”を与えます。デフォルトのポートは22222です。 - -サポートしているコマンドの全リストは接続後に、"help"と入力すると得られます。 - - +サポートしているコマンドの全リストは、接続後に"help"と入力すると得られます。 ``` wolfSSH sftp> help @@ -58,9 +50,7 @@ Commands : interrupt get/put cmd ``` -他のシステムへの接続例は: - +他のシステムへの接続例は次のとおりです: ``` src/wolfssh$ ./examples/sftpclient/wolfsftp -p 22 -u user -h 192.168.1.111 ``` - diff --git a/wolfSSH/src-ja/chapter09.md b/wolfSSH/src-ja/chapter09.md index 99c7aafd..986b093c 100644 --- a/wolfSSH/src-ja/chapter09.md +++ b/wolfSSH/src-ja/chapter09.md @@ -1,3 +1,3 @@ # メモと制限事項 -実装ファイル属性の一部は考慮されておらず、デフォルトの属性またはモード値が使用されます。特に`wolfSSH_SFTP_Open`では、ファイルからタイムスタンプを取得し、すべての拡張ファイル属性を取得します。 +実装の一部では、ファイル属性が考慮されず、デフォルトの属性またはモード値が使用されます。具体的には、`wolfSSH_SFTP_Open`、ファイルからのタイムスタンプの取得、およびすべての拡張ファイル属性において、属性は考慮されません。 diff --git a/wolfSSH/src-ja/chapter11.md b/wolfSSH/src-ja/chapter11.md index 6594e27c..bf6ea8a8 100644 --- a/wolfSSH/src-ja/chapter11.md +++ b/wolfSSH/src-ja/chapter11.md @@ -2,49 +2,52 @@ ## サポートを得るには -一般的な製品サポートのために、wolfSSL(旧Cyassl)は、wolfSSL製品ファミリーのオンラインフォーラムを維持しています。フォーラムに投稿するか、弊社までご連絡ください。 - - -**wolfssl(yassl)フォーラム:** https://www.wolfssl.com/forumshoremail
-**サポート：** support@wolfssl.com +一般的な製品サポートのために、wolfSSLは、wolfSSL製品ファミリーのオンラインフォーラムを維持しています。ご質問がありましたら、フォーラムに投稿するか、wolfSSLまで直接ご連絡ください。 +- wolfSSLフォーラム: [https://www.wolfssl.com/forums](https://www.wolfssl.com/forums) +- メールサポート: support@wolfssl.com wolfSSL製品、ライセンスに関する質問、または一般的なコメントに関する情報については、**facts@wolfssl.com** 宛にメールしてください。 - ### バグレポートと障害のサポート -バグレポートを提出したり、問題についてお尋ねになる場合は、次の情報もあわせてお知らせください:
- -1. wolfSSLバージョン番号
- -2. オペレーティングシステムバージョン
- -3. コンパイラバージョン
- -4. 表示されている正確なエラー番号
- -5. 障害の再現方法
+バグレポートを提出したり、問題についてお尋ねになる場合は、次の情報もあわせてお知らせください: +1. wolfSSLバージョン番号 +2. オペレーティングシステムバージョン +3. コンパイラバージョン +4. 表示されている正確なエラー +5. 障害を再現または再試行する方法の説明 上記の情報が提供いただけると障害解決に向けて最善を尽くすことができますが、情報のご提供がなければ、問題の原因を特定することは非常に困難となります。wolfSSLはお寄せいただいたフィードバックを大切にし、できるだけ早くご回答することを最優先事項にします。 ## コンサルティング -wolfSSLは、機能の追加、移植、競争力のあるアップグレードプログラム、およびデザインコンサルティングを提供します。 +wolfSSLは、機能の追加、移植、競争力のあるアップグレードプログラム（Competitive Upgrade Program）、およびデザインコンサルティングを含む、オンサイトおよびオフサイトの両方のコンサルティングを提供します。 詳細は info@wolfssl.jp 宛にお問い合わせください。 - ### 機能追加と移植 現時点で、ご要望いただいているのに弊社製品で提供されていない機能を、契約または共同開発ベースで追加することができます。また、当社の製品を新しいホスト言語または新しい操作環境に移植するサービスも提供しています。 詳細は info@wolfssl.jp 宛にお問い合わせください。 +### 競争力のあるアップグレードプログラム（Competitive Upgrade Program） + +古くなった、あるいは高価なSSL/TLSライブラリから、低コストかつコードベースへの影響を最小限に抑えて wolfSSL への移行をお手伝いします。 + +プログラム概要: + +1. 現在、wolfSSLの商用競合製品を使用している必要があります。 +2. 古いSSLライブラリをwolfSSLに置き換えるために、最大1週間のオンサイトコンサルティングを受けられます。旅費は含まれません。 +3. 通常、お客様のコードでの置き換えと初期テストを行うには、最大1週間が適切な期間です。置き換えに関する追加のコンサルティングも必要に応じてご利用いただけます。 +4. お客様の製品に同梱するための標準的なwolfSSLのロイヤリティフリーライセンスを受けられます。 + +このプログラムの目的は、現在組み込みSSL実装に多くの費用をかけているユーザーが、容易にwolfSSLへ移行できるようにすることです。詳しくお知りになりたい場合は、facts@wolfssl.com 宛にお問い合わせください。 + ### デザインコンサルティング アプリケーションまたはフレームワークをSSL/TLSで保護する必要があるが、安全なシステムの最適な設計がどのように構造化されるべきかについて不確かな場合は、お手伝いできます！ -wolfSSLを使用して、SSL/TLSセキュリティをデバイスにビルドするためのデザインコンサルティングを提供しています。 - +wolfSSLを使用して、SSL/TLSセキュリティをデバイスにビルドするためのデザインコンサルティングを提供しています。当社のコンサルタントは、以下のサービスを提供できます: diff --git a/wolfSSH/src-ja/chapter13.md b/wolfSSH/src-ja/chapter13.md index 1d5b63c1..94e93449 100644 --- a/wolfSSH/src-ja/chapter13.md +++ b/wolfSSH/src-ja/chapter13.md @@ -1,128 +1,184 @@ -# APIリファレンス +# API リファレンス -このセクションでは、wolfSSH Libraryの公開APIについて説明します。 +このセクションでは、wolfSSH ライブラリの公開アプリケーションプログラムインターフェイスについて説明します。 ## エラーコード + ### WS_ErrorCodes (enum) -以下の戻り値は、wolfssh/wolfssh/error.hで定義されていて、発生する可能性のあるさまざまなタイプのエラーを表します。 - -- WS_SUCCESS (0): 関数は成功 -- WS_FATAL_ERROR (-1): 一般的な失敗 -- WS_BAD_ARGUMENT (-2): 引数が範囲外 -- WS_MEMORY_E (-3): メモリ確保に失敗 -- WS_BUFFER_E (-4): 入/出力バッファのサイズエラー -- WS_PARSE_E (-5): 一般的な解析エラー -- WS_NOT_COMPILED (-6): 機能が組み込まれていない -- WS_OVERFLOW_E (-7): 継続するとオーバーフローする可能性あり -- WS_BAD_USAGE (-8): 使用方法が間違っている -- WS_SOCKET_ERROR_E (-9): ソケットで発生したエラー -- WS_WANT_READ (-10): IOコールバックで読み込みがブロック（再度リードせよ） -- WS_WANT_WRITE (-11): IOコールバックで書き込みがブロック（再度ライトせよ） -- WS_RECV_OVERFLOW_E (-12): 受信バッファがオーバーフローした -- WS_VERSION_E (-13): 相手が異なるSSHバージョンを使っている -- WS_SEND_OOB_READ_E (-14): 帯域外データを読み出そうとした -- WS_INPUT_CASE_E (-15): プロセス入力状態不正あるいはプログラミングエラー -- WS_BAD_FILETYPE_E (-16): ファイルタイプ不正 -- WS_UNIMPLEMENTED_E (-17): 機能が未実装 -- WS_RSA_E (-18): RSAバッファーエラー -- WS_BAD_FILE_E (-19): ファイル不正 -- WS_INVALID_ALGO_ID (-20): 無効なアルゴリズムID -- WS_DECRYPT_E (-21): 復号エラー -- WS_ENCRYPT_E (-22): 暗号化エラー -- WS_VERIFY_MAC_E (-23): mac検証エラー -- WS_CREATE_MAC_E (-24): mac作成エラー -- WS_RESOURCE_E (-25): 新たなチャネル作成にリソース不足 -- WS_INVALID_CHANTYPE (-26): 無効なチャネルタイプ -- WS_INVALID_CHANID(-27): ピアが無効なチャネルIDを要求した -- WS_INVALID_USERNAME(-28): 無効なユーザー名 -- WS_CRYPTO_FAILED(-29): 暗号アクションが失敗 -- WS_INVALID_STATE_E(-30): 無効な状態 -- WC_EOF(-31): ファイルの終了 -- WS_INVALID_PRIME_CURVE(-32): 無効なECCプライムカーブ -- WS_ECC_E(-33): ECDSAバッファーエラー -- WS_CHANOPEN_FAILED(-34): ピアがチャネルオープン失敗を返した -- WS_REKEYING(-35): ピアとリキーイング -- WS_CHANNEL_CLOSED(-36): チャネルがクローンした + +以下の API 応答コードは wolfssh/error.h で定義されており、発生し得るさまざまな種類のエラーを表す。`WS_SUCCESS` は 0 であり、すべてのエラーコードは負の値である。`WS_FATAL_ERROR` は `WS_ERROR` の非推奨エイリアスであり、`WS_LAST_E` は常に最後に定義されたエラーコードを指す。 + +- WS_SUCCESS (0): 関数成功 +- WS_ERROR (-1001): 一般的な関数失敗 +- WS_FATAL_ERROR (-1001): WS_ERROR の非推奨エイリアス +- WS_BAD_ARGUMENT (-1002): 不正な関数引数 +- WS_MEMORY_E (-1003): メモリ割り当て失敗 +- WS_BUFFER_E (-1004): 入出力バッファサイズエラー +- WS_PARSE_E (-1005): 一般的な解析エラー +- WS_NOT_COMPILED (-1006): 機能がコンパイルに含まれていない +- WS_OVERFLOW_E (-1007): 続行するとオーバーフローする +- WS_BAD_USAGE (-1008): 不正な使用例 +- WS_SOCKET_ERROR_E (-1009): ソケットエラー +- WS_WANT_READ (-1010): ノンブロッキング読み込みがブロックする、再度呼び出すこと +- WS_WANT_WRITE (-1011): ノンブロッキング書き込みがブロックする、再度呼び出すこと +- WS_RECV_OVERFLOW_E (-1012): 受信バッファオーバーフロー +- WS_VERSION_E (-1013): ピアが誤ったバージョンの SSH を使用している +- WS_SEND_OOB_READ_E (-1014): バッファの範囲外読み込みを試みた +- WS_INPUT_CASE_E (-1015): 不正な処理入力状態、プログラミングエラー +- WS_BAD_FILETYPE_E (-1016): 不正なファイルタイプ +- WS_UNIMPLEMENTED_E (-1017): 機能が実装されていない +- WS_RSA_E (-1018): RSA バッファエラー +- WS_BAD_FILE_E (-1019): 不正なファイル +- WS_INVALID_ALGO_ID (-1020): 無効なアルゴリズム ID +- WS_DECRYPT_E (-1021): 復号エラー +- WS_ENCRYPT_E (-1022): 暗号化エラー +- WS_VERIFY_MAC_E (-1023): MAC 検証エラー +- WS_CREATE_MAC_E (-1024): MAC 生成エラー +- WS_RESOURCE_E (-1025): 新しいチャネルのためのリソース不足 +- WS_INVALID_CHANTYPE (-1026): 無効なチャネルタイプ +- WS_INVALID_CHANID (-1027): ピアが無効なチャネル ID を要求した +- WS_INVALID_USERNAME (-1028): 無効なユーザー名 +- WS_CRYPTO_FAILED (-1029): 暗号処理が失敗した +- WS_INVALID_STATE_E (-1030): 無効な状態 +- WS_EOF (-1031): ファイルの終端 +- WS_INVALID_PRIME_CURVE (-1032): ECC における無効な素数曲線 +- WS_ECC_E (-1033): ECDSA バッファエラー +- WS_CHANOPEN_FAILED (-1034): ピアがチャネルオープン失敗を返した +- WS_REKEYING (-1035): ステータス: 再鍵交換が進行中 +- WS_CHANNEL_CLOSED (-1036): ステータス: チャネルがクローズされた +- WS_INVALID_PATH_E (-1037): 無効なパス +- WS_SCP_CMD_E (-1038): SCP コマンドエラー +- WS_SCP_BAD_MSG_E (-1039): SCP 不正メッセージ +- WS_SCP_PATH_LEN_E (-1040): SCP パスが長すぎる +- WS_SCP_TIMESTAMP_E (-1041): SCP タイムスタンプエラー +- WS_SCP_DIR_STACK_EMPTY_E (-1042): SCP ディレクトリスタックが空 +- WS_SCP_CONTINUE (-1043): ステータス: SCP 継続 +- WS_SCP_ABORT (-1044): ステータス: SCP 中断 +- WS_SCP_ENTER_DIR (-1045): ステータス: SCP ディレクトリに入る +- WS_SCP_EXIT_DIR (-1046): ステータス: SCP ディレクトリから出る +- WS_SCP_EXIT_DIR_FINAL (-1047): ステータス: SCP 最終ディレクトリから出る +- WS_SCP_COMPLETE (-1048): ステータス: SCP 転送完了 +- WS_SCP_INIT (-1049): ステータス: SCP 転送が検証された +- WS_MATCH_KEX_ALGO_E (-1050): ピアと KEX アルゴリズムが一致しない +- WS_MATCH_KEY_ALGO_E (-1051): ピアと鍵アルゴリズムが一致しない +- WS_MATCH_ENC_ALGO_E (-1052): ピアと暗号化アルゴリズムが一致しない +- WS_MATCH_MAC_ALGO_E (-1053): ピアと MAC アルゴリズムが一致しない +- WS_PERMISSIONS (-1054): 権限エラー +- WS_SFTP_COMPLETE (-1055): ステータス: SFTP 接続確立 +- WS_NEXT_ERROR (-1056): 次の値/状態の取得がエラー +- WS_CHAN_RXD (-1057): ステータス: チャネルデータを受信した +- WS_INVALID_EXTDATA (-1058): 無効なチャネル拡張データタイプ +- WS_SFTP_BAD_REQ_ID (-1060): SFTP 不正リクエスト ID +- WS_SFTP_BAD_REQ_TYPE (-1061): SFTP 不正リクエストタイプ +- WS_SFTP_STATUS_NOT_OK (-1062): SFTP ステータスが OK ではない +- WS_SFTP_FILE_DNE (-1063): SFTP ファイルが存在しない +- WS_SIZE_ONLY (-1064): 必要なバッファのサイズのみ取得している +- WS_CLOSE_FILE_E (-1065): ローカルファイルをクローズできない +- WS_PUBKEY_REJECTED_E (-1066): サーバーの公開鍵が拒否された +- WS_EXTDATA (-1067): 読み取り可能な拡張データがある +- WS_USER_AUTH_E (-1068): ユーザー認証エラー +- WS_SSH_NULL_E (-1069): SSH オブジェクトが NULL だった +- WS_SSH_CTX_NULL_E (-1070): SSH_CTX オブジェクトが NULL だった +- WS_CHANNEL_NOT_CONF (-1071): チャネルオープンが確認されていない +- WS_CHANGE_AUTH_E (-1072): 認証タイプの変更が試みられた +- WS_WINDOW_FULL (-1073): チャネルウィンドウが満杯 +- WS_MISSING_CALLBACK (-1074): コールバックが不足している +- WS_DH_SIZE_E (-1075): DH 素数が想定より大きい +- WS_PUBKEY_SIG_MIN_E (-1076): 署名が小さすぎる +- WS_AGENT_NULL_E (-1077): エージェントオブジェクトが NULL だった +- WS_AGENT_NO_KEY_E (-1078): エージェントが要求された鍵を保持していない +- WS_AGENT_CXN_FAIL (-1079): エージェントに接続できなかった +- WS_SFTP_BAD_HEADER (-1080): SFTP 不正ヘッダー +- WS_CERT_NO_SIGNER_E (-1081): 署名者証明書が利用できない +- WS_CERT_EXPIRED_E (-1082): 証明書が期限切れ +- WS_CERT_REVOKED_E (-1083): ユーザー証明書が失効していると報告された +- WS_CERT_SIG_CONFIRM_E (-1084): ルート証明書の署名検証失敗 +- WS_CERT_OTHER_E (-1085): その他の証明書に関する問題 +- WS_CERT_PROFILE_E (-1086): 証明書がプロファイル要件を満たしていない +- WS_CERT_KEY_SIZE_E (-1087): 鍵サイズエラー +- WS_CTX_KEY_COUNT_E (-1088): 秘密鍵の追加が多すぎる +- WS_MATCH_UA_KEY_ID_E (-1089): ユーザー認証鍵の照合失敗 +- WS_KEY_AUTH_MAGIC_E (-1090): OpenSSH 鍵の認証マジックチェック失敗 +- WS_KEY_CHECK_VAL_E (-1091): OpenSSH 鍵のチェック値失敗 +- WS_KEY_FORMAT_E (-1092): OpenSSH 鍵形式失敗 +- WS_SFTP_NOT_FILE_E (-1093): 通常のファイルではない +- WS_MSGID_NOT_ALLOWED_E (-1094): ユーザー認証前は許可されないメッセージ +- WS_ED25519_E (-1095): Ed25519 失敗 +- WS_AUTH_PENDING (-1096): ユーザー認証がまだ保留中 +- WS_KDF_E (-1097): KDF エラー +- WS_DISCONNECT (-1098): ピアが切断を送信した ### WS_IOerrors (enum) -以下は、ライブラリがユーザー提供のI/Oコールバックから受け取ることを期待しているリターンコードです。それ以外の場合、ライブラリは、I/Oアクションから読み取られたバイト数を期待しています。 +これらは、ユーザー提供の I/O コールバックからライブラリが受け取ることを想定している戻りコードである。それ以外の場合、ライブラリは I/O 動作によって読み書きされたバイト数を期待する。 + - WS_CBIO_ERR_GENERAL (-1): 一般的な予期しないエラー -- WS_CBIO_ERR_WANT_READ (-2): ソケットの読み取りブロック（再度リードせよ） -- WS_CBIO_ERR_WANT_WRITE (-2): ソケットの書き込みブロック（再度ライトせよ） -- WS_CBIO_ERR_CONN_RST (-3): コネクションがリセットされた -- WS_CBIO_ERR_ISR (-4): 割り込み発生 -- WS_CBIO_ERR_CONN_CLOSE (-5): コネクションがクローンした +- WS_CBIO_ERR_WANT_READ (-2): ソケットの読み込みがブロックする、再度呼び出すこと +- WS_CBIO_ERR_WANT_WRITE (-2): ソケットの書き込みがブロックする、再度呼び出すこと +- WS_CBIO_ERR_CONN_RST (-3): 接続がリセットされた +- WS_CBIO_ERR_ISR (-4): 割り込み +- WS_CBIO_ERR_CONN_CLOSE (-5): 接続がクローズされた、または EPIPE - WS_CBIO_ERR_TIMEOUT (-6): ソケットタイムアウト -## 初期化 /シャットダウン +## 初期化 / シャットダウン ### wolfSSH_Init() +```c +#include - -**用法** +int wolfSSH_Init(void); +``` **説明** -wolfSSHライブラリを初期化します。アプリケーションごとに1回、ライブラリへの他の呼び出しの前に呼び出される必要があります。 - -**戻り値** - -WS_SUCCESS
- -WS_CRYPTO_FAILED +使用に先立って wolfSSH ライブラリを初期化する。ライブラリへの他のいかなる呼び出しよりも前に、アプリケーションごとに一度だけ呼び出す必要がある。 **引数** なし -``` -#include -int wolfSSH_Init(void); -``` -**関連項目** +**戻り値** + +- `WS_SUCCESS` +- `WS_CRYPTO_FAILED` -wolfSSH_Cleanup() +**関連項目** +- `wolfSSH_Cleanup()` ### wolfSSH_Cleanup() +```c +#include - -**用法** +int wolfSSH_Cleanup(void); +``` **説明** -wolfSSHライブラリをクリーンアップします。アプリケーションの終了前に呼び出す必要があります。本関数呼び出し後は、ライブラリAPIの呼び出しはできません。 - -**戻り値** - -**WS_SUCCESS** - -**WS_CRYPTO_FAILED** +使用を終えた際に wolfSSH ライブラリをクリーンアップする。アプリケーションの終了前に呼び出すべきである。呼び出した後は、それ以上ライブラリを呼び出してはならない。 **引数** なし +**戻り値** -``` -#include -int wolfSSH_Cleanup(void); -``` +- `WS_SUCCESS` +- `WS_CRYPTO_FAILED` **関連項目** -wolfSSH_Init() +- `wolfSSH_Init()` ## デバッグ出力関数 @@ -130,61 +186,51 @@ wolfSSH_Init() ### wolfSSH_Debugging_ON() +```c +#include - -**用法** +void wolfSSH_Debugging_ON(void); +``` **説明** -実行中にデバッグロギングを有効にします。ビルド時にデバッグが無効になっている場合、何もしません。 +実行時のデバッグログ出力を有効にする。ビルド時にデバッグが無効化されている場合は何も行わない。 - -**戻り値** +**引数** なし -**引数** +**戻り値** なし -``` -#include -void wolfSSH_Debugging_ON(void); -``` - **関連項目** -wolfSSH_Debugging_OFF() - +- `wolfSSH_Debugging_OFF()` ### wolfSSH_Debugging_OFF() +```c +#include - -**用法** +void wolfSSH_Debugging_OFF(void); +``` **説明** -実行時にデバッグロギングを無効にします。ビルド時にデバッグが無効になっている場合、何もしません。 - - -**戻り値** - -なし +実行時のデバッグログ出力を無効にする。ビルド時にデバッグが無効化されている場合は何も行わない。 **引数** なし +**戻り値** -``` -#include -void wolfSSH_Debugging_OFF(void); -``` +なし **関連項目** -wolfSSH_Debugging_ON() +- `wolfSSH_Debugging_ON()` ## コンテキスト関数 @@ -192,1394 +238,3657 @@ wolfSSH_Debugging_ON() ### wolfSSH_CTX_new() +```c +#include - -**用法** +WOLFSSH_CTX* wolfSSH_CTX_new(byte side, void* heap); +``` **説明** -wolfSSHコンテキストオブジェクトを作成します。このオブジェクトはwolfSSHセッションオブジェクトのファクトリとして使用されます。 - -**戻り値** - -**WOLFSSH_CTX** – 割り当てられたWOLFSSH_CTXオブジェクトへのポインターあるいはNULL +wolfSSH コンテキストオブジェクトを作成する。このオブジェクトは設定した上で、wolfSSH セッションオブジェクトのファクトリとして使用できる。 **引数** -**side** – クライアントサイド(実装なし)またはサーバーサイドを示します
+- `side` - エンドポイントの役割: `WOLFSSH_ENDPOINT_SERVER` または `WOLFSSH_ENDPOINT_CLIENT` +- `heap` - メモリ割り当てに使用するヒープへのポインター、または `NULL` -**heap** – メモリ割り当てに使用するヒープへのポインター +**戻り値** -``` -#include -WOLFSSH_CTX* wolfSSH_CTX_new(byte side , void* heap ); -``` +- `WOLFSSH_CTX*` - 新しく割り当てられたコンテキストオブジェクトへのポインター +- `NULL` - 失敗時 **関連項目** -wolfSSH_CTX_free() - +- `wolfSSH_CTX_free()` ### wolfSSH_CTX_free() +```c +#include - -**用法** +void wolfSSH_CTX_free(WOLFSSH_CTX* ctx); +``` **説明** -WOLFSSH_CTXオブジェクトを解放します - -**戻り値** - -なし +wolfSSH コンテキストオブジェクトを解放する。 **引数** -**ctx** – WOLFSSH_CTXオブジェクト +- `ctx` - 解放する wolfSSH コンテキスト -``` -#include -void wolfSSH_CTX_free(WOLFSSH_CTX* ctx ); -``` +**戻り値** + +なし **関連項目** -wolfSSH_CTX_new() +- `wolfSSH_CTX_new()` ### wolfSSH_CTX_SetBanner() +```c +#include -**用法** +int wolfSSH_CTX_SetBanner(WOLFSSH_CTX* ctx, const char* newBanner); +``` **説明** -バナーメッセージをセットします +認証前にピアへ提示されるバナーメッセージを設定する。 -**戻り値** +**引数** -WS_BAD_ARGUMENT
+- `ctx` - wolfSSH コンテキストへのポインター +- `newBanner` - バナーメッセージのテキスト -WS_SUCCESS +**戻り値** -**引数** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` -**ssh** - wolfSSHオブジェクト
+**関連項目** -**newBanner** - バナーメッセージ文字列 +- `wolfSSH_CTX_UsePrivateKey_buffer()` -``` +### wolfSSH_CTX_UsePrivateKey_buffer() + +```c #include -int wolfSSH_CTX_SetBanner(WOLFSSH_CTX* ctx , const char* newBanner ); + +int wolfSSH_CTX_UsePrivateKey_buffer(WOLFSSH_CTX* ctx, + const byte* in, word32 inSz, int format); ``` -### wolfSSH_CTX_UsePrivateKey_buffer() +**説明** +ファイルではなくバッファから秘密鍵を SSH コンテキストに読み込む。鍵は `in` 引数によって渡され、サイズは `inSz` である。`format` 引数はバッファのエンコーディングを指定する: `WOLFSSH_FORMAT_ASN1` または `WOLFSSH_FORMAT_PEM`（PEM は現時点では未実装）。 -**用法** +**引数** -**説明**
-この関数は、秘密鍵バッファをSSHコンテキストにロードします。ファイルの代わりにバッファーを入力として呼び出されます。バッファは、**insz** の **in** 引数によって提供されます。
+- `ctx` - wolfSSH コンテキストへのポインター +- `in` - 読み込む秘密鍵を含むバッファ +- `inSz` - 入力バッファのサイズ +- `format` - 入力バッファ内の秘密鍵の形式 -**引数** +**戻り値** -**format** バッファのタイプを指定します：**wolfssh_format_asn1** または **wolfssl_format_pem** (現時点では未実装)。 +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_BAD_FILETYPE_E` +- `WS_UNIMPLEMENTED_E` +- `WS_MEMORY_E` +- `WS_RSA_E` +- `WS_BAD_FILE_E` +**関連項目** -**戻り値** +- `wolfSSH_CTX_UseCert_buffer()` -**WS_SUCCESS**
+### wolfSSH_CTX_UseCert_buffer() -**WS_BAD_ARGUMENT** – 少なくとも一つの引数が不正
+**利用可能性** -**WS_BAD_FILETYPE_E** – フォーマットが不正
+`WOLFSSH_CERTS` が必要。 -**WS_UNIMPLEMENTED_E** – PEMフォーマットは未対応
+```c +#include -**WS_MEMORY_E** – メモリ確保エラー
+int wolfSSH_CTX_UseCert_buffer(WOLFSSH_CTX* ctx, + const byte* cert, word32 certSz, int format); +``` -**WS_RSA_E** – RSA鍵をデコードできない
+**説明** -**WS_BAD_FILE_E** – バッファを解析できない
+証明書ベースのホスト認証のために、サーバーの X.509 証明書をバッファからコンテキストに読み込む。`format` は `WOLFSSH_FORMAT_ASN1` または `WOLFSSH_FORMAT_PEM` である。 **引数** -**ctx** – wolfSSH_CTXオブジェクトへのポインター
+- `ctx` - wolfSSH コンテキストへのポインター +- `cert` - 証明書を含むバッファ +- `certSz` - 証明書バッファのサイズ +- `format` - 証明書のエンコーディング + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` + +**関連項目** -**in** – 秘密鍵を含むバッファへのポインター
+- `wolfSSH_CTX_AddRootCert_buffer()` -**inSz** – 入力バッファのサイズ
+### wolfSSH_CTX_AddRootCert_buffer() -**format** – 秘密鍵のフォーマット
+**利用可能性** -``` +`WOLFSSH_CERTS` が必要。 + +```c #include -int wolfSSH_CTX_UsePrivateKey_buffer(WOLFSSH_CTX* ctx , const byte* in , word32 inSz , int format); + +int wolfSSH_CTX_AddRootCert_buffer(WOLFSSH_CTX* ctx, + const byte* cert, word32 certSz, int format); ``` -**関連項目** +**説明** -wolfSSH_UseCert_buffer()
+ピアから提示された証明書を検証するために使用する、信頼されたルート CA 証明書をコンテキストに追加する。`format` は `WOLFSSH_FORMAT_ASN1` または `WOLFSSH_FORMAT_PEM` である。 -wolfSSH_UseCaCert_buffer()
+**引数** +- `ctx` - wolfSSH コンテキストへのポインター +- `cert` - ルート証明書を含むバッファ +- `certSz` - 証明書バッファのサイズ +- `format` - 証明書のエンコーディング -## SSH セッション関数 +**戻り値** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` -### wolfSSH_new() +**関連項目** + +- `wolfSSH_CTX_UseCert_buffer()` +## SSH セッション関数 -**用法** -**説明** +### wolfSSH_new() -wolfSSHセッションオブジェクトを確保し、与えられたwolfSSH_CTXオブジェクトを使って初期化します。 +```c +#include -**戻り値** +WOLFSSH* wolfSSH_new(WOLFSSH_CTX* ctx); +``` -**WOLFSSH*** – WOLFSSHオブジェクトへのポインターあるいはNULL +**説明** + +提供された wolfSSH コンテキストで初期化された wolfSSH セッションオブジェクトを作成する。 **引数** -**ctx** – wolfSSHセッションの初期化に使用されるwolfSSHコンテキスト +- `ctx` - セッションの初期化に使用する wolfSSH コンテキスト +**戻り値** -``` -#include -WOLFSSH* wolfSSH_new(WOLFSSH_CTX* ctx ); -``` +- `WOLFSSH*` - 新しく割り当てられたセッションオブジェクトへのポインター +- `NULL` - 失敗時 **関連項目** -wolfSSH_free() +- `wolfSSH_free()` ### wolfSSH_free() +```c +#include - -**用法** +void wolfSSH_free(WOLFSSH* ssh); +``` **説明** -wolfSSHオブジェクトを解放します +wolfSSH セッションオブジェクトを解放する。 + +**引数** + +- `ssh` - 解放するセッション **戻り値** なし -**引数** +**関連項目** -**ssh** – 解放するWOLFSSHオブジェクトへのポインター +- `wolfSSH_new()` -``` +### wolfSSH_worker() + +```c #include -void wolfSSH_free(WOLFSSH* ssh ); + +int wolfSSH_worker(WOLFSSH* ssh, word32* channelId); ``` -**関連項目** +**説明** -wolfSSH_new() +SSH 接続を処理する。保留中の受信データを受け取り、保留中の送信パケットをフラッシュする。これは実行中のセッションに対する主要なドライバー呼び出しである。成功時、`channelId` が NULL でなければ、最も直近にデータを受信したチャネルの ID がそこに書き込まれる。 +**引数** -### wolfSSH_set_fd() +- `ssh` - wolfSSH セッションへのポインター +- `channelId` - 最後にデータを受信したチャネル ID の出力先（任意、NULL でもよい） + +**戻り値** +- `WS_SUCCESS` +- `WS_CHAN_RXD` +- `WS_REKEYING` +- `WS_WANT_READ` +- `WS_WANT_WRITE` +- `WS_BAD_ARGUMENT` +**関連項目** -**用法** +- `wolfSSH_GetLastRxId()` -**説明** +### wolfSSH_GetLastRxId() -与えられたファイルディスクリプタをsshオブジェクトに関連付けます。ファイルディスクリプタはネットワークI/Oに使用され、I/Oコールバック関数に渡されます。 +```c +#include -**戻り値** +int wolfSSH_GetLastRxId(WOLFSSH* ssh, word32* channelId); +``` -WS_SUCCESS
+**説明** -WS_BAD_ARGUMENT – 引数の少なくともひとつが不正 +最も直近にデータを受信したチャネルの ID を `channelId` に書き込む。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
+- `ssh` - wolfSSH セッションへのポインター +- `channelId` - 最後に受信したチャネル ID の出力先 -**fd** – セッションで使用されるソケットディスクリプター +**戻り値** -``` -#include -int wolfSSH_set_fd(WOLFSSH* ssh , int fd ); -``` +- `WS_SUCCESS` +- `WS_ERROR` **関連項目** -wolfSSH_get_fd() - -### wolfSSH_get_fd() +- `wolfSSH_worker()` +### wolfSSH_set_fd() +```c +#include -**用法** +int wolfSSH_set_fd(WOLFSSH* ssh, WS_SOCKET_T fd); +``` **説明** -SSHコネクションの入出力機能で使用されるファイルディスクリプタ( **fd** )を返します。一般的にはソケットファイルディスクリプタを返します。 +指定されたファイルディスクリプタをセッションに割り当てる。セッションは、デフォルトの I/O コールバックにおいて、このディスクリプタをネットワーク I/O に使用する。 + +**引数** +- `ssh` - ディスクリプタを設定するセッション +- `fd` - セッションが使用するソケットのファイルディスクリプタ **戻り値** -**int** – ファイルディスクリプタ
- -**WS_BAD_ARGUEMENT** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` -**引数** +**関連項目** -**ssh** – WOLFSSHオブジェクトへのポインター
+- `wolfSSH_get_fd()` +### wolfSSH_get_fd() -``` +```c #include -int wolfSSH_get_fd(const WOLFSSH* ssh ); + +WS_SOCKET_T wolfSSH_get_fd(const WOLFSSH* ssh); ``` -**関連項目** +**説明** -wolfSSH_set_fd() +SSH 接続の入出力に使用されているファイルディスクリプタを返す。通常はソケットのファイルディスクリプタである。 -## ハイウォーターマーク機能 +**引数** +- `ssh` - wolfSSH セッションへのポインター +**戻り値** -### wolfSSH_SetHighwater() +- 成功時はセッションのソケットファイルディスクリプタ +- `ssh` が NULL の場合は `WS_BAD_ARGUMENT`（Windows では `INVALID_SOCKET`） +**関連項目** -**用法** +- `wolfSSH_set_fd()` -**説明** +### wolfSSH_SetFilesystemHandle() -SSHセッションで使用するハイウォーターマークをセットします。 +```c +#include -**戻り値** +int wolfSSH_SetFilesystemHandle(WOLFSSH* ssh, void* handle); +``` -WS_SUCCESS
+**説明** -WS_BAD_ARGUMENT +ユーザーが提供するファイルシステムハンドルをセッションに関連付ける。独自のファイルシステム層を提供する移植環境では、セッションに対するファイル操作を行う際にこのハンドルを使用する。 **引数** -**ssh** - WOLFSSHオブジェクトへのポインター
+- `ssh` - wolfSSH セッションへのポインター +- `handle` - セッションに関連付ける不透明なファイルシステムハンドル -**highwater** - ハイウォーターマークを示すデータ +**戻り値** -``` -#include -int wolfSSH_SetHighwater(WOLFSSH* ssh , word32 highwater ); -``` +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` -### wolfSSH_GetHighwater() +**関連項目** +- `wolfSSH_GetFilesystemHandle()` -**用法** +### wolfSSH_GetFilesystemHandle() + +```c +#include + +void* wolfSSH_GetFilesystemHandle(WOLFSSH* ssh); +``` **説明** -ハイウォーターマークを返します。 +wolfSSH_SetFilesystemHandle() によって以前にセッションへ関連付けられたファイルシステムハンドルを返す。設定されていない場合は NULL を返す。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター **戻り値** -**word32** - ハイウォーターマーク +- セッションに関連付けられたファイルシステムハンドル +- `NULL` - `ssh` が NULL の場合、またはハンドルが設定されていない場合 -**引数** +**関連項目** -**ssh** - WOLFSSHオブジェクトへのポインター
+- `wolfSSH_SetFilesystemHandle()` -``` -#include -word32 wolfSSH_GetHighwater(WOLFSSH* ssh ); -``` +## データ最高水位関数 -### wolfSSH_SetHighwaterCb() -**用法** +### wolfSSH_SetHighwater() -**説明** -SSHセッションにハイウォーターマークとハイウォーターコールバック関数を設定します。 +```c +#include +int wolfSSH_SetHighwater(WOLFSSH* ssh, word32 level); +``` -**戻り値** +**説明** -なし +セッションのデータハイウォーターマークをバイト単位で設定する。転送されたデータ量がこのレベルに達すると、ハイウォーターコールバックが呼び出される（通常はリキーをトリガーするため）。 **引数** -**ctx** – wolfSSHコンテキスト
+- `ssh` - wolfSSH セッションへのポインター +- `level` - ハイウォーターマーク（バイト単位） -**highwater** - ハイウォーターマーク
+**戻り値** -**cb** - ハイウォーターコールバック関数
+- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +**関連項目** -``` -#include -void wolfSSH_SetHighwaterCb(WOLFSSH_CTX* ctx , word32 highwater , -WS_CallbackHighwater cb ); -``` +- `wolfSSH_GetHighwater()` + +### wolfSSH_GetHighwater() -### wolfSSH_SetHighwaterCtx() +```c +#include -**用法** +word32 wolfSSH_GetHighwater(WOLFSSH* ssh); +``` **説明** -ハイウォーターコールバック関数に渡されるコンテキストを設定します。 +セッションの現在のデータハイウォーターマークをバイト単位で返す。 + +**引数** +- `ssh` - wolfSSH セッションへのポインター **戻り値** -なし +- データハイウォーターマーク（バイト単位） -**引数** +**関連項目** + +- `wolfSSH_SetHighwater()` -**ssh** - WOLFSSHオブジェクトへのポインター
+### wolfSSH_SetHighwaterCb() -**ctx** - ハイウォーターコールバック関数に渡されるコンテキスト -``` +```c #include -void wolfSSH_SetHighwaterCtx(WOLFSSH* ssh, void* ctx); -``` -### wolfSSH_GetHighwaterCtx() +void wolfSSH_SetHighwaterCb(WOLFSSH_CTX* ctx, word32 level, + WS_CallbackHighwater cb); +``` +**説明** -**用法** +コンテキストレベルで、デフォルトのデータハイウォーターマークと、セッションがそれに到達したときに呼び出されるコールバックを設定する。このコンテキストから作成されたセッションは、これらのデフォルト値を継承する。 -**説明** +**引数** -SSHセッションにセットされたハイウォーターマークを返します。 +- `ctx` - wolfSSH コンテキストへのポインター +- `level` - デフォルトのデータハイウォーターマーク（バイト単位） +- `cb` - ハイウォーターコールバック関数 **戻り値** -**void*** - ハイウォーターマーク
+なし -**NULL** - WOLFSSHオブジェクトにハイウォーターマークがセットされていない場合 +**関連項目** -**引数** +- `wolfSSH_SetHighwaterCtx()` -**ssh**　- WOLFSSHオブジェクトへのポインター +### wolfSSH_SetHighwaterCtx() -``` + +```c #include -void wolfSSH_GetHighwaterCtx(WOLFSSH* ssh ); + +void wolfSSH_SetHighwaterCtx(WOLFSSH* ssh, void* ctx); ``` -## エラーチェック +**説明** +セッションのハイウォーターコールバックが呼び出される際に渡される、ユーザーコンテキストポインターを設定する。 +**引数** -### wolfSSH_get_error() +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - ハイウォーターコールバックに渡すユーザーコンテキストポインター +**戻り値** +なし -**用法** +**関連項目** -**説明** +- `wolfSSH_GetHighwaterCtx()` -wolfSSHセッションオブジェクトにセットされたエラーコードを返します。 +### wolfSSH_GetHighwaterCtx() -**戻り値** -WS_ErrorCodes (enum) +```c +#include + +void* wolfSSH_GetHighwaterCtx(WOLFSSH* ssh); +``` + +**説明** + +wolfSSH_SetHighwaterCtx() によって以前に設定された、ハイウォーターコールバックに渡されるユーザーコンテキストポインターを返す。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- ハイウォーターのユーザーコンテキストポインター +- `NULL` - `ssh` が無効な場合、またはコンテキストが設定されていない場合 + +**関連項目** + +- `wolfSSH_SetHighwaterCtx()` + +### wolfSSH_CTX_SetMsgHighwater() + +```c +#include + +void wolfSSH_CTX_SetMsgHighwater(WOLFSSH_CTX* ctx, word32 level); +``` + +**説明** + +コンテキストレベルで、デフォルトのパケット数ハイウォーターマーク（RFC 4344, Section 3.1）を設定する。セッションで送受信されたパケット数がこのレベルに達すると、リキーがトリガーされる。このコンテキストから作成されたセッションは、このデフォルト値を継承する。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `level` - パケット数ハイウォーターマーク + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_SetMsgHighwater()` + +### wolfSSH_SetMsgHighwater() + +```c +#include + +void wolfSSH_SetMsgHighwater(WOLFSSH* ssh, word32 level); +``` + +**説明** + +単一のセッションに対して、パケット数ハイウォーターマーク（RFC 4344, Section 3.1）を設定する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `level` - パケット数ハイウォーターマーク + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_GetMsgHighwater()` + +### wolfSSH_GetMsgHighwater() + +```c +#include + +word32 wolfSSH_GetMsgHighwater(WOLFSSH* ssh); +``` + +**説明** + +セッションの現在のパケット数ハイウォーターマークを返す。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- パケット数ハイウォーターマーク + +**関連項目** + +- `wolfSSH_SetMsgHighwater()` + +## エラーチェック + + + +### wolfSSH_get_error() + + + +```c +#include + +int wolfSSH_get_error(const WOLFSSH* ssh); +``` + +**説明** + +wolfSSH セッションオブジェクトに設定された最後のエラーを返します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- `WS_ErrorCodes` の値（エラーコードを参照） + +**関連項目** + +- `wolfSSH_get_error_name()` + +### wolfSSH_get_error_name() + + + +```c +#include + +const char* wolfSSH_get_error_name(const WOLFSSH* ssh); +``` + +**説明** + +wolfSSH セッションオブジェクトに設定された最後のエラーの名前文字列を返します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- エラー名文字列へのポインター + +**関連項目** + +- `wolfSSH_get_error()` + +### wolfSSH_ErrorToName() + + +```c +#include + +const char* wolfSSH_ErrorToName(int err); +``` + +**説明** + +指定した wolfSSH エラーコードの名前文字列を返します。 + +**引数** + +- `err` - エラーコードの値（`WS_ErrorCodes` の値） + +**戻り値** + +- エラー名文字列へのポインター + +**関連項目** + +- `wolfSSH_get_error_name()` + +## I/O コールバック + + + +### wolfSSH_SetIORecv() + + +```c +#include + +void wolfSSH_SetIORecv(WOLFSSH_CTX* ctx, WS_CallbackIORecv cb); +``` + +**説明** + +wolfSSH が入力データを読み取る際に使用する受信コールバックを登録します。コールバックのシグネチャは `WS_CallbackIORecv` 型で示されます。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - コンテキストの受信コールバックとして登録する関数 + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_SetIOSend()` + +### wolfSSH_SetIOSend() + + +```c +#include + +void wolfSSH_SetIOSend(WOLFSSH_CTX* ctx, WS_CallbackIOSend cb); +``` + +**説明** + +wolfSSH が出力データを書き込む際に使用する送信コールバックを登録します。コールバックのシグネチャは `WS_CallbackIOSend` 型で示されます。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - コンテキストの送信コールバックとして登録する関数 + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_SetIORecv()` + +### wolfSSH_SetIOReadCtx() + + +```c +#include + +void wolfSSH_SetIOReadCtx(WOLFSSH* ssh, void* ctx); +``` + +**説明** + +セッションの受信（I/O 読み取り）コールバックに渡されるコンテキストを登録します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - セッションの受信コールバックに登録するコンテキスト + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_GetIOReadCtx()` + +### wolfSSH_SetIOWriteCtx() + + +```c +#include + +void wolfSSH_SetIOWriteCtx(WOLFSSH* ssh, void* ctx); +``` + +**説明** + +セッションの送信（I/O 書き込み）コールバックに渡されるコンテキストを登録します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - セッションの送信コールバックに登録するコンテキスト + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_GetIOWriteCtx()` + +### wolfSSH_GetIOReadCtx() + + +```c +#include + +void* wolfSSH_GetIOReadCtx(WOLFSSH* ssh); +``` + +**説明** + +セッションの受信（I/O 読み取り）コールバックに以前登録されたコンテキストを返します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- 登録された読み取りコンテキストへのポインター。登録されていない場合は `NULL` + +**関連項目** + +- `wolfSSH_SetIOReadCtx()` + +### wolfSSH_GetIOWriteCtx() + + +```c +#include + +void* wolfSSH_GetIOWriteCtx(WOLFSSH* ssh); +``` + +**説明** + +セッションの送信（I/O 書き込み）コールバックに以前登録されたコンテキストを返します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- 登録された書き込みコンテキストへのポインター。登録されていない場合は `NULL` + +**関連項目** + +- `wolfSSH_SetIOWriteCtx()` + +## ユーザー認証 + + + +### wolfSSH_SetUserAuth() + + +```c +#include + +void wolfSSH_SetUserAuth(WOLFSSH_CTX* ctx, WS_CallbackUserAuth cb); +``` + +**説明** + +wolfSSH コンテキストにユーザー認証コールバックを登録します。このコールバックはハンドシェイク中にピアを認証するために呼び出されます。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - ユーザー認証コールバック関数 + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_SetUserAuthCtx()` + +### wolfSSH_SetUserAuthCtx() + + +```c +#include + +void wolfSSH_SetUserAuthCtx(WOLFSSH* ssh, void* userAuthCtx); +``` + +**説明** + +ユーザー認証コールバックに渡されるユーザーコンテキストポインターを設定します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `userAuthCtx` - 認証コールバックに渡すユーザーコンテキストポインター + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_GetUserAuthCtx()` + +### wolfSSH_GetUserAuthCtx() + + +```c +#include + +void* wolfSSH_GetUserAuthCtx(WOLFSSH* ssh); +``` + +**説明** + +wolfSSH_SetUserAuthCtx() によって以前設定されたユーザーコンテキストポインターを返します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- ユーザー認証コンテキストポインター +- `NULL` - `ssh` が NULL の場合 + +**関連項目** + +- `wolfSSH_SetUserAuthCtx()` + +### wolfSSH_SetUserAuthTypes() + +```c +#include + +void wolfSSH_SetUserAuthTypes(WOLFSSH_CTX* ctx, WS_CallbackUserAuthTypes cb); +``` + +**説明** + +サーバーが提供するユーザー認証タイプを報告するコールバックを登録します。このコールバックは `WOLFSSH_USERAUTH_*` の値（例えば `WOLFSSH_USERAUTH_PASSWORD` や `WOLFSSH_USERAUTH_PUBLICKEY`）のビットマスクを返します。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - ユーザー認証タイプコールバック + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_SetUserAuth()` + +### wolfSSH_SetUserAuthResult() + +```c +#include + +void wolfSSH_SetUserAuthResult(WOLFSSH_CTX* ctx, WS_CallbackUserAuthResult cb); +``` + +**説明** + +ユーザー認証試行の結果とともに呼び出されるコールバックを登録します。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - ユーザー認証結果コールバック + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_SetUserAuthResultCtx()` + +### wolfSSH_SetUserAuthResultCtx() + +```c +#include + +void wolfSSH_SetUserAuthResultCtx(WOLFSSH* ssh, void* userAuthResultCtx); +``` + +**説明** + +ユーザー認証結果コールバックに渡されるユーザーコンテキストポインターを設定します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `userAuthResultCtx` - 結果コールバックに渡すユーザーコンテキストポインター + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_GetUserAuthResultCtx()` + +### wolfSSH_GetUserAuthResultCtx() + +```c +#include + +void* wolfSSH_GetUserAuthResultCtx(WOLFSSH* ssh); +``` + +**説明** + +wolfSSH_SetUserAuthResultCtx() によって以前設定されたユーザーコンテキストポインターを返します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- ユーザー認証結果コンテキストポインター +- `NULL` - `ssh` が NULL の場合 + +**関連項目** + +- `wolfSSH_SetUserAuthResultCtx()` + +### wolfSSH_CTX_SetPublicKeyCheck() + +```c +#include + +void wolfSSH_CTX_SetPublicKeyCheck(WOLFSSH_CTX* ctx, + WS_CallbackPublicKeyCheck cb); +``` + +**説明** + +クライアント側で、ハンドシェイクを続行する前にサーバーの公開鍵（ホスト鍵）を確認するために使用されるコールバックを登録します。アプリケーションはこのコールバックから鍵を受け入れるか拒否するかを判断できます。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - 公開鍵確認コールバック + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_SetPublicKeyCheckCtx()` + +### wolfSSH_SetPublicKeyCheckCtx() + +```c +#include + +void wolfSSH_SetPublicKeyCheckCtx(WOLFSSH* ssh, void* publicKeyCheckCtx); +``` + +**説明** + +公開鍵確認コールバックに渡されるユーザーコンテキストポインターを設定します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `publicKeyCheckCtx` - コールバックに渡すユーザーコンテキストポインター + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_GetPublicKeyCheckCtx()` + +### wolfSSH_GetPublicKeyCheckCtx() + +```c +#include + +void* wolfSSH_GetPublicKeyCheckCtx(WOLFSSH* ssh); +``` + +**説明** + +wolfSSH_SetPublicKeyCheckCtx() によって以前設定されたユーザーコンテキストポインターを返します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- 公開鍵確認コンテキストポインター +- `NULL` - `ssh` が NULL の場合 + +**関連項目** + +- `wolfSSH_SetPublicKeyCheckCtx()` + +## ユーザー名の設定 + + + +### wolfSSH_SetUsername() + + +```c +#include + +int wolfSSH_SetUsername(WOLFSSH* ssh, const char* username); +``` + +**説明** + +SSH 接続に使用するユーザー名を NULL 終端の文字列として設定します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `username` - SSH 接続に使用するユーザー名 + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` + +**関連項目** + +- `wolfSSH_GetUsername()` + +### wolfSSH_SetUsernameRaw() + +```c +#include + +int wolfSSH_SetUsernameRaw(WOLFSSH* ssh, const byte* username, + word32 usernameSz); +``` + +**説明** + +SSH 接続に使用するユーザー名を、NULL 終端の文字列ではなくバッファと長さから設定します。ユーザー名が NULL 終端でない場合や任意のバイト列を含む場合に有用です。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `username` - ユーザー名を含むバッファ +- `usernameSz` - ユーザー名バッファの長さ + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` + +**関連項目** + +- `wolfSSH_SetUsername()` + +### wolfSSH_GetUsername() + +```c +#include + +char* wolfSSH_GetUsername(WOLFSSH* ssh); +``` + +**説明** + +セッションに関連付けられたユーザー名を返します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- セッションのユーザー名文字列へのポインター +- `NULL` - `ssh` が NULL の場合、またはユーザー名が設定されていない場合 + +**関連項目** + +- `wolfSSH_SetUsername()` + +## 接続関数 + +### wolfSSH_accept() + + + +```c +#include + +int wolfSSH_accept(WOLFSSH* ssh); +``` + +**説明** + +サーバー側で呼び出す。SSH クライアントが SSH ハンドシェイクを開始するのを待ち、それを完了させる。 + +wolfSSH_accept() はブロッキング I/O・ノンブロッキング I/O のいずれとも併用できる。基盤となる I/O がノンブロッキングの場合、wolfSSH_accept() はハンドシェイクをまだ満たせない時点で戻り、続けて wolfSSH_get_error() を呼び出すと `WS_WANT_READ` または `WS_WANT_WRITE` が得られる。呼び出し側はデータが利用可能になった時点で再度呼び出すことで、wolfSSH は中断した箇所から処理を再開する。 + +基盤となる I/O がブロッキングの場合、wolfSSH_accept() はハンドシェイクが完了するかエラーが発生するまで戻らない。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` + +**関連項目** + +- `wolfSSH_connect()` +- `wolfSSH_stream_read()` + +### wolfSSH_connect() + + +```c +#include + +int wolfSSH_connect(WOLFSSH* ssh); +``` + +**説明** + +クライアント側で呼び出す。サーバーとの SSH ハンドシェイクを開始する。この呼び出しの前に、基盤となる通信チャネルがセットアップ済みである必要がある。 + +wolfSSH_connect() はブロッキング I/O・ノンブロッキング I/O のいずれとも併用できる。基盤となる I/O がノンブロッキングの場合、wolfSSH_connect() はハンドシェイクをまだ満たせない時点で戻り、続けて wolfSSH_get_error() を呼び出すと `WS_WANT_READ` または `WS_WANT_WRITE` が得られる。呼び出し側は I/O が準備できた時点で再度呼び出すことで、wolfSSH は中断した箇所から処理を再開する。 + +基盤となる I/O がブロッキングの場合、wolfSSH_connect() はハンドシェイクが完了するかエラーが発生するまで戻らない。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` + +**関連項目** + +- `wolfSSH_accept()` + +### wolfSSH_shutdown() + + +```c +#include + +int wolfSSH_shutdown(WOLFSSH* ssh); +``` + +**説明** + +SSH セッションを閉じて切断し、ピアに切断メッセージを送信する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**関連項目** + +- `wolfSSH_connect()` +- `wolfSSH_accept()` + +### wolfSSH_stream_read() + + + +```c +#include + +int wolfSSH_stream_read(WOLFSSH* ssh, byte* buf, word32 bufSz); +``` + +**説明** + +内部の復号化済みデータストリームバッファから最大 `bufSz` バイトを読み取る。読み取られたバイトは内部バッファから取り除かれる。 + +wolfSSH_stream_read() はブロッキング I/O・ノンブロッキング I/O のいずれとも併用できる。基盤となる I/O がノンブロッキングで読み取りを満たせない場合、wolfSSH_get_error() を呼び出すと `WS_WANT_READ` または `WS_WANT_WRITE` が得られ、呼び出し側はデータが利用可能になった時点で再度呼び出す。基盤となる I/O がブロッキングの場合、データが利用可能になるかエラーが発生するまで戻らない。リキー（`WS_REKEYING`）が進行中の場合は、wolfSSH_worker() を呼び出してそれを完了させる。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `buf` - データを格納するバッファ +- `bufSz` - バッファのサイズ + +**戻り値** + +- 0 より大きい値 - 成功時に読み取ったバイト数 +- 0 - 接続がシャットダウンされた +- `WS_BAD_ARGUMENT` +- `WS_EOF` +- `WS_FATAL_ERROR` +- `WS_REKEYING` + +**関連項目** + +- `wolfSSH_stream_send()` +- `wolfSSH_accept()` + + +### wolfSSH_stream_send() + + + +```c +#include + +int wolfSSH_stream_send(WOLFSSH* ssh, byte* buf, word32 bufSz); +``` + +**説明** + +`buf` から `bufSz` バイトを SSH ストリームデータバッファに書き込む。 + +wolfSSH_stream_send() はブロッキング I/O・ノンブロッキング I/O のいずれとも併用できる。基盤となる I/O がノンブロッキングで保留中のデータすべてを送信できない場合、wolfSSH_get_error() を呼び出すと `WS_WANT_READ` または `WS_WANT_WRITE` が得られ、呼び出し側はソケットが送信可能になった時点で再度呼び出す。基盤となる I/O がブロッキングの場合、データの送信が完了するかエラーが発生するまで戻らない。エラーが want-read/want-write でない場合（例えば `WS_REKEYING`）は、内部の SSH 処理が完了するまで wolfSSH_worker() を呼び出す。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `buf` - 送信するバッファ +- `bufSz` - バッファのサイズ + +**戻り値** + +- 0 より大きい値 - 成功時に書き込んだバイト数 +- 0 - 接続がシャットダウンされた +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` +- `WS_REKEYING` + +**関連項目** + +- `wolfSSH_stream_read()` +- `wolfSSH_accept()` + + +### wolfSSH_stream_exit() + + +```c +#include + +int wolfSSH_stream_exit(WOLFSSH* ssh, int status); +``` + +**説明** + +SSH ストリームを終了し、指定した終了ステータスをピアに送信してチャネルを閉じる。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `status` - ピアに報告する終了ステータス + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**関連項目** + +- `wolfSSH_stream_send()` + +### wolfSSH_TriggerKeyExchange() + + +```c +#include + +int wolfSSH_TriggerKeyExchange(WOLFSSH* ssh); +``` + +**説明** + +初期ハンドシェイクパケットを準備・送信することで、鍵交換（リキー）プロセスを開始する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**関連項目** + +- `wolfSSH_worker()` + +### wolfSSH_stream_peek() + +```c +#include + +int wolfSSH_stream_peek(WOLFSSH* ssh, byte* buf, word32 bufSz); +``` + +**説明** + +内部バッファから取り除くことなく、保留中の復号化済みストリームデータを最大 `bufSz` バイトまで `buf` にコピーする。その後 wolfSSH_stream_read() を呼び出すと同じデータが返される。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `buf` - 覗き見したデータを格納するバッファ +- `bufSz` - バッファのサイズ + +**戻り値** + +- 0 以上の値 - コピーされたバイト数 +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` + +**関連項目** + +- `wolfSSH_stream_read()` + +### wolfSSH_extended_data_send() + +```c +#include + +int wolfSSH_extended_data_send(WOLFSSH* ssh, byte* buf, word32 bufSz); +``` + +**説明** + +`bufSz` バイトを拡張チャネルデータ（通常は stderr データ型）として送信する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `buf` - 送信するバッファ +- `bufSz` - バッファのサイズ + +**戻り値** + +- 0 より大きい値 - 成功時に送信したバイト数 +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` + +**関連項目** + +- `wolfSSH_extended_data_read()` + +### wolfSSH_extended_data_read() + +```c +#include + +int wolfSSH_extended_data_read(WOLFSSH* ssh, byte* out, word32 outSz); +``` + +**説明** + +受信した拡張チャネルデータ（通常は stderr）を最大 `outSz` バイトまで `out` に読み取る。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `out` - データを格納するバッファ +- `outSz` - バッファのサイズ + +**戻り値** + +- 0 以上の値 - 読み取ったバイト数 +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` + +**関連項目** + +- `wolfSSH_extended_data_send()` + +### wolfSSH_SendIgnore() + +```c +#include + +int wolfSSH_SendIgnore(WOLFSSH* ssh, const byte* buf, word32 bufSz); +``` + +**説明** + +指定したペイロードを含む SSH_MSG_IGNORE メッセージを送信する。ピアはその内容を破棄する。キープアライブやトラフィック解析対策として使用できる。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `buf` - メッセージに含めるペイロード +- `bufSz` - ペイロードのサイズ + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_SendDisconnect() + +```c +#include + +int wolfSSH_SendDisconnect(WOLFSSH* ssh, word32 reason); +``` + +**説明** + +指定した理由コード（`WS_DisconnectReasonCodes` の値を参照）を伴う SSH_MSG_DISCONNECT メッセージをピアに送信する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `reason` - 切断理由コード + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**関連項目** + +- `wolfSSH_shutdown()` + +### wolfSSH_global_request() + +```c +#include + +int wolfSSH_global_request(WOLFSSH* ssh, const unsigned char* data, + word32 dataSz, int reply); +``` + +**説明** + +指定したデータを含むグローバルリクエストをピアに送信する。`reply` が非ゼロの場合、ピアに成功または失敗の応答を要求する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `data` - リクエストのペイロード +- `dataSz` - ペイロードのサイズ +- `reply` - ピアからの応答を要求する場合は非ゼロ + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` + +### wolfSSH_ChannelIdRead() + +```c +#include + +int wolfSSH_ChannelIdRead(WOLFSSH* ssh, word32 channelId, + byte* buf, word32 bufSz); +``` + +**説明** + +`channelId` で識別されるチャネルから受信したデータを最大 `bufSz` バイトまで読み取る。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `channelId` - 読み取り対象のチャネル +- `buf` - データを格納するバッファ +- `bufSz` - バッファのサイズ + +**戻り値** + +- 0 以上の値 - 読み取ったバイト数 +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` + +**関連項目** + +- `wolfSSH_ChannelIdSend()` + +### wolfSSH_ChannelIdSend() + +```c +#include + +int wolfSSH_ChannelIdSend(WOLFSSH* ssh, word32 channelId, + byte* buf, word32 bufSz); +``` + +**説明** + +`channelId` で識別されるチャネル上で `bufSz` バイトを送信する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `channelId` - 送信対象のチャネル +- `buf` - 送信するバッファ +- `bufSz` - バッファのサイズ + +**戻り値** + +- 0 より大きい値 - 成功時に送信したバイト数 +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` + +**関連項目** + +- `wolfSSH_ChannelIdRead()` + +### wolfSSH_CTX_SetSshProtoIdStr() + +```c +#include + +int wolfSSH_CTX_SetSshProtoIdStr(WOLFSSH_CTX* ctx, const char* protoIdStr); +``` + +**説明** + +接続開始時のバージョン交換でピアに送信される SSH プロトコル識別文字列を上書きする。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `protoIdStr` - 送信するプロトコル識別文字列 + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_CTX_SetWindowPacketSize() + +```c +#include + +int wolfSSH_CTX_SetWindowPacketSize(WOLFSSH_CTX* ctx, + word32 windowSz, word32 maxPacketSz); +``` + +**説明** + +このコンテキストから作成されるセッションに対する、デフォルトのチャネルウィンドウサイズと最大パケットサイズを設定する。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `windowSz` - チャネルウィンドウサイズ（バイト単位） +- `maxPacketSz` - 最大パケットサイズ（バイト単位） + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +## チャネルコールバック + +wolfSSH ライブラリへのインターフェースは単一の int 値を返す。ピアがチャネルを開くといった非同期な情報の状態を伝えるには、このインターフェースでは不十分である。wolfSSH は、チャネルの状態変化を呼び出し元アプリケーションに通知するためにコールバック関数を使用する。 + +以下の SSHv2 プロトコルメッセージの受信に対応するコールバック関数が存在する。 + +* SSH_MSG_CHANNEL_OPEN +* SSH_MSG_CHANNEL_OPEN_CONFIRMATION +* SSH_MSG_CHANNEL_OPEN_FAILURE +* SSH_MSG_CHANNEL_REQUEST + - "shell" + - "subsystem" + - "exec" +* SSH_MSG_CHANNEL_EOF +* SSH_MSG_CHANNEL_CLOSE + +### コールバック関数のプロトタイプ + +チャネルコールバック関数はいずれも、**WOLFSSH_CHANNEL** オブジェクトへのポインター _channel_ と、アプリケーションが定義したデータ構造へのポインター _ctx_ を引数に取る。チャネルに関するプロパティは API 関数を使って取得できる。 + +``` +typedef int (*WS_CallbackChannelOpen)(WOLFSSH_CHANNEL* channel, void* ctx); +typedef int (*WS_CallbackChannelReq)(WOLFSSH_CHANNEL* channel, void* ctx); +typedef int (*WS_CallbackChannelEof)(WOLFSSH_CHANNEL* channel, void* ctx); +typedef int (*WS_CallbackChannelClose)(WOLFSSH_CHANNEL* channel, void* ctx); +``` + +### wolfSSH_CTX_SetChannelOpenCb() + +```c +#include + +int wolfSSH_CTX_SetChannelOpenCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelOpen cb); +``` + +**説明** + +ピアからチャネルオープン（SSH_MSG_CHANNEL_OPEN）メッセージを受信した際に呼び出されるコールバックを設定する。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - チャネルオープンコールバック + +**戻り値** + +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` + +**関連項目** + +- `wolfSSH_SetChannelOpenCtx()` + + +### wolfSSH_CTX_SetChannelOpenRespCb() + +```c +#include + +int wolfSSH_CTX_SetChannelOpenRespCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelOpen confCb, WS_CallbackChannelOpen failCb); +``` + +**説明** + +ピアからチャネルオープン確認（SSH_MSG_CHANNEL_OPEN_CONFIRMATION）またはチャネルオープン失敗（SSH_MSG_CHANNEL_OPEN_FAILURE）メッセージを受信した際に呼び出されるコールバックを設定する。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `confCb` - チャネルオープン確認のコールバック +- `failCb` - チャネルオープン失敗のコールバック + +**戻り値** + +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` + +**関連項目** + +- `wolfSSH_CTX_SetChannelOpenCb()` + + +### wolfSSH_CTX_SetChannelReqShellCb() + +```c +#include + +int wolfSSH_CTX_SetChannelReqShellCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelReq cb); +``` + +**説明** + +ピアから _shell_ に対するチャネルリクエスト（SSH_MSG_CHANNEL_REQUEST）メッセージを受信した際に呼び出されるコールバックを設定する。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - チャネルリクエストコールバック + +**戻り値** + +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` + +**関連項目** + +- `wolfSSH_CTX_SetChannelReqExecCb()` + + +### wolfSSH_CTX_SetChannelReqSubsysCb() + +```c +#include + +int wolfSSH_CTX_SetChannelReqSubsysCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelReq cb); +``` + +**説明** + +ピアから _subsystem_ に対するチャネルリクエスト（SSH_MSG_CHANNEL_REQUEST）メッセージを受信した際に呼び出されるコールバックを設定する。サブシステムの一般的な例としては SFTP がある。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - チャネルリクエストコールバック + +**戻り値** + +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` + +**関連項目** + +- `wolfSSH_CTX_SetChannelReqShellCb()` + + +### wolfSSH_CTX_SetChannelReqExecCb() + +```c +#include + +int wolfSSH_CTX_SetChannelReqExecCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelReq cb); +``` + +**説明** + +ピアから _exec_ するコマンドに対するチャネルリクエスト（SSH_MSG_CHANNEL_REQUEST）メッセージを受信した際に呼び出されるコールバックを設定する。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - チャネルリクエストコールバック + +**戻り値** + +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` + +**関連項目** + +- `wolfSSH_CTX_SetChannelReqShellCb()` + + +### wolfSSH_CTX_SetChannelEofCb() + +```c +#include + +int wolfSSH_CTX_SetChannelEofCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelEof cb); +``` + +**説明** + +ピアからチャネル EOF（SSH_MSG_CHANNEL_EOF）メッセージを受信した際に呼び出されるコールバックを設定する。これはピアがこのチャネル上でこれ以上データを送信しないことを示す。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - チャネル EOF コールバック + +**戻り値** + +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` + +**関連項目** + +- `wolfSSH_CTX_SetChannelCloseCb()` + + +### wolfSSH_CTX_SetChannelCloseCb() + +```c +#include + +int wolfSSH_CTX_SetChannelCloseCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelClose cb); +``` + +**説明** + +ピアからチャネルクローズ（SSH_MSG_CHANNEL_CLOSE）メッセージを受信した際に呼び出されるコールバックを設定する。これはピアがこのチャネルを終了させたいことを示す。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - チャネルクローズコールバック + +**戻り値** + +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` + +**関連項目** + +- `wolfSSH_CTX_SetChannelEofCb()` + + +### wolfSSH_SetChannelOpenCtx() + +```c +#include + +int wolfSSH_SetChannelOpenCtx(WOLFSSH* ssh, void* ctx); +``` + +**説明** + +チャネルオープン、チャネルオープン確認、およびチャネルオープン失敗の各コールバックに渡されるユーザーコンテキストを設定する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - チャネルオープンコールバックに渡すユーザーコンテキスト + +**戻り値** + +- `WS_SUCCESS` +- `WS_SSH_NULL_E` + +**関連項目** + +- `wolfSSH_GetChannelOpenCtx()` + + +### wolfSSH_SetChannelReqCtx() + +```c +#include + +int wolfSSH_SetChannelReqCtx(WOLFSSH* ssh, void* ctx); +``` + +**説明** + +チャネルリクエスト（shell/exec/subsystem）コールバックに渡されるユーザーコンテキストを設定する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - チャネルリクエストコールバックに渡すユーザーコンテキスト + +**戻り値** + +- `WS_SUCCESS` +- `WS_SSH_NULL_E` + +**関連項目** + +- `wolfSSH_GetChannelReqCtx()` + + +### wolfSSH_SetChannelEofCtx() + +```c +#include + +int wolfSSH_SetChannelEofCtx(WOLFSSH* ssh, void* ctx); +``` + +**説明** + +チャネル EOF コールバックに渡されるユーザーコンテキストを設定する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - チャネル EOF コールバックに渡すユーザーコンテキスト + +**戻り値** + +- `WS_SUCCESS` +- `WS_SSH_NULL_E` + +**関連項目** + +- `wolfSSH_GetChannelEofCtx()` + + +### wolfSSH_SetChannelCloseCtx() + +```c +#include + +int wolfSSH_SetChannelCloseCtx(WOLFSSH* ssh, void* ctx); +``` + +**説明** + +チャネルクローズコールバックに渡されるユーザーコンテキストを設定する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - チャネルクローズコールバックに渡すユーザーコンテキスト + +**戻り値** + +- `WS_SUCCESS` +- `WS_SSH_NULL_E` + +**関連項目** + +- `wolfSSH_GetChannelCloseCtx()` + + +### wolfSSH_GetChannelOpenCtx() + +```c +#include + +void* wolfSSH_GetChannelOpenCtx(WOLFSSH* ssh); +``` + +**説明** + +wolfSSH_SetChannelOpenCtx() によって以前に設定された、チャネルオープンコールバック用のユーザーコンテキストを返す。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- チャネルオープンコンテキストへのポインター。設定されていない場合は `NULL` + +**関連項目** + +- `wolfSSH_SetChannelOpenCtx()` + + +### wolfSSH_GetChannelReqCtx() + +```c +#include + +void* wolfSSH_GetChannelReqCtx(WOLFSSH* ssh); +``` + +**説明** + +wolfSSH_SetChannelReqCtx() によって以前に設定された、チャネルリクエストコールバック用のユーザーコンテキストを返す。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- チャネルリクエストコンテキストへのポインター。設定されていない場合は `NULL` + +**関連項目** + +- `wolfSSH_SetChannelReqCtx()` + + +### wolfSSH_GetChannelEofCtx() + +```c +#include + +void* wolfSSH_GetChannelEofCtx(WOLFSSH* ssh); +``` + +**説明** + +wolfSSH_SetChannelEofCtx() によって以前に設定された、チャネル EOF コールバック用のユーザーコンテキストを返す。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- チャネル EOF コンテキストへのポインター。設定されていない場合は `NULL` + +**関連項目** + +- `wolfSSH_SetChannelEofCtx()` + + +### wolfSSH_GetChannelCloseCtx() + +```c +#include + +void* wolfSSH_GetChannelCloseCtx(WOLFSSH* ssh); +``` + +**説明** + +wolfSSH_SetChannelCloseCtx() によって以前に設定された、チャネルクローズコールバック用のユーザーコンテキストを返す。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- チャネルクローズコンテキストへのポインター。設定されていない場合は `NULL` + +**関連項目** + +- `wolfSSH_SetChannelCloseCtx()` + + +## チャネル関数 + +これらの関数は、SSH セッション上で多重化される個々のチャネルを表す `WOLFSSH_CHANNEL` オブジェクトに対して直接操作を行う。 + +### wolfSSH_ChannelGetSessionType() + +```c +#include + +WS_SessionType wolfSSH_ChannelGetSessionType(const WOLFSSH_CHANNEL* channel); +``` + +**説明** + +指定したチャネルの `WS_SessionType`（shell、exec、subsystem、terminal、または unknown）を返す。 + +**引数** + +- `channel` - チャネルへのポインター + +**戻り値** + +- チャネルの `WS_SessionType` + +**関連項目** + +- `wolfSSH_ChannelGetSessionCommand()` + + +### wolfSSH_ChannelGetSessionCommand() + +```c +#include + +const char* wolfSSH_ChannelGetSessionCommand(const WOLFSSH_CHANNEL* channel); +``` + +**説明** + +指定したチャネル上でピアが実行を要求したコマンド（"exec" リクエストの場合）を返す。 + +**引数** + +- `channel` - チャネルへのポインター + +**戻り値** + +- コマンド文字列へのポインター。存在しない場合は `NULL` + +**関連項目** + +- `wolfSSH_ChannelGetSessionType()` + +### wolfSSH_ChannelFree() + +```c +#include + +int wolfSSH_ChannelFree(WOLFSSH_CHANNEL* channel); +``` + +**説明** + +チャネルオブジェクトを解放し、そのセッションから削除する。 + +**引数** + +- `channel` - 解放するチャネルへのポインター + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_ChannelGetId() + +```c +#include + +int wolfSSH_ChannelGetId(WOLFSSH_CHANNEL* channel, word32* id, byte peer); +``` + +**説明** + +指定したチャネルの数値チャネル ID を取得する。`peer` に `WS_CHANNEL_ID_SELF` を指定すると自分側の ID、`WS_CHANNEL_ID_PEER` を指定するとピア側の ID が取得される。 + +**引数** + +- `channel` - チャネルへのポインター +- `id` - チャネル ID の出力先 +- `peer` - `WS_CHANNEL_ID_SELF` または `WS_CHANNEL_ID_PEER` + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**関連項目** + +- `wolfSSH_ChannelFind()` -``` +### wolfSSH_ChannelFind() + +```c #include -int wolfSSH_get_error(const WOLFSSH* ssh ); + +WOLFSSH_CHANNEL* wolfSSH_ChannelFind(WOLFSSH* ssh, word32 id, byte peer); ``` -**関連項目** +**説明** + +指定した ID に一致するセッション上のチャネルを検索する。`peer` に `WS_CHANNEL_ID_SELF` を指定すると自分側の ID に、`WS_CHANNEL_ID_PEER` を指定するとピア側の ID に一致するものが検索される。 -wolfSSH_get_error_name() +**引数** +- `ssh` - wolfSSH セッションへのポインター +- `id` - 検索するチャネル ID +- `peer` - `WS_CHANNEL_ID_SELF` または `WS_CHANNEL_ID_PEER` -### wolfSSH_get_error_name() +**戻り値** + +- 一致したチャネルへのポインター。見つからない場合は `NULL` +**関連項目** + +- `wolfSSH_ChannelNext()` + +### wolfSSH_ChannelNext() +```c +#include -**用法** +WOLFSSH_CHANNEL* wolfSSH_ChannelNext(WOLFSSH* ssh, WOLFSSH_CHANNEL* channel); +``` **説明** -wolfSSHセッションオブジェクトにセットされたエラーの名前を返します。 +セッション上のチャネルを反復処理する。`channel` に `NULL` を渡すと最初のチャネルが取得され、あるチャネルを渡すとその次のチャネルが取得される。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `channel` - 現在のチャネル。反復を開始する場合は `NULL` **戻り値** -**const char*** – エラー名文字列
+- 次のチャネルへのポインター。リストの末尾に達した場合は `NULL` -**引数** +**関連項目** -**ssh** – WOLFSSHオブジェクトへのポインター +- `wolfSSH_ChannelFind()` +### wolfSSH_ChannelRead() -``` +```c #include -const char* wolfSSH_get_error_name(const WOLFSSH* ssh ); + +int wolfSSH_ChannelRead(WOLFSSH_CHANNEL* channel, byte* buf, word32 bufSz); ``` +**説明** + +指定したチャネルから受信済みデータを最大 `bufSz` バイト読み込む。 + +**引数** + +- `channel` - チャネルへのポインター +- `buf` - データを格納するバッファ +- `bufSz` - バッファのサイズ + +**戻り値** + +- 0 以上 - 読み込まれたバイト数 +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` + **関連項目** -wolfSSH_get_error() +- `wolfSSH_ChannelSend()` -### wolfSSH_ErrorToName() +### wolfSSH_ChannelSend() +```c +#include -**用法** +int wolfSSH_ChannelSend(WOLFSSH_CHANNEL* channel, const byte* buf, + word32 bufSz); +``` **説明** -引数で指定されたエラーコードに対応するエラーの名前を返します。 +指定したチャネル上で `bufSz` バイトを送信する。 + +**引数** +- `channel` - チャネルへのポインター +- `buf` - 送信するバッファ +- `bufSz` - バッファのサイズ **戻り値** -**const char*** – エラー名文字列
+- 0 より大きい値 - 成功時に送信されたバイト数 +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` -**引数** +**関連項目** -**err** - エラーコード +- `wolfSSH_ChannelRead()` -``` +### wolfSSH_ChannelExit() + +```c #include -const char* wolfSSH_ErrorToName(int err ); + +int wolfSSH_ChannelExit(WOLFSSH_CHANNEL* channel); ``` -## I/O コールバック関数 +**説明** +指定したチャネルを閉じ、EOF メッセージとクローズメッセージをピアへ送信する。 +**引数** -### wolfSSH_SetIORecv() +- `channel` - チャネルへのポインター +**戻り値** -**用法** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` -**説明** +### wolfSSH_ChannelGetEof() -入力データを受信する為の受信コールバック関数を登録します。 +```c +#include +int wolfSSH_ChannelGetEof(WOLFSSH_CHANNEL* channel); +``` -**戻り値** +**説明** -なし +指定したチャネル上でピアが EOF を送信済みかどうかを報告する。 **引数** -**ctx** – wolfSSHコンテキスト
+- `channel` - チャネルへのポインター + +**戻り値** -**cb** – wolfSSHコンテキストに関連つけられる、受信コールバック関数 +- 1 - チャネルが EOF を受信済み +- 0 - チャネルが EOF を受信していない -``` +### wolfSSH_ChannelGetType() + +```c #include -void wolfSSH_SetIORecv(WOLFSSH_CTX* ctx , WS_CallbackIORecv cb ); + +const char* wolfSSH_ChannelGetType(const WOLFSSH_CHANNEL* channel); ``` -### wolfSSH_SetIOSend() +**説明** +指定したチャネルのチャネルタイプ文字列（例: "session"）を返す。 -**用法** +**引数** + +- `channel` - チャネルへのポインター + +**戻り値** + +- チャネルタイプ文字列へのポインター。存在しない場合は `NULL` + +### wolfSSH_ChannelIsPty() + +```c +#include + +int wolfSSH_ChannelIsPty(const WOLFSSH_CHANNEL* channel); +``` **説明** -送信データを送信するための送信コールバック関数を登録します。 +指定したチャネルに疑似端末（PTY）が関連付けられているかどうかを報告する。 + +**引数** + +- `channel` - チャネルへのポインター **戻り値** -なし +- 1 - チャネルに PTY がある +- 0 - チャネルに PTY がない -**引数** -**ctx** – wolfSSHコンテキスト
+## テスト関数 -**cb** – wolfSSHコンテキストに関連つけられる、送信コールバック関数。 -``` -#include -void wolfSSH_SetIOSend(WOLFSSH_CTX* ctx , WS_CallbackIOSend cb ); -``` +### wolfSSH_GetStats() -### wolfSSH_SetIOReadCtx() +```c +#include -**用法** +void wolfSSH_GetStats(WOLFSSH* ssh, word32* txCount, word32* rxCount, + word32* seq, word32* peerSeq); +``` **説明** -受信コールバック関数に渡されるコンテキストを設定します +セッションの転送統計情報を、指定した出力先ポインターに書き込む。 + +**引数** +- `ssh` - wolfSSH セッションへのポインター +- `txCount` - セッションで送信された総バイト数の出力先 +- `rxCount` - セッションで受信された総バイト数の出力先 +- `seq` - 送信パケットのシーケンス番号の出力先 +- `peerSeq` - ピアのパケットシーケンス番号の出力先 **戻り値** なし -**引数** +### wolfSSH_KDF() -**ssh** – WOLFSSHオブジェクトへのポインター
-**ctx** – コンテキストへのポインター。受信コールバック関数に渡される +```c +#include +int wolfSSH_KDF(byte hashId, byte keyId, byte* key, word32 keySz, + const byte* k, word32 kSz, const byte* h, word32 hSz, + const byte* sessionId, word32 sessionIdSz); ``` -#include -void wolfSSH_SetIOReadCtx(WOLFSSH* ssh , void* ctx ); + +**説明** + +SSH 鍵導出関数を実行する。この関数は、鍵材料の元となる `k`（ディフィー・ヘルマン共有秘密）と `h`（鍵交換時に生成される交換ハッシュ）から対称鍵を導出する。生成される鍵の種類は `keyId` によって選択される。この関数は主に、テストスイートが鍵導出に対して既知の解答によるテストを実行できるように公開されている。 + +`keyId` の値は以下の通り。 + +``` +A - initial IV, client to server +B - initial IV, server to client +C - encryption key, client to server +D - encryption key, server to client +E - integrity key, client to server +F - integrity key, server to client ``` -### wolfSSH_SetIOWriteCtx() +**引数** + +- `hashId` - 鍵材料の導出に使用するハッシュタイプ（例: `WC_HASH_TYPE_SHA` や `WC_HASH_TYPE_SHA256`） +- `keyId` - どの鍵を導出するか（上記の A〜F） +- `key` - 導出された鍵の出力バッファ +- `keySz` - 出力鍵バッファのサイズ +- `k` - ディフィー・ヘルマン共有秘密 +- `kSz` - `k` のサイズ +- `h` - 交換ハッシュ +- `hSz` - `h` のサイズ +- `sessionId` - セッション識別子 +- `sessionIdSz` - セッション識別子のサイズ + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_CRYPTO_FAILED` +### wolfSSH_ShowSizes() -**用法** +```c +#include + +void wolfSSH_ShowSizes(void); +``` **説明** -送信コールバック関数に渡されるコンテキストを設定します +wolfSSH の内部データ構造体のサイズを表示する。これは診断用の補助機能であり、リソースに制約のあるターゲットでのメモリ使用量の調整に役立つ。 + +**引数** + +なし **戻り値** なし -**引数** -**ssh** – WOLFSSHオブジェクトへのポインター
+## セッション関数 -**ctx** – コンテキストへのポインター。送信コールバック関数に渡される -``` -#include -void wolfSSH_SetIOWriteCtx(WOLFSSH* ssh , void* ctx ); -``` -### wolfSSH_GetIOReadCtx() +### wolfSSH_GetSessionType() + +```c +#include -**用法** +WS_SessionType wolfSSH_GetSessionType(const WOLFSSH* ssh); +``` **説明** -WOLFSSHオブジェクトのioReadCtxメンバーを返します。 +セッションのチャネルにおけるセッションタイプを返す。`WOLFSSH_SESSION_UNKNOWN`、`WOLFSSH_SESSION_SHELL`、`WOLFSSH_SESSION_EXEC`、`WOLFSSH_SESSION_SUBSYSTEM`、`WOLFSSH_SESSION_TERMINAL` のいずれか。 +**引数** + +- `ssh` - wolfSSH セッションへのポインター **戻り値** -**void*** - WOLFSSHオブジェクトのioReadCtxメンバーへのポインター +- セッションの `WS_SessionType` -**引数** +**関連項目** -**ssh** – WOLFSSHオブジェクトへのポインター +- `wolfSSH_GetSessionCommand()` -``` -#include -void* wolfSSH_GetIOReadCtx(WOLFSSH* ssh ); -``` +### wolfSSH_GetSessionCommand() -### wolfSSH_GetIOWriteCtx() +```c +#include -**用法** +const char* wolfSSH_GetSessionCommand(const WOLFSSH* ssh); +``` **説明** -WOLFSSHオブジェクトのioWriteCtxメンバーを返します。 +このセッションについてピアが実行を要求したコマンド（"exec" リクエストの場合）を返す。 + +**引数** +- `ssh` - wolfSSH セッションへのポインター **戻り値** -**void*** – WOLFSSHオブジェクトのioWriteCtxメンバーへのポインター +- コマンド文字列へのポインター、存在しない場合は `NULL` -**引数** +**関連項目** -**ssh** – WOLFSSHオブジェクトへのポインター +- `wolfSSH_GetSessionType()` -``` +### wolfSSH_SetChannelType() + +```c #include -void* wolfSSH_GetIOWriteCtx(WOLFSSH* ssh); + +int wolfSSH_SetChannelType(WOLFSSH* ssh, byte type, byte* name, + word32 nameSz); ``` -## ユーザー認証 +**説明** + +セッションのチャネルに対して、チャネルリクエストタイプ（shell、exec、subsystem など）と、それに関連付ける任意の名前を設定する。 +**引数** +- `ssh` - wolfSSH セッションへのポインター +- `type` - チャネルリクエストタイプ +- `name` - タイプに関連付ける任意の名前（例えば subsystem 名） +- `nameSz` - `name` の長さ -### wolfSSH_SetUserAuth() +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +### wolfSSH_ChangeTerminalSize() + +```c +#include -**用法** +int wolfSSH_ChangeTerminalSize(WOLFSSH* ssh, word32 columns, + word32 rows, word32 widthPixels, word32 heightPixels); +``` **説明** +ターミナル（ウィンドウ）サイズが変更されたことをピアに通知し、新しい寸法を送信する。 -現在のWOLFSSL_CTXオブジェクトに対してユーザー認証コールバック関数を登録します。 +**引数** +- `ssh` - wolfSSH セッションへのポインター +- `columns` - 新しい幅（文字カラム数） +- `rows` - 新しい高さ（文字行数） +- `widthPixels` - 新しい幅（ピクセル数） +- `heightPixels` - 新しい高さ（ピクセル数） **戻り値** -なし +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` -**引数** +**関連項目** -**ctx** – WOLFSSH_CTXオブジェクトへのポインター
+- `wolfSSH_SetTerminalResizeCb()` -**cb** – ユーザー認証コールバック関数 +### wolfSSH_SetTerminalResizeCb() -``` +```c #include -void wolfSSH_SetUserAuth(WOLFSSH_CTX* ctx, WS_CallbackUserAuth cb) -``` -### wolfSSH_SetUserAuthCtx() +void wolfSSH_SetTerminalResizeCb(WOLFSSH* ssh, WS_CallbackTerminalSize cb); +``` +**説明** -**用法** +ピアがターミナルサイズの変更を報告した際に呼び出されるコールバックを登録する。 -**説明** +**引数** -ユーザー認証コールバック関数に渡されるコンテキストを登録します。 +- `ssh` - wolfSSH セッションへのポインター +- `cb` - ターミナルリサイズコールバック **戻り値** なし -**引数** +**関連項目** -**ssh** – WOLFSSHオブジェクトへのポインター
+- `wolfSSH_SetTerminalResizeCtx()` -**userAuthCtx** – ユーザー認証コールバック関数へ渡すコンテキスト +### wolfSSH_SetTerminalResizeCtx() -``` +```c #include -void wolfSSH_SetUserAuthCtx(WOLFSSH* ssh , void* userAuthCtx) + +void wolfSSH_SetTerminalResizeCtx(WOLFSSH* ssh, void* usrCtx); ``` -### wolfSSH_GetUserAuthCtx() +**説明** + +ターミナルリサイズコールバックに渡すユーザーコンテキストポインターを設定する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `usrCtx` - コールバックに渡すユーザーコンテキストポインター + +**戻り値** +なし + +### wolfSSH_GetExitStatus() + +```c +#include -**用法** +int wolfSSH_GetExitStatus(WOLFSSH* ssh); +``` **説明** -ユーザー認証コールバック関数に渡されるコンテキストを返します。 +セッションのコマンドについてピアが報告した終了ステータスを返す。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター **戻り値** -**void*** – ユーザー認証コールバック関数へ渡すコンテキスト
+- ピアが報告した終了ステータス -**NULL** – ssh引数がNULLの場合 +**関連項目** -**引数** +- `wolfSSH_SetExitStatus()` -**ssh** – pointer to WOLFSSH object +### wolfSSH_SetExitStatus() -``` +```c #include -void* wolfSSH_GetUserAuthCtx(WOLFSSH* ssh ) + +int wolfSSH_SetExitStatus(WOLFSSH* ssh, word32 exitStatus); ``` -## ユーザー名設定機能 +**説明** + +セッションのコマンドについてピアに報告する終了ステータスを設定する。 +**引数** +- `ssh` - wolfSSH セッションへのポインター +- `exitStatus` - 報告する終了ステータス -### wolfSSH_SetUsername() +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**関連項目** +- `wolfSSH_GetExitStatus()` -**用法** +### wolfSSH_DoModes() + +```c +#include + +int wolfSSH_DoModes(const byte* modes, word32 modesSz, int fd); +``` **説明** -SSHコネクションに必要なユーザー名を設定します。 +`modes` に含まれる SSH エンコード済みのターミナルモードを、ファイルディスクリプタ `fd` が参照するターミナルに適用する。 + +**引数** + +- `modes` - SSH エンコード済みターミナルモードのバッファ +- `modesSz` - modes バッファの長さ +- `fd` - 設定対象ターミナルのファイルディスクリプタ **戻り値** -WS_BAD_ARGUMENT
+- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_ConvertConsole() -WS_SUCCESS
+**利用可能性** -WS_MEMORY_E
+Windows ビルド（`USE_WINDOWS_API`）でのみ利用可能。 + +```c +#include + +int wolfSSH_ConvertConsole(WOLFSSH* ssh, WOLFSSH_HANDLE handle, + byte* buf, word32 bufSz); +``` + +**説明** + +Windows コンソールハンドルから読み取ったコンソールデータを処理し、SSH ストリーム用に変換する。 **引数** -**ssh** - WOLFSSHオブジェクトへのポインター
+- `ssh` - wolfSSH セッションへのポインター +- `handle` - Windows コンソールハンドル +- `buf` - 変換対象のコンソールデータバッファ +- `bufSz` - バッファの長さ + +**戻り値** -**username** - ユーザー名文字列 +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` -``` +### wolfSSH_SetKeyingCompletionCb() + +```c #include -int wolfSSH_setUsername(WOLFSSH* ssh , const char* username); + +void wolfSSH_SetKeyingCompletionCb(WOLFSSH_CTX* ctx, + WS_CallbackKeyingCompletion cb); ``` -## 接続機能 +**説明** -### wolfSSH_accept() +鍵交換（初回またはリキー）が完了した際に呼び出されるコールバックを登録する。 + +**引数** +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - キーイング完了コールバック +**戻り値** -**用法** +なし -**説明** +**関連項目** -wolfssh_acceptはサーバー側で呼び出され、SSHクライアントがSSHハンドシェイクを開始するのを待ちます。 +- `wolfSSH_SetKeyingCompletionCbCtx()` -wolfssl_accept()は、ブロッキングI/OノンブロッキングI/Oの両方で機能します。使用しているI/Oが非ブロッキングである場合、wolfSSH_accept()は、ハンドシェークが完了できなかった場合は即戻ります。この場合、wolfssh_get_error()を呼び出すと、**WS_WANT_READ** または**WS_WANT_WRITE**のいずれかが返されます。 +### wolfSSH_SetKeyingCompletionCbCtx() +```c +#include + +void wolfSSH_SetKeyingCompletionCbCtx(WOLFSSH* ssh, void* ctx); +``` -この場合呼び出し元は、読み取るべきデータを受信してwolfSSHが中断されたところからピックアップできるように、wolfSSH_acceptへの呼び出しを繰り返す必要があります。非ブロッキングソケットを使用する場合、何も実行する必要はありませんが、select()を使用して必要な条件を確認できます。 +**説明** +キーイング完了コールバックに渡すユーザーコンテキストポインターを設定する。 -使用しているI/Oがブロッキングの場合、wolfSSH_accept()は、ハンドシェークが終了したか、エラーが発生した場合にのみ戻ります。 +**引数** +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - コールバックに渡すユーザーコンテキストポインター **戻り値** -**WS_SUCCESS** - 成功
+なし + +### wolfSSH_RealPath() + +```c +#include + +int wolfSSH_RealPath(const char* defaultPath, char* in, + char* out, word32 outSz); +``` -**WS_BAD_ARGUMENT** - 引数がNULL
+**説明** -**WS_FATAL_ERROR** – エラーが発生した。wolfSSH_get_error()を呼び出して詳細を取得すべき +`defaultPath` を基準として、パス `in` を解決し、正規化された絶対パスを `out` に書き込む。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
+- `defaultPath` - 相対パスの `in` を解決する際の基準パス +- `in` - 解決対象のパス +- `out` - 解決されたパスを書き込むバッファ +- `outSz` - 出力バッファのサイズ -``` +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +## ポートフォワーディング関数 + + + +本セクションのすべての関数は、wolfSSH がポートフォワーディングサポート（`WOLFSSH_FWD`、`./configure --enable-fwd`）付きでビルドされていることを必要とする。 + +### wolfSSH_ChannelFwdNewLocal() + +```c #include -int wolfSSH_accept(WOLFSSH* ssh); + +WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNewLocal(WOLFSSH* ssh, + const char* host, word32 hostPort, + const char* origin, word32 originPort); ``` -**関連項目** +**説明** -wolfSSH_stream_read() +セッション上にローカル TCP/IP フォワーディングチャネルを設定する。セッションが接続および認証されると、接続は `hostPort` ポートの `host` へフォワードされ、送信元アドレス `origin` とポート `originPort` がタグ付けされる。 +**引数** -### wolfSSH_connect() +- `ssh` - wolfSSH セッションへのポインター +- `host` - 転送先ホストアドレス +- `hostPort` - 転送先ポート +- `origin` - 送信元接続アドレス +- `originPort` - 送信元接続ポート +**戻り値** + +- 新しいチャネルへのポインター、エラー時は `NULL` + +**関連項目** + +- `wolfSSH_ChannelFwdNewRemote()` + +### wolfSSH_ChannelFwdNewRemote() + +```c +#include -**用法** +WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNewRemote(WOLFSSH* ssh, + const char* host, word32 hostPort, + const char* origin, word32 originPort); +``` **説明** -この関数はクライアント側で呼び出されSSHハンドシェークをサーバーに対して開始します。 -この関数が呼び出される時点では下層の通信チャネルは接続が完了している必要があります。 +セッション上にリモート TCP/IP フォワーディングチャネルを設定し、ピアに対して `hostPort` ポートの `host` へ接続をフォワードするよう要求する。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `host` - 転送先ホストアドレス +- `hostPort` - 転送先ポート +- `origin` - 送信元接続アドレス +- `originPort` - 送信元接続ポート -wolfSSH_connect()関数はブロッキングとノンブロッキングI/Oの両方で動作できます。ノンブロッキングI/Oの場合にはハンドシェークが完了できなかった場合は即戻ります。この場合、wolfssh_get_error()を呼び出すと、**WS_WANT_READ** または**WS_WANT_WRITE**のいずれかが返されます。 +**戻り値** -この場合呼び出し元は、読み取るべきデータを受信してwolfSSHが中断されたところからピックアップできるように、wolfSSH_connectへの呼び出しを繰り返す必要があります。非ブロッキングソケットを使用する場合、何も実行する必要はありませんが、select()を使用して必要な条件を確認できます。 +- 新しいチャネルへのポインター、エラー時は `NULL` +**関連項目** -使用しているI/Oがブロッキングの場合、wolfSSH_accept()は、ハンドシェークが終了したか、エラーが発生した場合にのみ戻ります。 +- `wolfSSH_ChannelFwdNewLocal()` +### wolfSSH_CTX_SetFwdCb() -**戻り値** -**WS_SUCCESS** - 接続に成功
+```c +#include -**WS_BAD_ARGUMENT** - 引数がNULL
+int wolfSSH_CTX_SetFwdCb(WOLFSSH_CTX* ctx, + WS_CallbackFwd fwdCb, WS_CallbackFwdIO fwdIoCb); +``` -**WS_FATAL_ERROR** - エラーが発生した。wolfSSH_get_error()を呼び出して詳細を取得すべき +**説明** +コンテキストに対して、ポートフォワーディングのセットアップ／クリーンアップコールバック（`fwdCb`）とフォワーディング I/O コールバック（`fwdIoCb`）を登録する。 **引数** -**ssh** - WOLFSSHオブジェクトへのポインター
+- `ctx` - wolfSSH コンテキストへのポインター +- `fwdCb` - フォワーディングのセットアップ／クリーンアップコールバック +- `fwdIoCb` - フォワーディング I/O コールバック -``` -#include -int wolfSSH_connect(WOLFSSH* ssh); -``` +**戻り値** -### wolfSSH_shutdown() +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +**関連項目** -**用法** +- `wolfSSH_SetFwdCbCtx()` -**説明** +### wolfSSH_SetFwdCbCtx() -SSHチャネルの接続を終了してクローズします +```c +#include -**戻り値** +int wolfSSH_SetFwdCbCtx(WOLFSSH* ssh, void* ctx); +``` -**WS_BAD_ARGUMENT** - 引数がNULL
+**説明** -**WS_SUCCES** - 正常にシャットダウンが成功した +ポートフォワーディングコールバックに渡すユーザーコンテキストポインターを設定する。 **引数** -**ssh** - WOLFSSHオブジェクトへのポインター
+- `ssh` - wolfSSH セッションへのポインター +- `ctx` - フォワーディングコールバックに渡すユーザーコンテキストポインター -``` -#include -int wolfSSH_shutdown(WOLFSSH* ssh); -``` +**戻り値** -### wolfSSH_stream_read() +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +### wolfSSH_ChannelFwdNew() +```c +#include -**用法** +WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNew(WOLFSSH* ssh, + const char* host, word32 hostPort, + const char* origin, word32 originPort); +``` **説明** -wolfSSH_stream_read()は内部のバッファから復号済みデータを**bufSz**で指定されたバイト数まで読みだします。読み込まれたデータはバッファから取り除かれます。 - -wolfSSH_stream_read()はブロッキングとノンブロッキングI/Oの両方で動作できます。ノンブロッキングI/Oの場合にはハンドシェークが完了できなかった場合は即戻ります。この場合、wolfssh_get_error()を呼び出すと、**WS_WANT_READ** または**WS_WANT_WRITE**のいずれかが返されます。 +非推奨。`wolfSSH_ChannelFwdNewLocal()` を使用すること。この関数は後方互換性のために維持されており、内部でそちらへ処理を転送する。 -この場合呼び出し元は、読み取るべきデータを受信してwolfSSHが中断されたところからピックアップできるように、wolfSSH_stream_read()の呼び出しを繰り返す必要があります。非ブロッキングI/Oが使用されている場合、何も実行する必要はありませんが、select()を使用して必要な条件を確認できます。 +**引数** -ブロッキングI/Oが使用されている場合は、wolfSSH_stream_read()は、データがIsAbaibleまたはエラーが発生した場合にのみ戻ります。 +- `ssh` - wolfSSH セッションへのポインター +- `host` - 転送先ホストアドレス +- `hostPort` - 転送先ポート +- `origin` - 送信元接続アドレス +- `originPort` - 送信元接続ポート **戻り値** -**>0** – 読み取りに成功したバイト数
+- 新しいチャネルへのポインター、エラー時は `NULL` + +**関連項目** + +- `wolfSSH_ChannelFwdNewLocal()` -**0** – クリーンコネクションシャットダウンかソケットエラー
+### wolfSSH_ChannelSetFwdFd() -**WS_BAD_ARGUMENT** – 引数の一つがNULL
+```c +#include -**WS_EOF** – ストリームの終端に到達
+int wolfSSH_ChannelSetFwdFd(WOLFSSH_CHANNEL* channel, int fwdFd); +``` -**WS_FATAL_ERROR** – エラーが発生。**wolfSSH_get_error()** を呼び出して詳細を取得すべき
+**説明** -**WS_REKEYING** - リキーイング処理中。 wolfSSH_worker()を呼び出して完了させること +非推奨。フォワーディングチャネルにフォワーディング用ファイルディスクリプタを関連付ける。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
+- `channel` - フォワーディングチャネルへのポインター +- `fwdFd` - フォワーディング用ファイルディスクリプタ -**buf** – wolfSSH_stream_read()が読みだしたデータを格納するバッファへのポインター
+**戻り値** -**bufSz** – バッファサイズ +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +### wolfSSH_ChannelGetFwdFd() -``` +```c #include -int wolfSSH_stream_read(WOLFSSH* ssh, byte* buf, word32 bufSz); + +int wolfSSH_ChannelGetFwdFd(const WOLFSSH_CHANNEL* channel); ``` -**関連項目** +**説明** -wolfSSH_accept()
+非推奨。フォワーディングチャネルに関連付けられたフォワーディング用ファイルディスクリプタを返す。 -wolfSSH_stream_send() +**引数** +- `channel` - フォワーディングチャネルへのポインター -### wolfSSH_stream_send() +**戻り値** +- フォワーディング用ファイルディスクリプタ、または負のエラーコード -**用法** +## 鍵ロード関数 -**説明** -wolfSSH_stream_send()はバッファで与えたデータを**bufSz**で指定されたバイト数までSSHストリームデータバッファに書き込みます。 +### wolfSSH_ReadKey_buffer() + +```c +#include -wolfSSH_stream_send()はブロッキングとノンブロッキングI/Oの両方で動作できます。ノンブロッキングI/Oの場合にはハンドシェークが完了できなかった場合は即戻ります。この場合、wolfssh_get_error()を呼び出すと、**WS_WANT_READ** または**WS_WANT_WRITE**のいずれかが返されます。 +int wolfSSH_ReadKey_buffer(const byte* in, word32 inSz, + int format, byte** out, word32* outSz, + const byte** outType, word32* outTypeSz, + void* heap); +``` -この場合呼び出し元は、データの書き込みがペンディングされ、wolfSSHが中断されたところから書き込みを再開できるように、wolfSSH_stream_send()の呼び出しを繰り返す必要があります。非ブロッキングソケットを使用する場合、何も実行する必要はありませんが、select()を使用して必要な条件を確認できます。 +**説明** -ブロッキングI/Oが使用されている場合は、wolfSSH_stream_send()は、データが送信されたときかエラーが発生した時のみ戻ります。 +サイズ `inSz` のバッファ `in` から鍵を読み込み、`format` 型の鍵としてデコードする。`format` には `WOLFSSH_FORMAT_ASN1`、`WOLFSSH_FORMAT_PEM`、`WOLFSSH_FORMAT_SSH`、または `WOLFSSH_FORMAT_OPENSSH` を指定できる。デコードされた鍵は、`wolfSSH_CTX_UsePrivateKey_buffer()` で利用できる形式で、`out` が指すバッファに格納され、そのサイズが `outSz` に格納される。`out` が NULL の場合、`heap` を使って鍵用のバッファが確保される。鍵種別文字列は `outType` に格納され、その長さが `outTypeSz` に格納される。 -WS_WANT_READ またはWS_WANT_WRITEのいずれもかえされていない場合(すなわち**WS_REKEYING**が返された場合）は、内部処理が終了するまでwolfSSH_worker()を呼び出し続ける必要があります。 +**引数** +- `in` - エンコードされた鍵を含むバッファ +- `inSz` - 入力バッファのサイズ +- `format` - 入力鍵のエンコーディング +- `out` - デコードされた鍵の出力バッファ（NULL の場合は `heap` から確保） +- `outSz` - デコードされた鍵サイズの出力先 +- `outType` - 鍵種別文字列の出力先 +- `outTypeSz` - 鍵種別文字列の長さの出力先 +- `heap` - `out` が NULL の場合に確保で使用されるヒープ **戻り値** -**>0** – SSHストリームバッファに書き込んだバイト数
+- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` +- `WS_BUFFER_E` +- `WS_PARSE_E` +- `WS_UNIMPLEMENTED_E` +- `WS_RSA_E` +- `WS_ECC_E` +- `WS_KEY_AUTH_MAGIC_E` +- `WS_KEY_FORMAT_E` +- `WS_KEY_CHECK_VAL_E` -**0** – クリーンコネクションシャットダウンかソケットエラー。 **wolfSSH_get_error()** を呼び出して詳細を取得すること
+**関連項目** -**WS_FATAL_ERROR** – エラーが発生。**wolfSSH_get_error()** を呼び出して詳細を取得すること
+- `wolfSSH_ReadKey_file()` -**WS_BAD_ARGUMENT** - 引数の一つがNULL
+### wolfSSH_ReadKey_buffer_ex() -**WS_REKEYING** - リキーイング処理中。 wolfSSH_worker()を呼び出して完了させること +```c +#include -**引数** +int wolfSSH_ReadKey_buffer_ex(const byte* in, word32 inSz, int format, + byte** out, word32* outSz, const byte** outType, word32* outTypeSz, + int isPrivate, void* heap); +``` -**ssh** – WOLFSSHオブジェクトへのポインター
+**説明** -**buf** – wolfSSH_stream_send()が送信するデータを格納するバッファへのポインター
+wolfSSH_ReadKey_buffer() と同様だが、バッファが秘密鍵か公開鍵かを推測するのではなく、明示的な `isPrivate` フラグで指定する。 -**bufSz** – size of the buffer
+**引数** -``` -#include -int wolfSSH_stream_send(WOLFSSH* ssh , byte* buf , word32　bufSz); -``` +- `in` - エンコードされた鍵を含むバッファ +- `inSz` - 入力バッファのサイズ +- `format` - 入力鍵のエンコーディング +- `out` - デコードされた鍵の出力バッファ（NULL の場合は `heap` から確保） +- `outSz` - デコードされた鍵サイズの出力先 +- `outType` - 鍵種別文字列の出力先 +- `outTypeSz` - 鍵種別文字列の長さの出力先 +- `isPrivate` - 鍵が秘密鍵の場合は非ゼロ、公開鍵の場合は 0 +- `heap` - `out` が NULL の場合に確保で使用されるヒープ +**戻り値** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` +- `WS_BUFFER_E` +- `WS_PARSE_E` +- `WS_UNIMPLEMENTED_E` **関連項目** -wolfSSH_accept()
+- `wolfSSH_ReadKey_buffer()` -wolfSSH_stream_read() - - -### wolfSSH_stream_exit() +### wolfSSH_ReadPublicKey_buffer() +```c +#include -**用法** +int wolfSSH_ReadPublicKey_buffer(const byte* in, word32 inSz, int format, + byte** out, word32* outSz, const byte** outType, word32* outTypeSz, + void* heap); +``` **説明** -SSHストリームを終了させます。 +バッファ `in` から公開鍵を読み込みデコードする。wolfSSH_ReadKey_buffer() と同様に動作するが、公開鍵専用である。 + +**引数** +- `in` - エンコードされた公開鍵を含むバッファ +- `inSz` - 入力バッファのサイズ +- `format` - 入力鍵のエンコーディング +- `out` - デコードされた鍵の出力バッファ（NULL の場合は `heap` から確保） +- `outSz` - デコードされた鍵サイズの出力先 +- `outType` - 鍵種別文字列の出力先 +- `outTypeSz` - 鍵種別文字列の長さの出力先 +- `heap` - `out` が NULL の場合に確保で使用されるヒープ **戻り値** -**WS_BAD_ARGUMENT** - 引数の一つがNULL
+- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` +- `WS_BUFFER_E` +- `WS_PARSE_E` +- `WS_UNIMPLEMENTED_E` -**WS_SUCCESS** - 成功 +**関連項目** -**引数** +- `wolfSSH_ReadKey_buffer()` -**ssh** – WOLFSSHオブジェクトへのポインター
-**status** – SSHコネクションの状態 +### wolfSSH_ReadKey_file() -``` +```c #include -int wolfSSH_stream_exit(WOLFSSH* ssh, int status); -``` -### wolfSSH_TriggerKeyExchange() - - -**用法** +int wolfSSH_ReadKey_file(const char* name, + byte** out, word32* outSz, + const byte** outType, word32* outTypeSz, + byte* isPrivate, void* heap); +``` **説明** -鍵交換処理を開始します。ハンドシェークに必要なパケットを用意して送信します。 +ファイル `name` から鍵を読み込む。フォーマットはファイル内容から推測される。鍵バッファ `out`、鍵種別 `outType`、およびそれぞれのサイズは wolfSSH_ReadKey_buffer() と同様に生成される。`isPrivate` フラグは、鍵が秘密鍵であるかどうかを示すよう設定される。確保処理には指定された `heap` が使用される。 +**引数** -**戻り値** - -**WS_BAD_ARGUEMENT** – 引数がNULL
+- `name` - 鍵ファイルへのパス +- `out` - デコードされた鍵の出力バッファ（NULL の場合は `heap` から確保） +- `outSz` - デコードされた鍵サイズの出力先 +- `outType` - 鍵種別文字列の出力先 +- `outTypeSz` - 鍵種別文字列の長さの出力先 +- `isPrivate` - 鍵が秘密鍵の場合に非ゼロが設定される出力 +- `heap` - `out` が NULL の場合に確保で使用されるヒープ -**WS_SUCCESS** - 成功 +**戻り値** -**引数** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_BAD_FILE_E` +- `WS_MEMORY_E` +- `WS_BUFFER_E` +- `WS_PARSE_E` +- `WS_UNIMPLEMENTED_E` +- `WS_RSA_E` +- `WS_ECC_E` +- `WS_KEY_AUTH_MAGIC_E` +- `WS_KEY_FORMAT_E` +- `WS_KEY_CHECK_VAL_E` -**ssh** – WOLFSSHオブジェクトへのポインター
+**関連項目** -``` -#include -int wolfSSH_TriggerKeyExchange(WOLFSSH* ssh ); -``` +- `wolfSSH_ReadKey_buffer()` -## テスト機能 +## 鍵交換アルゴリズムの設定 +wolfSSH は、使用している wolfCrypt ライブラリでのアルゴリズムの利用可否に基づいて、 +鍵交換 (KEX) 時に使用するアルゴリズムリストの集合をセットアップする。 -### wolfSSH_GetStats() +利用可能なアルゴリズムを確認するためのアクセサ関数と、KEX で使用されるアルゴリズムリストを +確認するためのアクセサ関数が用意されている。アクセサ関数は 4 つ 1 組で提供される。すなわち、 +CTX オブジェクトからの設定・取得、および SSH オブジェクトからの設定・取得である。CTX を使って +作成された SSH オブジェクトはすべて CTX のアルゴリズムリストを継承するが、独自のリストを +与えることもできる。 +デフォルトでは、SHA-1 を使用するアルゴリズムはすべて無効化されているが、以下のいずれかの +関数を使って再度有効化できる。wolfCrypt 側で SHA-1 が無効化されている場合、SHA-1 は使用できない。 -**用法** -**説明** +### wolfSSH アルゴリズムリストの設定 -**ssh**セッションに関連した、**txCount** , **rxCount** , **seq** , と **peerSeq** を更新します。 +```c +#include +int wolfSSH_CTX_SetAlgoListKex(WOLFSSH_CTX* ctx, const char* list); +int wolfSSH_CTX_SetAlgoListKey(WOLFSSH_CTX* ctx, const char* list); +int wolfSSH_CTX_SetAlgoListCipher(WOLFSSH_CTX* ctx, const char* list); +int wolfSSH_CTX_SetAlgoListMac(WOLFSSH_CTX* ctx, const char* list); +int wolfSSH_CTX_SetAlgoListKeyAccepted(WOLFSSH_CTX* ctx, const char* list); -**戻り値** +int wolfSSH_SetAlgoListKex(WOLFSSH* ssh, const char* list); +int wolfSSH_SetAlgoListKey(WOLFSSH* ssh, const char* list); +int wolfSSH_SetAlgoListCipher(WOLFSSH* ssh, const char* list); +int wolfSSH_SetAlgoListMac(WOLFSSH* ssh, const char* list); +int wolfSSH_SetAlgoListKeyAccepted(WOLFSSH* ssh, const char* list); +``` -なし +**説明** -**引数** +これらの関数は、wolfSSH の _ctx_ または _ssh_ オブジェクトに設定される各種アルゴリズムリストの +セッターとして機能する。これらの文字列は KEX 初期化時にピアへ送信され、ピアが KEX 初期化 +メッセージを送ってきた際の比較に使用される。KeyAccepted リストはユーザー認証に使用される。 -**ssh** – WOLFSSHオブジェクトへのポインター
+CTX 版の関数は、指定された WOLFSSH_CTX オブジェクト _ctx_ に対してアルゴリズムリストを設定する。 +これらはコンパイル時にデフォルト値が設定されている。指定した値がその代わりに使用される。 +なお、このライブラリは文字列をコピーしないため、その所有権はアプリケーション側にあり、 +アプリケーションが CTX を解放する際に文字列を解放するのはアプリケーションの責任である。 +CTX を使って SSH オブジェクトを作成すると、SSH オブジェクトは CTX の文字列を継承する。 +SSH オブジェクトのアルゴリズムリストは上書きすることができる。 -**txCount** – 総送信済みデータ数を返却する為の変数のアドレス
+`Kex` は鍵交換アルゴリズムリストを指定する。`Key` はサーバー公開鍵アルゴリズムリストを指定する。 +`Cipher` はバルク暗号化アルゴリズムリストを指定する。`Mac` はメッセージ認証コードアルゴリズム +リストを指定する。`KeyAccepted` はユーザー認証で許可される公開鍵アルゴリズムを指定する。 -**rxCount** – 総受信済みデータ数を返却する為の変数のアドレス
+**戻り値** -**seq** – パケットシーケンス番号を返却する為の変数のアドレス。パケットシーケンス番号は0から始まりパケット毎にインクリメントされる
+- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` +- `WS_SSH_NULL_E` -**peerSeq** – 相手パケットシーケンス番号を返却する為の変数のアドレス。パケットシーケンス番号は0から始まりパケット毎にインクリメントされる
+### wolfSSH アルゴリズムリストの取得 -``` +```c #include -void wolfSSH_GetStats(WOLFSSH* ssh , word32* txCount , word32* rxCount , -word32* seq , word32* peerSeq ) -``` - -### wolfSSH_KDF() +const char* wolfSSH_CTX_GetAlgoListKex(WOLFSSH_CTX* ctx); +const char* wolfSSH_CTX_GetAlgoListKey(WOLFSSH_CTX* ctx); +const char* wolfSSH_CTX_GetAlgoListCipher(WOLFSSH_CTX* ctx); +const char* wolfSSH_CTX_GetAlgoListMac(WOLFSSH_CTX* ctx); +const char* wolfSSH_CTX_GetAlgoListKeyAccepted(WOLFSSH_CTX* ctx); -**用法** +const char* wolfSSH_GetAlgoListKex(WOLFSSH* ssh); +const char* wolfSSH_GetAlgoListKey(WOLFSSH* ssh); +const char* wolfSSH_GetAlgoListCipher(WOLFSSH* ssh); +const char* wolfSSH_GetAlgoListMac(WOLFSSH* ssh); +const char* wolfSSH_GetAlgoListKeyAccepted(WOLFSSH* ssh); +``` **説明** -APIテストが鍵派生の既知の回答テストを行うことができるように使用されます。 -鍵派生関数は鍵マテリアル**k** と **h**を元に対称鍵を生成します。ここで、**k**はデフィーヘルマンのシェアードシークレットであり、**h**は初期の鍵交換中に生成されたハンドシェークのハッシュ値です。**keyid**および**hashid**によって指定される複数のタイプの鍵が導出される可能性があります。 +これらの関数は、wolfSSH の _ctx_ または _ssh_ オブジェクトに設定される各種アルゴリズムリストの +ゲッターとして機能する。 +`Kex` は鍵交換アルゴリズムリストを指定する。`Key` はサーバー公開鍵アルゴリズムリストを指定する。 +`Cipher` はバルク暗号化アルゴリズムリストを指定する。`Mac` はメッセージ認証コードアルゴリズム +リストを指定する。`KeyAccepted` はユーザー認証で許可される公開鍵アルゴリズムを指定する。 -``` -Initial IV client to server: keyId = A -Initial IV server to client: keyId = B -Encryption key client to server: keyId = C -Encryption key server to client: keyId = D -Integrity key client to server: keyId = E -Integrity key server to client : keyId = F -``` **戻り値** -**WS_SUCCESS**
- -**WS_CRYPTO_FAILED** +これらの関数は、コンパイル時に設定されたデフォルト値、またはセッター関数で実行時に設定された +値へのポインターを返す。`ctx` または `ssh` パラメーターが NULL の場合、関数は NULL を返す。 -**引数** -**hashId** – キーイングマテリアルを生成させる為のハッシュのタイプ(WC_HASH_TYPE_SHA あるいは WC_HASH_TYPE_SHA256)
+### wolfSSH_CheckAlgoName() -**keyId** – 生成する鍵を示す文字A から F
+```c +#include -**key** – 期待されている鍵との比較に使用される生成済みの鍵
+int wolfSSH_CheckAlgoName(const char* name); +``` -**keySz** – 鍵**key**の生成に必要なサイズ
+**説明** -**k** – デフィーヘルマン鍵交換で得たシェアードシークレット
+指定した単一のアルゴリズム名 `name` が有効かつサポートされているかどうかを確認する。 -**kSz** – シェアードシークレット**k**のサイズ
+**引数** -**h** – 鍵交換中に生成されたハンドシェークのハッシュ値
+- `name` - 確認するアルゴリズム名 -**hSz** – ハッシュ**h**のサイズ
+**戻り値** -**sessionId** – 最初のハッシュ**h**のユニークなID
+- `WS_SUCCESS` +- `WS_INVALID_ALGO_ID` -**sessionIdSz** – **sessionId**のサイズ +### wolfSSH アルゴリズムの照会 -``` +```c #include -int wolfSSH_KDF(byte hashId , byte keyId , byte* key , word32　keySz , -const byte* k , word32 kSz , const byte* h , word32　hSz , -const byte* sessionId , word32 sessionIdSz ); + +const char* wolfSSH_QueryKex(word32* index); +const char* wolfSSH_QueryKey(word32* index); +const char* wolfSSH_QueryCipher(word32* index); +const char* wolfSSH_QueryMac(word32* index); ``` +**説明** + +指定された種別（Kex、Key、Cipher、または Mac）の有効なアルゴリズムの名前文字列を返す。Key +種別は、ユーザー認証で受理される鍵種別としても使用される。`index` を 0 に初期化し、呼び出す +たびに同じポインターを渡すことで反復処理を行う。関数はこのポインターを進める。戻り値が NULL +の場合、リストの末尾に達したことを意味する。 +**引数** -## セッション機能 +- `index` - イテレーター。0 に初期化し、呼び出しごとに渡す +**戻り値** +- アルゴリズム名文字列へのポインター、またはリストの末尾に達した場合は `NULL` -### wolfSSH_GetSessionType() +### wolfSSH_GetText() +```c +#include -**用法** +size_t wolfSSH_GetText(WOLFSSH* ssh, WS_Text id, char* str, size_t strSz); +``` **説明** -wolfSSH_GetSessionType()はセッションの種類を返します。 +`id`（KEX アルゴリズム、KEX 曲線、KEX ハッシュ、入出力暗号、入出力 MAC などの `WS_Text` 値） +で識別されるネゴシエーション済み項目のテキスト表現を `str` に書き込む。終端 NULL を含めて +`strSz` バイトを超えて書き込むことはない。 -**戻り値** +**引数** -WOLFSSH_SESSION_UNKNOWN
+- `ssh` - wolfSSH セッションへのポインター +- `id` - 取得する `WS_Text` 項目 +- `str` - テキストの出力バッファ +- `strSz` - 出力バッファのサイズ -WOLFSSH_SESSION_SHELL
+**戻り値** -WOLFSSH_SESSION_EXEC
+- 書き込まれた文字数（終端 NULL を除く）。値が `strSz` 以上の場合、出力が切り詰められたことを + 意味する -WOLFSSH_SESSION_SUBSYSTEM
+## グローバルリクエストコールバック -**引数** +これらのコールバックは、SSH グローバルリクエストメッセージおよびその成功/失敗応答を処理する。 -**ssh** - WOLFSSHオブジェクトへのポインター
+### wolfSSH_SetGlobalReq() -``` +```c #include -WS_SessionType wolfSSH_GetSessionType(const WOLFSSH* ssh ); -``` -### wolfSSH_GetSessionCommand() +void wolfSSH_SetGlobalReq(WOLFSSH_CTX* ctx, WS_CallbackGlobalReq cb); +``` +**説明** -**用法** +ピアからグローバルリクエストメッセージを受信した際に呼び出されるコールバックを登録する。 -**説明** +**引数** -セッションの現在のコマンドを返します +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - グローバルリクエストコールバック **戻り値** -**const char*** - コマンドへのポインター +なし -**引数** +**関連項目** -**ssh** - WOLFSSHオブジェクトへのポインター
+- `wolfSSH_SetGlobalReqCtx()` -``` +### wolfSSH_SetGlobalReqCtx() + +```c #include -const char* wolfSSH_GetSessionCommand(const WOLFSSH* ssh ); + +void wolfSSH_SetGlobalReqCtx(WOLFSSH* ssh, void* ctx); ``` -## ポートフォワーディング関数 +**説明** +グローバルリクエストコールバックに渡されるユーザーコンテキストポインターを設定する。 +**引数** -### wolfSSH_ChannelFwdNew() +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - コールバックに渡すユーザーコンテキストポインター +**戻り値** -**用法** +なし -**説明** +### wolfSSH_GetGlobalReqCtx() -wolfSSHセッションにTCP/IP転送チャネルを設定します。SSHセッションが接続され、認証された場合、ポート_hostport_のaddress_host_のインターフェイスにローカルリスナーが作成されます。そのリスナーの新しい接続があれば、SSHサーバーへの新しいChannelRequestをトリガーして、ポート_hostport_で_host_への接続を確立します。 +```c +#include +void* wolfSSH_GetGlobalReqCtx(WOLFSSH* ssh); +``` -**戻り値** +**説明** -**WOLFSSH_CHAN*** – エラーの場合はNULL、成功の場合は新たな新しいチャンネルレコード +wolfSSH_SetGlobalReqCtx() で以前に設定されたユーザーコンテキストポインターを返す。 **引数** -**ssh** - WOLFSSHオブジェクトへのポインター
- -**host** – バインドリスナーのホストアドレス
+- `ssh` - wolfSSH セッションへのポインター -**hostPort** – バインドリスナーのポート
+**戻り値** -**origin** – 接続元のIPアドレス
+- グローバルリクエストコンテキストポインター。存在しない場合は `NULL` -**originPort** – 接続元のポート
+### wolfSSH_SetReqSuccess() -``` +```c #include -WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNew(WOLFSSH* ssh , -const char* host , word32 hostPort , -const char* origin , word32 originPort ); -``` - -### wolfSSH_ChannelFree() - -**用法** +void wolfSSH_SetReqSuccess(WOLFSSH_CTX* ctx, WS_CallbackReqSuccess cb); +``` **説明** -チャネル _channel_のメモリを解放します。チャネルはセッションのチャネルリストから削除されます。 +ピアからリクエスト成功応答を受信した際に呼び出されるコールバックを登録する。 + +**引数** +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - リクエスト成功コールバック **戻り値** -**int** – エラーコード +なし + +**関連項目** -**引数** +- `wolfSSH_SetReqSuccessCtx()` -**channel** – 解放されるwolfSSHチャネル +### wolfSSH_SetReqSuccessCtx() -``` +```c #include -int wolfSSH_ChannelFree(WOLFSSH_CHANNEL* channel ); + +void wolfSSH_SetReqSuccessCtx(WOLFSSH* ssh, void* ctx); ``` -### wolfSSH_worker() +**説明** + +リクエスト成功コールバックに渡されるユーザーコンテキストポインターを設定する。 +**引数** -**用法** +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - コールバックに渡すユーザーコンテキストポインター -**説明** +**戻り値** -wolfSSH Worker機能は接続を見守り、データが受信されると処理します。SSHセッションにはセッションの多くの管理すべきメッセージがあり、これにより自動的にケアがあります。特定のチャネルのデータが受信されると、ワーカーはデータをチャネルに配置します。(function wolfssh_stream_read()dosmuchも同じですが、単一のチャネルの受信データも返します。）wolfssh_worker()は次のアクションを実行します： +なし -1. _outputbuffer_　内に保留中のデータを送信しようとします。 -2. セッションのソケットに対して _DoReceive()_ を呼び出します。 -3. 特定のチャネルのデータが受信された場合、データを返して通知を受け取り、チャネルIDを指定して通知します。 +### wolfSSH_GetReqSuccessCtx() +```c +#include -**戻り値** +void* wolfSSH_GetReqSuccessCtx(WOLFSSH* ssh); +``` -**int** – エラーコードあるいはステータス
+**説明** -**WS_CHANNEL_RXD** – チャネルに受信済みのデータとチャネルIDがセットされている +wolfSSH_SetReqSuccessCtx() で以前に設定されたユーザーコンテキストポインターを返す。 **引数** -**ssh** - WOLFSSHオブジェクトへのポインター
+- `ssh` - wolfSSH セッションへのポインター -**id** – IDを格納する変数へのポインター +**戻り値** +- リクエスト成功コンテキストポインター。存在しない場合は `NULL` -``` +### wolfSSH_SetReqFailure() + +```c #include -int wolfSSH_worker(WOLFSSH* ssh , word32* channelId ); -``` -### wolfSSH_ChannelGetId() +void wolfSSH_SetReqFailure(WOLFSSH_CTX* ctx, WS_CallbackReqSuccess cb); +``` +**説明** -**用法** +ピアからリクエスト失敗応答を受信した際に呼び出されるコールバックを登録する。 -**説明** +**引数** -引数で与えられたチャネルに対してIDあるいは相手のIDを返します。 +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - リクエスト失敗コールバック **戻り値** -**int** – エラーコード
- -**引数** +なし -**channel** – チャネルへのポインター
+**関連項目** -**id** – IDを格納する変数へのポインター
+- `wolfSSH_SetReqFailureCtx()` -**peer** – 自チャネルIDか相手チャネルID +### wolfSSH_SetReqFailureCtx() -``` +```c #include -int wolfSSH_ChannelGetId(WOLFSSH_CHANNEL* channel ,　word32* id , byte peer); -``` - -### wolfSSH_ChannelFind() - -**用法** +void wolfSSH_SetReqFailureCtx(WOLFSSH* ssh, void* ctx); +``` **説明** -Given a session _ssh_ , find the channel associated with _id_. - -**戻り値** - -**WOLFSSH_CHANNEL*** – チャネルへのポインター,IDがリストになければNULL +リクエスト失敗コールバックに渡されるユーザーコンテキストポインターを設定する。 **引数** -**ssh** - WOLFSSHオブジェクトへのポインター
+- `ssh` - wolfSSH セッションへのポインター +- `ctx` - コールバックに渡すユーザーコンテキストポインター -**id** – 検索したいチャネルID
+**戻り値** -**peer** – どちらの側(自channel ID か相手channel ID) +なし +### wolfSSH_GetReqFailureCtx() -``` +```c #include -WOLFSSH_CHANNEL* wolfSSH_ChannelFind(WOLFSSH* ssh , -word32 id , byte peer ); -``` - -### wolfSSH_ChannelRead() - -**用法** +void* wolfSSH_GetReqFailureCtx(WOLFSSH* ssh); +``` **説明** -チャネルオブジェクトからデータをコピーします +wolfSSH_SetReqFailureCtx() で以前に設定されたユーザーコンテキストポインターを返す。 +**引数** -**戻り値** +- `ssh` - wolfSSH セッションへのポインター -**int** – 読みだしたバイト数
+**戻り値** -**>0** – 成功時には読みだしたバイト数を返します +- リクエスト失敗コンテキストポインター。存在しない場合は `NULL` -**0** – クリーンコネクションシャットダウンかソケットエラーが発生している。 エラー詳細を取得するためにwolfSSH_get_error()を呼び出すこと。
+## TPM 2.0 連携 -**WS_FATAL_ERROR** – そのほかのエラーが発生。エラー詳細を取得するためにwolfSSH_get_error()を呼び出すこと。
+これらの関数は、ホスト鍵操作のために wolfTPM 2.0 デバイスおよび鍵を統合する。使用するには、 +wolfSSH を `WOLFSSH_TPM` を有効にしてビルドし、wolfTPM がインストールされている必要がある。 -**引数** +### wolfSSH_SetTpmDev() -**channel** – wolfSSH channelへのポインター
+```c +#include -**buf** – wolfSSH_ChannelReadが読みだしたデータを格納するバッファアドレス
+void wolfSSH_SetTpmDev(WOLFSSH* ssh, WOLFTPM2_DEV* dev); +``` -**bufSz** – バッファのサイズ
+**説明** -``` -#include -int wolfSSH_ChannelRead(WOLFSSH_CHANNEL* channel, byte* buf, word32 bufSz ); -``` +TPM を利用したホスト鍵操作のために、wolfTPM 2.0 デバイスをセッションに関連付ける。 -### wolfSSH_ChannelSend() +**引数** +- `ssh` - wolfSSH セッションへのポインター +- `dev` - wolfTPM 2.0 デバイスへのポインター -**用法** +**戻り値** -**説明** +なし -指定したチャネル経由でデータを相手に送信します。データはチャネルデータメッセージにパッキングされて送られます。さらに送信すべきデータがある場合には、 _wolfSSH_worker()_ を呼び出すと相手へのデータ送信を継続します。 +**関連項目** -**戻り値** +- `wolfSSH_SetTpmKey()` -**int** – 送信したバイト数
+### wolfSSH_SetTpmKey() -**>0** – 成功時には送信したバイト数を返す
+```c +#include -**0** – クリーンコネクションシャットダウンかソケットエラーが発生している。 エラー詳細を取得するためにwolfSSH_get_error()を呼び出すこと。
+void wolfSSH_SetTpmKey(WOLFSSH* ssh, WOLFTPM2_KEY* key); +``` -**WS_FATAL_ERROR** – そのほかのエラーが発生。エラー詳細を取得するためにwolfSSH_get_error()を呼び出すこと。
+**説明** +TPM を利用したホスト鍵操作のために、wolfTPM 2.0 鍵をセッションに関連付ける。 **引数** -**channel** – wolfSSH channelへのポインター
+- `ssh` - wolfSSH セッションへのポインター +- `key` - wolfTPM 2.0 鍵へのポインター -**buf** – wolfSSH_ChannelSend()が送信のために読みだすバッファへのポインター
+**戻り値** -**bufSz** – バッファのサイズ
+なし +### wolfSSH_GetTpmDev() -``` +```c #include -int* wolfSSH_ChannelSend(WOLFSSH_CHANNEL* channel, const byte* buf, word32 bufSz); -``` -### wolfSSH_ChannelExit() +void* wolfSSH_GetTpmDev(WOLFSSH* ssh); +``` +**説明** -**用法** +以前にセッションに関連付けられた wolfTPM 2.0 デバイスを返す。 -**説明** +**引数** -チャネルを終了し、相手へのメッセージ送信を停止し、チャネルがクローズしたとマークします。この関数はチャネルと残ったデータを解放しませんし、チャネルはリストに残ります。クローズ後は未送信データはそのままですが、受信は可能です。（現時点ではEOFとcloseを送りチャネルを削除します） +- `ssh` - wolfSSH セッションへのポインター **戻り値** -**int** – エラーコード - -**引数** +- wolfTPM 2.0 デバイスへのポインター。存在しない場合は `NULL` -**channel** – wolfSSH channelへのポインター
+### wolfSSH_GetTpmKey() -``` +```c #include -int wolfSSH_ChannelExit(WOLFSSH_CHANNEL* channel ); + +void* wolfSSH_GetTpmKey(WOLFSSH* ssh); ``` -### wolfSSH_ChannelNext() +**説明** +以前にセッションに関連付けられた wolfTPM 2.0 鍵を返す。 -**用法** +**引数** -**説明** +- `ssh` - wolfSSH セッションへのポインター -_ssh_ の _channel_ の次のチャネルを返します。_channel_ がNULLの場合には、チャネルリスト内の最初のチャネルを返します。 +**戻り値** +- wolfTPM 2.0 鍵へのポインター。存在しない場合は `NULL` -**戻り値** +### wolfSSH_CTX_UseTpmHostKey() -**WOLFSSH_CHANNEL** – 最初のチャネルあるいは次のチャネルへのポインターあるいはNULL +```c +#include -**引数** +int wolfSSH_CTX_UseTpmHostKey(WOLFSSH_CTX* ctx, + WOLFTPM2_DEV* dev, WOLFTPM2_KEY* key); +``` -**ssh** - WOLFSSHオブジェクトへのポインター
+**説明** -**channel** – wolfSSH channelへのポインター
+指定された wolfTPM 2.0 デバイスおよび鍵をサーバーホスト鍵として使用するようコンテキストを +設定する。 -``` -#include -WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNew(WOLFSSH* ssh , WOLFSSH_CHANNEL* channel ); -``` +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `dev` - wolfTPM 2.0 デバイスへのポインター +- `key` - wolfTPM 2.0 鍵へのポインター + +**戻り値** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` diff --git a/wolfSSH/src-ja/chapter14.md b/wolfSSH/src-ja/chapter14.md index f2f34ff3..85a871e7 100644 --- a/wolfSSH/src-ja/chapter14.md +++ b/wolfSSH/src-ja/chapter14.md @@ -1,6 +1,6 @@ -# wolfSSL SFTP API リファレンス +# wolfSSH SFTP API リファレンス -## 接続機能 +## 接続関数 @@ -8,837 +8,556 @@ -**用法** - -**説明** +```c +#include -クライアントからの接続要求を処理します +int wolfSSH_SFTP_accept(WOLFSSH* ssh); +``` -**戻り値** +**説明** -**WS_SFTP_COMPLETE** - 成功 +クライアントからの受信 SFTP 接続要求を処理します。SSH セッションが確立された後、 +サーバー側で呼び出します。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
- - -``` -#include -int wolfSSH_SFTP_accept(WOLFSSH* ssh ); -``` -**使用例** - -``` -WOLFSSH* ssh; +- `ssh` - 接続に使用する wolfSSH セッションへのポインター -//create new WOLFSSH structure -... +**戻り値** -if (wolfSSH_SFTP_accept(ssh) != WS_SUCCESS) { -//handle error case -} -``` +- 成功時は `WS_SFTP_COMPLETE` +- 失敗時は負のエラーコード **関連項目** -wolfSSH_SFTP_free()
- -wolfSSH_new()
- -wolfSSH_SFTP_connect()
- +- `wolfSSH_SFTP_connect()` +- `wolfSSH_SFTP_negotiate()` ### wolfSSH_SFTP_connect() -**用法** -**説明** +```c +#include -SFTPサーバーへの接続を開始します。 +int wolfSSH_SFTP_connect(WOLFSSH* ssh); +``` -**戻り値** +**説明** -**WS_SFTP_COMPLETE** - 成功
+サーバーへの SFTP 接続を開始します。SSH セッションが確立された後、クライアント側で +呼び出します。 **引数** -**ssh** - – WOLFSSHオブジェクトへのポインター
- +- `ssh` - 接続に使用する wolfSSH セッションへのポインター -``` -#include -int wolfSSH_SFTP_connect(WOLFSSH* ssh ); -``` - - -**使用例** - -``` -WOLFSSH* ssh; - -//after creating a new WOLFSSH structure +**戻り値** -wolfSSH_SFTP_connect(ssh); -``` +- 成功時は `WS_SFTP_COMPLETE` +- 失敗時は負のエラーコード **関連項目** -wolfSSH_SFTP_accept()
- -wolfSSH_new()
- -wolfSSH_free()
- +- `wolfSSH_SFTP_accept()` +- `wolfSSH_SFTP_negotiate()` ### wolfSSH_SFTP_negotiate() -**用法** - -**説明** - -本関数はクライアントからの接続要求かサーバーへの接続要求のいずれかを処理します。いずれを処理するかはwolfSSHオブジェクトにセットされているアクションに依存します。 - - -**戻り値** - -**WS_SUCCESS** - 成功 - -**引数** - -**ssh** - – WOLFSSHオブジェクトへのポインター
- - -``` +```c #include -int wolfSSH_SFTP_negotiate(WOLFSSH* ssh) -``` - -**使用例** +int wolfSSH_SFTP_negotiate(WOLFSSH* ssh); ``` -WOLFSSH* ssh; -//create new WOLFSSH structure with side of connection -set -.... - -if (wolfSSH_SFTP_negotiate(ssh) != WS_SUCCESS) { -//handle error case -} -``` - -**関連項目** - -wolfSSH_SFTP_free()
- -wolfSSH_new()
+**説明** -wolfSSH_SFTP_connect()
+SFTP プロトコルのネゴシエーションを実行します。セッションがどちら側のために作成 +されたかに応じて、クライアントからの受信接続を処理するか、サーバーへ接続要求を +送信します。 -wolfSSH_SFTP_accept()
+**引数** +- `ssh` - 接続に使用する wolfSSH セッションへのポインター +**戻り値** -## プロトコル関係 +- 成功時は `WS_SUCCESS` +- 失敗時は負のエラーコード +**関連項目** +- `wolfSSH_SFTP_accept()` +- `wolfSSH_SFTP_connect()` -### wolfSSH_SFTP_RealPath() +### wolfSSH_SFTP_SetDefaultPath() +```c +#include -**用法** +int wolfSSH_SFTP_SetDefaultPath(WOLFSSH* ssh, const char* path); +``` **説明** -REALPATHパケットを相手に送信し、相手から取得したファイル名を返します。 +SFTP セッションのデフォルト（開始）ディレクトリを設定します。サーバー側では、これは +相対パスを解決する際の基準となるベースディレクトリです。 +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `path` - 設定するデフォルトパス **戻り値** -成功時にはWS_SFTPNAME構造体へのポインターを返します。エラー発生時にはNULLを返します。 +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +## プロトコルレベル関数 -**引数** -**ssh** – WOLFSSHオブジェクトへのポインター
-**dir** - 実際のパスを取得するためのディレクトリ/ファイル名 +### wolfSSH_SFTP_RealPath() -``` +```c #include -WS_SFTPNAME* wolfSSH_SFTP_RealPath(WOLFSSH* ssh , char* dir); -``` -**使用例** - -``` -WOLFSSH* ssh ; -//set up ssh and do sftp connections -... - -if (wolfSSH_SFTP_read( ssh ) != WS_SUCCESS) { -//handle error case -} +WS_SFTPNAME* wolfSSH_SFTP_RealPath(WOLFSSH* ssh, char* dir); ``` -**関連項目** - -wolfSSH_SFTP_accept()
- -wolfSSH_SFTP_connect()
- - - -### wolfSSH_SFTP_Close() - - - -**用法** - **説明** -相手にクローズパケットを送信します。 - - -**戻り値** - -**WS_SUCCESS** - 成功 +ピアに REALPATH 要求を送信し、ファイルまたはディレクトリの正規名を返します。返された +`WS_SFTPNAME` は wolfSSH_SFTPNAME_free() で解放する必要があります。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
- -**handle** - 閉じようとするハンドル
- -**handleSz** - ハンドルバッファーのサイズ - +- `ssh` - wolfSSH セッションへのポインター +- `dir` - 解決するファイル名またはディレクトリ名 -``` -#include -int wolfSSH_SFTP_Close(WOLFSSH* ssh , byte* handle , word32 handleSz ); -``` -**使用例** - -``` -WOLFSSH* ssh; -byte handle[HANDLE_SIZE]; -word32 handleSz = HANDLE_SIZE; - -//set up ssh and do sftp connections -... +**戻り値** -if (wolfSSH_SFTP_Close(ssh, handle, handleSz) != WS_SUCCESS) { -//handle error case -} -``` +- 成功時は `WS_SFTPNAME` 構造体へのポインター +- エラー時は `NULL` **関連項目** -wolfSSH_SFTP_accept()
- -wolfSSH_SFTP_connect()
+- `wolfSSH_SFTPNAME_free()` +### wolfSSH_SFTP_Close() -### wolfSSH_SFTP_Open() +```c +#include -**用法** +int wolfSSH_SFTP_Close(WOLFSSH* ssh, byte* handle, word32 handleSz); +``` **説明** -Openパケットを相手に送信します。結果を受け取るバッファサイズのをhandleSzで指定し、相手から受け取ったハンドルをバッファに格納します。 - - -openの理由として取り得る値は:
+指定されたファイルハンドルについて、ピアにクローズ要求を送信します。このハンドルは、 +以前の wolfSSH_SFTP_Open() の呼び出しから取得したものです。 -WOLFSSH_FXF_READ
- -WOLFSSH_FXF_WRITE
- -WOLFSSH_FXF_APPEND
- -WOLFSSH_FXF_CREAT
- -WOLFSSH_FXF_TRUNC
- -WOLFSSH_FXF_EXCL
+**引数** +- `ssh` - wolfSSH セッションへのポインター +- `handle` - クローズするファイルハンドル +- `handleSz` - ハンドルバッファのサイズ **戻り値** -**WS_SUCCESS** - 成功 - -**引数** +- `WS_SUCCESS` +- 失敗時は負のエラーコード -**ssh** – WOLFSSHオブジェクトへのポインター
- -**dir** - 開くファイルの名前
- -**reason** - ファイルを開く理由
+**関連項目** -**atr** - ファイルの初期属性
+- `wolfSSH_SFTP_Open()` -**handle** - 結果として得られるハンドル
+### wolfSSH_SFTP_Open() -**handleSz** - ハンドル用バッファのサイズ
-``` +```c #include -int wolfSSH_SFTP_Open(WOLFSSH* ssh , char* dir , word32　reason, WS_SFTP_FILEATRB* atr , byte* handle , word32* handleSz); -``` - -**使用例** - - +int wolfSSH_SFTP_Open(WOLFSSH* ssh, char* dir, word32 reason, + WS_SFTP_FILEATRB* atr, byte* handle, word32* handleSz); ``` -WOLFSSH* ssh ; -char name[NAME_SIZE]; -byte handle[HANDLE_SIZE]; -word32 handleSz = HANDLE_SIZE; -WS_SFTP_FILEATRB atr; - -//set up ssh and do sftp connections -... - -if (wolfSSH_SFTP_Open( ssh , name , WOLFSSH_FXF_WRITE | WOLFSSH_FXF_APPEND | WOLFSSH_FXF_CREAT , &atr , handle , &handleSz ) != WS_SUCCESS) { -//handle error case -} -``` - -**関連項目** - -wolfSSH_SFTP_accept()
- -wolfSSH_SFTP_connect()
- - -### wolfSSH_SFTP_SendReadPacket() - -**用法** **説明** -readパケットを相手に送信します。ハンドル用のバッファは直前のwolfSSH_SFTP_Openで得られたハンドルを格納していなければなりません。読みだすことができたデータはoutバッファに格納されます。 - - -**戻り値** - -成功時には読みだしたデータ数を返します。エラー発生時には、負の値を返します。 +`dir` で指定された名前のファイルについて、ピアにオープン要求を送信します。成功時、 +得られたファイルハンドルが `handle` に格納され、そのサイズが `handleSz` に書き込ま +れます。`reason` 引数はオープンフラグのビットマスクで、`WOLFSSH_FXF_READ`、 +`WOLFSSH_FXF_WRITE`、`WOLFSSH_FXF_APPEND`、`WOLFSSH_FXF_CREAT`、`WOLFSSH_FXF_TRUNC`、 +`WOLFSSH_FXF_EXCL` のいずれかです。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
- -**handle** - 読みだそうとするハンドル
+- `ssh` - wolfSSH セッションへのポインター +- `dir` - オープンするファイルの名前 +- `reason` - オープンフラグのビットマスク（上記を参照） +- `atr` - 初期ファイル属性 +- `handle` - 得られたファイルハンドルの出力バッファ +- `handleSz` - 入力時はバッファのサイズ、出力時はハンドルのサイズが設定される -**handleSz** - ハンドルバッファのサイズ
+**戻り値** -**ofst** - 読み出しを開始するオフセット
+- `WS_SUCCESS` +- 失敗時は負のエラーコード -**out** - 読み出した結果を格納するバッファ
+**関連項目** -**outSz** - バッファサイズ +- `wolfSSH_SFTP_Close()` +- `wolfSSH_SFTP_SendReadPacket()` +- `wolfSSH_SFTP_SendWritePacket()` +### wolfSSH_SFTP_SendReadPacket() -``` +```c #include -int wolfSSH_SFTP_SendReadPacket(WOLFSSH* ssh , byte*　handle , word32 handleSz , word64 ofst , byte* out , word32 outSz ); -``` - - - -**使用例** +int wolfSSH_SFTP_SendReadPacket(WOLFSSH* ssh, byte* handle, + word32 handleSz, const word32* ofst, byte* out, word32 outSz); ``` -WOLFSSH* ssh; -byte handle[HANDLE_SIZE]; -word32 handleSz = HANDLE_SIZE; -byte out[OUT_SIZE]; -word32 outSz = OUT_SIZE; -word32 ofst = 0; -int ret; - -//set up ssh and do sftp connections -... -//get handle with wolfSSH_SFTP_Open() - -if ((ret = wolfSSH_SFTP_SendReadPacket(ssh, handle, handleSz, ofst, out, outSz)) < 0) { -//handle error case -} -//ret holds the number of bytes placed into out buffer -``` - -**関連項目** - -wolfSSH_SFTP_SendWritePacket()
- -wolfSSH_SFTP_Open()
- - -### wolfSSH_SFTP_SendWritePacket() - - - -**用法** **説明** -writeパケットを相手に送信します。ハンドル用のバッファは直前のwolfSSH_SFTP_Openで得られたハンドルを格納していなければなりません。 - -**戻り値** - -成功時には書き込んだサイズを返します。エラー発生時には負の値を返します。 +`handle`（wolfSSH_SFTP_Open() から取得）が参照するファイルについて、ピアに読み取り +要求を送信します。読み取られたバイトは `out` バッファに格納されます。`ofst` 引数は、 +読み取りを開始するファイルオフセットを指します。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
- -**handle** - 書き込もうとするハンドル
- -**handleSz** - ハンドルバッファのサイズ
- -**ofst** - 書き込みを開始するオフセット
- -**out** - 書き込むデータを保持するバッファ
- -**outSz** - バッファサイズ
- - -``` -#include -int wolfSSH_SFTP_SendWritePacket(WOLFSSH* ssh, byte*　handle, word32　handleSz, word64 ofst, byte* out, word32 outSz); -``` - -**使用例** +- `ssh` - wolfSSH セッションへのポインター +- `handle` - 読み取り元のファイルハンドル +- `handleSz` - ハンドルバッファのサイズ +- `ofst` - 読み取りを開始するファイルオフセットへのポインター +- `out` - 読み取ったデータを保持するバッファ +- `outSz` - 出力バッファのサイズ +**戻り値** -``` -WOLFSSH* ssh; -byte handle[HANDLE_SIZE]; -word32 handleSz = HANDLE_SIZE; -byte out[OUT_SIZE]; -word32 outSz = OUT_SIZE; -word32 ofst = 0; -int ret; - -//set up ssh and do sftp connections -... -//get handle with wolfSSH_SFTP_Open() - -if ((ret = wolfSSH_SFTP_SendWritePacket(ssh, handle, handleSz, ofst, out, outSz)) < 0) { -//handle error case -} -//ret holds the number of bytes written -``` +- 0 以上 - 成功時に読み取ったバイト数 +- 失敗時は負のエラーコード **関連項目** -wolfSSH_SFTP_SendReadPacket()
+- `wolfSSH_SFTP_SendWritePacket()` +- `wolfSSH_SFTP_Open()` -wolfSSH_SFTP_Open()
+### wolfSSH_SFTP_SendWritePacket() -### wolfSSH_SFTP_STAT() - +```c +#include -**用法** +int wolfSSH_SFTP_SendWritePacket(WOLFSSH* ssh, byte* handle, + word32 handleSz, const word32* ofst, byte* out, word32 outSz); +``` **説明** -STATパケットを相手に送信します。ファイルあるいはディレクトリの属性を取得します。ファイルが存在しないかあるいは属性が存在しない場合は相手はエラーを返します。 +`handle`（wolfSSH_SFTP_Open() から取得）が参照するファイルについて、ピアに書き込み +要求を送信し、`out` バッファの内容を書き込みます。`ofst` 引数は、書き込みを行う +ファイルオフセットを指します。 +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `handle` - 書き込み先のファイルハンドル +- `handleSz` - ハンドルバッファのサイズ +- `ofst` - 書き込みを開始するファイルオフセットへのポインター +- `out` - ピアに送信するデータのバッファ +- `outSz` - バッファのサイズ **戻り値** -**WS_SUCCESS** - 成功 +- 0 以上 - 成功時に書き込んだバイト数 +- 失敗時は負のエラーコード -**引数** +**関連項目** -**ssh** – WOLFSSHオブジェクトへのポインター
+- `wolfSSH_SFTP_SendReadPacket()` +- `wolfSSH_SFTP_Open()` -**dir** - NULLターミネートされたファイルあるいはディレクトリ名
+### wolfSSH_SFTP_STAT() -**atr** - 属性値がこの構造体に返却されます -``` +```c #include -int wolfSSH_SFTP_STAT(WOLFSSH* ssh , char* dir, WS_SFTP_FILEATRB* atr); -``` -**使用例** +int wolfSSH_SFTP_STAT(WOLFSSH* ssh, char* dir, WS_SFTP_FILEATRB* atr); ``` -WOLFSSH* ssh; -byte name[NAME_SIZE]; -int ret; -WS_SFTP_FILEATRB atr; -//set up ssh and do sftp connections -... +**説明** -if ((ret = wolfSSH_SFTP_STAT(ssh, name, &atr)) < 0) { -//handle error case -} -``` +ファイルまたはディレクトリの属性を取得するために、ピアに STAT 要求を送信します。 +シンボリックリンクをたどります。対象が存在しない場合、ピアはエラーを返し、この関数は +エラー値を返します。 -**関連項目** +**引数** -wolfSSH_SFTP_LSTAT()
+- `ssh` - wolfSSH セッションへのポインター +- `dir` - ファイルまたはディレクトリの NULL 終端の名前 +- `atr` - 得られた属性を受け取る構造体 -wolfSSH_SFTP_connect()
+**戻り値** +- `WS_SUCCESS` +- 失敗時は負のエラーコード -### wolfSSH_SFTP_LSTAT() +**関連項目** -**用法** +- `wolfSSH_SFTP_LSTAT()` +- `wolfSSH_SFTP_SetSTAT()` -**説明** +### wolfSSH_SFTP_LSTAT() -LSTATパケットを相手に送信します。ファイルあるいはディレクトリの属性値を取得します。STATパケットがシンボリックリンクをたどりませんがLSTATパケットはシンボリックリンクをたどって処理します。ファイルが存在しないかあるいは属性が存在しない場合は相手はエラーを返します。 +```c +#include +int wolfSSH_SFTP_LSTAT(WOLFSSH* ssh, char* dir, WS_SFTP_FILEATRB* atr); +``` -**戻り値** +**説明** -**WS_SUCCESS** - 成功 +ファイルまたはディレクトリの属性を取得するために、ピアに LSTAT 要求を送信します。 +wolfSSH_SFTP_STAT() とは異なり、LSTAT はシンボリックリンクをたどらず、リンク自体の +属性を返します。対象が存在しない場合、ピアはエラーを返し、この関数はエラー値を +返します。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
- -**dir** - NULLターミネートされたファイルあるいはディレクトリ名
- -**atr** - 属性値がこの構造体に返却されます +- `ssh` - wolfSSH セッションへのポインター +- `dir` - ファイルまたはディレクトリの NULL 終端の名前 +- `atr` - 得られた属性を受け取る構造体 +**戻り値** -``` -#include -int wolfSSH_SFTP_LSTAT(WOLFSSH* ssh, char* dir, WS_SFTP_FILEATRB* atr); -``` -**使用例** -``` -WOLFSSH* ssh; -byte name[NAME_SIZE]; -int ret; -WS_SFTP_FILEATRB atr; - -//set up ssh and do sftp connections -... - -if ((ret = wolfSSH_SFTP_LSTAT(ssh, name, &atr)) < 0) { -//handle error case -} -``` +- `WS_SUCCESS` +- 失敗時は負のエラーコード **関連項目** -wolfSSH_SFTP_STAT()
- -wolfSSH_SFTP_connect()
+- `wolfSSH_SFTP_STAT()` +- `wolfSSH_SFTP_SetSTAT()` +### wolfSSH_SFTP_SetSTAT() -### wolfSSH_SFTPNAME_free() +```c +#include -**用法** +int wolfSSH_SFTP_SetSTAT(WOLFSSH* ssh, char* dir, WS_SFTP_FILEATRB* atr); +``` **説明** -単一のWS_SFTPNAMEノードを解放します。指定したノードがノードリストの途中のものであった場合には、リストは壊れます。 - -**戻り値** - -なし +`atr` の属性（例えばパーミッション、サイズ、タイムスタンプ）を指定されたファイル +またはディレクトリに適用するために、ピアに SETSTAT 要求を送信します。 **引数** -**name** - 解放されるノード - - +- `ssh` - wolfSSH セッションへのポインター +- `dir` - ファイルまたはディレクトリの NULL 終端の名前 +- `atr` - 適用する属性 +**戻り値** -``` -#include -void wolfSSH_SFTPNAME_free(WS_SFTPNAME* name ); -``` -**使用例** - -``` -WOLFSSH* ssh; -WS_SFTPNAME* name; - -//set up ssh and do sftp connections -... -name = wolfSSH_SFTP_RealPath(ssh, path); -if (name != NULL) { -wolfSSH_SFTPNAME_free(name); -} -``` +- `WS_SUCCESS` +- 失敗時は負のエラーコード **関連項目** -wolfSSH_SFTPNAME_list_free() - - -### wolfSSH_SFTPNAME_list_free() +- `wolfSSH_SFTP_STAT()` +### wolfSSH_SFTPNAME_free() +```c +#include -**用法** +void wolfSSH_SFTPNAME_free(WS_SFTPNAME* n); +``` **説明** -リスト中の全WS_SFTPNAMEノードを解放します。 +単一の `WS_SFTPNAME` ノードを解放します。ノードがリストの途中にある場合、それを解放 +するとリストが壊れます。リスト全体を解放するには wolfSSH_SFTPNAME_list_free() を使用 +してください。 + +**引数** +- `n` - 解放する `WS_SFTPNAME` ノード **戻り値** なし -**引数** - -**name** - 解放するリストの先頭 +**関連項目** +- `wolfSSH_SFTPNAME_list_free()` +### wolfSSH_SFTPNAME_list_free() -``` +```c #include -void wolfSSH_SFTPNAME_list_free(WS_SFTPNMAE* name ); -``` - -**使用例** +void wolfSSH_SFTPNAME_list_free(WS_SFTPNAME* n); ``` -WOLFSSH* ssh; -WS_SFTPNAME* name; - -//set up ssh and do sftp connections -... - -name = wolfSSH_SFTP_LS(ssh, path); -if (name != NULL) { -wolfSSH_SFTPNAME_list_free(name); -} -``` - -**関連項目** - -wolfSSH_SFTPNAME_free() - - -## Reget/Reput 機能 - -### wolfSSH_SFTP_SaveOfst() - - - -**用法** **説明** -get あるいはputコマンドが中断された場合のオフセットを保存します。オフセットはwolfSSH_SFTP_GetOfstで復元できます。 - - -**戻り値** -**WS_SUCCESS** - 成功 +wolfSSH_SFTP_LS() が返すリストのような、`WS_SFTPNAME` ノードのリスト全体を解放し +ます。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
+- `n` - 解放する `WS_SFTPNAME` リストの先頭 -**from** - NULL終端されたソースパスを示す文字列
- -**to** - NULL終端されたデスティネーションパスを示す文字列
- -**ofst** - 記憶されるべきファイルのオフセット - - - -``` -#include -int wolfSSH_SFTP_SaveOfst(WOLFSSH* ssh , char* from , char* -to , -word64 ofst ); -``` - -**使用例** - -``` -WOLFSSH* ssh; -char from[NAME_SZ]; -char to[NAME_SZ]; -word64 ofst; - -//set up ssh and do sftp connections -... +**戻り値** -if (wolfSSH_SFTP_SaveOfst(ssh, from, to, ofst) !=　WS_SUCCESS) { -//handle error case -} -``` +なし **関連項目** -wolfSSH_SFTP_GetOfst()
+- `wolfSSH_SFTPNAME_free()` -wolfSSH_SFTP_Interrupt()
+## Reget / Reput 関数 +### wolfSSH_SFTP_SaveOfst() -### wolfSSH_SFTP_GetOfst() +```c +#include -**用法** +int wolfSSH_SFTP_SaveOfst(WOLFSSH* ssh, char* frm, char* to, + const word32* ofst); +``` **説明** -get あるいはputコマンドが中断された場合のオフセットを取得します。 +中断された get または put の転送オフセットを、ソース（`frm`）と宛先（`to`）のパスを +キーとして保存します。保存されたオフセットは、後で wolfSSH_SFTP_GetOfst() により +取得できます。 +**引数** -**戻り値** +- `ssh` - wolfSSH セッションへのポインター +- `frm` - NULL 終端のソースパス +- `to` - NULL 終端の宛先パス +- `ofst` - 保存するオフセットへのポインター -成功時にはオフセット値を返します。オフセットが保存されていない場合には0が返されます。 +**戻り値** +- `WS_SUCCESS` +- 失敗時は負のエラーコード -**引数** +**関連項目** -**ssh** – WOLFSSHオブジェクトへのポインター
+- `wolfSSH_SFTP_GetOfst()` +- `wolfSSH_SFTP_Interrupt()` -**from** - NULL終端されたソースパスを示す文字列
+### wolfSSH_SFTP_GetOfst() -**to** - NULL終端されたデスティネーションパスを示す文字列
-``` +```c #include -word64 wolfSSH_SFTP_GetOfst(WOLFSSH* ssh, char* from, char* to); -``` - -**使用例** +int wolfSSH_SFTP_GetOfst(WOLFSSH* ssh, char* frm, char* to, + word32* ofst); ``` -WOLFSSH* ssh; -char from[NAME_SZ]; -char to[NAME_SZ]; -word64 ofst; - -//set up ssh and do sftp connections -... -ofst = wolfSSH_SFTP_GetOfst(ssh, from, to); -//start reading/writing from ofst -``` +**説明** -**関連項目** +中断された get または put について、ソース（`frm`）と宛先（`to`）のパスをキーとして +保存された転送オフセットを取得し、`ofst` に書き込みます。保存されたオフセットが +見つからない場合、`ofst` は 0 に設定されます。 -wolfSSH_SFTP_SaveOfst()
+**引数** -wolfSSH_SFTP_Interrup()
+- `ssh` - wolfSSH セッションへのポインター +- `frm` - NULL 終端のソースパス +- `to` - NULL 終端の宛先パス +- `ofst` - 保存されたオフセットの出力 +**戻り値** +- `WS_SUCCESS` +- 失敗時は負のエラーコード -### wolfSSH_SFTP_ClearOfst() +**関連項目** +- `wolfSSH_SFTP_SaveOfst()` +- `wolfSSH_SFTP_Interrupt()` +### wolfSSH_SFTP_ClearOfst() -**用法** -**説明** -保存されている全オフセット値をクリアします。 +```c +#include +int wolfSSH_SFTP_ClearOfst(WOLFSSH* ssh); +``` -**戻り値** +**説明** -**WS_SUCCESS** - 成功 +セッションについて保存されているすべての転送オフセットをクリアします。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
+- `ssh` - wolfSSH セッションへのポインター +**戻り値** -``` -#include -int wolfSSH_SFTP_ClearOfst(WOLFSSH* ssh); -``` -**使用例** +- `WS_SUCCESS` +- 失敗時は負のエラーコード **関連項目** -wolfSSH_SFTP_SaveOfst()
- -wolfSSH_SFTP_GetOfst()
- +- `wolfSSH_SFTP_SaveOfst()` +- `wolfSSH_SFTP_GetOfst()` ### wolfSSH_SFTP_Interrupt() -**用法** - -**説明** - -中断フラグをセットし、get/putコマンドを停止します。 - - -**戻り値** - -なし - -**引数** - -**ssh** – WOLFSSHオブジェクトへのポインター
- - -``` +```c #include + void wolfSSH_SFTP_Interrupt(WOLFSSH* ssh); ``` -**使用例** - -``` -WOLFSSH* ssh; +**説明** -//set up ssh and do sftp connections -... - -if (wolfSSH_SFTP_ClearOfst(ssh) != WS_SUCCESS) { -//handle error -} -``` +進行中の get または put の転送を停止するために、セッションに割り込みフラグを設定 +します。転送を後で再開できるように、現在のオフセットを wolfSSH_SFTP_SaveOfst() で +保存できます。 +**引数** -``` -WOLFSSH* ssh; -char from[NAME_SZ]; -char to[NAME_SZ]; -word64 ofst; +- `ssh` - wolfSSH セッションへのポインター -//set up ssh and do sftp connections -... +**戻り値** -wolfSSH_SFTP_Interrupt(ssh); -wolfSSH_SFTP_SaveOfst(ssh, from, to, ofst); -``` +なし **関連項目** -wolfSSH_SFTP_SaveOfst()
- -wolfSSH_SFTP_GetOfst()
+- `wolfSSH_SFTP_SaveOfst()` +- `wolfSSH_SFTP_GetOfst()` - -## コマンド機能 +## コマンド関数 @@ -846,428 +565,304 @@ wolfSSH_SFTP_GetOfst()
-**用法** - -**説明** +```c +#include -"remove"パケットをチャネルを通じて送信します。削除するファイル名"f"は相手に渡されます。 +int wolfSSH_SFTP_Remove(WOLFSSH* ssh, char* f); +``` -**戻り値** +**説明** -**WS_SUCCESS** - 成功 +`f` で指定された名前のファイルを削除するために、ピアに remove 要求を送信します。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
-**f** - 削除したいファイル名 - - -``` -#include -int wolfSSH_SFTP_Remove(WOLFSSH* ssh , char* f ); -``` - -**使用例** - -``` -WOLFSSH* ssh; -int ret; -char* name[NAME_SZ]; +- `ssh` - wolfSSH セッションへのポインター +- `f` - 削除するファイルの NULL 終端の名前 -//set up ssh and do sftp connections -... +**戻り値** -ret = wolfSSH_SFTP_Remove(ssh, name); -``` +- `WS_SUCCESS` +- 失敗時は負のエラーコード **関連項目** -wolfSSH_SFTP_accept()
- -wolfSSH_SFTP_connect()
- +- `wolfSSH_SFTP_RMDIR()` ### wolfSSH_SFTP_MKDIR() -**用法** - -**説明** - -チャネルを通して“mkdir”パケットを送信します。相手に作成するディレクトリ名が"dir"として渡されます。現時点では、属性は使用されず、既定の属性が使用されます。 +```c +#include +int wolfSSH_SFTP_MKDIR(WOLFSSH* ssh, char* dir, WS_SFTP_FILEATRB* atr); +``` -**戻り値** +**説明** -**WS_SUCCESS** - 成功 +`dir` で指定された名前のディレクトリを作成するために、ピアに mkdir 要求を送信します。 +`atr` 属性は現在使用されておらず、代わりにデフォルトの属性が適用されます。 **引数** -ssh – WOLFSSHオブジェクトへのポインター
- -dir - NULL終端された作成するディレクトリ名を示す文字列
+- `ssh` - wolfSSH セッションへのポインター +- `dir` - 作成するディレクトリの NULL 終端の名前 +- `atr` - 新しいディレクトリの属性（現在は未使用） -atr - ディレクトリ作成に使う属性値 - - -``` -#include -int wolfSSH_SFTP_MKDIR(WOLFSSH* ssh, char* dir,　WS_SFTP_FILEATRB* atr); -``` - -**使用例** - -``` -WOLFSSH* ssh; -int ret; -char* dir[DIR_SZ]; - -//set up ssh and do sftp connections -... +**戻り値** -ret = wolfSSH_SFTP_MKDIR(ssh, dir, DIR_SZ); -``` +- `WS_SUCCESS` +- 失敗時は負のエラーコード **関連項目** -wolfSSH_SFTP_accept()
- -wolfSSH_SFTP_connect()
+- `wolfSSH_SFTP_RMDIR()` ### wolfSSH_SFTP_RMDIR() -**用法** - -**説明** +```c +#include -“rmdir”パケットをチャネルを通じて送信します。削除するディレクトリ名は"dir"として相手に送られます。 +int wolfSSH_SFTP_RMDIR(WOLFSSH* ssh, char* dir); +``` -**戻り値** +**説明** -**WS_SUCCESS** - 成功 +`dir` で指定された名前のディレクトリを削除するために、ピアに rmdir 要求を送信します。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
- -**dir** - NULL終端された削除するディレクトリ名を示す文字列
+- `ssh` - wolfSSH セッションへのポインター +- `dir` - 削除するディレクトリの NULL 終端の名前 +**戻り値** -``` -#include -int wolfSSH_SFTP_RMDIR(WOLFSSH* ssh , char* dir ); -``` -**使用例** - -``` -WOLFSSH* ssh; -int ret; -char* dir[DIR_SZ]; - -//set up ssh and do sftp connections -... - -ret = wolfSSH_SFTP_RMDIR(ssh, dir); -``` +- `WS_SUCCESS` +- 失敗時は負のエラーコード **関連項目** -wolfSSH_SFTP_accept()
- -wolfSSH_SFTP_connect()
+- `wolfSSH_SFTP_MKDIR()` ### wolfSSH_SFTP_Rename() -**用法** - -**説明** - -“rename”パケットをチャネルを通じて送信します。相手側のファイル名を“old” から “nw”に変更しようとします。 +```c +#include +int wolfSSH_SFTP_Rename(WOLFSSH* ssh, const char* old, const char* nw); +``` -**戻り値** +**説明** -**WS_SUCCESS** - 成功 +ピアに rename 要求を送信し、ファイル `old` を `nw` に名前変更します。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
+- `ssh` - wolfSSH セッションへのポインター +- `old` - 現在のファイル名 +- `nw` - 新しいファイル名 -**old** - 旧ファイル名
+**戻り値** -**nw** - 新ファイル名 +- `WS_SUCCESS` +- 失敗時は負のエラーコード +**関連項目** -``` -#include -int wolfSSH_SFTP_Rename(WOLFSSH* ssh , const char* old ,　const char* nw); -``` +- `wolfSSH_SFTP_Remove()` -**使用例** +### wolfSSH_SFTP_LS() -``` -WOLFSSH* ssh; -int ret; -char* old[NAME_SZ]; -char* nw[NAME_SZ]; //new file name -//set up ssh and do sftp connections -... +```c +#include -ret = wolfSSH_SFTP_Rename(ssh, old, nw); +WS_SFTPNAME* wolfSSH_SFTP_LS(WOLFSSH* ssh, char* dir); ``` -**関連項目** - -wolfSSH_SFTP_accept()
- -wolfSSH_SFTP_connect() - - -### wolfSSH_SFTP_LS() - - +**説明** -**用法** +`dir` 内のファイルとディレクトリを一覧表示します。これは REALPATH、OPENDIR、READDIR、 +CLOSE の各操作を実行する高レベルのヘルパーです。返されたリストは +wolfSSH_SFTPNAME_list_free() で解放する必要があります。 -**説明** +**引数** -LS操作（全ファイルとディレクトリのリストを取得する）を現在のワーキングディレクトリで実行します。 -この関数はREALPATH, OPENDIR, READDIR と CLOSE操作を実行する高水準関数です。 +- `ssh` - wolfSSH セッションへのポインター +- `dir` - 一覧表示するディレクトリ **戻り値** -成功時にはWS_SFTPNAME構造体のリストを返します。失敗時にはNULLを返します。 - -**引数** +- 成功時は `WS_SFTPNAME` 構造体のリストへのポインター +- 失敗時は `NULL` -**ssh** – WOLFSSHオブジェクトへのポインター
+**関連項目** -**dir** - リストを作成するディレクトリ名 +- `wolfSSH_SFTPNAME_list_free()` +- `wolfSSH_SFTP_RealPath()` +### wolfSSH_SFTP_CHMOD() -``` +```c #include -WS_SFTPNAME* wolfSSH_SFTP_LS(WOLFSSH* ssh , char* dir ); -``` +int wolfSSH_SFTP_CHMOD(WOLFSSH* ssh, char* n, char* oct); +``` +**説明** -**使用例** +ファイルまたはディレクトリ `n` のパーミッションビットを、8 進文字列 `oct`（例えば +"644"）で指定されたモードに変更します。新しいパーミッションを含む SETSTAT 要求を送信 +することで実装されています。 -``` -WOLFSSH* ssh; -int ret; -char* dir[DIR_SZ]; -WS_SFTPNAME* name; -WS_SFTPNAME* tmp; - -//set up ssh and do sftp connections -... - -name = wolfSSH_SFTP_LS(ssh, dir); -tmp = name; -while (tmp != NULL) { -printf("%s\n", tmp->fName); -tmp = tmp->next; -} -wolfSSH_SFTPNAME_list_free(name); -``` +**引数** -**関連項目** +- `ssh` - wolfSSH セッションへのポインター +- `n` - ファイルまたはディレクトリの NULL 終端の名前 +- `oct` - 8 進のパーミッション文字列（例えば "755"） -wolfSSH_SFTP_accept()
+**戻り値** -wolfSSH_SFTP_connect()
+- `WS_SUCCESS` +- 失敗時は負のエラーコード -wolfSSH_SFTPNAME_list_free()
+**関連項目** +- `wolfSSH_SFTP_SetSTAT()` ### wolfSSH_SFTP_Get() -**用法** - -**説明** - -相手からファイルを取得するget操作を実行し、ローカルディレクトリに配置します。この関数は高水準関数であり、LSTAT, OPEN, READ, とCLOSEを実行します。関数の実行を中断したい場合には、wolfSSH_SFTP_Interruptを呼び出すことができます。 +```c +#include +int wolfSSH_SFTP_Get(WOLFSSH* ssh, char* from, char* to, + byte resume, WS_STATUS_CB* statusCb); +``` -**戻り値** +**説明** -**WS_SUCCESS** - 成功 -その他の値はすべてエラーとみなすべきです。 +ピアからローカルパスへファイルをダウンロードします。これは LSTAT、OPEN、READ、CLOSE +の各操作を実行する高レベルのヘルパーです。進行中の転送は wolfSSH_SFTP_Interrupt() で +中断できます。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
- -**from** - 取得するファイルの名前
- -**to** - 配置する際のファイルの名前
- -**resume** - 操作を再開するか（1は再開する、0はしない）
- -**statusCb** - ステータスを取得するコールバック関数 +- `ssh` - wolfSSH セッションへのポインター +- `from` - 取得するリモートファイルの名前 +- `to` - ファイルを書き込むローカルパス +- `resume` - 以前に中断した転送を再開するには非ゼロ、それ以外は 0 +- `statusCb` - 転送の進捗とともに呼び出されるコールバック。または `NULL` +**戻り値** - -``` -#include -int wolfSSH_SFTP_Get(WOLFSSH* ssh , char* from , char* to ,　byte resume ,　WS_STATUS_CB* statusCb ); -``` - -**使用例** - -``` -static void myStatusCb(WOLFSSH* sshIn, long bytes, char* name) -{ -char buf[80]; -WSNPRINTF(buf, sizeof(buf), "Processed %8ld\t bytes -\r", bytes); -WFPUTS(buf, fout); -(void)name; -(void)sshIn; -} -... -WOLFSSH* ssh; -char* from[NAME_SZ]; -char* to[NAME_SZ]; - -//set up ssh and do sftp connections -... - -if (wolfSSH_SFTP_Get( ssh , from , to , 0 , & myStatusCb ) != WS_SUCCESS) { -//handle error case -} -``` +- `WS_SUCCESS` +- 失敗時は負のエラーコード **関連項目** -wolfSSH_SFTP_accept()
- -wolfSSH_SFTP_connect()
- +- `wolfSSH_SFTP_Put()` +- `wolfSSH_SFTP_Interrupt()` ### wolfSSH_SFTP_Put() -**用法** +```c +#include + +int wolfSSH_SFTP_Put(WOLFSSH* ssh, char* from, char* to, + byte resume, WS_STATUS_CB* statusCb); +``` **説明** -ローカルのファイルを相手のディレクトリに配置するput操作を実行します。この関数は高水準関数であり、OPEN, WRITE, と CLOSE操作を実行します。操作を中断する場合にはwolfSSH_SFTP_Interruptを呼び出してください。 +ローカルファイルをピアへアップロードします。これは OPEN、WRITE、CLOSE の各操作を +実行する高レベルのヘルパーです。進行中の転送は wolfSSH_SFTP_Interrupt() で中断でき +ます。 + +**引数** +- `ssh` - wolfSSH セッションへのポインター +- `from` - 送信するローカルファイルの名前 +- `to` - ファイルを書き込むリモートパス +- `resume` - 以前に中断した転送を再開するには非ゼロ、それ以外は 0 +- `statusCb` - 転送の進捗とともに呼び出されるコールバック。または `NULL` **戻り値** -**WS_SUCCESS** - 成功
+- `WS_SUCCESS` +- 失敗時は負のエラーコード -その他の値はすべてエラーとみなすべきです。 +**関連項目** -**引数** +- `wolfSSH_SFTP_Get()` +- `wolfSSH_SFTP_Interrupt()` -**ssh** – WOLFSSHオブジェクトへのポインター
+## SFTP サーバー関数 -**from** - 配置したい対象ファイルの名前
-**to** - 配置先でのファイルの名前
-**resume** - 操作を再開するかのフラグ(1は再開、0は再開しない）
+### wolfSSH_SFTP_read() -**statusCb** - ステータスを取得するコールバック関数 -``` +```c #include -int wolfSSH_SFTP_Put(WOLFSSH* ssh, char* from, char* to, byte resume, WS_STATUS_CB* statusCb); -``` -**使用例** -``` -static void myStatusCb(WOLFSSH* sshIn, long bytes, char* name) -{ -char buf[80]; -WSNPRINTF(buf, sizeof(buf), "Processed %8ld\t bytes -\r", bytes); -WFPUTS(buf, fout); -(void)name; -(void)sshIn; -} -... - -WOLFSSH* ssh; -char* from[NAME_SZ]; -char* to[NAME_SZ]; - -//set up ssh and do sftp connections -... - -if (wolfSSH_SFTP_Put(ssh, from, to, 0, &myStatusCb) != -WS_SUCCESS) { -//handle error case -} +int wolfSSH_SFTP_read(WOLFSSH* ssh); ``` -**関連項目** +**説明** -wolfSSH_SFTP_accept()
+サーバー側 SFTP のメインエントリポイントです。I/O バッファから読み取り、受信した +SFTP パケットの種類に基づいて適切な内部ハンドラーへディスパッチします。SFTP 要求を +処理するために、サーバーループからこれを呼び出します。 -wolfSSH_SFTP_connect()
+**引数** +- `ssh` - wolfSSH セッションへのポインター -## SFTPサーバー機能 +**戻り値** +- `WS_SUCCESS` +- 失敗時は負のエラーコード +**関連項目** -### wolfSSH_SFTP_read() +- `wolfSSH_SFTP_accept()` +- `wolfSSH_SFTP_PendingSend()` +### wolfSSH_SFTP_PendingSend() +```c +#include -**用法** +int wolfSSH_SFTP_PendingSend(WOLFSSH* ssh); +``` **説明** -メインのSFTPサーバー機能を提供する関数です。到着するパケットを処理し、I/O　バッファからデータを読み出しSFTPパケットのタイプに応じて内部の関数を呼び出します。 - - -**戻り値** - -**WS_SUCCESS** - 成功 +SFTP レイヤーに、送信待ちのバッファされた送出データがあるかどうかを報告します。これ +は、非ブロッキング I/O を駆動する際に、もう一度送信を試みる必要があることを知るのに +役立ちます。 **引数** -**ssh** – WOLFSSHオブジェクトへのポインター
+- `ssh` - wolfSSH セッションへのポインター +**戻り値** -``` -#include -int wolfSSH_SFTP_read(WOLFSSH* ssh ); -``` - - -**使用例** - -``` -WOLFSSH* ssh; - -//set up ssh and do sftp connections -... -if (wolfSSH_SFTP_read(ssh) != WS_SUCCESS) { -//handle error case -} -``` +- 送信待ちのデータがある場合は非ゼロ +- 送信待ちのデータがない場合は 0 **関連項目** -wolfSSH_SFTP_accept()
- -wolfSSH_SFTP_connect()
+- `wolfSSH_SFTP_read()` diff --git a/wolfSSH/src-ja/chapter15.md b/wolfSSH/src-ja/chapter15.md new file mode 100644 index 00000000..7124d9a7 --- /dev/null +++ b/wolfSSH/src-ja/chapter15.md @@ -0,0 +1,282 @@ +# wolfSSH SCP API リファレンス + +この章では、wolfSSH における SCP（Secure Copy）ファイル転送のパブリック +アプリケーションプログラミングインターフェイスについて説明します。 + +この章のすべての関数を使用するには、wolfSSH を SCP サポート付き +（`WOLFSSH_SCP`、`./configure --enable-scp` により有効化）でビルドする必要が +あります。 + +## SCP 転送関数 + +### wolfSSH_SCP_connect() + +```c +#include + +int wolfSSH_SCP_connect(WOLFSSH* ssh, byte* cmd); +``` + +**説明** + +確立済みの SSH 接続上で、SCP コマンド `cmd` をサーバーに送信して SCP セッション +を開始します。ファイルを転送する前に、クライアント側で呼び出します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `cmd` - サーバーに送信する SCP コマンド + +**戻り値** + +- `WS_SUCCESS` +- 失敗時は負のエラーコード + +**関連項目** + +- `wolfSSH_SCP_to()` +- `wolfSSH_SCP_from()` + +### wolfSSH_SCP_to() + +```c +#include + +int wolfSSH_SCP_to(WOLFSSH* ssh, const char* src, const char* dst); +``` + +**説明** + +ローカルのファイルまたはディレクトリ `src` を、SSH 接続を通じてリモートの宛先 +`dst` に送信（アップロード）します。クライアント側で呼び出します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `src` - ローカルのソースファイルまたはディレクトリのパス +- `dst` - リモートピア上の宛先パス + +**戻り値** + +- `WS_SUCCESS` +- 失敗時は負のエラーコード + +**関連項目** + +- `wolfSSH_SCP_from()` +- `wolfSSH_SCP_connect()` + +### wolfSSH_SCP_from() + +```c +#include + +int wolfSSH_SCP_from(WOLFSSH* ssh, const char* src, const char* dst); +``` + +**説明** + +リモートのファイルまたはディレクトリ `src` をピアから取得（ダウンロード）し、 +SSH 接続を通じてローカルの宛先 `dst` に書き込みます。クライアント側で呼び出し +ます。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `src` - リモートピア上のソースファイルまたはディレクトリのパス +- `dst` - ローカルシステム上の宛先パス + +**戻り値** + +- `WS_SUCCESS` +- 失敗時は負のエラーコード + +**関連項目** + +- `wolfSSH_SCP_to()` +- `wolfSSH_SCP_connect()` + +### wolfSSH_SetScpErrorMsg() + +```c +#include + +int wolfSSH_SetScpErrorMsg(WOLFSSH* ssh, const char* message); +``` + +**説明** + +セッションにカスタムのエラーメッセージ文字列を設定します。この文字列は、SCP 転送 +が失敗したときにピアへ報告されます。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `message` - 報告する NULL 終端のエラーメッセージ + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +## SCP コールバック + +アプリケーションが管理するストレージで SCP を使用する場合（例えばファイルシステム +のないシステム上や、転送をフィルタリングする場合）、アプリケーションは送信および +受信のコールバックを登録します。各コールバックにはユーザーコンテキストポインター +を渡すことができます。 + +### wolfSSH_SetScpRecv() + +```c +#include + +void wolfSSH_SetScpRecv(WOLFSSH_CTX* ctx, WS_CallbackScpRecv cb); +``` + +**説明** + +コンテキストに SCP 受信コールバックを登録します。このコールバックは受信ファイル +が受け取られる際に呼び出され、アプリケーション自身がデータを保存できるようにし +ます。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - SCP 受信コールバック + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_SetScpRecvCtx()` +- `wolfSSH_SetScpSend()` + +### wolfSSH_SetScpSend() + +```c +#include + +void wolfSSH_SetScpSend(WOLFSSH_CTX* ctx, WS_CallbackScpSend cb); +``` + +**説明** + +コンテキストに SCP 送信コールバックを登録します。このコールバックはピアがファイル +を要求した際に呼び出され、アプリケーション自身がデータを供給できるようにします。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `cb` - SCP 送信コールバック + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_SetScpSendCtx()` +- `wolfSSH_SetScpRecv()` + +### wolfSSH_SetScpRecvCtx() + +```c +#include + +void wolfSSH_SetScpRecvCtx(WOLFSSH* ssh, void* ctx); +``` + +**説明** + +SCP 受信コールバックに渡されるユーザーコンテキストポインターを設定します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - 受信コールバックに渡すユーザーコンテキストポインター + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_GetScpRecvCtx()` + +### wolfSSH_SetScpSendCtx() + +```c +#include + +void wolfSSH_SetScpSendCtx(WOLFSSH* ssh, void* ctx); +``` + +**説明** + +SCP 送信コールバックに渡されるユーザーコンテキストポインターを設定します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - 送信コールバックに渡すユーザーコンテキストポインター + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_GetScpSendCtx()` + +### wolfSSH_GetScpRecvCtx() + +```c +#include + +void* wolfSSH_GetScpRecvCtx(WOLFSSH* ssh); +``` + +**説明** + +wolfSSH_SetScpRecvCtx() で以前に設定されたユーザーコンテキストポインターを返し +ます。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- SCP 受信コンテキストポインター。設定されていない場合は `NULL` + +**関連項目** + +- `wolfSSH_SetScpRecvCtx()` + +### wolfSSH_GetScpSendCtx() + +```c +#include + +void* wolfSSH_GetScpSendCtx(WOLFSSH* ssh); +``` + +**説明** + +wolfSSH_SetScpSendCtx() で以前に設定されたユーザーコンテキストポインターを返し +ます。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター + +**戻り値** + +- SCP 送信コンテキストポインター。設定されていない場合は `NULL` + +**関連項目** + +- `wolfSSH_SetScpSendCtx()` diff --git a/wolfSSH/src-ja/chapter16.md b/wolfSSH/src-ja/chapter16.md new file mode 100644 index 00000000..be54ce4c --- /dev/null +++ b/wolfSSH/src-ja/chapter16.md @@ -0,0 +1,676 @@ +# wolfSSH 追加 API リファレンス + +この章では、wolfSSH の残りのパブリックインターフェイス、すなわち ssh-agent +フォワーディング、鍵生成、ロギング、証明書マネージャー、およびプラットフォーム +移植レイヤーについて説明します。 + +## SSH エージェント関数 + +これらの関数は ssh-agent フォワーディングをサポートします。使用するには、wolfSSH +をエージェントサポート付き（`WOLFSSH_AGENT`、`./configure --enable-agent` により +有効化）でビルドする必要があります。 + +### wolfSSH_AGENT_new() + +```c +#include + +WOLFSSH_AGENT_CTX* wolfSSH_AGENT_new(void* heap); +``` + +**説明** + +新しい ssh-agent コンテキストを割り当てて初期化します。 + +**引数** + +- `heap` - メモリ割り当てに使用するヒープへのポインター。または `NULL` + +**戻り値** + +- 新しいエージェントコンテキストへのポインター。失敗時は `NULL` + +**関連項目** + +- `wolfSSH_AGENT_free()` + +### wolfSSH_AGENT_free() + +```c +#include + +void wolfSSH_AGENT_free(WOLFSSH_AGENT_CTX* agent); +``` + +**説明** + +wolfSSH_AGENT_new() で以前に割り当てられた ssh-agent コンテキストを解放します。 + +**引数** + +- `agent` - 解放するエージェントコンテキスト + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_AGENT_new()` + +### wolfSSH_CTX_set_agent_cb() + +```c +#include + +int wolfSSH_CTX_set_agent_cb(WOLFSSH_CTX* ctx, + WS_CallbackAgent agentCb, WS_CallbackAgentIO agentIoCb); +``` + +**説明** + +コンテキストにエージェントコールバックとエージェント I/O コールバックを登録し +ます。これらのコールバックにより、アプリケーションはエージェント要求を処理し、 +エージェント I/O を実行できます。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `agentCb` - エージェントコールバック +- `agentIoCb` - エージェント I/O コールバック + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**関連項目** + +- `wolfSSH_set_agent_cb_ctx()` + +### wolfSSH_set_agent_cb_ctx() + +```c +#include + +int wolfSSH_set_agent_cb_ctx(WOLFSSH* ssh, void* ctx); +``` + +**説明** + +エージェントコールバックに渡されるユーザーコンテキストポインターを設定します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `ctx` - エージェントコールバックに渡すユーザーコンテキストポインター + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_CTX_AGENT_enable() + +```c +#include + +int wolfSSH_CTX_AGENT_enable(WOLFSSH_CTX* ctx, byte isEnabled); +``` + +**説明** + +コンテキストから作成されるセッションについて、ssh-agent フォワーディングを有効 +または無効にします。 + +**引数** + +- `ctx` - wolfSSH コンテキストへのポインター +- `isEnabled` - エージェントフォワーディングを有効にするには非ゼロ、無効にする + には 0 + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**関連項目** + +- `wolfSSH_AGENT_enable()` + +### wolfSSH_AGENT_enable() + +```c +#include + +int wolfSSH_AGENT_enable(WOLFSSH* ssh, byte isEnabled); +``` + +**説明** + +単一のセッションについて、ssh-agent フォワーディングを有効または無効にします。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `isEnabled` - エージェントフォワーディングを有効にするには非ゼロ、無効にする + には 0 + +**戻り値** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**関連項目** + +- `wolfSSH_CTX_AGENT_enable()` + +### wolfSSH_AGENT_Relay() + +```c +#include + +int wolfSSH_AGENT_Relay(WOLFSSH* ssh, + const byte* msg, word32* msgSz, byte* rsp, word32* rspSz); +``` + +**説明** + +エージェントプロトコルメッセージをエージェントへ中継し、エージェントの応答を返し +ます。入力時 `rspSz` は `rsp` バッファのサイズを保持し、出力時には書き込まれた +応答のサイズを保持します。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `msg` - 中継するエージェントメッセージ +- `msgSz` - メッセージのサイズへのポインター +- `rsp` - エージェントの応答を受け取るバッファ +- `rspSz` - 入力時は応答バッファのサイズ、出力時は応答のサイズが設定される + +**戻り値** + +- `WS_SUCCESS` +- 失敗時は負のエラーコード + +### wolfSSH_AGENT_SignRequest() + +```c +#include + +int wolfSSH_AGENT_SignRequest(WOLFSSH* ssh, + const byte* digest, word32 digestSz, + byte* sig, word32* sigSz, + const byte* keyBlob, word32 keyBlobSz, word32 flags); +``` + +**説明** + +`keyBlob` で識別される鍵を使用して、指定された `digest` に署名するようエージェント +に要求します。生成された署名は `sig` に書き込まれます。 + +**引数** + +- `ssh` - wolfSSH セッションへのポインター +- `digest` - 署名するダイジェスト +- `digestSz` - ダイジェストのサイズ +- `sig` - 署名を受け取るバッファ +- `sigSz` - 入力時は署名バッファのサイズ、出力時は署名のサイズが設定される +- `keyBlob` - どの鍵で署名するかを識別する公開鍵ブロブ +- `keyBlobSz` - 鍵ブロブのサイズ +- `flags` - 署名要求のフラグ + +**戻り値** + +- `WS_SUCCESS` +- 失敗時は負のエラーコード + +## 鍵生成関数 + +これらの関数は SSH 鍵ペアを生成します。使用するには、wolfSSH を鍵生成サポート付き +（`WOLFSSH_KEYGEN`、`./configure --enable-keygen` により有効化）でビルドし、対応 +するアルゴリズムが wolfCrypt で有効になっている必要があります。 + +### wolfSSH_MakeRsaKey() + +```c +#include + +int wolfSSH_MakeRsaKey(byte* out, word32 outSz, word32 size, word32 e); +``` + +**説明** + +公開指数 `e` を使用して `size` ビットの RSA 鍵ペアを生成し、エンコードされた鍵を +`out` に書き込みます。 + +**引数** + +- `out` - 生成された鍵を受け取るバッファ +- `outSz` - 出力バッファのサイズ +- `size` - RSA 鍵のサイズ（ビット単位、例えば 2048） +- `e` - RSA 公開指数（例えば 65537） + +**戻り値** + +- 成功時は書き込まれたバイト数 +- 失敗時は負のエラーコード + +**関連項目** + +- `wolfSSH_MakeEcdsaKey()` + +### wolfSSH_MakeEcdsaKey() + +```c +#include + +int wolfSSH_MakeEcdsaKey(byte* out, word32 outSz, word32 size); +``` + +**説明** + +指定された `size`（ビット単位、例えば NIST P-256 の場合 256）の曲線に対する ECDSA +鍵ペアを生成し、エンコードされた鍵を `out` に書き込みます。 + +**引数** + +- `out` - 生成された鍵を受け取るバッファ +- `outSz` - 出力バッファのサイズ +- `size` - ECC 曲線のサイズ（ビット単位、例えば 256、384、または 521） + +**戻り値** + +- 成功時は書き込まれたバイト数 +- 失敗時は負のエラーコード + +**関連項目** + +- `wolfSSH_MakeRsaKey()` +- `wolfSSH_MakeEd25519Key()` + +### wolfSSH_MakeEd25519Key() + +```c +#include + +int wolfSSH_MakeEd25519Key(byte* out, word32 outSz, word32 size); +``` + +**説明** + +Ed25519 鍵ペアを生成し、エンコードされた鍵を `out` に書き込みます。 + +**引数** + +- `out` - 生成された鍵を受け取るバッファ +- `outSz` - 出力バッファのサイズ +- `size` - 鍵のサイズ（ビット単位、Ed25519 の場合 256） + +**戻り値** + +- 成功時は書き込まれたバイト数 +- 失敗時は負のエラーコード + +**関連項目** + +- `wolfSSH_MakeEcdsaKey()` + +## ロギング関数 + +これらの関数は wolfSSH のデバッグロギングを制御します。ロギングのコードは、wolfSSH +を `DEBUG_WOLFSSH`（`./configure --enable-debug` により有効化）または `WOLFSSH_SSHD` +付きでビルドした場合にコンパイルされます。 + +### wolfSSH_SetLoggingCb() + +```c +#include + +void wolfSSH_SetLoggingCb(wolfSSH_LoggingCb logF); +``` + +**説明** + +デフォルトのロギング出力の代わりに、ログメッセージをそのログレベルおよびメッセージ +テキストとともに受け取るコールバックを登録します。 + +**引数** + +- `logF` - ロギングコールバック + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_LogEnabled()` + +### wolfSSH_LogEnabled() + +```c +#include + +int wolfSSH_LogEnabled(void); +``` + +**説明** + +現在ロギングが有効かどうかを報告します。 + +**引数** + +なし + +**戻り値** + +- ロギングが有効な場合は非ゼロ +- ロギングが無効な場合は 0 + +### wolfSSH_Log() + +```c +#include + +void wolfSSH_Log(enum wolfSSH_LogLevel level, const char* const fmt, ...); +``` + +**説明** + +指定されたレベルで printf 形式のフォーマット済みログメッセージを書き込みます。 +ログレベルは、低いものから高いものへ順に `WS_LOG_DEBUG`、`WS_LOG_INFO`、 +`WS_LOG_WARN`、`WS_LOG_ERROR`、`WS_LOG_USER`、およびサブシステムごとのレベル +`WS_LOG_SFTP`、`WS_LOG_SCP`、`WS_LOG_AGENT`、`WS_LOG_CERTMAN` です。 + +**引数** + +- `level` - メッセージの `wolfSSH_LogLevel` +- `fmt` - printf 形式のフォーマット文字列 +- `...` - フォーマット文字列に対する引数 + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_SetLoggingCb()` + +## 証明書マネージャー関数 + +証明書マネージャーは、証明書ベースの認証のために X.509 証明書を検証します。これ +らの関数を使用するには、wolfSSH を証明書サポート付き（`WOLFSSH_CERTS`、 +`./configure --enable-certs` により有効化）でビルドする必要があります。 + +### wolfSSH_CERTMAN_new() + +```c +#include + +WOLFSSH_CERTMAN* wolfSSH_CERTMAN_new(void* heap); +``` + +**説明** + +新しい証明書マネージャーを割り当てて初期化します。 + +**引数** + +- `heap` - メモリ割り当てに使用するヒープへのポインター。または `NULL` + +**戻り値** + +- 新しい証明書マネージャーへのポインター。失敗時は `NULL` + +**関連項目** + +- `wolfSSH_CERTMAN_free()` + +### wolfSSH_CERTMAN_free() + +```c +#include + +void wolfSSH_CERTMAN_free(WOLFSSH_CERTMAN* cm); +``` + +**説明** + +wolfSSH_CERTMAN_new() で以前に割り当てられた証明書マネージャーを解放します。 + +**引数** + +- `cm` - 解放する証明書マネージャー + +**戻り値** + +なし + +**関連項目** + +- `wolfSSH_CERTMAN_new()` + +### wolfSSH_CERTMAN_LoadRootCA_buffer() + +```c +#include + +int wolfSSH_CERTMAN_LoadRootCA_buffer(WOLFSSH_CERTMAN* cm, + const unsigned char* rootCa, word32 rootCaSz); +``` + +**説明** + +信頼されたルート CA 証明書をバッファから証明書マネージャーに読み込みます。読み込ま +れたルートは、ピアから提示された証明書を検証するために使用されます。 + +**引数** + +- `cm` - 証明書マネージャー +- `rootCa` - ルート CA 証明書を含むバッファ +- `rootCaSz` - ルート CA バッファのサイズ + +**戻り値** + +- `WS_SUCCESS` +- 失敗時は負のエラーコード + +**関連項目** + +- `wolfSSH_CERTMAN_VerifyCerts_buffer()` + +### wolfSSH_CERTMAN_VerifyCerts_buffer() + +```c +#include + +int wolfSSH_CERTMAN_VerifyCerts_buffer(WOLFSSH_CERTMAN* cm, + const unsigned char* cert, word32 certSz, word32 certCount); +``` + +**説明** + +バッファに含まれる `certCount` 個の証明書のチェーンを、証明書マネージャーに読み +込まれたルート CA に対して検証します。 + +**引数** + +- `cm` - 証明書マネージャー +- `cert` - 証明書チェーンを含むバッファ +- `certSz` - 証明書バッファのサイズ +- `certCount` - チェーン内の証明書の数 + +**戻り値** + +- `WS_SUCCESS` +- 失敗時は負のエラーコード + +**関連項目** + +- `wolfSSH_CERTMAN_LoadRootCA_buffer()` + +## 移植性関数 + +これらの関数は wolfSSH のプラットフォーム移植レイヤーの一部を構成し、サポートされる +ターゲット間でファイルシステム操作および文字列操作を抽象化します。主に内部的に、 +また wolfSSH を新しいプラットフォームに移植する際に使用されます。利用可能な関数の +正確なセットは、ターゲットのビルド構成によって異なります。 + +### wfopen() + +```c +#include + +int wfopen(WFILE** f, const char* filename, const char* mode); +``` + +**説明** + +移植可能なファイルオープンラッパーです。アクセスモード `mode` を使用して +`filename` を開き、得られたファイルハンドルを `f` に格納します。 + +**引数** + +- `f` - 開かれたファイルハンドルを受け取る +- `filename` - 開くファイルのパス +- `mode` - アクセスモード文字列（C ライブラリの `fopen` と同様） + +**戻り値** + +- 成功時は 0 +- 失敗時は非ゼロ + +### wstrnstr() + +```c +#include + +char* wstrnstr(const char* s1, const char* s2, unsigned int n); +``` + +**説明** + +`s1` の先頭 `n` バイト以内で、部分文字列 `s2` が最初に出現する位置を見つけます。 + +**引数** + +- `s1` - 検索対象の文字列 +- `s2` - 見つける部分文字列 +- `n` - `s1` を検索する最大バイト数 + +**戻り値** + +- `s1` 内で `s2` が最初に出現する位置へのポインター。見つからない場合は `NULL` + +### wstrncat() + +```c +#include + +char* wstrncat(char* s1, const char* s2, size_t n); +``` + +**説明** + +文字列 `s2` の最大 `n` バイトを `s1` の末尾に追加します。 + +**引数** + +- `s1` - 追加先の文字列。その場で追加される +- `s2` - 追加するソース文字列 +- `n` - 追加する最大バイト数 + +**戻り値** + +- 追加先の文字列 `s1` へのポインター + +### wstrdup() + +```c +#include + +char* wstrdup(const char* s1, void* heap, int type); +``` + +**説明** + +文字列 `s1` を複製します。複製は指定された `heap` から割り当てられます。 + +**引数** + +- `s1` - 複製する文字列 +- `heap` - 割り当てに使用するヒープ +- `type` - 割り当てタイプのヒント + +**戻り値** + +- 複製された文字列へのポインター。失敗時は `NULL` + +### WS_FindFirstFileA() + +**利用可能性** + +Windows ビルド（`USE_WINDOWS_API`）で利用可能です。 + +```c +#include + +void* WS_FindFirstFileA(const char* fileName, + char* realFileName, size_t realFileNameSz, int* isDir, void* heap); +``` + +**説明** + +`fileName` に対するディレクトリ列挙を開始し、検索ハンドルと最初に一致したエントリ +を返します。`isDir` には、そのエントリがディレクトリかどうかを示す値が設定され +ます。 + +**引数** + +- `fileName` - 列挙するディレクトリまたは検索パターン +- `realFileName` - 一致したファイル名を受け取るバッファ +- `realFileNameSz` - `realFileName` バッファのサイズ +- `isDir` - エントリがディレクトリの場合に非ゼロが設定される出力 +- `heap` - 割り当てに使用するヒープ + +**戻り値** + +- 成功時は不透明な検索ハンドル、失敗時は `NULL` + +**関連項目** + +- `WS_FindNextFileA()` + +### WS_FindNextFileA() + +**利用可能性** + +Windows ビルド（`USE_WINDOWS_API`）で利用可能です。 + +```c +#include + +int WS_FindNextFileA(void* findHandle, + char* realFileName, size_t realFileNameSz); +``` + +**説明** + +WS_FindFirstFileA() で開始したディレクトリ列挙を継続し、次に一致したエントリを +返します。 + +**引数** + +- `findHandle` - WS_FindFirstFileA() が返した検索ハンドル +- `realFileName` - 一致したファイル名を受け取るバッファ +- `realFileNameSz` - `realFileName` バッファのサイズ + +**戻り値** + +- 別のエントリが返された場合は非ゼロ +- これ以上エントリがない場合は 0 + +**関連項目** + +- `WS_FindFirstFileA()` diff --git a/wolfSSH/src-ja/chapter17.md b/wolfSSH/src-ja/chapter17.md new file mode 100644 index 00000000..9fd3b2d6 --- /dev/null +++ b/wolfSSH/src-ja/chapter17.md @@ -0,0 +1,101 @@ +# wolfSSH プリプロセッサガードマクロ + +wolfSSH の多くの機能、アルゴリズム、関数は、ビルド時のプリプロセッサマクロによって +制御されます。この章は、アプリケーションが設定することを意図したマクロのリファレンス +です。これらはビルド時にコンパイラのコマンドライン（例えば `CPPFLAGS`/`CFLAGS`）を +通じて、または「wolfSSH のビルド」の章で説明した `./configure` オプションによって +定義されます。 + +## アルゴリズム無効化マクロ + +以下の各 `WOLFSSH_NO_*` マクロは、1 つのアルゴリズム（またはアルゴリズムファミリー） +を無効にします。autotools ビルドでは、これらは通常、wolfCrypt でどのアルゴリズムが +有効になっているかに基づいて自動的に設定されます。wolfSSH からアルゴリズムを削除する +ために手動で定義することもできます。 + +2 つのアルゴリズムファミリーはデフォルトで「ソフト無効化」されています。これらは +コンパイルされており動作もしますが、再度有効化しない限り鍵交換時にアドバタイズ +されません。 + +| マクロ | 効果 | +|--------------------------------------|------------------------------------| +| `WOLFSSH_NO_SHA1_SOFT_DISABLE` | SHA-1 アルゴリズムはコンパイルされますが、デフォルトでは KEX 時にアドバタイズされません。デフォルトで SHA-1 アルゴリズムをアドバタイズするには、これを定義します。 | +| `WOLFSSH_NO_AES_CBC_SOFT_DISABLE` | AES-CBC アルゴリズムはコンパイルされますが、デフォルトでは KEX 時にアドバタイズされません。デフォルトで AES-CBC アルゴリズムをアドバタイズするには、これを定義します。 | +| `WOLFSSH_NO_SHA1` | HMAC およびデジタル署名における SHA-1 を無効にします。 | +| `WOLFSSH_NO_HMAC_SHA1` | HMAC-SHA1 を無効にします。 | +| `WOLFSSH_NO_HMAC_SHA1_96` | HMAC-SHA1-96 を無効にします。 | +| `WOLFSSH_NO_HMAC_SHA2_256` | HMAC-SHA2-256 を無効にします。 | +| `WOLFSSH_NO_HMAC_SHA2_512` | HMAC-SHA2-512 を無効にします。 | +| `WOLFSSH_NO_DH_GROUP1_SHA1` | SHA-1 を用いた DH グループ 1（Oakley 1）を無効にします。 | +| `WOLFSSH_NO_DH_GROUP14_SHA1` | SHA-1 を用いた DH グループ 14（Oakley 14）を無効にします。 | +| `WOLFSSH_NO_DH_GROUP14_SHA256` | SHA-256 を用いた DH グループ 14 を無効にします。 | +| `WOLFSSH_NO_DH_GROUP16_SHA512` | SHA-512 を用いた DH グループ 16 を無効にします。 | +| `WOLFSSH_NO_DH_GEX_SHA256` | SHA-256 を用いた DH グループ交換を無効にします。 | +| `WOLFSSH_NO_DH` | すべての DH 鍵合意を無効にします。 | +| `WOLFSSH_NO_ECDH_SHA2_NISTP256` | NIST P-256 を用いた ECDH 鍵交換を無効にします。 | +| `WOLFSSH_NO_ECDH_SHA2_NISTP384` | NIST P-384 を用いた ECDH 鍵交換を無効にします。 | +| `WOLFSSH_NO_ECDH_SHA2_NISTP521` | NIST P-521 を用いた ECDH 鍵交換を無効にします。 | +| `WOLFSSH_NO_ECDH` | すべての ECDH 鍵合意を無効にします。 | +| `WOLFSSH_NO_CURVE25519_SHA256` | Curve25519 鍵交換を無効にします。 | +| `WOLFSSH_NO_NISTP256_MLKEM768_SHA256` | NIST P-256 と ML-KEM-768 を組み合わせたポスト量子ハイブリッド鍵交換を無効にします。 | +| `WOLFSSH_NO_NISTP384_MLKEM1024_SHA384` | NIST P-384 と ML-KEM-1024 を組み合わせたポスト量子ハイブリッド鍵交換を無効にします。 | +| `WOLFSSH_NO_CURVE25519_MLKEM768_SHA256` | Curve25519 と ML-KEM-768 を組み合わせたポスト量子ハイブリッド鍵交換を無効にします。 | +| `WOLFSSH_NO_RSA` | RSA サーバー認証およびユーザー認証を無効にします。 | +| `WOLFSSH_NO_SSH_RSA_SHA1` | SHA-1 を用いた RSA サーバー認証を無効にします。 | +| `WOLFSSH_NO_ECDSA` | ECDSA サーバー認証およびユーザー認証を無効にします。 | +| `WOLFSSH_NO_ECDSA_SHA2_NISTP256` | NIST P-256 を用いた ECDSA 認証を無効にします。 | +| `WOLFSSH_NO_ECDSA_SHA2_NISTP384` | NIST P-384 を用いた ECDSA 認証を無効にします。 | +| `WOLFSSH_NO_ECDSA_SHA2_NISTP521` | NIST P-521 を用いた ECDSA 認証を無効にします。 | +| `WOLFSSH_NO_AES_CBC` | AES-CBC 暗号化を無効にします。 | +| `WOLFSSH_NO_AES_CTR` | AES-CTR 暗号化を無効にします。 | +| `WOLFSSH_NO_AES_GCM` | AES-GCM 暗号化を無効にします。 | +| `WOLFSSH_NO_AEAD` | すべての AEAD 暗号を無効にします。 | + +## 機能有効化マクロ + +これらのマクロはサブシステム全体を有効にします。autotools ビルドでは、各マクロは +以下に示す対応する `./configure` オプションによって定義されます。これらの機能の +ほとんどに関連する API は、API リファレンスの各章で説明されています。 + +| マクロ | 有効化する機能 | Configure オプション | +|--------------------------------|---------------------|------------------------------| +| `WOLFSSH_SFTP` | SFTP サポート | `--enable-sftp` | +| `WOLFSSH_SCP` | SCP サポート | `--enable-scp` | +| `WOLFSSH_FWD` | TCP/IP ポートフォワーディング | `--enable-fwd` | +| `WOLFSSH_AGENT` | ssh-agent フォワーディング | `--enable-agent` | +| `WOLFSSH_CERTS` | X.509 証明書サポート | `--enable-certs` | +| `WOLFSSH_TPM` | TPM 2.0 ホスト鍵サポート | `--enable-tpm` | +| `WOLFSSH_SSHD` | wolfsshd デーモン | `--enable-sshd` | +| `WOLFSSH_SHELL` | echoserver のシェルサポート | `--enable-shell` | +| `WOLFSSH_KEYGEN` | 鍵生成 API | `--enable-keygen` | +| `WOLFSSH_KEYBOARD_INTERACTIVE` | キーボードインタラクティブ認証 | `--enable-keyboard-interactive` | +| `WOLFSSH_SSHCLIENT` | wolfSSH クライアントアプリケーション | `--enable-sshclient` | +| `WOLFSSH_TERM` | PTY / 端末処理 | デフォルトで有効（削除するには `--disable-term`） | +| `WOLFSSH_SMALL_STACK` | リソース制約のあるターゲット向けのスタック使用量削減 | `--enable-smallstack` | + +次のマクロは、サブシステムを有効にするのではなく、動作を調整します。 + +| マクロ | 効果 | +|--------------------------------------|--------------------------------------------------| +| `WOLFSSH_NO_DEFAULT_LOGGING_CB` | 組み込みのデフォルトロギングコールバックを省略します。 | +| `WOLFSSH_NO_TIMESTAMP` | ログ出力からタイムスタンプを省略します。 | +| `WOLFSSH_NO_SYMLINK_CHECK` | SFTP のシンボリックリンク安全性チェックを無効にします。 | +| `WOLFSSH_NO_SFTP_BUFFER_ZERO` | 操作の間で SFTP 転送バッファをゼロクリアする処理をスキップします。 | + +## チューニングおよび値マクロ + +これらのマクロは、オン/オフのスイッチとして機能するのではなく、数値を取ります。 +デフォルトを上書きするには、ビルド時に定義します。 + +| マクロ | 意味 | デフォルト | +|-------------------------------------|-----------------------------------|--------------| +| `DEFAULT_WINDOW_SZ` | 初期のチャネルウィンドウサイズ（バイト単位）。 | 131072（128 KB） | +| `DEFAULT_MAX_PACKET_SZ` | チャネルの最大パケットサイズ（バイト単位）。 | 32768 | +| `DEFAULT_HIGHWATER_MARK` | 再鍵交換がトリガーされるまでのデフォルトのデータ最高水位（バイト単位）。 | 約 1 GB | +| `WOLFSSH_DEFAULT_MSG_HIGHWATER_MARK` | 再鍵交換がトリガーされるまでのデフォルトのパケット数最高水位。 | 0x80000000 | +| `WOLFSSH_MR_ROUNDS` | クライアントがサーバーの DH グループ交換素数を検査する際に使用する Miller-Rabin のラウンド数。 | 8 | +| `WOLFSSH_KEY_QUANTITY_REQ` | OpenSSH 形式の鍵ラッパーで必要な鍵の数。 | 1 | +| `WOLFSSH_MAX_FILENAME` | 最大ファイル名長（バイト単位）。 | 256 | +| `WOLFSSH_MAX_SFTP_RW` | SFTP の読み書きチャンクの最大サイズ（バイト単位）。 | 32768 | +| `WOLFSSH_MAX_SFTP_RECV` | SFTP の最大受信サイズ（バイト単位）。 | 32768 | +| `WOLFSSH_MAX_SFTP_NAME` | SFTP 名前リストの最大サイズ（バイト単位）。 | 1048576（1 MB） | diff --git a/wolfSSH/src/chapter13.md b/wolfSSH/src/chapter13.md index ba9107d8..5253e2e4 100644 --- a/wolfSSH/src/chapter13.md +++ b/wolfSSH/src/chapter13.md @@ -10,45 +10,107 @@ This section describes the public application program interfaces for the wolfSSH -The following API response codes are defined in: wolfssh/wolfssh/error.h and describe the different types of errors that can occur. +The following API response codes are defined in wolfssh/error.h and describe the different types of errors that can occur. `WS_SUCCESS` is 0; all error codes are negative. `WS_FATAL_ERROR` is a deprecated alias for `WS_ERROR`, and `WS_LAST_E` always tracks the last defined error code. - WS_SUCCESS (0): Function success -- WS_FATAL_ERROR (-1): General function failure -- WS_BAD_ARGUMENT (-2): Function argument out of bounds -- WS_MEMORY_E (-3): Memory allocation error -- WS_BUFFER_E (-4): Input/output buffer size error -- WS_PARSE_E (-5): General parsing error -- WS_NOT_COMPILED (-6): Feature not compiled in -- WS_OVERFLOW_E (-7): Would overflow if continued -- WS_BAD_USAGE (-8): Bad example usage -- WS_SOCKET_ERROR_E (-9): Socket error -- WS_WANT_READ (-10): IO callback would read block error -- WS_WANT_WRITE (-11): IO callback would write block error -- WS_RECV_OVERFLOW_E (-12): Received buffer overflow -- WS_VERSION_E (-13): Peer using wrong version of SSH -- WS_SEND_OOB_READ_E (-14): Attempted to read buffer out of bounds -- WS_INPUT_CASE_E (-15): Bad process input state, programming error -- WS_BAD_FILETYPE_E (-16): Bad filetype -- WS_UNIMPLEMENTED_E (-17): Feature not implemented -- WS_RSA_E (-18): RSA buffer error -- WS_BAD_FILE_E (-19): Bad file -- WS_INVALID_ALGO_ID (-20): invalid algorithm ID -- WS_DECRYPT_E (-21): Decrypt error -- WS_ENCRYPT_E (-22): Encrypt error -- WS_VERIFY_MAC_E (-23): verify mac error -- WS_CREATE_MAC_E (-24): Create mac error -- WS_RESOURCE_E (-25): Insufficient resources for new channel -- WS_INVALID_CHANTYPE (-26): Invalid channel type -- WS_INVALID_CHANID(-27): Peer requested invalid channel ID -- WS_INVALID_USERNAME(-28): Invalid user name -- WS_CRYPTO_FAILED(-29): Crypto action failed -- WS_INVALID_STATE_E(-30): Invalid State -- WC_EOF(-31): End of File -- WS_INVALID_PRIME_CURVE(-32): Invalid prime curve in ECC -- WS_ECC_E(-33): ECDSA buffer error -- WS_CHANOPEN_FAILED(-34): Peer returned channel open failure -- WS_REKEYING(-35): Rekeying with peer -- WS_CHANNEL_CLOSED(-36): Channel closed +- WS_ERROR (-1001): General function failure +- WS_FATAL_ERROR (-1001): Deprecated alias for WS_ERROR +- WS_BAD_ARGUMENT (-1002): Bad function argument +- WS_MEMORY_E (-1003): Memory allocation failure +- WS_BUFFER_E (-1004): Input/output buffer size error +- WS_PARSE_E (-1005): General parsing error +- WS_NOT_COMPILED (-1006): Feature not compiled in +- WS_OVERFLOW_E (-1007): Would overflow if continued +- WS_BAD_USAGE (-1008): Bad example usage +- WS_SOCKET_ERROR_E (-1009): Socket error +- WS_WANT_READ (-1010): Nonblocking read would block, call again +- WS_WANT_WRITE (-1011): Nonblocking write would block, call again +- WS_RECV_OVERFLOW_E (-1012): Received buffer overflow +- WS_VERSION_E (-1013): Peer using wrong version of SSH +- WS_SEND_OOB_READ_E (-1014): Attempted to read buffer out of bounds +- WS_INPUT_CASE_E (-1015): Bad process input state, programming error +- WS_BAD_FILETYPE_E (-1016): Bad file type +- WS_UNIMPLEMENTED_E (-1017): Feature not implemented +- WS_RSA_E (-1018): RSA buffer error +- WS_BAD_FILE_E (-1019): Bad file +- WS_INVALID_ALGO_ID (-1020): Invalid algorithm ID +- WS_DECRYPT_E (-1021): Decrypt error +- WS_ENCRYPT_E (-1022): Encrypt error +- WS_VERIFY_MAC_E (-1023): Verify MAC error +- WS_CREATE_MAC_E (-1024): Create MAC error +- WS_RESOURCE_E (-1025): Insufficient resources for new channel +- WS_INVALID_CHANTYPE (-1026): Invalid channel type +- WS_INVALID_CHANID (-1027): Peer requested invalid channel ID +- WS_INVALID_USERNAME (-1028): Invalid user name +- WS_CRYPTO_FAILED (-1029): Crypto action failed +- WS_INVALID_STATE_E (-1030): Invalid state +- WS_EOF (-1031): End of file +- WS_INVALID_PRIME_CURVE (-1032): Invalid prime curve in ECC +- WS_ECC_E (-1033): ECDSA buffer error +- WS_CHANOPEN_FAILED (-1034): Peer returned channel open failure +- WS_REKEYING (-1035): Status: rekey in progress +- WS_CHANNEL_CLOSED (-1036): Status: channel closed +- WS_INVALID_PATH_E (-1037): Invalid path +- WS_SCP_CMD_E (-1038): SCP command error +- WS_SCP_BAD_MSG_E (-1039): SCP bad message +- WS_SCP_PATH_LEN_E (-1040): SCP path too long +- WS_SCP_TIMESTAMP_E (-1041): SCP timestamp error +- WS_SCP_DIR_STACK_EMPTY_E (-1042): SCP directory stack empty +- WS_SCP_CONTINUE (-1043): Status: SCP continue +- WS_SCP_ABORT (-1044): Status: SCP abort +- WS_SCP_ENTER_DIR (-1045): Status: SCP enter directory +- WS_SCP_EXIT_DIR (-1046): Status: SCP exit directory +- WS_SCP_EXIT_DIR_FINAL (-1047): Status: SCP exit final directory +- WS_SCP_COMPLETE (-1048): Status: SCP transfer complete +- WS_SCP_INIT (-1049): Status: SCP transfer verified +- WS_MATCH_KEX_ALGO_E (-1050): Cannot match KEX algorithm with peer +- WS_MATCH_KEY_ALGO_E (-1051): Cannot match key algorithm with peer +- WS_MATCH_ENC_ALGO_E (-1052): Cannot match encryption algorithm with peer +- WS_MATCH_MAC_ALGO_E (-1053): Cannot match MAC algorithm with peer +- WS_PERMISSIONS (-1054): Permissions error +- WS_SFTP_COMPLETE (-1055): Status: SFTP connection established +- WS_NEXT_ERROR (-1056): Getting next value/state is error +- WS_CHAN_RXD (-1057): Status: channel data received +- WS_INVALID_EXTDATA (-1058): Invalid channel extended data type +- WS_SFTP_BAD_REQ_ID (-1060): SFTP bad request ID +- WS_SFTP_BAD_REQ_TYPE (-1061): SFTP bad request type +- WS_SFTP_STATUS_NOT_OK (-1062): SFTP status not OK +- WS_SFTP_FILE_DNE (-1063): SFTP file does not exist +- WS_SIZE_ONLY (-1064): Only getting size of buffer needed +- WS_CLOSE_FILE_E (-1065): Unable to close local file +- WS_PUBKEY_REJECTED_E (-1066): Server public key rejected +- WS_EXTDATA (-1067): Extended data available to be read +- WS_USER_AUTH_E (-1068): User authentication error +- WS_SSH_NULL_E (-1069): SSH object was null +- WS_SSH_CTX_NULL_E (-1070): SSH_CTX object was null +- WS_CHANNEL_NOT_CONF (-1071): Channel open not confirmed +- WS_CHANGE_AUTH_E (-1072): Changing auth type attempt +- WS_WINDOW_FULL (-1073): Channel window full +- WS_MISSING_CALLBACK (-1074): Callback is missing +- WS_DH_SIZE_E (-1075): DH prime larger than expected +- WS_PUBKEY_SIG_MIN_E (-1076): Signature too small +- WS_AGENT_NULL_E (-1077): Agent object was null +- WS_AGENT_NO_KEY_E (-1078): Agent does not have requested key +- WS_AGENT_CXN_FAIL (-1079): Could not connect to agent +- WS_SFTP_BAD_HEADER (-1080): SFTP bad header +- WS_CERT_NO_SIGNER_E (-1081): No signer certificate available +- WS_CERT_EXPIRED_E (-1082): Certificate expired +- WS_CERT_REVOKED_E (-1083): User certificate reported revoked +- WS_CERT_SIG_CONFIRM_E (-1084): Root certificate signature verify failure +- WS_CERT_OTHER_E (-1085): Other certificate issue +- WS_CERT_PROFILE_E (-1086): Certificate does not meet profile requirements +- WS_CERT_KEY_SIZE_E (-1087): Key size error +- WS_CTX_KEY_COUNT_E (-1088): Adding too many private keys +- WS_MATCH_UA_KEY_ID_E (-1089): Match user auth key failure +- WS_KEY_AUTH_MAGIC_E (-1090): OpenSSH key auth magic check failure +- WS_KEY_CHECK_VAL_E (-1091): OpenSSH key check value failure +- WS_KEY_FORMAT_E (-1092): OpenSSH key format failure +- WS_SFTP_NOT_FILE_E (-1093): Not a regular file +- WS_MSGID_NOT_ALLOWED_E (-1094): Message not allowed before user authentication +- WS_ED25519_E (-1095): Ed25519 failure +- WS_AUTH_PENDING (-1096): User authentication still pending +- WS_KDF_E (-1097): KDF error +- WS_DISCONNECT (-1098): Peer sent disconnect ### WS_IOerrors (enum) @@ -62,7 +124,7 @@ These are the return codes the library expects to receive from a user-provided I - WS_CBIO_ERR_CONN_RST (-3): Connection reset - WS_CBIO_ERR_ISR (-4): Interrupt - WS_CBIO_ERR_CONN_CLOSE (-5): Connection closed or EPIPE -- WS_CBIO_ERR_TIMEOUT (-6): Socket timeout" +- WS_CBIO_ERR_TIMEOUT (-6): Socket timeout ## Initialization / Shutdown @@ -70,60 +132,53 @@ These are the return codes the library expects to receive from a user-provided I ### wolfSSH_Init() +```c +#include - -**Synopsis** +int wolfSSH_Init(void); +``` **Description** -Initializes the wolfSSH library for use. Must be called once per application and before any other calls to the library. - -**Return Values** - -WS_SUCCESS -WS_CRYPTO_FAILED +Initializes the wolfSSH library for use. Must be called once per application before any other call into the library. **Parameters** None -**See Also** +**Return Values** -wolfSSH_Cleanup() +- `WS_SUCCESS` +- `WS_CRYPTO_FAILED` -``` -#include -int wolfSSH_Init(void); -``` +**See Also** -### wolfSSH_Cleanup() +- `wolfSSH_Cleanup()` +### wolfSSH_Cleanup() +```c +#include -**Synopsis** +int wolfSSH_Cleanup(void); +``` **Description** -Cleans up the wolfSSH library when done. Should be called at before termination of the application. After calling, do not make any more calls to the library. - -**Return Values** - -**WS_SUCCESS** - -**WS_CRYPTO_FAILED** +Cleans up the wolfSSH library when done. Should be called before termination of the application. After calling, do not make any more calls to the library. **Parameters** None -**See Also** +**Return Values** -wolfSSH_Init() +- `WS_SUCCESS` +- `WS_CRYPTO_FAILED` -``` -#include -int wolfSSH_Cleanup(void); -``` +**See Also** + +- `wolfSSH_Init()` ## Debugging output functions @@ -131,57 +186,51 @@ int wolfSSH_Cleanup(void); ### wolfSSH_Debugging_ON() +```c +#include - -**Synopsis** +void wolfSSH_Debugging_ON(void); +``` **Description** Enables debug logging during runtime. Does nothing when debugging is disabled at build time. -**Return Values** +**Parameters** None -**Parameters** +**Return Values** None **See Also** -wolfSSH_Debugging_OFF() - -``` -#include -void wolfSSH_Debugging_ON(void); -``` +- `wolfSSH_Debugging_OFF()` ### wolfSSH_Debugging_OFF() +```c +#include - -**Synopsis** +void wolfSSH_Debugging_OFF(void); +``` **Description** Disables debug logging during runtime. Does nothing when debugging is disabled at build time. -**Return Values** +**Parameters** None -**Parameters** +**Return Values** None **See Also** -wolfSSH_Debugging_ON() - -``` -#include -void wolfSSH_Debugging_OFF(void); -``` +- `wolfSSH_Debugging_ON()` ## Context Functions @@ -189,1995 +238,3663 @@ void wolfSSH_Debugging_OFF(void); ### wolfSSH_CTX_new() +```c +#include - -**Synopsis** +WOLFSSH_CTX* wolfSSH_CTX_new(byte side, void* heap); +``` **Description** Creates a wolfSSH context object. This object can be configured and then used as a factory for wolfSSH session objects. -**Return Values** +**Parameters** -**WOLFSSH_CTX*** – returns pointer to allocated WOLFSSH_CTX object or NULL +- `side` - the endpoint role: `WOLFSSH_ENDPOINT_SERVER` or `WOLFSSH_ENDPOINT_CLIENT` +- `heap` - pointer to a heap to use for memory allocations, or `NULL` -**Parameters** +**Return Values** -**side** – indicate client side (unimplemented) or server side -**heap** – pointer to a heap to use for memory allocations +- `WOLFSSH_CTX*` - pointer to the newly allocated context object +- `NULL` - on failure **See Also** -wolfSSH_wolfSSH_CTX_free() - -``` -#include -WOLFSSH_CTX* wolfSSH_CTX_new(byte side , void* heap ); -``` +- `wolfSSH_CTX_free()` ### wolfSSH_CTX_free() +```c +#include - -**Synopsis** +void wolfSSH_CTX_free(WOLFSSH_CTX* ctx); +``` **Description** Deallocates a wolfSSH context object. -**Return Values** +**Parameters** -None +- `ctx` - the wolfSSH context to free -**Parameters** +**Return Values** -**ctx** – the wolfSSH context used to initialize the wolfSSH session +None **See Also** -wolfSSH_wolfSSH_CTX_new() - -``` -#include -void wolfSSH_CTX_free(WOLFSSH_CTX* ctx ); -``` +- `wolfSSH_CTX_new()` ### wolfSSH_CTX_SetBanner() +```c +#include -**Synopsis** +int wolfSSH_CTX_SetBanner(WOLFSSH_CTX* ctx, const char* newBanner); +``` **Description** -Sets a banner message that a user can see. - -**Return Values** - -WS_BAD_ARGUMENT -WS_SUCCESS +Sets a banner message presented to the peer before authentication. **Parameters** -**ssh -** Pointer to wolfSSH session -**newBanner** - The banner message text. +- `ctx` - pointer to the wolfSSH context +- `newBanner` - the banner message text -``` -#include -int wolfSSH_CTX_SetBanner(WOLFSSH_CTX* ctx , const char* -newBanner ); -``` +**Return Values** -### wolfSSH_CTX_UsePrivateKey_buffer() +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +**See Also** +- `wolfSSH_CTX_UsePrivateKey_buffer()` -**Synopsis** +### wolfSSH_CTX_UsePrivateKey_buffer() -**Description** +```c +#include -This function loads a private key buffer into the SSH context. It is called with a buffer as input instead of a file. The buffer is provided by the **in** argument of size **inSz**. The argument **format** specifies the type of buffer: **WOLFSSH_FORMAT_ASN1** or **WOLFSSL_FORMAT_PEM** (unimplemented at this time). +int wolfSSH_CTX_UsePrivateKey_buffer(WOLFSSH_CTX* ctx, + const byte* in, word32 inSz, int format); +``` -**Return Values** +**Description** -**WS_SUCCESS -WS_BAD_ARGUMENT** – at least one of the parameters is invalid -**WS_BAD_FILETYPE_E** – wrong format -**WS_UNIMPLEMENTED_E** – support for PEM format not implemented -**WS_MEMORY_E** – out of memory condition -**WS_RSA_E** – cannot decode RSA key -**WS_BAD_FILE_E** – cannot parse buffer +Loads a private key from a buffer into the SSH context instead of from a file. The key is provided by the `in` argument of size `inSz`. The `format` argument specifies the buffer encoding: `WOLFSSH_FORMAT_ASN1` or `WOLFSSH_FORMAT_PEM` (PEM is unimplemented at this time). **Parameters** -**ctx** – pointer to the wolfSSH context -**in** – buffer containing the private key to be loaded -**inSz** – size of the input buffer -**format** – format of the private key located in the input buffer - -**See Also** +- `ctx` - pointer to the wolfSSH context +- `in` - buffer containing the private key to be loaded +- `inSz` - size of the input buffer +- `format` - format of the private key in the input buffer -wolfSSH_UseCert_buffer() -wolfSSH_UseCaCert_buffer() +**Return Values** -``` -#include -int wolfSSH_CTX_UsePrivateKey_buffer(WOLFSSH_CTX* ctx , -const byte* in , word32 inSz , int format ); -``` +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_BAD_FILETYPE_E` +- `WS_UNIMPLEMENTED_E` +- `WS_MEMORY_E` +- `WS_RSA_E` +- `WS_BAD_FILE_E` -## SSH Session Functions +**See Also** +- `wolfSSH_CTX_UseCert_buffer()` +### wolfSSH_CTX_UseCert_buffer() -### wolfSSH_new() +**Availability** +Requires `WOLFSSH_CERTS`. +```c +#include -**Synopsis** +int wolfSSH_CTX_UseCert_buffer(WOLFSSH_CTX* ctx, + const byte* cert, word32 certSz, int format); +``` **Description** -Creates a wolfSSH session object. It is initialized with the provided wolfSSH context. +Loads the server's X.509 certificate from a buffer into the context, for certificate-based host authentication. The `format` is `WOLFSSH_FORMAT_ASN1` or `WOLFSSH_FORMAT_PEM`. -**Return Values** +**Parameters** -**WOLFSSH*** – returns pointer to allocated WOLFSSH object or NULL +- `ctx` - pointer to the wolfSSH context +- `cert` - buffer containing the certificate +- `certSz` - size of the certificate buffer +- `format` - encoding of the certificate -**Parameters** +**Return Values** -**ctx** – the wolfSSH context used to initialize the wolfSSH session +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` **See Also** -wolfSSH_free() +- `wolfSSH_CTX_AddRootCert_buffer()` -``` -#include -WOLFSSH* wolfSSH_new(WOLFSSH_CTX* ctx ); -``` +### wolfSSH_CTX_AddRootCert_buffer() -### wolfSSH_free() +**Availability** +Requires `WOLFSSH_CERTS`. +```c +#include -**Synopsis** +int wolfSSH_CTX_AddRootCert_buffer(WOLFSSH_CTX* ctx, + const byte* cert, word32 certSz, int format); +``` **Description** -Deallocates a wolfSSH session object. - -**Return Values** - -None +Adds a trusted root CA certificate to the context, used to verify certificates presented by the peer. The `format` is `WOLFSSH_FORMAT_ASN1` or `WOLFSSH_FORMAT_PEM`. **Parameters** -**ssh** – session to deallocate +- `ctx` - pointer to the wolfSSH context +- `cert` - buffer containing the root certificate +- `certSz` - size of the certificate buffer +- `format` - encoding of the certificate -**See Also** +**Return Values** -wolfSSH_new() +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` -``` -#include -void wolfSSH_free(WOLFSSH* ssh ); -``` +**See Also** -### wolfSSH_set_fd() +- `wolfSSH_CTX_UseCert_buffer()` +## SSH Session Functions -**Synopsis** -**Description** +### wolfSSH_new() -Assigns the provided file descriptor to the ssh object. The ssh session will use the file descriptor for network I/O in the default I/O callbacks. +```c +#include -**Return Values** +WOLFSSH* wolfSSH_new(WOLFSSH_CTX* ctx); +``` -#### WS_SUCCESS +**Description** -WS_BAD_ARGUMENT – one of the parameters is invalid +Creates a wolfSSH session object, initialized with the provided wolfSSH context. **Parameters** -**ssh** – session to set the fd -**fd** – file descriptor for the socket used by the session +- `ctx` - the wolfSSH context used to initialize the session -**See Also** +**Return Values** -wolfSSH_get_fd() +- `WOLFSSH*` - pointer to the newly allocated session object +- `NULL` - on failure -``` -#include -int wolfSSH_set_fd(WOLFSSH* ssh , int fd ); -``` +**See Also** -### wolfSSH_get_fd() +- `wolfSSH_free()` +### wolfSSH_free() +```c +#include -**Synopsis** +void wolfSSH_free(WOLFSSH* ssh); +``` **Description** -This function returns the file descriptor ( **fd** ) used as the input/output facility for the SSH connection. Typically this will be a socket file descriptor. +Deallocates a wolfSSH session object. -**Return Values** +**Parameters** -**int** – file descriptor -**WS_BAD_ARGUEMENT** +- `ssh` - session to deallocate -**Parameters** +**Return Values** -**ssh** – pointer to the SSL session. +None **See Also** -wolfSSH_set_fd() +- `wolfSSH_new()` -``` +### wolfSSH_worker() + +```c #include -int wolfSSH_get_fd(const WOLFSSH* ssh ); + +int wolfSSH_worker(WOLFSSH* ssh, word32* channelId); ``` -## Data High Water Mark Functions +**Description** +Services the SSH connection: receives any pending inbound data and flushes pending outbound packets. This is the main driver call for a running session. On success, if `channelId` is not NULL, the ID of the channel that most recently received data is written to it. +**Parameters** -### wolfSSH_SetHighwater() +- `ssh` - pointer to the wolfSSH session +- `channelId` - optional output for the last channel ID that received data; may be NULL + +**Return Values** + +- `WS_SUCCESS` +- `WS_CHAN_RXD` +- `WS_REKEYING` +- `WS_WANT_READ` +- `WS_WANT_WRITE` +- `WS_BAD_ARGUMENT` + +**See Also** + +- `wolfSSH_GetLastRxId()` +### wolfSSH_GetLastRxId() -**Synopsis** +```c +#include + +int wolfSSH_GetLastRxId(WOLFSSH* ssh, word32* channelId); +``` **Description** -Sets the highwater mark for the ssh session. +Writes the channel ID of the channel that most recently received data into `channelId`. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `channelId` - output for the last received channel ID **Return Values** -WS_SUCCESS -WS_BAD_ARGUMENT +- `WS_SUCCESS` +- `WS_ERROR` -**Parameters** +**See Also** -**ssh -** Pointer to wolfSSH session -**highwater** - data indicating the highwater security mark +- `wolfSSH_worker()` -``` +### wolfSSH_set_fd() + +```c #include -int wolfSSH_SetHighwater(WOLFSSH* ssh , word32 highwater ); -``` -### wolfSSH_GetHighwater() +int wolfSSH_set_fd(WOLFSSH* ssh, WS_SOCKET_T fd); +``` +**Description** -**Synopsis** +Assigns the provided file descriptor to the session. The session uses this descriptor for network I/O in the default I/O callbacks. -**Description** +**Parameters** -Returns the highwater security mark +- `ssh` - session to set the descriptor on +- `fd` - file descriptor for the socket used by the session **Return Values** -**word32** - The highwater security mark. +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` -**Parameters** +**See Also** -**ssh -** Pointer to wolfSSH session +- `wolfSSH_get_fd()` -``` +### wolfSSH_get_fd() + +```c #include -word32 wolfSSH_GetHighwater(WOLFSSH* ssh ); -``` -### wolfSSH_SetHighwaterCb() +WS_SOCKET_T wolfSSH_get_fd(const WOLFSSH* ssh); +``` +**Description** -**Synopsis** +Returns the file descriptor used as the input/output facility for the SSH connection. Typically this is a socket file descriptor. -**Description** +**Parameters** -The wolfSSH_SetHighwaterCb function sets the highwater security mark for the SSH session as well as the high water call back. +- `ssh` - pointer to the wolfSSH session **Return Values** -none +- the session's socket file descriptor on success +- `WS_BAD_ARGUMENT` (or `INVALID_SOCKET` on Windows) if `ssh` is NULL -**Parameters** +**See Also** -**ctx** – The wolfSSH context used to initialize the wolfSSH session. -**highwater** - The highwater security mark. -**cb** - The call back highwater function. +- `wolfSSH_set_fd()` -``` +### wolfSSH_SetFilesystemHandle() + +```c #include -void wolfSSH_SetHighwaterCb(WOLFSSH_CTX* ctx , word32 highwater , -WS_CallbackHighwater cb ); -``` -### wolfSSH_SetHighwaterCtx() +int wolfSSH_SetFilesystemHandle(WOLFSSH* ssh, void* handle); +``` +**Description** -**Synopsis** +Associates a user-provided filesystem handle with the session. Ports that supply their own filesystem layer use this handle when performing file operations for the session. -**Description** +**Parameters** -The wolfSSH_SetHighwaterCTX function sets the highwater security mark for the given context. +- `ssh` - pointer to the wolfSSH session +- `handle` - opaque filesystem handle to associate with the session **Return Values** -none +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` -**Parameters** +**See Also** -**ssh -** pointer to wolfSSH session -**ctx** - pointer to highwater security mark in the wolfSSH context. +- `wolfSSH_GetFilesystemHandle()` -``` +### wolfSSH_GetFilesystemHandle() + +```c #include -void wolfSSH_SetHighwaterCtx(WOLFSSH* ssh, void* ctx); -``` -### wolfSSH_GetHighwaterCtx() +void* wolfSSH_GetFilesystemHandle(WOLFSSH* ssh); +``` +**Description** -**Synopsis** +Returns the filesystem handle previously associated with the session by wolfSSH_SetFilesystemHandle(), or NULL if none was set. -**Description** +**Parameters** -The wolfSSH_GetHighwaterCtx() returns the highwaterCtx security mark from the SSH session. +- `ssh` - pointer to the wolfSSH session **Return Values** -**void*** - the highwater security mark -**NULL** - if there is an error with the WOLFSSH object. - -**Parameters** +- the filesystem handle associated with the session +- `NULL` - if `ssh` is NULL or no handle was set -**ssh -** pointer to WOLFSSH object +**See Also** -``` -#include -void wolfSSH_GetHighwaterCtx(WOLFSSH* ssh ); -``` +- `wolfSSH_SetFilesystemHandle()` -## Error Checking +## Data High Water Mark Functions -### wolfSSH_get_error() +### wolfSSH_SetHighwater() +```c +#include -**Synopsis** +int wolfSSH_SetHighwater(WOLFSSH* ssh, word32 level); +``` **Description** -Returns the error set in the wolfSSH session object. +Sets the data highwater mark, in bytes, for the session. When the amount of data transferred reaches this level, the highwater callback is invoked (typically to trigger a rekey). -**Return Values** +**Parameters** -WS_ErrorCodes (enum) +- `ssh` - pointer to the wolfSSH session +- `level` - the highwater mark, in bytes -**Parameters** +**Return Values** -**ssh** – pointer to WOLFSSH object +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` **See Also** -wolfSSH_get_error_name() - -``` -#include -int wolfSSH_get_error(const WOLFSSH* ssh ); -``` +- `wolfSSH_GetHighwater()` -### wolfSSH_get_error_name() +### wolfSSH_GetHighwater() +```c +#include -**Synopsis** +word32 wolfSSH_GetHighwater(WOLFSSH* ssh); +``` **Description** -Returns the name of the error set in the wolfSSH session object. +Returns the current data highwater mark, in bytes, for the session. -**Return Values** +**Parameters** -**const char*** – error name string +- `ssh` - pointer to the wolfSSH session -**Parameters** +**Return Values** -**ssh** – pointer to WOLFSSH object +- the data highwater mark, in bytes **See Also** -wolfSSH_get_error() +- `wolfSSH_SetHighwater()` -``` -#include -const char* wolfSSH_get_error_name(const WOLFSSH* ssh ); -``` +### wolfSSH_SetHighwaterCb() -### wolfSSH_ErrorToName() +```c +#include -**Synopsis** +void wolfSSH_SetHighwaterCb(WOLFSSH_CTX* ctx, word32 level, + WS_CallbackHighwater cb); +``` **Description** -Returns the name of an error when called with an error number in the parameter. - -**Return Values** - -**const char*** – name of error string +Sets, at the context level, the default data highwater mark and the callback that is invoked when a session reaches it. Sessions created from this context inherit these defaults. **Parameters** -**err** - the int value of the error +- `ctx` - pointer to the wolfSSH context +- `level` - the default data highwater mark, in bytes +- `cb` - the highwater callback function -``` -#include -const char* wolfSSH_ErrorToName(int err ); -``` +**Return Values** -## I/O Callbacks +None +**See Also** +- `wolfSSH_SetHighwaterCtx()` -### wolfSSH_SetIORecv() +### wolfSSH_SetHighwaterCtx() -**Synopsis** +```c +#include + +void wolfSSH_SetHighwaterCtx(WOLFSSH* ssh, void* ctx); +``` **Description** -This function registers a receive callback for wolfSSL to get input data. +Sets the user context pointer that is passed to the session's highwater callback when it is invoked. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context pointer to pass to the highwater callback **Return Values** None -**Parameters** +**See Also** -**ctx** – pointer to the SSH context -**cb** – function to be registered as the receive callback for the wolfSSH context, **ctx**. The signature of this function must follow that as shown above in the Synopsis section. +- `wolfSSH_GetHighwaterCtx()` -``` -#include -void wolfSSH_SetIORecv(WOLFSSH_CTX* ctx , WS_CallbackIORecv cb ); -``` +### wolfSSH_GetHighwaterCtx() -### wolfSSH_SetIOSend() +```c +#include -**Synopsis** +void* wolfSSH_GetHighwaterCtx(WOLFSSH* ssh); +``` **Description** -This function registers a send callback for wolfSSL to write output data. +Returns the user context pointer previously set with wolfSSH_SetHighwaterCtx() that is passed to the highwater callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session **Return Values** -None +- the highwater user context pointer +- `NULL` - if `ssh` is invalid or no context was set -**Parameters** +**See Also** -**ctx** – pointer to the wolfSSH context -**cb** – function to be registered as the send callback for the wolfSSH context, **ctx**. The signature of this function must follow that as shown above in the Synopsis section. +- `wolfSSH_SetHighwaterCtx()` -``` +### wolfSSH_CTX_SetMsgHighwater() + +```c #include -void wolfSSH_SetIOSend(WOLFSSH_CTX* ctx , WS_CallbackIOSend cb ); -``` -### wolfSSH_SetIOReadCtx() +void wolfSSH_CTX_SetMsgHighwater(WOLFSSH_CTX* ctx, word32 level); +``` +**Description** -**Synopsis** +Sets, at the context level, the default packet-count highwater mark (RFC 4344, Section 3.1). When the number of packets sent or received on a session reaches this level, a rekey is triggered. Sessions created from this context inherit the default. -**Description** +**Parameters** -This function registers a context for the SSH session receive callback function. +- `ctx` - pointer to the wolfSSH context +- `level` - the packet-count highwater mark **Return Values** None -**Parameters** +**See Also** -**ssh** – pointer to WOLFSSH object -**ctx** – pointer to the context to be registered with the SSH session ( **ssh** ) receive callback -function. +- `wolfSSH_SetMsgHighwater()` -``` +### wolfSSH_SetMsgHighwater() + +```c #include -void wolfSSH_SetIOReadCtx(WOLFSSH* ssh , void* ctx ); -``` -### wolfSSH_SetIOWriteCtx() +void wolfSSH_SetMsgHighwater(WOLFSSH* ssh, word32 level); +``` +**Description** -**Synopsis** +Sets the packet-count highwater mark (RFC 4344, Section 3.1) for a single session. -**Description** +**Parameters** -This function registers a context for the SSH session’s send callback function. +- `ssh` - pointer to the wolfSSH session +- `level` - the packet-count highwater mark **Return Values** None -**Parameters** - -**ssh** – pointer to WOLFSSH session. -**ctx** – pointer to be registered with the SSH session’s ( **ssh** ) send callback function. +**See Also** -``` -#include -void wolfSSH_SetIOWriteCtx(WOLFSSH* ssh , void* ctx ); -``` +- `wolfSSH_GetMsgHighwater()` -### wolfSSH_GetIOReadCtx() +### wolfSSH_GetMsgHighwater() +```c +#include -**Synopsis** +word32 wolfSSH_GetMsgHighwater(WOLFSSH* ssh); +``` **Description** -This function return the ioReadCtx member of the WOLFSSH structure. - -**Return Values** - -**Void*** - pointer to the ioReadCtx member of the WOLFSSH structure. +Returns the current packet-count highwater mark for the session. **Parameters** -**ssh** – pointer to WOLFSSH object +- `ssh` - pointer to the wolfSSH session -``` -#include -void* wolfSSH_GetIOReadCtx(WOLFSSH* ssh ); -``` +**Return Values** -### wolfSSH_GetIOWriteCtx() +- the packet-count highwater mark +**See Also** -**Synopsis** +- `wolfSSH_SetMsgHighwater()` -**Description** +## Error Checking -This function returns the ioWriteCtx member of the WOLFSSH structure. -**Return Values** -**Void*** – pointer to the ioWriteCtx member of the WOLFSSH structure. +### wolfSSH_get_error() -**Parameters** -**ssh** – pointer to WOLFSSH object -``` +```c #include -void* wolfSSH_GetIOWriteCtx(WOLFSSH* ssh ); -``` -## User Authentication +int wolfSSH_get_error(const WOLFSSH* ssh); +``` +**Description** +Returns the last error set on the wolfSSH session object. -### wolfSSH_SetUserAuth() +**Parameters** +- `ssh` - pointer to the wolfSSH session -**Synopsis** +**Return Values** -**Description** +- a `WS_ErrorCodes` value (see Error Codes) -The wolfSSH_SetUserAuth() function is used to set the user authentication for the -current wolfSSH context if the context does not equal NULL. +**See Also** -**Return Values** +- `wolfSSH_get_error_name()` -None +### wolfSSH_get_error_name() -**Parameters** -**ctx** – pointer to the wolfSSH context -**cb** – call back function for the user authentication -``` +```c #include -void wolfSSH_SetUserAuth(WOLFSSH_CTX* ctx , -WS_CallbackUserAuth cb ) -``` -### wolfSSH_SetUserAuthCtx() +const char* wolfSSH_get_error_name(const WOLFSSH* ssh); +``` +**Description** -**Synopsis** +Returns the name string of the last error set on the wolfSSH session object. -**Description** +**Parameters** -The wolfSSH_SetUserAuthCtx() function is used to set the value of the user -authentication context in the SSH session. +- `ssh` - pointer to the wolfSSH session **Return Values** -None +- pointer to the error name string -**Parameters** +**See Also** -**ssh** – pointer to WOLFSSH object -**userAuthCtx** – pointer to the user authentication context +- `wolfSSH_get_error()` -``` -#include -void wolfSSH_SetUserAuthCtx(WOLFSSH* ssh , void* -userAuthCtx ) -``` +### wolfSSH_ErrorToName() -### wolfSSH_GetUserAuthCtx() +```c +#include -**Synopsis** +const char* wolfSSH_ErrorToName(int err); +``` **Description** -The wolfSSH_GetUserAuthCtx() function is used to return the pointer to the user -authentication context. +Returns the name string for the given wolfSSH error code. + +**Parameters** + +- `err` - the error code value (a `WS_ErrorCodes` value) **Return Values** -**Void*** – pointer to the user authentication context -**Null** – returns if ssh is equal to NULL +- pointer to the error name string -**Parameters** +**See Also** -**ssh** – pointer to WOLFSSH object +- `wolfSSH_get_error_name()` + +## I/O Callbacks -``` -#include -void* wolfSSH_GetUserAuthCtx(WOLFSSH* ssh ) -``` -### wolfSSH_SetKeyboardAuthPrompts() +### wolfSSH_SetIORecv() + + +```c +#include -**Synopsis** +void wolfSSH_SetIORecv(WOLFSSH_CTX* ctx, WS_CallbackIORecv cb); +``` **Description** -The wolfSSH_SetKeyboardAuthPrompts() function is used to setup the callback -which will provide the server with the prompts to send to the client. +Registers a receive callback used by wolfSSH to read input data. The callback signature is shown by the `WS_CallbackIORecv` type. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - function to register as the receive callback for the context **Return Values** None -**Parameters** +**See Also** -**ctx** - pointer to the wolfSSH context -**cb** - callback function to provide the keyboard prompts +- `wolfSSH_SetIOSend()` -``` -#include -void wolfSSH_SetKeyboardAuthPrompts(WOLFSSH_CTX* ctx, - WS_CallbackKeyboardAuthPrompts cb) -``` +### wolfSSH_SetIOSend() -### wolfSSH_SetKeyboardAuthCtx() +```c +#include -**Synopsis** +void wolfSSH_SetIOSend(WOLFSSH_CTX* ctx, WS_CallbackIOSend cb); +``` **Description** -The wolfSSH_SetKeyboardAuthCtx() function is used to setup the user context -for the wolfSSH_SetKeyboardAuthPrompts() function. +Registers a send callback used by wolfSSH to write output data. The callback signature is shown by the `WS_CallbackIOSend` type. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - function to register as the send callback for the context **Return Values** None -**Parameters** +**See Also** -**ssh** - pointer to the WOLFSSH object -**keyboardAuthCtx* - pointer to the user context data +- `wolfSSH_SetIORecv()` -``` +### wolfSSH_SetIOReadCtx() + + +```c #include -void wolfSSH_SetKeyboardAuthCtx(WOLFSSH* ssh, void* keyboardAuthCtx) + +void wolfSSH_SetIOReadCtx(WOLFSSH* ssh, void* ctx); ``` -## Set Username +**Description** +Registers a context passed to the session's receive (I/O read) callback. +**Parameters** -### wolfSSH_SetUsername() +- `ssh` - pointer to the wolfSSH session +- `ctx` - context to register with the session's receive callback + +**Return Values** +None + +**See Also** -**Synopsis** +- `wolfSSH_GetIOReadCtx()` -**Description** +### wolfSSH_SetIOWriteCtx() -Sets the username required for the SSH connection. -**Return Values** +```c +#include + +void wolfSSH_SetIOWriteCtx(WOLFSSH* ssh, void* ctx); +``` + +**Description** -WS_BAD_ARGUMENT -WS_SUCCESS -WS_MEMORY_E +Registers a context passed to the session's send (I/O write) callback. **Parameters** -**ssh -** Pointer to wolfSSH session -**username** - The input username for the SSH connection. +- `ssh` - pointer to the wolfSSH session +- `ctx` - context to register with the session's send callback -``` -#include -int wolfSSH_setUsername(WOLFSSH* ssh , const char* username ); -``` +**Return Values** -## Connection Functions +None -### wolfSSH_accept() +**See Also** + +- `wolfSSH_GetIOWriteCtx()` + +### wolfSSH_GetIOReadCtx() +```c +#include -**Synopsis** +void* wolfSSH_GetIOReadCtx(WOLFSSH* ssh); +``` **Description** -wolfSSH_accept is called on the server side and waits for an SSH client to initiate the -SSH handshake. +Returns the context previously registered for the session's receive (I/O read) callback. -wolfSSL_accept() works with both blocking and non-blocking I/O. When the underlying -I/O is non-blocking, wolfSSH_accept() will return when the underlying I/O could not -satisfy the needs of wolfSSH_accept to continue the handshake. In this case, a call to -wolfSSH_get_error() will yield either **WS_WANT_READ** or **WS_WANT_WRITE**. The -calling process must then repeat the call to wolfSSH_accept when data is available to -read and wolfSSH will pick up where it left off. When using a non-blocking socket, -nothing needs to be done, but select() can be used to check for the required condition. +**Parameters** -If the underlying I/O is blocking, wolfSSH_accept() will only return once the handshake -has been finished or an error occurred. +- `ssh` - pointer to the wolfSSH session **Return Values** -**WS_SUCCESS** - The function succeeded. -**WS_BAD_ARGUMENT** - A parameter value was null. -**WS_FATAL_ERROR** – There was an error, call wolfSSH_get_error() for more detail +- the registered read context pointer, or `NULL` if none -**Parameters** +**See Also** -**ssh** – pointer to the wolfSSH session +- `wolfSSH_SetIOReadCtx()` -**See Also** +### wolfSSH_GetIOWriteCtx() -wolfSSH_stream_read() -``` +```c #include -int wolfSSH_accept(WOLFSSH* ssh); + +void* wolfSSH_GetIOWriteCtx(WOLFSSH* ssh); ``` -### wolfSSH_connect() +**Description** +Returns the context previously registered for the session's send (I/O write) callback. -**Synopsis** +**Parameters** -**Description** +- `ssh` - pointer to the wolfSSH session -This function is called on the client side and initiates an SSH handshake with a server. -When this function is called, the underlying communication channel has already been -set up. +**Return Values** -wolfSSH_connect() works with both blocking and non-blocking I/O. When the -underlying I/O is non-blocking, wolfSSH_connect() will return when the underlying I/O -could not satisfy the needs of wolfSSH_connect to continue the handshake. In this -case, a call to wolfSSH_get_error() will yield either **WS_WANT_READ** or -**WS_WANT_WRITE**. The calling process must then repeat the call to -wolfSSH_connect() when the underlying I/O is ready and wolfSSH will pick up where it -left off. When using a non-blocking socket, nothing needs to be done, but select() can -be used to check for the required condition. +- the registered write context pointer, or `NULL` if none -If the underlying I/O is blocking, wolfSSH_connect() will only return once the handshake -has been finished or an error occurred. +**See Also** -**Return Values** +- `wolfSSH_SetIOWriteCtx()` -**WS_BAD_ARGUMENT -WS_FATAL_ERROR -WS_SUCCESS** - This will return if the call is successful. +## User Authentication -**Parameters** -**ssh** - Pointer to wolfSSH session -``` -#include -int wolfSSH_connect(WOLFSSH* ssh); -``` +### wolfSSH_SetUserAuth() -### wolfSSH_shutdown() +```c +#include -**Synopsis** +void wolfSSH_SetUserAuth(WOLFSSH_CTX* ctx, WS_CallbackUserAuth cb); +``` **Description** -Closes and disconnects the SSH channel. +Registers the user authentication callback on the wolfSSH context. The callback is invoked during the handshake to authenticate the peer. -**Return Values** +**Parameters** -**WS_BAD_ARGUMENT** - returned if the parameter is NULL -**WS_SUCCES** - returns when everything has been correctly shutdown +- `ctx` - pointer to the wolfSSH context +- `cb` - the user authentication callback function -**Parameters** +**Return Values** -**ssh -** Pointer to wolfSSH session +None -``` -#include -int wolfSSH_shutdown(WOLFSSH* ssh); -``` +**See Also** -### wolfSSH_stream_read() +- `wolfSSH_SetUserAuthCtx()` + +### wolfSSH_SetUserAuthCtx() +```c +#include -**Synopsis** +void wolfSSH_SetUserAuthCtx(WOLFSSH* ssh, void* userAuthCtx); +``` **Description** -wolfSSH_stream_read reads up to **bufSz** bytes from the internal decrypted data stream -buffer. The bytes are removed from the internal buffer. +Sets the user context pointer passed to the user authentication callback. -wolfSSH_stream_read() works with both blocking and non-blocking I/O. When the -underlying I/O is non-blocking, wolfSSH_stream_read() will return when the underlying -I/O could not satisfy the needs of wolfSSH_stream_read to continue the read. In this -case, a call to wolfSSH_get_error() will yield either **WS_WANT_READ** or -**WS_WANT_WRITE**. The calling process must then repeat the call to -wolfSSH_stream_read when data is available to read and wolfSSH will pick up where it -left off. When using a non-blocking socket, nothing needs to be done, but select() can -be used to check for the required condition. +**Parameters** -If the underlying I/O is blocking, wolfSSH_stream_read() will only return when data is -available or an error occurred. +- `ssh` - pointer to the wolfSSH session +- `userAuthCtx` - user context pointer to pass to the authentication callback **Return Values** -**>0** – number of bytes read upon success -**0** – returned on socket failure caused by either a clean connection shutdown or a -socket. -**WS_BAD_ARGUMENT** – returns if one or more parameters is equal to NULL -**WS_EOF** – returns when end of stream is reached -**WS_FATAL_ERROR** – there was an error, call **wolfSSH_get_error()** for more detail -**WS_REKEYING** if currently a rekey is in process, use wolfSSH_worker() to complete +None -**Parameters** +**See Also** -**ssh** – pointer to the wolfSSH session +- `wolfSSH_GetUserAuthCtx()` -``` +### wolfSSH_GetUserAuthCtx() + + +```c #include -int wolfSSH_stream_read(WOLFSSH* ssh , -byte* buf , word32 bufSz ); + +void* wolfSSH_GetUserAuthCtx(WOLFSSH* ssh); ``` -**buf** – buffer where wolfSSH_stream_read() will place the data -**bufSz** – size of the buffer +**Description** -**See Also** +Returns the user context pointer previously set with wolfSSH_SetUserAuthCtx(). -wolfSSH_accept() -wolfSSH_stream_send() +**Parameters** +- `ssh` - pointer to the wolfSSH session -### wolfSSH_stream_send() +**Return Values** +- the user authentication context pointer +- `NULL` - if `ssh` is NULL +**See Also** -**Synopsis** +- `wolfSSH_SetUserAuthCtx()` -**Description** +### wolfSSH_SetUserAuthTypes() -wolfSSH_stream_send writes **bufSz** bytes from buf to the SSH stream data buffer. -wolfSSH_stream_send() works with both blocking and non-blocking I/O. When the -underlying I/O is non-blocking, wolfSSH_stream_send() will return a want write -error when the underlying I/O could not satisfy the needs of wolfSSH_stream_send -and there is still pending data in the SSH stream data buffer to be sent. In this -case, a call to wolfSSH_get_error() will yield either **WS_WANT_READ** or -**WS_WANT_WRITE**. The calling process must then repeat the call to -wolfSSH_stream_send when the socket is ready to send and wolfSSH will send out -any pending data left in the SSH stream data buffer then pull data from the input -**buf**. When using a non-blocking socket, nothing needs to be done, but select() -can be used to check for the required condition. - -If the underlying I/O is blocking, wolfSSH_stream_send() will only return when the data -has been sent or an error occurred. - -In cases where I/O want write/read is not the error encountered (i.e. WS_REKEYING) -then wolfSSH_worker() should be called until the internal SSH processes are completed. +```c +#include -**Return Values** +void wolfSSH_SetUserAuthTypes(WOLFSSH_CTX* ctx, WS_CallbackUserAuthTypes cb); +``` + +**Description** -**>0** – number of bytes written to SSH stream data buffer upon success -**0** – returned on socket failure caused by either a clean connection shutdown or a socket -error, call **wolfSSH_get_error()** for more detail -**WS_FATAL_ERROR** – there was an error, call wolfSSH_get_error() for more detail -**WS_BAD_ARGUMENT** if any of the parameters is null -**WS_REKEYING** if currently a rekey is in process, use wolfSSH_worker() to complete +Registers a callback that reports which user authentication types the server offers. The callback returns a bitmask of the `WOLFSSH_USERAUTH_*` values (for example, `WOLFSSH_USERAUTH_PASSWORD` or `WOLFSSH_USERAUTH_PUBLICKEY`). **Parameters** -**ssh** – pointer to the wolfSSH session -**buf** – buffer wolfSSH_stream_send() will send +- `ctx` - pointer to the wolfSSH context +- `cb` - the user authentication types callback -``` -#include -int wolfSSH_stream_send(WOLFSSH* ssh , byte* buf , word32 -bufSz ); -``` +**Return Values** -**bufSz** – size of the buffer +None **See Also** -wolfSSH_accept() -wolfSSH_stream_read() +- `wolfSSH_SetUserAuth()` +### wolfSSH_SetUserAuthResult() -### wolfSSH_stream_exit() - +```c +#include -**Synopsis** +void wolfSSH_SetUserAuthResult(WOLFSSH_CTX* ctx, WS_CallbackUserAuthResult cb); +``` **Description** -This function is used to exit the SSH stream. +Registers a callback that is invoked with the result of a user authentication attempt. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the user authentication result callback **Return Values** -**WS_BAD_ARGUMENT** - returned if a parameter value is NULL -**WS_SUCCESS** - returns if function was a success +None -**Parameters** +**See Also** -**ssh** – Pointer to wolfSSH session -**status** – the status of the SSH connection +- `wolfSSH_SetUserAuthResultCtx()` -``` +### wolfSSH_SetUserAuthResultCtx() + +```c #include -int wolfSSH_stream_exit(WOLFSSH* ssh, int status); -``` -### wolfSSH_TriggerKeyExchange() +void wolfSSH_SetUserAuthResultCtx(WOLFSSH* ssh, void* userAuthResultCtx); +``` +**Description** -**Synopsis** +Sets the user context pointer passed to the user authentication result callback. -**Description** +**Parameters** -Triggers key exchange process. Prepares and sends packet of allocated handshake -info. +- `ssh` - pointer to the wolfSSH session +- `userAuthResultCtx` - user context pointer to pass to the result callback **Return Values** -**WS_BAD_ARGUEMENT** – if **ssh** is NULL -**WS_SUCCESS** +None -**Parameters** +**See Also** -**ssh** – pointer to the wolfSSH session +- `wolfSSH_GetUserAuthResultCtx()` -``` +### wolfSSH_GetUserAuthResultCtx() + +```c #include -int wolfSSH_TriggerKeyExchange(WOLFSSH* ssh ); + +void* wolfSSH_GetUserAuthResultCtx(WOLFSSH* ssh); ``` -## Channel Callbacks +**Description** -Interfaces to the wolfSSH library return single int values. Communicating -status of asynchronous information, like the peer opening a channel, isn't -easy with that interface. wolfSSH uses callback functions to notify the -calling application of changes in state of a channel. +Returns the user context pointer previously set with wolfSSH_SetUserAuthResultCtx(). -There are callback functions for receipt of the following SSHv2 protocol -messages: +**Parameters** -* SSH_MSG_CHANNEL_OPEN -* SSH_MSG_CHANNEL_OPEN_CONFIRMATION -* SSH_MSG_CHANNEL_OPEN_FAILURE -* SSH_MSG_CHANNEL_REQUEST - - "shell" - - "subsystem" - - "exec" -* SSH_MSG_CHANNEL_EOF -* SSH_MSG_CHANNEL_CLOSE +- `ssh` - pointer to the wolfSSH session -### Callback Function Prototypes +**Return Values** -The channel callback functions all take a pointer to a **WOLFSSH_CHANNEL** -object, _channel_, and a pointer to the application defined data structure, -_ctx_. Properties about the channel may be queried using API functions. +- the user authentication result context pointer +- `NULL` - if `ssh` is NULL -``` -typedef int (*WS_CallbackChannelOpen)(WOLFSSH_CHANNEL* channel, void* ctx); -typedef int (*WS_CallbackChannelReq)(WOLFSSH_CHANNEL* channel, void* ctx); -typedef int (*WS_CallbackChannelEof)(WOLFSSH_CHANNEL* channel, void* ctx); -typedef int (*WS_CallbackChannelClose)(WOLFSSH_CHANNEL* channel, void* ctx); -``` +**See Also** -### wolfSSH_CTX_SetChannelOpenCb +- `wolfSSH_SetUserAuthResultCtx()` -**Synopsis** +### wolfSSH_CTX_SetPublicKeyCheck() -``` +```c #include -int wolfSSH_CTX_SetChannelOpenCb(WOLFSSH_CTX* ctx, - WS_CallbackChannelOpen cb); + +void wolfSSH_CTX_SetPublicKeyCheck(WOLFSSH_CTX* ctx, + WS_CallbackPublicKeyCheck cb); ``` **Description** -Sets the callback function, _cb_, into the wolfSSH _ctx_ used when a Channel -Open (**SSH_MSG_CHANNEL_OPEN**) message is received from the peer. +Registers a callback, used on the client side, to check the server's public (host) key before continuing the handshake. The application can accept or reject the key from this callback. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the public key check callback **Return Values** -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** +None +**See Also** -### wolfSSH_CTX_SetChannelOpenRespCb +- `wolfSSH_SetPublicKeyCheckCtx()` -**Synopsis** +### wolfSSH_SetPublicKeyCheckCtx() -``` +```c #include -int wolfSSH_CTX_SetChannelOpenRespCb(WOLFSSH_CTX* ctx, - WS_CallbackChannelOpen confCb, - WS_CallbackChannelOpen failCb); + +void wolfSSH_SetPublicKeyCheckCtx(WOLFSSH* ssh, void* publicKeyCheckCtx); ``` **Description** -Sets the callback functions, _confCb_ and _failCb_, into the wolfSSH _ctx_ -used when a Channel Open Confirmation (**SSH_MSG_CHANNEL_OPEN_CONFIRMATION**) -or a Channel Open Failure (**SSH_MSG_CHANNEL_OPEN_FAILURE**) message is -received from the peer. +Sets the user context pointer passed to the public key check callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `publicKeyCheckCtx` - user context pointer to pass to the callback **Return Values** -* **WS_SUCCESS** - Setting callbacks in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** +None +**See Also** -### wolfSSH_CTX_SetChannelReqShellCb +- `wolfSSH_GetPublicKeyCheckCtx()` -**Synopsis** +### wolfSSH_GetPublicKeyCheckCtx() -``` +```c #include -int wolfSSH_CTX_SetChannelReqShellCb(WOLFSSH_CTX* ctx, - WS_CallbackChannelReq cb); + +void* wolfSSH_GetPublicKeyCheckCtx(WOLFSSH* ssh); ``` **Description** -Sets the callback function, _cb_, into the wolfSSH _ctx_ used when a Channel -Request (**SSH_MSG_CHANNEL_REQUEST**) message is received from the peer for -a _shell_. +Returns the user context pointer previously set with wolfSSH_SetPublicKeyCheckCtx(). + +**Parameters** + +- `ssh` - pointer to the wolfSSH session **Return Values** -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** +- the public key check context pointer +- `NULL` - if `ssh` is NULL +**See Also** -### wolfSSH_CTX_SetChannelReqSubsysCb +- `wolfSSH_SetPublicKeyCheckCtx()` -**Synopsis** +## Set Username -``` + + +### wolfSSH_SetUsername() + + +```c #include -int wolfSSH_CTX_SetChannelReqSubsysCb(WOLFSSH_CTX* ctx, - WS_CallbackChannelReq cb); + +int wolfSSH_SetUsername(WOLFSSH* ssh, const char* username); ``` **Description** -Sets the callback function, _cb_, into the wolfSSH _ctx_ used when a Channel -Request (**SSH_MSG_CHANNEL_REQUEST**) message is received from the peer for -a _subsystem_. A common example of a subsystem is SFTP. +Sets the username used for the SSH connection, provided as a null-terminated string. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `username` - the username for the SSH connection **Return Values** -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` +**See Also** -### wolfSSH_CTX_SetChannelReqExecCb +- `wolfSSH_GetUsername()` -**Synopsis** +### wolfSSH_SetUsernameRaw() -``` +```c #include -int wolfSSH_CTX_SetChannelReqExecCb(WOLFSSH_CTX* ctx, - WS_CallbackChannelReq cb); + +int wolfSSH_SetUsernameRaw(WOLFSSH* ssh, const byte* username, + word32 usernameSz); ``` **Description** -Sets the callback function, _cb_, into the wolfSSH _ctx_ used when a Channel -Request (**SSH_MSG_CHANNEL_REQUEST**) message is received from the peer for -a command to _exec_. +Sets the username used for the SSH connection from a buffer and length, rather than a null-terminated string. Useful when the username is not null-terminated or may contain arbitrary bytes. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `username` - buffer containing the username +- `usernameSz` - length of the username buffer **Return Values** -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` +**See Also** -### wolfSSH_CTX_SetChannelEofCb +- `wolfSSH_SetUsername()` -**Synopsis** +### wolfSSH_GetUsername() -``` +```c #include -int wolfSSH_CTX_SetChannelEof(WOLFSSH_CTX* ctx, - WS_CallbackChannelEof cb); + +char* wolfSSH_GetUsername(WOLFSSH* ssh); ``` **Description** -Sets the callback function, _cb_, into the wolfSSH _ctx_ used when a Channel -EOF (**SSH_MSG_CHANNEL_EOF**) message is received from the peer. This -message indicates that the peer isn't going to transmit any more data on this -channel. +Returns the username associated with the session. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session **Return Values** -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** +- pointer to the session's username string +- `NULL` - if `ssh` is NULL or no username is set + +**See Also** + +- `wolfSSH_SetUsername()` +## Connection Functions -### wolfSSH_CTX_SetChannelCloseCb +### wolfSSH_accept() -**Synopsis** -``` + +```c #include -int wolfSSH_CTX_SetChannelClose(WOLFSSH_CTX* ctx, - WS_CallbackChannelClose cb); + +int wolfSSH_accept(WOLFSSH* ssh); ``` **Description** -Sets the callback function, _cb_, into the wolfSSH _ctx_ used when a Channel -Close (**SSH_MSG_CHANNEL_CLOSE**) message is received from the peer. This -message indicates that the peer is interested in terminating this channel. +Called on the server side; waits for an SSH client to initiate the SSH handshake and completes it. + +wolfSSH_accept() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, wolfSSH_accept() returns when the I/O cannot yet satisfy the handshake; a call to wolfSSH_get_error() then yields either `WS_WANT_READ` or `WS_WANT_WRITE`. The caller repeats the call when data is available and wolfSSH resumes where it left off. + +If the underlying I/O is blocking, wolfSSH_accept() returns only once the handshake has finished or an error occurred. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session **Return Values** -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` +**See Also** -### wolfSSH_SetChannelOpenCtx +- `wolfSSH_connect()` +- `wolfSSH_stream_read()` -**Synopsis** +### wolfSSH_connect() -``` + +```c #include -int wolfSSH_SetChannelOpenCtx(WOLFSSH* ssh, void* ctx); + +int wolfSSH_connect(WOLFSSH* ssh); ``` **Description** -Sets the context, _ctx_, into the wolfSSH _ssh_ object used when the callback -for the Channel Open (**SSH_MSG_CHANNEL_OPEN**) message, Channel Open -Confirmation (**SSH_MSG_CHANNEL_CONFIRMATION**) message, or Channel Open -Failure (**SSH_MSG_CHANNEL_FAILURE**) is received from the peer. +Called on the client side; initiates an SSH handshake with a server. The underlying communication channel must already be set up before this call. + +wolfSSH_connect() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, wolfSSH_connect() returns when the I/O cannot yet satisfy the handshake; a call to wolfSSH_get_error() then yields either `WS_WANT_READ` or `WS_WANT_WRITE`. The caller repeats the call when the I/O is ready and wolfSSH resumes where it left off. + +If the underlying I/O is blocking, wolfSSH_connect() returns only once the handshake has finished or an error occurred. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session **Return Values** -* **WS_SUCCESS** - Setting context in _ssh_ was successful -* **WS_SSH_NULL_E** - _ssh_ is **NULL** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` +**See Also** -### wolfSSH_SetChannelReqCtx +- `wolfSSH_accept()` -**Synopsis** +### wolfSSH_shutdown() -``` + +```c #include -int wolfSSH_SetChannelReqCtx(WOLFSSH* ssh, void* ctx); + +int wolfSSH_shutdown(WOLFSSH* ssh); ``` **Description** -Sets the context, _ctx_, into the wolfSSH _ssh_ object used when the callback -for the Channel Request (**SSH_MSG_CHANNEL_REQUEST**) message is received from -the peer. +Closes and disconnects the SSH session, sending a disconnect message to the peer. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session **Return Values** -* **WS_SUCCESS** - Setting context in _ssh_ was successful -* **WS_SSH_NULL_E** - _ssh_ is **NULL** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**See Also** + +- `wolfSSH_connect()` +- `wolfSSH_accept()` +### wolfSSH_stream_read() -### wolfSSH_SetChannelEofCtx -**Synopsis** -``` +```c #include -int wolfSSH_SetChannelEofCtx(WOLFSSH* ssh, void* ctx); + +int wolfSSH_stream_read(WOLFSSH* ssh, byte* buf, word32 bufSz); ``` **Description** -Sets the context, _ctx_, into the wolfSSH _ssh_ object used when the callback -for the Channel EOF (**SSH_MSG_CHANNEL_EOF**) message is received from -the peer. +Reads up to `bufSz` bytes from the internal decrypted data stream buffer. The bytes read are removed from the internal buffer. + +wolfSSH_stream_read() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking and cannot satisfy the read, a call to wolfSSH_get_error() yields `WS_WANT_READ` or `WS_WANT_WRITE`, and the caller repeats the call when data is available. If the underlying I/O is blocking, the call returns only when data is available or an error occurred. If a rekey is in progress (`WS_REKEYING`), call wolfSSH_worker() to complete it. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `buf` - buffer where the data is placed +- `bufSz` - size of the buffer **Return Values** -* **WS_SUCCESS** - Setting context in _ssh_ was successful -* **WS_SSH_NULL_E** - _ssh_ is **NULL** +- greater than 0 - number of bytes read on success +- 0 - the connection was shut down +- `WS_BAD_ARGUMENT` +- `WS_EOF` +- `WS_FATAL_ERROR` +- `WS_REKEYING` +**See Also** -### wolfSSH_SetChannelCloseCtx +- `wolfSSH_stream_send()` +- `wolfSSH_accept()` -**Synopsis** -``` +### wolfSSH_stream_send() + + + +```c #include -int wolfSSH_SetChannelCloseCtx(WOLFSSH* ssh, void* ctx); + +int wolfSSH_stream_send(WOLFSSH* ssh, byte* buf, word32 bufSz); ``` **Description** -Sets the context, _ctx_, into the wolfSSH _ssh_ object used when the callback -for the Channel Close (**SSH_MSG_CHANNEL_CLOSE**) message is received from -the peer. +Writes `bufSz` bytes from `buf` to the SSH stream data buffer. + +wolfSSH_stream_send() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking and cannot send all pending data, a call to wolfSSH_get_error() yields `WS_WANT_READ` or `WS_WANT_WRITE`, and the caller repeats the call when the socket is ready to send. If the underlying I/O is blocking, the call returns only once the data has been sent or an error occurred. If the error is not want-read/want-write (for example `WS_REKEYING`), call wolfSSH_worker() until the internal SSH processing completes. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `buf` - buffer to send +- `bufSz` - size of the buffer **Return Values** -* **WS_SUCCESS** - Setting context in _ssh_ was successful -* **WS_SSH_NULL_E** - _ssh_ is **NULL** +- greater than 0 - number of bytes written on success +- 0 - the connection was shut down +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` +- `WS_REKEYING` +**See Also** -### wolfSSH_GetChannelOpenCtx +- `wolfSSH_stream_read()` +- `wolfSSH_accept()` -**Synopsis** -``` +### wolfSSH_stream_exit() + + +```c #include -void* wolfSSH_GetChannelOpenCtx(WOLFSSH* ssh); + +int wolfSSH_stream_exit(WOLFSSH* ssh, int status); ``` **Description** -Gets the context from the wolfSSH _ssh_ object used when the callback for the -Channel Open (**SSH_MSG_CHANNEL_OPEN**) message. +Exits the SSH stream, sending the given exit status to the peer and closing the channel. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `status` - the exit status to report to the peer **Return Values** -* pointer to the context data +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +**See Also** -### wolfSSH_GetChannelReqCtx +- `wolfSSH_stream_send()` -**Synopsis** +### wolfSSH_TriggerKeyExchange() -``` + +```c #include -void* wolfSSH_GetChannelReqCtx(WOLFSSH* ssh); + +int wolfSSH_TriggerKeyExchange(WOLFSSH* ssh); ``` **Description** -Gets the context from the wolfSSH _ssh_ object used when the callback for the -Channel Request (**SSH_MSG_CHANNEL_REQUEST**) message. +Triggers the key exchange (rekey) process by preparing and sending the initial handshake packet. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session **Return Values** -* pointer to the context data +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +**See Also** -### wolfSSH_GetChannelEofCtx +- `wolfSSH_worker()` -**Synopsis** +### wolfSSH_stream_peek() -``` +```c #include -void* wolfSSH_GetChannelEofCtx(WOLFSSH* ssh); + +int wolfSSH_stream_peek(WOLFSSH* ssh, byte* buf, word32 bufSz); ``` **Description** -Gets the context from the wolfSSH _ssh_ object used when the callback for the -Channel EOF (**SSH_MSG_CHANNEL_EOF**) message. +Copies up to `bufSz` bytes of pending decrypted stream data into `buf` without removing them from the internal buffer. A subsequent wolfSSH_stream_read() will return the same data. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `buf` - buffer where the peeked data is placed +- `bufSz` - size of the buffer **Return Values** -* pointer to the context data +- greater than or equal to 0 - number of bytes copied +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` +**See Also** -### wolfSSH_GetChannelCloseCtx +- `wolfSSH_stream_read()` -**Synopsis** +### wolfSSH_extended_data_send() -``` +```c #include -void* wolfSSH_GetChannelCloseCtx(WOLFSSH* ssh); + +int wolfSSH_extended_data_send(WOLFSSH* ssh, byte* buf, word32 bufSz); ``` **Description** -Gets the context from the wolfSSH _ssh_ object used when the callback for the -Channel Close (**SSH_MSG_CHANNEL_CLOSE**) message. +Sends `bufSz` bytes as extended channel data (typically the stderr data type). + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `buf` - buffer to send +- `bufSz` - size of the buffer **Return Values** -* pointer to the context data +- greater than 0 - number of bytes sent on success +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` +**See Also** -### wolfSSH_ChannelGetSessionType +- `wolfSSH_extended_data_read()` -**Synopsis** +### wolfSSH_extended_data_read() -``` +```c #include -WS_SessionType wolfSSH_ChannelGetSessionType(const WOLFSSH_CHANNEL* channel); + +int wolfSSH_extended_data_read(WOLFSSH* ssh, byte* out, word32 outSz); ``` **Description** -Returns the **WS_SessionType** for the specified _channel_. +Reads up to `outSz` bytes of received extended channel data (typically stderr) into `out`. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `out` - buffer where the data is placed +- `outSz` - size of the buffer **Return Values** -* **WS_SessionType** - type for the session +- greater than or equal to 0 - number of bytes read +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` +**See Also** -### wolfSSH_ChannelGetSessionCommand +- `wolfSSH_extended_data_send()` -**Synopsis** +### wolfSSH_SendIgnore() -``` +```c #include -const char* wolfSSH_ChannelGetSessionCommand(const WOLFSSH_CHANNEL* channel); + +int wolfSSH_SendIgnore(WOLFSSH* ssh, const byte* buf, word32 bufSz); ``` **Description** -Returns a pointer to the command the user wishes to execute over the specified -_channel_. - -**Return Values** +Sends an SSH_MSG_IGNORE message carrying the given payload. The peer discards the contents; this can be used as a keepalive or for traffic-analysis resistance. -* **const char*** - pointer to the string holding the command sent by the user +**Parameters** +- `ssh` - pointer to the wolfSSH session +- `buf` - payload to include in the message +- `bufSz` - size of the payload -## Testing Functions +**Return Values** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` -### wolfSSH_GetStats() +### wolfSSH_SendDisconnect() +```c +#include -**Synopsis** +int wolfSSH_SendDisconnect(WOLFSSH* ssh, word32 reason); +``` **Description** -Updates **txCount** , **rxCount** , **seq** , and **peerSeq** with their respective **ssh** session -statistics. +Sends an SSH_MSG_DISCONNECT message to the peer with the given reason code (see the `WS_DisconnectReasonCodes` values). -**Return Values** +**Parameters** -none +- `ssh` - pointer to the wolfSSH session +- `reason` - disconnect reason code -**Parameters** +**Return Values** -**ssh** – pointer to the wolfSSH session -**txCount** – address where total transferred bytes in **ssh** session are stored. -**rxCount** – address where total received bytes in **ssh** session are stored. -**seq** – packet sequence number is initially 0 and is incremented after every packet -**peerSeq** – peer packet sequence number is initially 0 and is incremented after every -packet +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` -``` -#include -void wolfSSH_GetStats(WOLFSSH* ssh , word32* txCount , word32* -rxCount , -word32* seq , word32* peerSeq ) -``` +**See Also** -### wolfSSH_KDF() +- `wolfSSH_shutdown()` +### wolfSSH_global_request() -**Synopsis** +```c +#include + +int wolfSSH_global_request(WOLFSSH* ssh, const unsigned char* data, + word32 dataSz, int reply); +``` **Description** -This is used so that the API test can do known answer tests for the key derivation. +Sends a global request to the peer carrying the given data. If `reply` is non-zero, the peer is asked to reply with success or failure. + +**Parameters** -The Key Derivation Function derives a symmetric **key** based on source keying material, -**k** and **h**. Where **k** is the Diffie-Hellman shared secret and **h** is the hash of the -handshake that was produced during initial key exchange. Multiple types of keys could -be derived which are specified by the **keyId** and **hashId**. +- `ssh` - pointer to the wolfSSH session +- `data` - request payload +- `dataSz` - size of the payload +- `reply` - non-zero to request a reply from the peer -``` -Initial IV client to server: keyId = A -Initial IV server to client: keyId = B -Encryption key client to server: keyId = C -Encryption key server to client: keyId = D -Integrity key client to server: keyId = E -Integrity key server to client : keyId = F -``` **Return Values** -WS_SUCCESS -WS_CRYPTO_FAILED - -**Parameters** +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` -**hashId** – type of hash to generate keying material. -e.g. ( WC_HASH_TYPE_SHA and WC_HASH_TYPE_SHA256 ) -**keyId** – letter A - F to indicate which key to make -**key** – generated key used for comparisons to expected key +### wolfSSH_ChannelIdRead() -``` +```c #include -int wolfSSH_KDF(byte hashId , byte keyId , byte* key , word32 -keySz , -const byte* k , word32 kSz , const byte* h , word32 -hSz , -const byte* sessionId , word32 sessionIdSz ); + +int wolfSSH_ChannelIdRead(WOLFSSH* ssh, word32 channelId, + byte* buf, word32 bufSz); ``` -**keySz** – needed size of **key -k** – shared secret from the Diffie-Hellman key exchange -**kSz** – size of the shared secret ( **k** ) -**h** – hash of the handshake that was produced during key exchange -**hSz** – size of the hash ( **h** ) -**sessionId** – unique identifier from first **h** calculated. -**sessionIdSz** – size of the **sessionId** +**Description** +Reads up to `bufSz` bytes of received data from the channel identified by `channelId`. -## Session Functions +**Parameters** +- `ssh` - pointer to the wolfSSH session +- `channelId` - the channel to read from +- `buf` - buffer where the data is placed +- `bufSz` - size of the buffer +**Return Values** -### wolfSSH_GetSessionType() +- greater than or equal to 0 - number of bytes read +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` +**See Also** -**Synopsis** +- `wolfSSH_ChannelIdSend()` -**Description** +### wolfSSH_ChannelIdSend() -The wolfSSH_GetSessionType() is used to return the type of session +```c +#include -**Return Values** +int wolfSSH_ChannelIdSend(WOLFSSH* ssh, word32 channelId, + byte* buf, word32 bufSz); +``` + +**Description** -WOLFSSH_SESSION_UNKNOWN -WOLFSSH_SESSION_SHELL -WOLFSSH_SESSION_EXEC -WOLFSSH_SESSION_SUBSYSTEM +Sends `bufSz` bytes on the channel identified by `channelId`. **Parameters** -**ssh -** pointer to wolfSSH session +- `ssh` - pointer to the wolfSSH session +- `channelId` - the channel to send on +- `buf` - buffer to send +- `bufSz` - size of the buffer -``` -#include -WS_SessionType wolfSSH_GetSessionType(const WOLFSSH* ssh ); -``` +**Return Values** -### wolfSSH_GetSessionCommand() +- greater than 0 - number of bytes sent on success +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` +**See Also** -**Synopsis** +- `wolfSSH_ChannelIdRead()` -**Description** +### wolfSSH_CTX_SetSshProtoIdStr() -This function is used to return the current command in the session. +```c +#include -**Return Values** +int wolfSSH_CTX_SetSshProtoIdStr(WOLFSSH_CTX* ctx, const char* protoIdStr); +``` + +**Description** -**const char*** - Pointer to command +Overrides the SSH protocol identification string that is sent to the peer during the version exchange at the start of the connection. **Parameters** -**ssh -** pointer to wolfSSH session +- `ctx` - pointer to the wolfSSH context +- `protoIdStr` - the protocol identification string to send -``` -#include -const char* wolfSSH_GetSessionCommand(const WOLFSSH* ssh ); -``` +**Return Values** -## Port Forwarding Functions +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +### wolfSSH_CTX_SetWindowPacketSize() +```c +#include -### wolfSSH_ChannelFwdNew() +int wolfSSH_CTX_SetWindowPacketSize(WOLFSSH_CTX* ctx, + word32 windowSz, word32 maxPacketSz); +``` +**Description** -**Synopsis** +Sets the default channel window size and maximum packet size for sessions created from this context. -**Description** +**Parameters** -Sets up a TCP/IP forwarding channel on a WOLFSSH session. When the SSH session -is connected and authenticated, a local listener is created on the interface for address -_host_ on port _hostPort_. Any new connections on that listener will trigger a new channel -request to the SSH server to establish a connection to _host_ on port _hostPort_. +- `ctx` - pointer to the wolfSSH context +- `windowSz` - the channel window size, in bytes +- `maxPacketSz` - the maximum packet size, in bytes **Return Values** -**WOLFSSH_CHAN*** – NULL on error or new channel record +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` -**Parameters** +## Channel Callbacks -**ssh** – wolfSSH session -**host** – host address to bind listener -**hostPort** – host port to bind listener -**origin** – IP address of the originating connection -**originPort** – port number of the originating connection +Interfaces to the wolfSSH library return single int values. Communicating +status of asynchronous information, like the peer opening a channel, isn't +easy with that interface. wolfSSH uses callback functions to notify the +calling application of changes in state of a channel. + +There are callback functions for receipt of the following SSHv2 protocol +messages: + +* SSH_MSG_CHANNEL_OPEN +* SSH_MSG_CHANNEL_OPEN_CONFIRMATION +* SSH_MSG_CHANNEL_OPEN_FAILURE +* SSH_MSG_CHANNEL_REQUEST + - "shell" + - "subsystem" + - "exec" +* SSH_MSG_CHANNEL_EOF +* SSH_MSG_CHANNEL_CLOSE + +### Callback Function Prototypes + +The channel callback functions all take a pointer to a **WOLFSSH_CHANNEL** +object, _channel_, and a pointer to the application defined data structure, +_ctx_. Properties about the channel may be queried using API functions. ``` -#include -WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNew(WOLFSSH* ssh , -const char* host , word32 hostPort , -const char* origin , word32 originPort ); +typedef int (*WS_CallbackChannelOpen)(WOLFSSH_CHANNEL* channel, void* ctx); +typedef int (*WS_CallbackChannelReq)(WOLFSSH_CHANNEL* channel, void* ctx); +typedef int (*WS_CallbackChannelEof)(WOLFSSH_CHANNEL* channel, void* ctx); +typedef int (*WS_CallbackChannelClose)(WOLFSSH_CHANNEL* channel, void* ctx); ``` -### wolfSSH_ChannelFree() +### wolfSSH_CTX_SetChannelOpenCb() +```c +#include -**Synopsis** +int wolfSSH_CTX_SetChannelOpenCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelOpen cb); +``` **Description** -Releases the memory allocated for the channel _channel_. The channel is removed from -its session’s channel list. +Sets the callback invoked when a Channel Open (SSH_MSG_CHANNEL_OPEN) message is received from the peer. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the channel open callback **Return Values** -**int** – error code +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` -**Parameters** +**See Also** -**channel** – wolfSSH channel to free +- `wolfSSH_SetChannelOpenCtx()` -``` -#include -int wolfSSH_ChannelFree(WOLFSSH_CHANNEL* channel ); -``` -### wolfSSH_worker() +### wolfSSH_CTX_SetChannelOpenRespCb() +```c +#include -**Synopsis** +int wolfSSH_CTX_SetChannelOpenRespCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelOpen confCb, WS_CallbackChannelOpen failCb); +``` **Description** -The wolfSSH worker function babysits the connection and as data is received -processes it. SSH sessions have many bookkeeping messages for the session and this -takes care of them automatically. When data for a particular channel is received, the -worker places the data into the channel. (The function wolfSSH_stream_read() does -much the same but also returns the receive data for a single channel.) -wolfSSH_worker() will perform the following actions: +Sets the callbacks invoked when a Channel Open Confirmation (SSH_MSG_CHANNEL_OPEN_CONFIRMATION) or a Channel Open Failure (SSH_MSG_CHANNEL_OPEN_FAILURE) message is received from the peer. + +**Parameters** -1. Attempt to send any pending data in the _outputBuffer_. -2. Call _DoReceive()_ on the session’s socket. -3. If data is received for a particular channel, return data received notice and set the - channel ID. +- `ctx` - pointer to the wolfSSH context +- `confCb` - callback for a channel open confirmation +- `failCb` - callback for a channel open failure **Return Values** -**int** – error or status -**WS_CHANNEL_RXD** – data has been received on a channel and the ID is set +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` -**Parameters** +**See Also** -**ssh** – pointer to the wolfSSH session -**id** – pointer to the location to save the ID value +- `wolfSSH_CTX_SetChannelOpenCb()` -``` -#include -int wolfSSH_worker(WOLFSSH* ssh , word32* channelId ); -``` -### wolfSSH_ChannelGetId() +### wolfSSH_CTX_SetChannelReqShellCb() +```c +#include -**Synopsis** +int wolfSSH_CTX_SetChannelReqShellCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelReq cb); +``` **Description** -Given a channel, returns the ID or peer’s ID for the channel. +Sets the callback invoked when a Channel Request (SSH_MSG_CHANNEL_REQUEST) message is received from the peer for a _shell_. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the channel request callback **Return Values** -**int** – error code +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` -**Parameters** +**See Also** -**channel** – pointer to channel -**id** – pointer to location to save the ID value -**peer** – either self (my channel ID) or peer (my peer’s channel ID) +- `wolfSSH_CTX_SetChannelReqExecCb()` -``` -#include -int wolfSSH_ChannelGetId(WOLFSSH_CHANNEL* channel , -word32* id , byte peer ); -``` -### wolfSSH_ChannelFind() +### wolfSSH_CTX_SetChannelReqSubsysCb() +```c +#include -**Synopsis** +int wolfSSH_CTX_SetChannelReqSubsysCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelReq cb); +``` **Description** -Given a session _ssh_ , find the channel associated with _id_. +Sets the callback invoked when a Channel Request (SSH_MSG_CHANNEL_REQUEST) message is received from the peer for a _subsystem_. A common example of a subsystem is SFTP. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the channel request callback **Return Values** -**WOLFSSH_CHANNEL*** – pointer to the channel, NULL if the ID isn’t in the list +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` -**Parameters** +**See Also** -**ssh** – wolfSSH session -**id** – channel ID to find -**peer** – either self (my channel ID) or peer (my peer’s channel ID) +- `wolfSSH_CTX_SetChannelReqShellCb()` -``` -#include -WOLFSSH_CHANNEL* wolfSSH_ChannelFind(WOLFSSH* ssh , -word32 id , byte peer ); -``` -### wolfSSH_ChannelRead() +### wolfSSH_CTX_SetChannelReqExecCb() +```c +#include -**Synopsis** +int wolfSSH_CTX_SetChannelReqExecCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelReq cb); +``` **Description** -Copies data out of a channel object. +Sets the callback invoked when a Channel Request (SSH_MSG_CHANNEL_REQUEST) message is received from the peer for a command to _exec_. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the channel request callback **Return Values** -**int** – bytes read -**>0** – number of bytes read upon success -**0** – returns on socket failure cause by either a clean connection shutdown or a -socket error, call wolfSSH_get_error() for more detail -**WS_FATAL_ERROR** – there was some other error, call wolfSSH_get_error() for -more detail +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` -**Parameters** +**See Also** -**channel** – pointer to the wolfSSH channel -**buf** – buffer where wolfSSH_ChannelRead will place the data -**bufSz** – size of the buffer +- `wolfSSH_CTX_SetChannelReqShellCb()` -``` -#include -int wolfSSH_ChannelRead(WOLFSSH_CHANNEL* channel , -byte* buf , word32 bufSz ); -``` -### wolfSSH_ChannelSend() +### wolfSSH_CTX_SetChannelEofCb() +```c +#include -**Synopsis** +int wolfSSH_CTX_SetChannelEofCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelEof cb); +``` **Description** -Sends data to the peer via the specified channel. Data is packaged into a channel data -message. This will send as much data as possible via the peer socket. If there is more -to be sent, calls to _wolfSSH_worker()_ will continue sending more data for the channel to -the peer. +Sets the callback invoked when a Channel EOF (SSH_MSG_CHANNEL_EOF) message is received from the peer, indicating the peer will not transmit any more data on this channel. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the channel EOF callback **Return Values** -**int** – bytes sent -**>0** – number of bytes sent upon success -**0** – returns on socket failure cause by either a clean connection shutdown or a -socket error, call wolfSSH_get_error() for more detail -**WS_FATAL_ERROR** – there was some other error, call wolfSSH_get_error() for -more detail +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` -**Parameters** +**See Also** -**channel** – pointer to the wolfSSH channel -**buf** – buffer wolfSSH_ChannelSend() will send -**bufSz** – size of the buffer +- `wolfSSH_CTX_SetChannelCloseCb()` -``` -#include -int* wolfSSH_ChannelSend(WOLFSSH_CHANNEL* channel , -const byte* buf , word32 bufSz ); -``` -### wolfSSH_ChannelExit() +### wolfSSH_CTX_SetChannelCloseCb() +```c +#include -**Synopsis** +int wolfSSH_CTX_SetChannelCloseCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelClose cb); +``` **Description** -Terminates a channel, sending the close message to the peer, marks the channel as -closed. This does not free the channel and it remains on the channel list. After closure, -data can not be sent on the channel, but data may still be available to be received. (At -the moment, it sends EOF, close, and deletes the channel.) +Sets the callback invoked when a Channel Close (SSH_MSG_CHANNEL_CLOSE) message is received from the peer, indicating the peer wants to terminate this channel. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the channel close callback **Return Values** -**int** – error code +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` -**Parameters** +**See Also** -**channel** – wolfSSH session channel +- `wolfSSH_CTX_SetChannelEofCb()` -``` -#include -int wolfSSH_ChannelExit(WOLFSSH_CHANNEL* channel ); -``` -### wolfSSH_ChannelNext() +### wolfSSH_SetChannelOpenCtx() +```c +#include -**Synopsis** +int wolfSSH_SetChannelOpenCtx(WOLFSSH* ssh, void* ctx); +``` **Description** -Returns the next channel after _channel_ in _ssh_ ’s channel list. If _channel_ is NULL, the first -channel from the channel list for _ssh_ is returned. +Sets the user context passed to the channel open, channel open confirmation, and channel open failure callbacks. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context to pass to the channel open callbacks **Return Values** -**WOLFSSH_CHANNEL*** – pointer to either the first channel, next channel, or NULL +- `WS_SUCCESS` +- `WS_SSH_NULL_E` -**Parameters** +**See Also** -**ssh** – wolfSSH session -**channel** – wolfSSH session channel +- `wolfSSH_GetChannelOpenCtx()` -``` + +### wolfSSH_SetChannelReqCtx() + +```c #include -WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNew(WOLFSSH* ssh , -WOLFSSH_CHANNEL* channel ); + +int wolfSSH_SetChannelReqCtx(WOLFSSH* ssh, void* ctx); ``` +**Description** + +Sets the user context passed to the channel request (shell/exec/subsystem) callbacks. -## Key Load Functions +**Parameters** +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context to pass to the channel request callbacks -### wolfSSH_ReadKey_buffer() +**Return Values** -**Synopsis** +- `WS_SUCCESS` +- `WS_SSH_NULL_E` -``` +**See Also** + +- `wolfSSH_GetChannelReqCtx()` + + +### wolfSSH_SetChannelEofCtx() + +```c #include -int wolfSSH_ReadKey_buffer(const byte* in, word32 inSz, - int format, byte** out, word32* outSz, - const byte** outType, word32* outTypeSz, - void* heap); +int wolfSSH_SetChannelEofCtx(WOLFSSH* ssh, void* ctx); ``` **Description** -Reads a key file from the buffer _in_ of size _inSz_ and tries to decode it -as a _format_ type key. The _format_ can be **WOLFSSH_FORMAT_ASN1**, -**WOLFSSH_FORMAT_PEM**, **WOLFSSH_FORMAT_SSH**, or **WOLFSSH_FORMAT_OPENSSH**. -The key ready for use by `wolfSSH_UsePrivateKey_buffer()` is stored in the -buffer pointed to by _out_, of size _outSz_. If _out_ is NULL, _heap_ is used -to allocate a buffer for the key. The type string of the key is stored in -_outType_, with its string length in _outTypeSz_. +Sets the user context passed to the channel EOF callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context to pass to the channel EOF callback **Return Values** -* **WS_SUCCESS** - read key is successful -* **WS_BAD_ARGUMENT** - parameter has a bad value -* **WS_MEMORY_E** - failure allocating memory -* **WS_BUFFER_E** - buffer not large enough for indicated size -* **WS_PARSE_E** - problem parsing the key file -* **WS_UNIMPLEMENTED_E** - key type not supported -* **WS_RSA_E** - something wrong with RSA (PKCS1) key -* **WS_ECC_E** - something wrong with ECC (X9.63) key -* **WS_KEY_AUTH_MAGIC_E** - OpenSSH key auth magic value bad -* **WS_KEY_FORMAT_E** - OpenSSH key format incorrect -* **WS_KEY_CHECK_VAL_E** - OpenSSH key check value corrupt +- `WS_SUCCESS` +- `WS_SSH_NULL_E` +**See Also** -### wolfSSH_ReadKey_file() +- `wolfSSH_GetChannelEofCtx()` -**Synopsis** -``` +### wolfSSH_SetChannelCloseCtx() + +```c #include -int wolfSSH_ReadKey_file(const char* name, - byte** out, word32* outSz, - const byte** outType, word32* outTypeSz, - byte* isPrivate, void* heap); +int wolfSSH_SetChannelCloseCtx(WOLFSSH* ssh, void* ctx); ``` **Description** -Reads the key from the file _name_. The format is guessed based on data in -the file. The key buffer _out_, the key type _outType_, and their sizes -are passed to `wolfSSH_ReadKey_buffer()`. The flag _isPrivate_ is set -as appropriate. Any memory allocations use the specified _heap_. - -**Return Values** - -* **WS_SUCCESS** - read key is successful -* **WS_BAD_ARGUMENT** - parameter has a bad value -* **WS_BAD_FILE_E** - problem reading the file -* **WS_MEMORY_E** - failure allocating memory -* **WS_BUFFER_E** - buffer not large enough for indicated size -* **WS_PARSE_E** - problem parsing the key file -* **WS_UNIMPLEMENTED_E** - key type not supported -* **WS_RSA_E** - something wrong with RSA (PKCS1) key -* **WS_ECC_E** - something wrong with ECC (X9.63) key -* **WS_KEY_AUTH_MAGIC_E** - OpenSSH key auth magic value bad -* **WS_KEY_FORMAT_E** - OpenSSH key format incorrect -* **WS_KEY_CHECK_VAL_E** - OpenSSH key check value corrupt +Sets the user context passed to the channel close callback. +**Parameters** -## Key Exchange Algorithm Configuration +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context to pass to the channel close callback -wolfSSH sets up a set of algorithm lists used during the Key Exchange (KEX) -based on the availability of algorithms in the wolfCrypt library used. +**Return Values** -Provided are some accessor functions to see which algorithms are available -to use and to see the algorithm lists used in the KEX. The accessor functions -come in sets of four: set or get from CTX object, and set or get from SSH -object. All SSH objects made with a CTX inherit the CTX's algorithm lists, -and they may be provided their own. +- `WS_SUCCESS` +- `WS_SSH_NULL_E` -By default, any algorithms using SHA-1 are disabled but may be re-enabled -using one of the following functions. If SHA-1 is disabled in wolfCrypt, then -SHA-1 cannot be used. +**See Also** +- `wolfSSH_GetChannelCloseCtx()` -### wolfSSH Set Algo Lists -**Synopsis** +### wolfSSH_GetChannelOpenCtx() -``` +```c #include -int wolfSSH_CTX_SetAlgoListKex(WOLFSSH_CTX* ctx, const char* list); -int wolfSSH_CTX_SetAlgoListKey(WOLFSSH_CTX* ctx, const char* list); -int wolfSSH_CTX_SetAlgoListCipher(WOLFSSH_CTX* ctx, const char* list); -int wolfSSH_CTX_SetAlgoListMac(WOLFSSH_CTX* ctx, const char* list); -int wolfSSH_CTX_SetAlgoListKeyAccepted(WOLFSSH_CTX* ctx, const char* list); - -int wolfSSH_SetAlgoListKex(WOLFSSH* ssh, const char* list); -int wolfSSH_SetAlgoListKey(WOLFSSH* ssh, const char* list); -int wolfSSH_SetAlgoListCipher(WOLFSSH* ssh, const char* list); -int wolfSSH_SetAlgoListMac(WOLFSSH* ssh, const char* list); -int wolfSSH_SetAlgoListKeyAccepted(WOLFSSH* ssh, const char* list); +void* wolfSSH_GetChannelOpenCtx(WOLFSSH* ssh); ``` **Description** -These functions act as setters for the various algorithm lists set in the -wolfSSH _ctx_ or _ssh_ objects. The strings are sent to the peer during the -KEX Initialization and are used to compare against when the peer sends its -KEX Initialization message. The KeyAccepted list is used for user -authentication. +Returns the user context previously set with wolfSSH_SetChannelOpenCtx() for the channel open callbacks. -The CTX versions of the functions set the algorithm list for the specified -WOLFSSH_CTX object, _ctx_. They have default values set at compile time. The -specified value is used instead. Note, the library does not copy this string, -it is owned by the application and it is up to the application to free it -when the CTX is deallocated by the application. When creating an SSH object -using a CTX, the SSH object inherits the CTX's strings. The SSH object -algorithm lists may be overridden. +**Parameters** -`Kex` specifies the key exchange algorithm list. `Key` specifies the server -public key algorithm list. `Cipher` specifies the bulk encryption algorithm -list. `Mac` specifies the message authentication code algorithm list. -`KeyAccepted` specifies the public key algorithms allowed for user -authentication. +- `ssh` - pointer to the wolfSSH session **Return Values** -* **WS_SUCCESS** - successful -* **WS_SSH_CTX_NULL_E** - provided CTX was null -* **WS_SSH_NULL_E** - provide SSH was null +- the channel open context pointer, or `NULL` if none + +**See Also** +- `wolfSSH_SetChannelOpenCtx()` -### wolfSSH Get Algo List -**Synopsis** +### wolfSSH_GetChannelReqCtx() -``` +```c #include -const char* wolfSSH_CTX_GetAlgoListKex(WOLFSSH_CTX* ctx); -const char* wolfSSH_CTX_GetAlgoListKey(WOLFSSH_CTX* ctx); -const char* wolfSSH_CTX_GetAlgoListCipher(WOLFSSH_CTX* ctx); -const char* wolfSSH_CTX_GetAlgoListMac(WOLFSSH_CTX* ctx); -const char* wolfSSH_CTX_GetAlgoListKeyAccepted(WOLFSSH_CTX* ctx); - -const char* wolfSSH_GetAlgoListKex(WOLFSSH* ssh); -const char* wolfSSH_GetAlgoListKey(WOLFSSH* ssh); -const char* wolfSSH_GetAlgoListCipher(WOLFSSH* ssh); -const char* wolfSSH_GetAlgoListMac(WOLFSSH* ssh); -const char* wolfSSH_GetAlgoListKeyAccepted(WOLFSSH* ssh); +void* wolfSSH_GetChannelReqCtx(WOLFSSH* ssh); ``` **Description** -These functions act as getters for the various algorithm lists set in the -wolfSSH _ctx_ or _ssh_ objects. +Returns the user context previously set with wolfSSH_SetChannelReqCtx() for the channel request callbacks. -`Kex` specifies the key exchange algorithm list. `Key` specifies the server -public key algorithm list. `Cipher` specifies the bulk encryption algorithm -list. `Mac` specifies the message authentication code algorithm list. -`KeyAccepted` specifies the public key algorithms allowed for user -authentication. +**Parameters** + +- `ssh` - pointer to the wolfSSH session **Return Values** -These functions return a pointer to either the default value set at compile -time or the value set at run time with the setter functions. If the _ctx_ -or `ssh` parameters are NULL the functions return NULL. +- the channel request context pointer, or `NULL` if none + +**See Also** +- `wolfSSH_SetChannelReqCtx()` -### wolfSSH_CheckAlgoName -**Synopsis** +### wolfSSH_GetChannelEofCtx() -``` +```c #include -int wolfSSH_CheckAlgoName(const char* name); +void* wolfSSH_GetChannelEofCtx(WOLFSSH* ssh); ``` **Description** -Given a single algorithm _name_ checks to see if it is valid. +Returns the user context previously set with wolfSSH_SetChannelEofCtx() for the channel EOF callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session **Return Values** -* **WS_SUCCESS** - _name_ is a valid algorithm name -* **WS_INVALID_ALGO_ID** - _name_ is an invalid algorithm name +- the channel EOF context pointer, or `NULL` if none + +**See Also** +- `wolfSSH_SetChannelEofCtx()` -### wolfSSH Query Algorithms -**Synopsis** +### wolfSSH_GetChannelCloseCtx() -``` +```c #include -const char* wolfSSH_QueryKex(word32* index); -const char* wolfSSH_QueryKey(word32* index); -const char* wolfSSH_QueryCipher(word32* index); -const char* wolfSSH_QueryMac(word32* index); +void* wolfSSH_GetChannelCloseCtx(WOLFSSH* ssh); ``` **Description** -Returns the name string for a valid algorithm of the particular type: Kex, -Key, Cipher, or Mac. Note, Key types are also used for the user authentication -accepted key types. The value passed as _index_ must be initialized to 0, -the passed in on each call to the function. At the end of the list, the -_index_ is invalid. +Returns the user context previously set with wolfSSH_SetChannelCloseCtx() for the channel close callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session + +**Return Values** + +- the channel close context pointer, or `NULL` if none + +**See Also** + +- `wolfSSH_SetChannelCloseCtx()` + + +## Channel Functions + +These functions operate directly on `WOLFSSH_CHANNEL` objects, which represent the individual channels multiplexed over an SSH session. + +### wolfSSH_ChannelGetSessionType() + +```c +#include + +WS_SessionType wolfSSH_ChannelGetSessionType(const WOLFSSH_CHANNEL* channel); +``` + +**Description** + +Returns the `WS_SessionType` (shell, exec, subsystem, terminal, or unknown) for the specified channel. + +**Parameters** + +- `channel` - pointer to the channel + +**Return Values** + +- the channel's `WS_SessionType` + +**See Also** + +- `wolfSSH_ChannelGetSessionCommand()` + + +### wolfSSH_ChannelGetSessionCommand() + +```c +#include + +const char* wolfSSH_ChannelGetSessionCommand(const WOLFSSH_CHANNEL* channel); +``` + +**Description** + +Returns the command the peer requested to execute over the specified channel (for an "exec" request). + +**Parameters** + +- `channel` - pointer to the channel + +**Return Values** + +- pointer to the command string, or `NULL` if none + +**See Also** + +- `wolfSSH_ChannelGetSessionType()` + +### wolfSSH_ChannelFree() + +```c +#include + +int wolfSSH_ChannelFree(WOLFSSH_CHANNEL* channel); +``` + +**Description** + +Frees a channel object and removes it from its session. + +**Parameters** + +- `channel` - pointer to the channel to free + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_ChannelGetId() + +```c +#include + +int wolfSSH_ChannelGetId(WOLFSSH_CHANNEL* channel, word32* id, byte peer); +``` + +**Description** + +Retrieves the numeric channel ID for the given channel. Set `peer` to `WS_CHANNEL_ID_SELF` for this side's ID or `WS_CHANNEL_ID_PEER` for the peer's ID. + +**Parameters** + +- `channel` - pointer to the channel +- `id` - output for the channel ID +- `peer` - `WS_CHANNEL_ID_SELF` or `WS_CHANNEL_ID_PEER` + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**See Also** + +- `wolfSSH_ChannelFind()` + +### wolfSSH_ChannelFind() + +```c +#include + +WOLFSSH_CHANNEL* wolfSSH_ChannelFind(WOLFSSH* ssh, word32 id, byte peer); +``` + +**Description** + +Finds the channel on the session matching the given ID. Set `peer` to `WS_CHANNEL_ID_SELF` to match this side's ID or `WS_CHANNEL_ID_PEER` to match the peer's ID. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `id` - the channel ID to find +- `peer` - `WS_CHANNEL_ID_SELF` or `WS_CHANNEL_ID_PEER` + +**Return Values** + +- pointer to the matching channel, or `NULL` if not found + +**See Also** + +- `wolfSSH_ChannelNext()` + +### wolfSSH_ChannelNext() + +```c +#include + +WOLFSSH_CHANNEL* wolfSSH_ChannelNext(WOLFSSH* ssh, WOLFSSH_CHANNEL* channel); +``` + +**Description** + +Iterates the channels on a session. Pass `NULL` for `channel` to get the first channel; pass a channel to get the one after it. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `channel` - the current channel, or `NULL` to start iteration + +**Return Values** + +- pointer to the next channel, or `NULL` at the end of the list + +**See Also** + +- `wolfSSH_ChannelFind()` + +### wolfSSH_ChannelRead() + +```c +#include + +int wolfSSH_ChannelRead(WOLFSSH_CHANNEL* channel, byte* buf, word32 bufSz); +``` + +**Description** + +Reads up to `bufSz` bytes of received data from the given channel. + +**Parameters** + +- `channel` - pointer to the channel +- `buf` - buffer where the data is placed +- `bufSz` - size of the buffer + +**Return Values** + +- greater than or equal to 0 - number of bytes read +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` + +**See Also** + +- `wolfSSH_ChannelSend()` + +### wolfSSH_ChannelSend() + +```c +#include + +int wolfSSH_ChannelSend(WOLFSSH_CHANNEL* channel, const byte* buf, + word32 bufSz); +``` + +**Description** + +Sends `bufSz` bytes on the given channel. + +**Parameters** + +- `channel` - pointer to the channel +- `buf` - buffer to send +- `bufSz` - size of the buffer + +**Return Values** + +- greater than 0 - number of bytes sent on success +- `WS_BAD_ARGUMENT` +- `WS_FATAL_ERROR` + +**See Also** + +- `wolfSSH_ChannelRead()` + +### wolfSSH_ChannelExit() + +```c +#include + +int wolfSSH_ChannelExit(WOLFSSH_CHANNEL* channel); +``` + +**Description** + +Closes the given channel, sending EOF and close messages to the peer. + +**Parameters** + +- `channel` - pointer to the channel + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_ChannelGetEof() + +```c +#include + +int wolfSSH_ChannelGetEof(WOLFSSH_CHANNEL* channel); +``` + +**Description** + +Reports whether the peer has sent EOF on the given channel. + +**Parameters** + +- `channel` - pointer to the channel + +**Return Values** + +- 1 - the channel has received EOF +- 0 - the channel has not received EOF + +### wolfSSH_ChannelGetType() + +```c +#include + +const char* wolfSSH_ChannelGetType(const WOLFSSH_CHANNEL* channel); +``` + +**Description** + +Returns the channel type string (for example, "session") for the given channel. + +**Parameters** + +- `channel` - pointer to the channel + +**Return Values** + +- pointer to the channel type string, or `NULL` if none + +### wolfSSH_ChannelIsPty() + +```c +#include + +int wolfSSH_ChannelIsPty(const WOLFSSH_CHANNEL* channel); +``` + +**Description** + +Reports whether the given channel has an associated pseudo-terminal (PTY). + +**Parameters** + +- `channel` - pointer to the channel + +**Return Values** + +- 1 - the channel has a PTY +- 0 - the channel does not have a PTY + + +## Testing Functions + + +### wolfSSH_GetStats() + + +```c +#include + +void wolfSSH_GetStats(WOLFSSH* ssh, word32* txCount, word32* rxCount, + word32* seq, word32* peerSeq); +``` + +**Description** + +Writes the session's transfer statistics into the provided output pointers. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `txCount` - output for the total bytes transmitted on the session +- `rxCount` - output for the total bytes received on the session +- `seq` - output for the outgoing packet sequence number +- `peerSeq` - output for the peer's packet sequence number + +**Return Values** + +None + +### wolfSSH_KDF() + + +```c +#include + +int wolfSSH_KDF(byte hashId, byte keyId, byte* key, word32 keySz, + const byte* k, word32 kSz, const byte* h, word32 hSz, + const byte* sessionId, word32 sessionIdSz); +``` + +**Description** + +Runs the SSH key derivation function. It derives a symmetric key from the source keying material `k` (the Diffie-Hellman shared secret) and `h` (the exchange hash produced during key exchange). The particular key produced is selected by `keyId`. This function is primarily exposed so the test suite can run known-answer tests against the key derivation. + +The `keyId` values are: + +``` +A - initial IV, client to server +B - initial IV, server to client +C - encryption key, client to server +D - encryption key, server to client +E - integrity key, client to server +F - integrity key, server to client +``` + +**Parameters** + +- `hashId` - the hash type used to derive keying material (for example, `WC_HASH_TYPE_SHA` or `WC_HASH_TYPE_SHA256`) +- `keyId` - which key to derive (A through F, as above) +- `key` - output buffer for the derived key +- `keySz` - size of the output key buffer +- `k` - the Diffie-Hellman shared secret +- `kSz` - size of `k` +- `h` - the exchange hash +- `hSz` - size of `h` +- `sessionId` - the session identifier +- `sessionIdSz` - size of the session identifier + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_CRYPTO_FAILED` + +### wolfSSH_ShowSizes() + +```c +#include + +void wolfSSH_ShowSizes(void); +``` + +**Description** + +Prints the sizes of wolfSSH's internal data structures. This is a diagnostic aid, useful for tuning memory use on constrained targets. + +**Parameters** + +None + +**Return Values** + +None + + +## Session Functions + + + +### wolfSSH_GetSessionType() + + +```c +#include + +WS_SessionType wolfSSH_GetSessionType(const WOLFSSH* ssh); +``` + +**Description** + +Returns the session type for the session's channel: one of `WOLFSSH_SESSION_UNKNOWN`, `WOLFSSH_SESSION_SHELL`, `WOLFSSH_SESSION_EXEC`, `WOLFSSH_SESSION_SUBSYSTEM`, or `WOLFSSH_SESSION_TERMINAL`. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session + +**Return Values** + +- the session's `WS_SessionType` + +**See Also** + +- `wolfSSH_GetSessionCommand()` + +### wolfSSH_GetSessionCommand() + + +```c +#include + +const char* wolfSSH_GetSessionCommand(const WOLFSSH* ssh); +``` + +**Description** + +Returns the command the peer requested to run for this session (for an "exec" request). + +**Parameters** + +- `ssh` - pointer to the wolfSSH session + +**Return Values** + +- pointer to the command string, or `NULL` if none + +**See Also** + +- `wolfSSH_GetSessionType()` + +### wolfSSH_SetChannelType() + +```c +#include + +int wolfSSH_SetChannelType(WOLFSSH* ssh, byte type, byte* name, + word32 nameSz); +``` + +**Description** + +Sets the channel request type (for example, shell, exec, or subsystem) and optional name for the session's channel. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `type` - the channel request type +- `name` - optional name associated with the type (for example, the subsystem name) +- `nameSz` - length of `name` + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_ChangeTerminalSize() + +```c +#include + +int wolfSSH_ChangeTerminalSize(WOLFSSH* ssh, word32 columns, + word32 rows, word32 widthPixels, word32 heightPixels); +``` + +**Description** + +Notifies the peer that the terminal (window) size has changed, sending the new dimensions. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `columns` - the new width in character columns +- `rows` - the new height in character rows +- `widthPixels` - the new width in pixels +- `heightPixels` - the new height in pixels + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**See Also** + +- `wolfSSH_SetTerminalResizeCb()` + +### wolfSSH_SetTerminalResizeCb() + +```c +#include + +void wolfSSH_SetTerminalResizeCb(WOLFSSH* ssh, WS_CallbackTerminalSize cb); +``` + +**Description** + +Registers a callback that is invoked when the peer reports a terminal size change. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `cb` - the terminal resize callback + +**Return Values** + +None + +**See Also** + +- `wolfSSH_SetTerminalResizeCtx()` + +### wolfSSH_SetTerminalResizeCtx() + +```c +#include + +void wolfSSH_SetTerminalResizeCtx(WOLFSSH* ssh, void* usrCtx); +``` + +**Description** + +Sets the user context pointer passed to the terminal resize callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `usrCtx` - user context pointer to pass to the callback + +**Return Values** + +None + +### wolfSSH_GetExitStatus() + +```c +#include + +int wolfSSH_GetExitStatus(WOLFSSH* ssh); +``` + +**Description** + +Returns the exit status the peer reported for the session's command. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session + +**Return Values** + +- the exit status reported by the peer + +**See Also** + +- `wolfSSH_SetExitStatus()` + +### wolfSSH_SetExitStatus() + +```c +#include + +int wolfSSH_SetExitStatus(WOLFSSH* ssh, word32 exitStatus); +``` + +**Description** + +Sets the exit status to report to the peer for the session's command. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `exitStatus` - the exit status to report + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**See Also** + +- `wolfSSH_GetExitStatus()` + +### wolfSSH_DoModes() + +```c +#include + +int wolfSSH_DoModes(const byte* modes, word32 modesSz, int fd); +``` + +**Description** + +Applies the SSH-encoded terminal modes in `modes` to the terminal referenced by the file descriptor `fd`. + +**Parameters** + +- `modes` - buffer of SSH-encoded terminal modes +- `modesSz` - length of the modes buffer +- `fd` - file descriptor of the terminal to configure + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_ConvertConsole() + +**Availability** + +Available only on Windows builds (`USE_WINDOWS_API`). + +```c +#include + +int wolfSSH_ConvertConsole(WOLFSSH* ssh, WOLFSSH_HANDLE handle, + byte* buf, word32 bufSz); +``` + +**Description** + +Processes console data read from the Windows console handle, translating it for the SSH stream. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `handle` - the Windows console handle +- `buf` - buffer of console data to convert +- `bufSz` - length of the buffer + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_SetKeyingCompletionCb() + +```c +#include + +void wolfSSH_SetKeyingCompletionCb(WOLFSSH_CTX* ctx, + WS_CallbackKeyingCompletion cb); +``` + +**Description** + +Registers a callback that is invoked when a key exchange (initial or rekey) completes. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the keying completion callback + +**Return Values** + +None + +**See Also** + +- `wolfSSH_SetKeyingCompletionCbCtx()` + +### wolfSSH_SetKeyingCompletionCbCtx() + +```c +#include + +void wolfSSH_SetKeyingCompletionCbCtx(WOLFSSH* ssh, void* ctx); +``` + +**Description** + +Sets the user context pointer passed to the keying completion callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context pointer to pass to the callback + +**Return Values** + +None + +### wolfSSH_RealPath() + +```c +#include + +int wolfSSH_RealPath(const char* defaultPath, char* in, + char* out, word32 outSz); +``` + +**Description** + +Resolves the path `in`, relative to `defaultPath`, into a canonical absolute path written to `out`. + +**Parameters** + +- `defaultPath` - the base path used to resolve a relative `in` +- `in` - the path to resolve +- `out` - buffer where the resolved path is written +- `outSz` - size of the output buffer + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +## Port Forwarding Functions + + + +All functions in this section require wolfSSH to be built with port forwarding support (`WOLFSSH_FWD`, from `./configure --enable-fwd`). + +### wolfSSH_ChannelFwdNewLocal() + +```c +#include + +WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNewLocal(WOLFSSH* ssh, + const char* host, word32 hostPort, + const char* origin, word32 originPort); +``` + +**Description** + +Sets up a local TCP/IP forwarding channel on the session. Once the session is connected and authenticated, connections are forwarded to `host` on port `hostPort`, tagged with the originating address `origin` and port `originPort`. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `host` - destination host address +- `hostPort` - destination port +- `origin` - originating connection address +- `originPort` - originating connection port + +**Return Values** + +- pointer to the new channel, or `NULL` on error + +**See Also** + +- `wolfSSH_ChannelFwdNewRemote()` + +### wolfSSH_ChannelFwdNewRemote() + +```c +#include + +WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNewRemote(WOLFSSH* ssh, + const char* host, word32 hostPort, + const char* origin, word32 originPort); +``` + +**Description** + +Sets up a remote TCP/IP forwarding channel on the session, requesting that the peer forward connections back to `host` on port `hostPort`. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `host` - destination host address +- `hostPort` - destination port +- `origin` - originating connection address +- `originPort` - originating connection port + +**Return Values** + +- pointer to the new channel, or `NULL` on error + +**See Also** + +- `wolfSSH_ChannelFwdNewLocal()` + +### wolfSSH_CTX_SetFwdCb() + +```c +#include + +int wolfSSH_CTX_SetFwdCb(WOLFSSH_CTX* ctx, + WS_CallbackFwd fwdCb, WS_CallbackFwdIO fwdIoCb); +``` + +**Description** + +Registers the port forwarding setup/cleanup callback (`fwdCb`) and the forwarding I/O callback (`fwdIoCb`) on the context. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `fwdCb` - forwarding setup/cleanup callback +- `fwdIoCb` - forwarding I/O callback + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**See Also** + +- `wolfSSH_SetFwdCbCtx()` + +### wolfSSH_SetFwdCbCtx() + +```c +#include + +int wolfSSH_SetFwdCbCtx(WOLFSSH* ssh, void* ctx); +``` + +**Description** + +Sets the user context pointer passed to the port forwarding callbacks. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context pointer to pass to the forwarding callbacks + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_ChannelFwdNew() + +```c +#include + +WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNew(WOLFSSH* ssh, + const char* host, word32 hostPort, + const char* origin, word32 originPort); +``` + +**Description** + +Deprecated. Use wolfSSH_ChannelFwdNewLocal(); this function is retained for backward compatibility and forwards to it. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `host` - destination host address +- `hostPort` - destination port +- `origin` - originating connection address +- `originPort` - originating connection port + +**Return Values** + +- pointer to the new channel, or `NULL` on error + +**See Also** + +- `wolfSSH_ChannelFwdNewLocal()` + +### wolfSSH_ChannelSetFwdFd() + +```c +#include + +int wolfSSH_ChannelSetFwdFd(WOLFSSH_CHANNEL* channel, int fwdFd); +``` + +**Description** + +Deprecated. Associates a forwarding file descriptor with a forwarding channel. + +**Parameters** + +- `channel` - pointer to the forwarding channel +- `fwdFd` - the forwarding file descriptor + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_ChannelGetFwdFd() + +```c +#include + +int wolfSSH_ChannelGetFwdFd(const WOLFSSH_CHANNEL* channel); +``` + +**Description** + +Deprecated. Returns the forwarding file descriptor associated with a forwarding channel. + +**Parameters** + +- `channel` - pointer to the forwarding channel + +**Return Values** + +- the forwarding file descriptor, or a negative error code + + +## Key Load Functions + + +### wolfSSH_ReadKey_buffer() + +```c +#include + +int wolfSSH_ReadKey_buffer(const byte* in, word32 inSz, + int format, byte** out, word32* outSz, + const byte** outType, word32* outTypeSz, + void* heap); +``` + +**Description** + +Reads a key from the buffer `in` of size `inSz` and decodes it as a `format` type key. The `format` can be `WOLFSSH_FORMAT_ASN1`, `WOLFSSH_FORMAT_PEM`, `WOLFSSH_FORMAT_SSH`, or `WOLFSSH_FORMAT_OPENSSH`. The decoded key, ready for use by `wolfSSH_CTX_UsePrivateKey_buffer()`, is stored in the buffer pointed to by `out` of size `outSz`. If `out` is NULL, `heap` is used to allocate a buffer for the key. The key type string is stored in `outType`, with its length in `outTypeSz`. + +**Parameters** + +- `in` - buffer containing the encoded key +- `inSz` - size of the input buffer +- `format` - the encoding of the input key +- `out` - output buffer for the decoded key (allocated from `heap` if NULL) +- `outSz` - output for the decoded key size +- `outType` - output for the key type string +- `outTypeSz` - output for the key type string length +- `heap` - heap used for allocation when `out` is NULL + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` +- `WS_BUFFER_E` +- `WS_PARSE_E` +- `WS_UNIMPLEMENTED_E` +- `WS_RSA_E` +- `WS_ECC_E` +- `WS_KEY_AUTH_MAGIC_E` +- `WS_KEY_FORMAT_E` +- `WS_KEY_CHECK_VAL_E` + +**See Also** + +- `wolfSSH_ReadKey_file()` + +### wolfSSH_ReadKey_buffer_ex() + +```c +#include + +int wolfSSH_ReadKey_buffer_ex(const byte* in, word32 inSz, int format, + byte** out, word32* outSz, const byte** outType, word32* outTypeSz, + int isPrivate, void* heap); +``` + +**Description** + +Like wolfSSH_ReadKey_buffer(), but takes an explicit `isPrivate` flag indicating whether the buffer holds a private or public key rather than inferring it. + +**Parameters** + +- `in` - buffer containing the encoded key +- `inSz` - size of the input buffer +- `format` - the encoding of the input key +- `out` - output buffer for the decoded key (allocated from `heap` if NULL) +- `outSz` - output for the decoded key size +- `outType` - output for the key type string +- `outTypeSz` - output for the key type string length +- `isPrivate` - non-zero if the key is a private key, 0 if public +- `heap` - heap used for allocation when `out` is NULL + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` +- `WS_BUFFER_E` +- `WS_PARSE_E` +- `WS_UNIMPLEMENTED_E` + +**See Also** + +- `wolfSSH_ReadKey_buffer()` + +### wolfSSH_ReadPublicKey_buffer() + +```c +#include + +int wolfSSH_ReadPublicKey_buffer(const byte* in, word32 inSz, int format, + byte** out, word32* outSz, const byte** outType, word32* outTypeSz, + void* heap); +``` + +**Description** + +Reads and decodes a public key from the buffer `in`. Behaves like wolfSSH_ReadKey_buffer() but is specialized for public keys. + +**Parameters** + +- `in` - buffer containing the encoded public key +- `inSz` - size of the input buffer +- `format` - the encoding of the input key +- `out` - output buffer for the decoded key (allocated from `heap` if NULL) +- `outSz` - output for the decoded key size +- `outType` - output for the key type string +- `outTypeSz` - output for the key type string length +- `heap` - heap used for allocation when `out` is NULL + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_MEMORY_E` +- `WS_BUFFER_E` +- `WS_PARSE_E` +- `WS_UNIMPLEMENTED_E` + +**See Also** + +- `wolfSSH_ReadKey_buffer()` + + +### wolfSSH_ReadKey_file() + +```c +#include + +int wolfSSH_ReadKey_file(const char* name, + byte** out, word32* outSz, + const byte** outType, word32* outTypeSz, + byte* isPrivate, void* heap); +``` + +**Description** + +Reads the key from the file `name`. The format is guessed from the file contents. The key buffer `out`, the key type `outType`, and their sizes are produced as by wolfSSH_ReadKey_buffer(). The `isPrivate` flag is set to indicate whether the key is private. Any allocations use the specified `heap`. + +**Parameters** + +- `name` - path to the key file +- `out` - output buffer for the decoded key (allocated from `heap` if NULL) +- `outSz` - output for the decoded key size +- `outType` - output for the key type string +- `outTypeSz` - output for the key type string length +- `isPrivate` - output set non-zero if the key is private +- `heap` - heap used for allocation when `out` is NULL + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +- `WS_BAD_FILE_E` +- `WS_MEMORY_E` +- `WS_BUFFER_E` +- `WS_PARSE_E` +- `WS_UNIMPLEMENTED_E` +- `WS_RSA_E` +- `WS_ECC_E` +- `WS_KEY_AUTH_MAGIC_E` +- `WS_KEY_FORMAT_E` +- `WS_KEY_CHECK_VAL_E` + +**See Also** + +- `wolfSSH_ReadKey_buffer()` + + +## Key Exchange Algorithm Configuration + +wolfSSH sets up a set of algorithm lists used during the Key Exchange (KEX) +based on the availability of algorithms in the wolfCrypt library used. + +Provided are some accessor functions to see which algorithms are available +to use and to see the algorithm lists used in the KEX. The accessor functions +come in sets of four: set or get from CTX object, and set or get from SSH +object. All SSH objects made with a CTX inherit the CTX's algorithm lists, +and they may be provided their own. + +By default, any algorithms using SHA-1 are disabled but may be re-enabled +using one of the following functions. If SHA-1 is disabled in wolfCrypt, then +SHA-1 cannot be used. + + +### wolfSSH Set Algo Lists + +```c +#include + +int wolfSSH_CTX_SetAlgoListKex(WOLFSSH_CTX* ctx, const char* list); +int wolfSSH_CTX_SetAlgoListKey(WOLFSSH_CTX* ctx, const char* list); +int wolfSSH_CTX_SetAlgoListCipher(WOLFSSH_CTX* ctx, const char* list); +int wolfSSH_CTX_SetAlgoListMac(WOLFSSH_CTX* ctx, const char* list); +int wolfSSH_CTX_SetAlgoListKeyAccepted(WOLFSSH_CTX* ctx, const char* list); + +int wolfSSH_SetAlgoListKex(WOLFSSH* ssh, const char* list); +int wolfSSH_SetAlgoListKey(WOLFSSH* ssh, const char* list); +int wolfSSH_SetAlgoListCipher(WOLFSSH* ssh, const char* list); +int wolfSSH_SetAlgoListMac(WOLFSSH* ssh, const char* list); +int wolfSSH_SetAlgoListKeyAccepted(WOLFSSH* ssh, const char* list); +``` + +**Description** + +These functions act as setters for the various algorithm lists set in the +wolfSSH _ctx_ or _ssh_ objects. The strings are sent to the peer during the +KEX Initialization and are used to compare against when the peer sends its +KEX Initialization message. The KeyAccepted list is used for user +authentication. + +The CTX versions of the functions set the algorithm list for the specified +WOLFSSH_CTX object, _ctx_. They have default values set at compile time. The +specified value is used instead. Note, the library does not copy this string, +it is owned by the application and it is up to the application to free it +when the CTX is deallocated by the application. When creating an SSH object +using a CTX, the SSH object inherits the CTX's strings. The SSH object +algorithm lists may be overridden. + +`Kex` specifies the key exchange algorithm list. `Key` specifies the server +public key algorithm list. `Cipher` specifies the bulk encryption algorithm +list. `Mac` specifies the message authentication code algorithm list. +`KeyAccepted` specifies the public key algorithms allowed for user +authentication. + +**Return Values** + +- `WS_SUCCESS` +- `WS_SSH_CTX_NULL_E` +- `WS_SSH_NULL_E` + + +### wolfSSH Get Algo List + +```c +#include + +const char* wolfSSH_CTX_GetAlgoListKex(WOLFSSH_CTX* ctx); +const char* wolfSSH_CTX_GetAlgoListKey(WOLFSSH_CTX* ctx); +const char* wolfSSH_CTX_GetAlgoListCipher(WOLFSSH_CTX* ctx); +const char* wolfSSH_CTX_GetAlgoListMac(WOLFSSH_CTX* ctx); +const char* wolfSSH_CTX_GetAlgoListKeyAccepted(WOLFSSH_CTX* ctx); + +const char* wolfSSH_GetAlgoListKex(WOLFSSH* ssh); +const char* wolfSSH_GetAlgoListKey(WOLFSSH* ssh); +const char* wolfSSH_GetAlgoListCipher(WOLFSSH* ssh); +const char* wolfSSH_GetAlgoListMac(WOLFSSH* ssh); +const char* wolfSSH_GetAlgoListKeyAccepted(WOLFSSH* ssh); +``` + +**Description** + +These functions act as getters for the various algorithm lists set in the +wolfSSH _ctx_ or _ssh_ objects. + +`Kex` specifies the key exchange algorithm list. `Key` specifies the server +public key algorithm list. `Cipher` specifies the bulk encryption algorithm +list. `Mac` specifies the message authentication code algorithm list. +`KeyAccepted` specifies the public key algorithms allowed for user +authentication. + +**Return Values** + +These functions return a pointer to either the default value set at compile +time or the value set at run time with the setter functions. If the _ctx_ +or `ssh` parameters are NULL the functions return NULL. + + +### wolfSSH_CheckAlgoName() + +```c +#include + +int wolfSSH_CheckAlgoName(const char* name); +``` + +**Description** + +Checks whether the given single algorithm `name` is valid and supported. + +**Parameters** + +- `name` - the algorithm name to check + +**Return Values** + +- `WS_SUCCESS` +- `WS_INVALID_ALGO_ID` + + +### wolfSSH Query Algorithms + +```c +#include + +const char* wolfSSH_QueryKex(word32* index); +const char* wolfSSH_QueryKey(word32* index); +const char* wolfSSH_QueryCipher(word32* index); +const char* wolfSSH_QueryMac(word32* index); +``` + +**Description** + +Returns the name string for a valid algorithm of the given type (Kex, Key, Cipher, or Mac). Key types are also used for the user-authentication accepted key types. Initialize `index` to 0 and pass the same pointer on each call to iterate; the functions advance it. When the returned value is NULL, the end of the list has been reached. + +**Parameters** + +- `index` - iterator, initialized to 0 and passed on each call + +**Return Values** + +- pointer to an algorithm name string, or `NULL` at the end of the list + +### wolfSSH_GetText() + +```c +#include + +size_t wolfSSH_GetText(WOLFSSH* ssh, WS_Text id, char* str, size_t strSz); +``` + +**Description** + +Writes the text representation of the negotiated item identified by `id` (a `WS_Text` value such as the KEX algorithm, KEX curve, KEX hash, input/output cipher, or input/output MAC) into `str`, writing no more than `strSz` bytes including the terminating null. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `id` - the `WS_Text` item to retrieve +- `str` - output buffer for the text +- `strSz` - size of the output buffer + +**Return Values** + +- the number of characters written (excluding the null terminator); a value of `strSz` or more means the output was truncated + +## Global Request Callbacks + +These callbacks handle SSH global request messages and their success/failure replies. + +### wolfSSH_SetGlobalReq() + +```c +#include + +void wolfSSH_SetGlobalReq(WOLFSSH_CTX* ctx, WS_CallbackGlobalReq cb); +``` + +**Description** + +Registers the callback invoked when a global request message is received from the peer. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the global request callback + +**Return Values** + +None + +**See Also** + +- `wolfSSH_SetGlobalReqCtx()` + +### wolfSSH_SetGlobalReqCtx() + +```c +#include + +void wolfSSH_SetGlobalReqCtx(WOLFSSH* ssh, void* ctx); +``` + +**Description** + +Sets the user context pointer passed to the global request callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context pointer to pass to the callback + +**Return Values** + +None + +### wolfSSH_GetGlobalReqCtx() + +```c +#include + +void* wolfSSH_GetGlobalReqCtx(WOLFSSH* ssh); +``` + +**Description** + +Returns the user context pointer previously set with wolfSSH_SetGlobalReqCtx(). + +**Parameters** + +- `ssh` - pointer to the wolfSSH session + +**Return Values** + +- the global request context pointer, or `NULL` if none + +### wolfSSH_SetReqSuccess() + +```c +#include + +void wolfSSH_SetReqSuccess(WOLFSSH_CTX* ctx, WS_CallbackReqSuccess cb); +``` + +**Description** + +Registers the callback invoked when a request-success reply is received from the peer. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the request-success callback + +**Return Values** + +None + +**See Also** + +- `wolfSSH_SetReqSuccessCtx()` + +### wolfSSH_SetReqSuccessCtx() + +```c +#include + +void wolfSSH_SetReqSuccessCtx(WOLFSSH* ssh, void* ctx); +``` + +**Description** + +Sets the user context pointer passed to the request-success callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context pointer to pass to the callback + +**Return Values** + +None + +### wolfSSH_GetReqSuccessCtx() + +```c +#include + +void* wolfSSH_GetReqSuccessCtx(WOLFSSH* ssh); +``` + +**Description** + +Returns the user context pointer previously set with wolfSSH_SetReqSuccessCtx(). + +**Parameters** + +- `ssh` - pointer to the wolfSSH session + +**Return Values** + +- the request-success context pointer, or `NULL` if none + +### wolfSSH_SetReqFailure() + +```c +#include + +void wolfSSH_SetReqFailure(WOLFSSH_CTX* ctx, WS_CallbackReqSuccess cb); +``` + +**Description** + +Registers the callback invoked when a request-failure reply is received from the peer. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the request-failure callback + +**Return Values** + +None + +**See Also** + +- `wolfSSH_SetReqFailureCtx()` + +### wolfSSH_SetReqFailureCtx() + +```c +#include + +void wolfSSH_SetReqFailureCtx(WOLFSSH* ssh, void* ctx); +``` + +**Description** + +Sets the user context pointer passed to the request-failure callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context pointer to pass to the callback + +**Return Values** + +None + +### wolfSSH_GetReqFailureCtx() + +```c +#include + +void* wolfSSH_GetReqFailureCtx(WOLFSSH* ssh); +``` + +**Description** + +Returns the user context pointer previously set with wolfSSH_SetReqFailureCtx(). + +**Parameters** + +- `ssh` - pointer to the wolfSSH session + +**Return Values** + +- the request-failure context pointer, or `NULL` if none + +## TPM 2.0 Integration + +These functions integrate a wolfTPM 2.0 device and key for host-key operations. They require wolfSSH to be built with `WOLFSSH_TPM` and a wolfTPM installation. + +### wolfSSH_SetTpmDev() + +```c +#include + +void wolfSSH_SetTpmDev(WOLFSSH* ssh, WOLFTPM2_DEV* dev); +``` + +**Description** + +Associates a wolfTPM 2.0 device with the session for TPM-backed host-key operations. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `dev` - pointer to the wolfTPM 2.0 device + +**Return Values** + +None + +**See Also** + +- `wolfSSH_SetTpmKey()` + +### wolfSSH_SetTpmKey() + +```c +#include + +void wolfSSH_SetTpmKey(WOLFSSH* ssh, WOLFTPM2_KEY* key); +``` + +**Description** + +Associates a wolfTPM 2.0 key with the session for TPM-backed host-key operations. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `key` - pointer to the wolfTPM 2.0 key + +**Return Values** + +None + +### wolfSSH_GetTpmDev() + +```c +#include + +void* wolfSSH_GetTpmDev(WOLFSSH* ssh); +``` + +**Description** + +Returns the wolfTPM 2.0 device previously associated with the session. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session + +**Return Values** + +- pointer to the wolfTPM 2.0 device, or `NULL` if none + +### wolfSSH_GetTpmKey() + +```c +#include + +void* wolfSSH_GetTpmKey(WOLFSSH* ssh); +``` + +**Description** + +Returns the wolfTPM 2.0 key previously associated with the session. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session + +**Return Values** + +- pointer to the wolfTPM 2.0 key, or `NULL` if none + +### wolfSSH_CTX_UseTpmHostKey() + +```c +#include + +int wolfSSH_CTX_UseTpmHostKey(WOLFSSH_CTX* ctx, + WOLFTPM2_DEV* dev, WOLFTPM2_KEY* key); +``` + +**Description** + +Configures the context to use the given wolfTPM 2.0 device and key as the server host key. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `dev` - pointer to the wolfTPM 2.0 device +- `key` - pointer to the wolfTPM 2.0 key **Return Values** -Returns a constant string with the name of an algorithm. Null indicates the -end of the list. +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` diff --git a/wolfSSH/src/chapter14.md b/wolfSSH/src/chapter14.md index 0b0794d9..edfa2dd2 100644 --- a/wolfSSH/src/chapter14.md +++ b/wolfSSH/src/chapter14.md @@ -1,4 +1,4 @@ -# wolfSSL SFTP API Reference +# wolfSSH SFTP API Reference ## Connection Functions @@ -8,1226 +8,819 @@ -**Synopsis:** +```c +#include -**Description:** +int wolfSSH_SFTP_accept(WOLFSSH* ssh); +``` -Function to handle an incoming connection request from a client. +**Description** -**Return Values:** +Handles an incoming SFTP connection request from a client. Called on the server side after the SSH session is established. -Returns WS_SFTP_COMPLETE on success. +**Parameters** -**Parameters:** +- `ssh` - pointer to the wolfSSH session used for the connection -**ssh** - pointer to WOLFSSH structure used for connection +**Return Values** -**Example:** +- `WS_SFTP_COMPLETE` on success +- a negative error code on failure -``` -#include -int wolfSSH_SFTP_accept(WOLFSSH* ssh ); -``` -``` -WOLFSSH* ssh; -``` -``` -//create new WOLFSSH structure -... -``` -``` -if (wolfSSH_SFTP_accept(ssh) != WS_SUCCESS) { -//handle error case -} -``` - -**See Also:** +**See Also** -wolfSSH_SFTP_free() -wolfSSH_new() -wolfSSH_SFTP_connect() +- `wolfSSH_SFTP_connect()` +- `wolfSSH_SFTP_negotiate()` ### wolfSSH_SFTP_connect() -**Synopsis:** - -**Description:** +```c +#include -Function for initiating a connection to a SFTP server. +int wolfSSH_SFTP_connect(WOLFSSH* ssh); +``` -**Return Values:** +**Description** -**WS_SFTP_COMPLETE:** on success. +Initiates an SFTP connection to a server. Called on the client side after the SSH session is established. -**Parameters:** +**Parameters** -**ssh** - pointer to WOLFSSH structure to be used for connection +- `ssh` - pointer to the wolfSSH session used for the connection -**Example:** +**Return Values** -**See Also:** +- `WS_SFTP_COMPLETE` on success +- a negative error code on failure -wolfSSH_SFTP_accept() -wolfSSH_new() -wolfSSH_free() +**See Also** -``` -#include -int wolfSSH_SFTP_connect(WOLFSSH* ssh ); -``` -``` -WOLFSSH* ssh; -``` -``` -//after creating a new WOLFSSH structrue -``` -``` -wolfSSH_SFTP_connect(ssh); -``` +- `wolfSSH_SFTP_accept()` +- `wolfSSH_SFTP_negotiate()` ### wolfSSH_SFTP_negotiate() -**Synopsis:** +```c +#include -**Description:** +int wolfSSH_SFTP_negotiate(WOLFSSH* ssh); +``` -Function to handle either an incoming connection from client or to send out a -connection request to a server. It is dependent on which side of the connection the -created WOLFSSH structure is set to for which action is performed. +**Description** -**Return Values:** +Performs SFTP protocol negotiation. Depending on which side the session was created for, this either handles an incoming connection from a client or sends a connection request to a server. -Returns WS_SUCCESS on success. +**Parameters** -**Parameters:** +- `ssh` - pointer to the wolfSSH session used for the connection -**ssh** - pointer to WOLFSSH structure used for connection +**Return Values** -**Example:** +- `WS_SUCCESS` on success +- a negative error code on failure -**See Also:** +**See Also** -wolfSSH_SFTP_free() +- `wolfSSH_SFTP_accept()` +- `wolfSSH_SFTP_connect()` -``` + +### wolfSSH_SFTP_SetDefaultPath() + +```c #include -int wolfSSH_SFTP_negotiate(WOLFSSH* ssh) -``` -``` -WOLFSSH* ssh; -``` -``` -//create new WOLFSSH structure with side of connection -set -.... -``` -``` -if (wolfSSH_SFTP_negotiate(ssh) != WS_SUCCESS) { -//handle error case -} + +int wolfSSH_SFTP_SetDefaultPath(WOLFSSH* ssh, const char* path); ``` -wolfSSH_new() -wolfSSH_SFTP_connect() -wolfSSH_SFTP_accept() +**Description** +Sets the default (starting) directory for the SFTP session. On the server side this is the base directory against which relative paths are resolved. -## Protocol Level Functions +**Parameters** +- `ssh` - pointer to the wolfSSH session +- `path` - the default path to set +**Return Values** -### wolfSSH_SFTP_RealPath() +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` +## Protocol Level Functions -**Synopsis:** -**Description:** +### wolfSSH_SFTP_RealPath() -Function to send REALPATH packet to peer. It gets the name of the file returned from -peer. -**Return Values:** -Returns a pointer to a WS_SFTPNAME structure on success and NULL on error. +```c +#include -**Parameters:** +WS_SFTPNAME* wolfSSH_SFTP_RealPath(WOLFSSH* ssh, char* dir); +``` -**ssh** - pointer to WOLFSSH structure used for connection -**dir** - directory / file name to get real path of +**Description** -**Example:** +Sends a REALPATH request to the peer and returns the canonical name of the file or directory. The returned `WS_SFTPNAME` must be freed with wolfSSH_SFTPNAME_free(). -``` -#include -WS_SFTPNAME* wolfSSH_SFTP_RealPath(WOLFSSH* ssh , char* -dir ); -``` +**Parameters** -**See Also:** +- `ssh` - pointer to the wolfSSH session +- `dir` - the file or directory name to resolve -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +**Return Values** -``` -WOLFSSH* ssh ; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -if (wolfSSH_SFTP_read( ssh ) != WS_SUCCESS) { -//handle error case -} -``` +- pointer to a `WS_SFTPNAME` structure on success +- `NULL` on error -### wolfSSH_SFTP_Close() +**See Also** +- `wolfSSH_SFTPNAME_free()` +### wolfSSH_SFTP_Close() -**Synopsis:** -**Description:** -Function to to send a close packet to the peer. +```c +#include -**Return Values:** +int wolfSSH_SFTP_Close(WOLFSSH* ssh, byte* handle, word32 handleSz); +``` -**WS_SUCCESS** on success. +**Description** -**Parameters:** +Sends a close request to the peer for the given file handle, which was obtained from a previous call to wolfSSH_SFTP_Open(). -**ssh** - pointer to WOLFSSH structure used for connection -**handle** - handle to try and close -**handleSz** - size of handle buffer +**Parameters** -**Example:** +- `ssh` - pointer to the wolfSSH session +- `handle` - the file handle to close +- `handleSz` - size of the handle buffer -``` -#include -int wolfSSH_SFTP_Close(WOLFSSH* ssh , byte* handle , word32 -handleSz ); -``` +**Return Values** -**See Also:** +- `WS_SUCCESS` +- a negative error code on failure -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +**See Also** -``` -WOLFSSH* ssh; -byte handle[HANDLE_SIZE]; -word32 handleSz = HANDLE_SIZE; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -if (wolfSSH_SFTP_Close(ssh, handle, handleSz) != -WS_SUCCESS) { -//handle error case -} -``` +- `wolfSSH_SFTP_Open()` ### wolfSSH_SFTP_Open() -**Synopsis:** +```c +#include -**Description:** +int wolfSSH_SFTP_Open(WOLFSSH* ssh, char* dir, word32 reason, + WS_SFTP_FILEATRB* atr, byte* handle, word32* handleSz); +``` -Function to to send an open packet to the peer. This sets handleSz with the size of -resulting buffer and gets the resulting handle from the peer and places it in the buffer -handle. +**Description** -Available reasons for open: -WOLFSSH_FXF_READ -WOLFSSH_FXF_WRITE -WOLFSSH_FXF_APPEND -WOLFSSH_FXF_CREAT -WOLFSSH_FXF_TRUNC -WOLFSSH_FXF_EXCL +Sends an open request to the peer for the file named by `dir`. On success the resulting file handle is placed in `handle` and its size is written to `handleSz`. The `reason` argument is a bitmask of the open flags: `WOLFSSH_FXF_READ`, `WOLFSSH_FXF_WRITE`, `WOLFSSH_FXF_APPEND`, `WOLFSSH_FXF_CREAT`, `WOLFSSH_FXF_TRUNC`, or `WOLFSSH_FXF_EXCL`. -**Return Values:** +**Parameters** -**WS_SUCCESS** on success. +- `ssh` - pointer to the wolfSSH session +- `dir` - name of the file to open +- `reason` - bitmask of open flags (see above) +- `atr` - initial file attributes +- `handle` - output buffer for the resulting file handle +- `handleSz` - on input the buffer size, set on output to the handle size -**Parameters:** +**Return Values** -**ssh** - pointer to WOLFSSH structure used for connection -**dir** - name of file to open -**reason** - reason for opening the file -**atr** - initial attributes for file -**handle** - resulting handle from open -**handleSz** - gets set to the size of resulting handle +- `WS_SUCCESS` +- a negative error code on failure -``` -#include -int wolfSSH_SFTP_Open(WOLFSSH* ssh , char* dir , word32 -reason , -WS_SFTP_FILEATRB* atr , byte* handle , word32* handleSz ) ; -``` +**See Also** -**Example:** +- `wolfSSH_SFTP_Close()` +- `wolfSSH_SFTP_SendReadPacket()` +- `wolfSSH_SFTP_SendWritePacket()` -**See Also:** +### wolfSSH_SFTP_SendReadPacket() -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +```c +#include -``` -WOLFSSH* ssh ; -char name[NAME_SIZE]; -byte handle[HANDLE_SIZE]; -word32 handleSz = HANDLE_SIZE; -WS_SFTP_FILEATRB atr; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -if (wolfSSH_SFTP_Open( ssh , name , WOLFSSH_FXF_WRITE | -WOLFSSH_FXF_APPEND | WOLFSSH_FXF_CREAT , & atr , handle , -& handleSz ) -!= WS_SUCCESS) { -//handle error case -} +int wolfSSH_SFTP_SendReadPacket(WOLFSSH* ssh, byte* handle, + word32 handleSz, const word32* ofst, byte* out, word32 outSz); ``` -### wolfSSH_SFTP_SendReadPacket() +**Description** -**Synopsis:** +Sends a read request to the peer for the file referenced by `handle` (obtained from wolfSSH_SFTP_Open()). The bytes read are placed into the `out` buffer. The `ofst` argument points to the file offset to read from. -**Description:** +**Parameters** -Function to to send a read packet to the peer. The buffer handle should contain the -result of a previous call to wolfSSH_SFTP_Open. The resulting bytes from a read are -placed into the “out” buffer. +- `ssh` - pointer to the wolfSSH session +- `handle` - the file handle to read from +- `handleSz` - size of the handle buffer +- `ofst` - pointer to the file offset to start reading from +- `out` - buffer to hold the data read +- `outSz` - size of the output buffer -**Return Values:** +**Return Values** -Returns the number of bytes read on success. -A negative value is returned on failure. +- greater than or equal to 0 - number of bytes read on success +- a negative error code on failure -**Parameters:** +**See Also** -**ssh** - pointer to WOLFSSH structure used for connection -**handle** - handle to try and read from -**handleSz** - size of handle buffer -**ofst** - offset to start reading from -**out** - buffer to hold result from read -**outSz** - size of out buffer +- `wolfSSH_SFTP_SendWritePacket()` +- `wolfSSH_SFTP_Open()` -**Example:** +### wolfSSH_SFTP_SendWritePacket() -``` -#include -int wolfSSH_SFTP_SendReadPacket(WOLFSSH* ssh , byte* -handle , word32 -handleSz , word64 ofst , byte* out , word32 outSz ); -``` -**See Also:** -wolfSSH_SFTP_SendWritePacket() -wolfSSH_SFTP_Open() +```c +#include -``` -WOLFSSH* ssh; -byte handle[HANDLE_SIZE]; -word32 handleSz = HANDLE_SIZE; -byte out[OUT_SIZE]; -word32 outSz = OUT_SIZE; -word32 ofst = 0; -int ret; -``` -``` -//set up ssh and do sftp connections -... -//get handle with wolfSSH_SFTP_Open() -``` -``` -if ((ret = wolfSSH_SFTP_SendReadPacket(ssh, handle, -handleSz, ofst, -out, outSz)) < 0) { -//handle error case -} -//ret holds the number of bytes placed into out buffer +int wolfSSH_SFTP_SendWritePacket(WOLFSSH* ssh, byte* handle, + word32 handleSz, const word32* ofst, byte* out, word32 outSz); ``` -### wolfSSH_SFTP_SendWritePacket() +**Description** +Sends a write request to the peer for the file referenced by `handle` (obtained from wolfSSH_SFTP_Open()), writing the contents of the `out` buffer. The `ofst` argument points to the file offset to write at. +**Parameters** -**Synopsis:** +- `ssh` - pointer to the wolfSSH session +- `handle` - the file handle to write to +- `handleSz` - size of the handle buffer +- `ofst` - pointer to the file offset to start writing at +- `out` - buffer of data to send to the peer +- `outSz` - size of the buffer -**Description:** +**Return Values** -Function to send a write packet to the peer. -The buffer handle should contain the result of a previous call to -wolfSSH_SFTP_Open(). +- greater than or equal to 0 - number of bytes written on success +- a negative error code on failure -**Return Values:** +**See Also** -Returns the number of bytes written on success. -A negative value is returned on failure. +- `wolfSSH_SFTP_SendReadPacket()` +- `wolfSSH_SFTP_Open()` -**Parameters:** +### wolfSSH_SFTP_STAT() -**ssh** - pointer to WOLFSSH structure used for connection -**handle** - handle to try and read from -**handleSz** - size of handle buffer -**ofst** - offset to start reading from -**out** - buffer to send to peer for writing -**outSz** - size of out buffer -**Example:** -``` +```c #include -int wolfSSH_SFTP_SendWritePacket(WOLFSSH* ssh , byte* -handle , word32 -handleSz , word64 ofst , byte* out , word32 outSz ); + +int wolfSSH_SFTP_STAT(WOLFSSH* ssh, char* dir, WS_SFTP_FILEATRB* atr); ``` -**See Also:** +**Description** -wolfSSH_SFTP_SendReadPacket() -wolfSSH_SFTP_Open() +Sends a STAT request to the peer to retrieve the attributes of a file or directory, following symbolic links. If the target does not exist, the peer returns an error and this function returns an error value. -``` -WOLFSSH* ssh; -byte handle[HANDLE_SIZE]; -word32 handleSz = HANDLE_SIZE; -byte out[OUT_SIZE]; -word32 outSz = OUT_SIZE; -word32 ofst = 0; -int ret; -``` -``` -//set up ssh and do sftp connections -... -//get handle with wolfSSH_SFTP_Open() -``` -``` -if ((ret = wolfSSH_SFTP_SendWritePacket(ssh, handle, -handleSz, ofst, -out,outSz)) < 0) { -//handle error case -} -//ret holds the number of bytes written -``` +**Parameters** -### wolfSSH_SFTP_STAT() +- `ssh` - pointer to the wolfSSH session +- `dir` - null-terminated name of the file or directory +- `atr` - structure that receives the resulting attributes +**Return Values** +- `WS_SUCCESS` +- a negative error code on failure -**Synopsis:** +**See Also** -**Description:** +- `wolfSSH_SFTP_LSTAT()` +- `wolfSSH_SFTP_SetSTAT()` -Function to send a STAT packet to the peer. This will get the attributes of file or -directory. If the file or attribute does not exist the peer will return resulting in this function -returning an error value. +### wolfSSH_SFTP_LSTAT() -**Return Values:** +```c +#include -**WS_SUCCESS** on success. +int wolfSSH_SFTP_LSTAT(WOLFSSH* ssh, char* dir, WS_SFTP_FILEATRB* atr); +``` -**Parameters:** +**Description** -**ssh** - pointer to WOLFSSH structure used for connection -**dir** - NULL terminated name of file or directory to get attributes of -**atr** - resulting attributes are set into this structure +Sends an LSTAT request to the peer to retrieve the attributes of a file or directory. Unlike wolfSSH_SFTP_STAT(), LSTAT does not follow symbolic links: it returns the attributes of the link itself. If the target does not exist, the peer returns an error and this function returns an error value. -**Example:** +**Parameters** -``` -#include -int wolfSSH_SFTP_STAT(WOLFSSH* ssh , char* dir , -WS_SFTP_FILEATRB* atr); -``` +- `ssh` - pointer to the wolfSSH session +- `dir` - null-terminated name of the file or directory +- `atr` - structure that receives the resulting attributes -**See Also:** +**Return Values** -wolfSSH_SFTP_LSTAT() -wolfSSH_SFTP_connect() +- `WS_SUCCESS` +- a negative error code on failure -``` -WOLFSSH* ssh; -byte name[NAME_SIZE]; -int ret; -WS_SFTP_FILEATRB atr; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -if ((ret = wolfSSH_SFTP_STAT(ssh, name, &atr)) < 0) { -//handle error case -} -``` +**See Also** -### wolfSSH_SFTP_LSTAT() +- `wolfSSH_SFTP_STAT()` +- `wolfSSH_SFTP_SetSTAT()` -**Synopsis:** +### wolfSSH_SFTP_SetSTAT() -**Description:** +```c +#include -Function to send a LSTAT packet to the peer. This will get the attributes of file or -directory. It follows symbolic links where a STAT packet will not follow symbolic links. If -the file or attribute does not exist the peer will return resulting in this function returning -an error value. +int wolfSSH_SFTP_SetSTAT(WOLFSSH* ssh, char* dir, WS_SFTP_FILEATRB* atr); +``` -**Return Values:** +**Description** -WS_SUCCESS on success. +Sends a SETSTAT request to the peer to apply the attributes in `atr` (for example permissions, size, or timestamps) to the named file or directory. -**Parameters:** +**Parameters** -**ssh** - pointer to WOLFSSH structure used for connection -**dir** - NULL terminated name of file or directory to get attributes of -**atr** - resulting attributes are set into this structure +- `ssh` - pointer to the wolfSSH session +- `dir` - null-terminated name of the file or directory +- `atr` - the attributes to apply -Example: +**Return Values** -``` -#include -int wolfSSH_SFTP_LSTAT(WOLFSSH* ssh , char* dir , -WS_SFTP_FILEATRB* atr ); -``` +- `WS_SUCCESS` +- a negative error code on failure -**See Also:** +**See Also** -wolfSSH_SFTP_STAT() -wolfSSH_SFTP_connect() +- `wolfSSH_SFTP_STAT()` -``` -WOLFSSH* ssh; -byte name[NAME_SIZE]; -int ret; -WS_SFTP_FILEATRB atr; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -if ((ret = wolfSSH_SFTP_LSTAT(ssh, name, &atr)) < 0) { -//handle error case -} +### wolfSSH_SFTPNAME_free() + +```c +#include + +void wolfSSH_SFTPNAME_free(WS_SFTPNAME* n); ``` -### wolfSSH_SFTPNAME_free() +**Description** -**Synopsis:** +Frees a single `WS_SFTPNAME` node. If the node is in the middle of a list, freeing it breaks the list; use wolfSSH_SFTPNAME_list_free() to free an entire list. -**Description:** +**Parameters** -Function to free a single WS_SFTPNAME node. Note that if this node is in the middle of a -list of nodes then the list will be broken. +- `n` - the `WS_SFTPNAME` node to free -**Return Values:** +**Return Values** None -**Parameters:** - -**name** - structure to be free’d +**See Also** -**Example:** +- `wolfSSH_SFTPNAME_list_free()` -**See Also:** +### wolfSSH_SFTPNAME_list_free() -``` +```c #include -``` -### void wolfSSH_SFTPNAME_free(WS_SFTPNMAE* name ); -``` -WOLFSSH* ssh; -WS_SFTPNAME* name; -``` -``` -//set up ssh and do sftp connections -... -name = wolfSSH_SFTP_RealPath(ssh, path); -if (name != NULL) { -wolfSSH_SFTPNAME_free(name); -} +void wolfSSH_SFTPNAME_list_free(WS_SFTPNAME* n); ``` -wolfSSH_SFTPNAME_list_free +**Description** -wolfSSH_SFTPNAME_list_free() +Frees an entire list of `WS_SFTPNAME` nodes, such as the list returned by wolfSSH_SFTP_LS(). +**Parameters** +- `n` - head of the `WS_SFTPNAME` list to free -**Synopsis:** +**Return Values** -**Description:** +None -Function to free a all WS_SFTPNAME nodes in a list. +**See Also** -**Return Values:** +- `wolfSSH_SFTPNAME_free()` -None +## Reget / Reput Functions -**Parameters:** +### wolfSSH_SFTP_SaveOfst() -**name** - head of list to be free’d -**Example:** -``` +```c #include -void wolfSSH_SFTPNAME_list_free(WS_SFTPNMAE* name ); -``` -**See Also:** - -wolfSSH_SFTPNAME_free() - -``` -WOLFSSH* ssh; -WS_SFTPNAME* name; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -name = wolfSSH_SFTP_LS(ssh, path); -if (name != NULL) { -wolfSSH_SFTPNAME_list_free(name); -} +int wolfSSH_SFTP_SaveOfst(WOLFSSH* ssh, char* frm, char* to, + const word32* ofst); ``` -## Reget / Reput Functions +**Description** -### wolfSSH_SFTP_SaveOfst() +Saves the transfer offset for an interrupted get or put, keyed by the source (`frm`) and destination (`to`) paths. The saved offset can later be recovered with wolfSSH_SFTP_GetOfst(). +**Parameters** +- `ssh` - pointer to the wolfSSH session +- `frm` - null-terminated source path +- `to` - null-terminated destination path +- `ofst` - pointer to the offset to save -**Synopsis:** +**Return Values** -**Description:** +- `WS_SUCCESS` +- a negative error code on failure -Function to save an offset for an interrupted get or put command. The offset can be -recovered by calling wolfSSH_SFTP_GetOfst +**See Also** -**Return Values:** +- `wolfSSH_SFTP_GetOfst()` +- `wolfSSH_SFTP_Interrupt()` -Returns WS_SUCCESS on success. - -**Parameters:** +### wolfSSH_SFTP_GetOfst() -**ssh** - pointer to WOLFSSH structure for connection -**from** - NULL terminated string of source path -**to** - NULL terminated string with destination path -**ofst** - offset into file to be saved -Example: -``` +```c #include -int wolfSSH_SFTP_SaveOfst(WOLFSSH* ssh , char* from , char* -to , -word64 ofst ); -``` -**See Also:** - -wolfSSH_SFTP_GetOfst() -wolfSSH_SFTP_Interrupt() - -``` -WOLFSSH* ssh; -char from[NAME_SZ]; -char to[NAME_SZ]; -word64 ofst; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -if (wolfSSH_SFTP_SaveOfst(ssh, from, to, ofst) != -WS_SUCCESS) { -//handle error case -} +int wolfSSH_SFTP_GetOfst(WOLFSSH* ssh, char* frm, char* to, + word32* ofst); ``` -### wolfSSH_SFTP_GetOfst() +**Description** +Retrieves the saved transfer offset for an interrupted get or put, keyed by the source (`frm`) and destination (`to`) paths, writing it to `ofst`. If no saved offset is found, `ofst` is set to 0. +**Parameters** -**Synopsis:** +- `ssh` - pointer to the wolfSSH session +- `frm` - null-terminated source path +- `to` - null-terminated destination path +- `ofst` - output for the saved offset -**Description:** +**Return Values** -Function to retrieve an offset for an interrupted get or put command. +- `WS_SUCCESS` +- a negative error code on failure -**Return Values:** +**See Also** -Returns offset value on success. If not stored offset is found then 0 is returned. +- `wolfSSH_SFTP_SaveOfst()` +- `wolfSSH_SFTP_Interrupt()` -**Parameters:** +### wolfSSH_SFTP_ClearOfst() -**ssh** - pointer to WOLFSSH structure for connection -**from** - NULL terminated string of source path -**to** - NULL terminated string with destination path -**Example:** -``` +```c #include -word64 wolfSSH_SFTP_GetOfst(WOLFSSH* ssh, char* from, -char* to); -``` -``` -WOLFSSH* ssh; -char from[NAME_SZ]; -char to[NAME_SZ]; -word64 ofst; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -ofst = wolfSSH_SFTP_GetOfst(ssh, from, to); -//start reading/writing from ofst -``` -**See Also:** - -wolfSSH_SFTP_SaveOfst() -wolfSSH_SFTP_Interrup() +int wolfSSH_SFTP_ClearOfst(WOLFSSH* ssh); +``` -### wolfSSH_SFTP_ClearOfst() +**Description** +Clears all stored transfer offsets for the session. +**Parameters** -**Synopsis:** +- `ssh` - pointer to the wolfSSH session -**Description:** +**Return Values** -Function to clear all stored offset values. +- `WS_SUCCESS` +- a negative error code on failure -**Return Values:** +**See Also** -**WS_SUCCESS** on success +- `wolfSSH_SFTP_SaveOfst()` +- `wolfSSH_SFTP_GetOfst()` -**Parameters:** +### wolfSSH_SFTP_Interrupt() -**ssh** - pointer to WOLFSSH structure -**Example:** -``` +```c #include -int wolfSSH_SFTP_ClearOfst(WOLFSSH* ssh); + +void wolfSSH_SFTP_Interrupt(WOLFSSH* ssh); ``` -**See Also:** +**Description** -wolfSSH_SFTP_SaveOfst() -wolfSSH_SFTP_GetOfst() +Sets the interrupt flag on the session to stop an in-progress get or put transfer. The current offset can be saved with wolfSSH_SFTP_SaveOfst() so the transfer can be resumed later. -### wolfSSH_SFTP_Interrupt() +**Parameters** +- `ssh` - pointer to the wolfSSH session +**Return Values** -**Synopsis:** +None -**Description:** +**See Also** -Function to set interrupt flag and stop a get/put command. +- `wolfSSH_SFTP_SaveOfst()` +- `wolfSSH_SFTP_GetOfst()` -**Return Values:** +## Command Functions -None -**Parameters:** -**ssh** - pointer to WOLFSSH structure +### wolfSSH_SFTP_Remove() -**Example:** -``` -WOLFSSH* ssh; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -if (wolfSSH_SFTP_ClearOfst(ssh) != WS_SUCCESS) { -//handle error -} -``` -``` + +```c #include -void wolfSSH_SFTP_Interrupt(WOLFSSH* ssh); + +int wolfSSH_SFTP_Remove(WOLFSSH* ssh, char* f); ``` -**See Also:** +**Description** -wolfSSH_SFTP_SaveOfst() -wolfSSH_SFTP_GetOfst() +Sends a remove request to the peer to delete the file named by `f`. -``` -WOLFSSH* ssh; -char from[NAME_SZ]; -char to[NAME_SZ]; -word64 ofst; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -wolfSSH_SFTP_Interrupt(ssh); -wolfSSH_SFTP_SaveOfst(ssh, from, to, ofst); -``` +**Parameters** -## Command Functions +- `ssh` - pointer to the wolfSSH session +- `f` - null-terminated name of the file to remove +**Return Values** +- `WS_SUCCESS` +- a negative error code on failure -### wolfSSH_SFTP_Remove() +**See Also** +- `wolfSSH_SFTP_RMDIR()` +### wolfSSH_SFTP_MKDIR() -**Synopsis:** -**Description:** -Function for sending a “remove” packet across the channel. -The file name passed in as “f” is sent to the peer for removal. +```c +#include -**Return Values:** +int wolfSSH_SFTP_MKDIR(WOLFSSH* ssh, char* dir, WS_SFTP_FILEATRB* atr); +``` -**WS_SUCCESS** : returns WS_SUCCESS on success. +**Description** -**Parameters:** +Sends a mkdir request to the peer to create the directory named by `dir`. The `atr` attributes are currently not used; default attributes are applied instead. -**ssh** - pointer to WOLFSSH structure used for connection -**f** - file name to be removed +**Parameters** -**Example:** +- `ssh` - pointer to the wolfSSH session +- `dir` - null-terminated name of the directory to create +- `atr` - attributes for the new directory (currently unused) -``` -#include -int wolfSSH_SFTP_Remove(WOLFSSH* ssh , char* f ); -``` -``` -WOLFSSH* ssh; -int ret; -char* name[NAME_SZ]; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -ret = wolfSSH_SFTP_Remove(ssh, name); -``` +**Return Values** -**See Also:** +- `WS_SUCCESS` +- a negative error code on failure -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +**See Also** -### wolfSSH_SFTP_MKDIR() +- `wolfSSH_SFTP_RMDIR()` +### wolfSSH_SFTP_RMDIR() -**Synopsis:** -**Description:** +```c +#include -Function for sending a “mkdir” packet across the channel. The directory name passed in -as “dir” is sent to the peer for creation. Currently the attributes passed in are not used -and default attributes is set instead. +int wolfSSH_SFTP_RMDIR(WOLFSSH* ssh, char* dir); +``` -**Return Values:** +**Description** -**WS_SUCCESS** : returns WS_SUCCESS on success. +Sends an rmdir request to the peer to delete the directory named by `dir`. -**Parameters:** +**Parameters** -ssh - pointer to WOLFSSH structure used for connection -dir - NULL terminated directory to be created -atr - attributes to be used with directory creation +- `ssh` - pointer to the wolfSSH session +- `dir` - null-terminated name of the directory to remove -**Example:** +**Return Values** -``` -#include -int wolfSSH_SFTP_MKDIR(WOLFSSH* ssh , char* dir , -WS_SFTP_FILEATRB* -atr ); -``` +- `WS_SUCCESS` +- a negative error code on failure -**See Also:** +**See Also** -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +- `wolfSSH_SFTP_MKDIR()` -### wolfSSH_SFTP_RMDIR() +### wolfSSH_SFTP_Rename() -**Synopsis:** +```c +#include -**Description:** +int wolfSSH_SFTP_Rename(WOLFSSH* ssh, const char* old, const char* nw); +``` -Function for sending a “rmdir” packet across the channel. The directory name passed in -as “dir” is sent to the peer for deletion. +**Description** -**Return Values:** +Sends a rename request to the peer, renaming the file `old` to `nw`. -**WS_SUCCESS** : returns WS_SUCCESS on success. +**Parameters** -**Parameters:** +- `ssh` - pointer to the wolfSSH session +- `old` - the current file name +- `nw` - the new file name -**ssh** - pointer to WOLFSSH structure used for connection -**dir** - NULL terminated directory to be remove +**Return Values** -``` -WOLFSSH* ssh; -int ret; -char* dir[DIR_SZ]; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -ret = wolfSSH_SFTP_MKDIR(ssh, dir, DIR_SZ); -``` -``` -#include -int wolfSSH_SFTP_RMDIR(WOLFSSH* ssh , char* dir ); -``` +- `WS_SUCCESS` +- a negative error code on failure -**Example:** +**See Also** -**See Also:** +- `wolfSSH_SFTP_Remove()` -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +### wolfSSH_SFTP_LS() -``` -WOLFSSH* ssh; -int ret; -char* dir[DIR_SZ]; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -ret = wolfSSH_SFTP_RMDIR(ssh, dir); -``` -### wolfSSH_SFTP_Rename() +```c +#include +WS_SFTPNAME* wolfSSH_SFTP_LS(WOLFSSH* ssh, char* dir); +``` -**Synopsis:** +**Description** -**Description:** +Lists the files and directories in `dir`. This is a high-level helper that performs the REALPATH, OPENDIR, READDIR, and CLOSE operations. The returned list must be freed with wolfSSH_SFTPNAME_list_free(). -Function for sending a “rename” packet across the channel. This tries to have a peer file -renamed from “old” to “nw”. +**Parameters** -**Return Values:** +- `ssh` - pointer to the wolfSSH session +- `dir` - the directory to list -**WS_SUCCESS** : returns WS_SUCCESS on success. +**Return Values** -**Parameters:** +- pointer to a list of `WS_SFTPNAME` structures on success +- `NULL` on failure -**ssh** - pointer to WOLFSSH structure used for connection -**old** - Old file name -**nw** - New file name +**See Also** -**Example:** +- `wolfSSH_SFTPNAME_list_free()` +- `wolfSSH_SFTP_RealPath()` -``` -#include -int wolfSSH_SFTP_Rename(WOLFSSH* ssh , const char* old , -const char* -nw ); -``` -``` -WOLFSSH* ssh; -int ret; -char* old[NAME_SZ]; -char* nw[NAME_SZ]; //new file name -``` -``` -//set up ssh and do sftp connections -... -``` -``` -ret = wolfSSH_SFTP_Rename(ssh, old, nw); -``` +### wolfSSH_SFTP_CHMOD() -**See Also:** +```c +#include -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +int wolfSSH_SFTP_CHMOD(WOLFSSH* ssh, char* n, char* oct); +``` -### wolfSSH_SFTP_LS() +**Description** +Changes the permission bits of the file or directory `n` to the mode given by the octal string `oct` (for example, "644"). Implemented by sending a SETSTAT request with the new permissions. +**Parameters** -**Synopsis:** +- `ssh` - pointer to the wolfSSH session +- `n` - null-terminated name of the file or directory +- `oct` - octal permission string (for example, "755") -**Description:** +**Return Values** -Function for performing LS operation which gets a list of all files and directories in the -current working directory. This is a high level function that performs REALPATH, -OPENDIR, READDIR, and CLOSE operations. +- `WS_SUCCESS` +- a negative error code on failure -**Return Values:** +**See Also** -On Success, returns a pointer to a list of WS_SFTPNAME structures. -NULL on failure. +- `wolfSSH_SFTP_SetSTAT()` -**Parameters:** +### wolfSSH_SFTP_Get() -**ssh** - pointer to WOLFSSH structure used for connection -**dir** - directory to list -**Example:** -``` +```c #include -WS_SFTPNAME* wolfSSH_SFTP_LS(WOLFSSH* ssh , char* dir ); -``` - -**See Also:** - -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() -wolfSSH_SFTPNAME_list_free() -``` -WOLFSSH* ssh; -int ret; -char* dir[DIR_SZ]; -WS_SFTPNAME* name; -WS_SFTPNAME* tmp; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -name = wolfSSH_SFTP_LS(ssh, dir); -tmp = name; -while (tmp != NULL) { -printf("%s\n", tmp->fName); -tmp = tmp->next; -} -wolfSSH_SFTPNAME_list_free(name); +int wolfSSH_SFTP_Get(WOLFSSH* ssh, char* from, char* to, + byte resume, WS_STATUS_CB* statusCb); ``` -### wolfSSH_SFTP_Get() +**Description** +Downloads a file from the peer to a local path. This is a high-level helper that performs the LSTAT, OPEN, READ, and CLOSE operations. A transfer in progress can be interrupted with wolfSSH_SFTP_Interrupt(). +**Parameters** -**Synopsis:** +- `ssh` - pointer to the wolfSSH session +- `from` - the remote file name to get +- `to` - the local path to write the file to +- `resume` - non-zero to resume a previously interrupted transfer, 0 otherwise +- `statusCb` - callback invoked with transfer progress, or `NULL` -**Description:** +**Return Values** -Function for performing get operation which gets a file from the peer and places it in a -local directory. This is a high level function that performs LSTAT, OPEN, READ, and -CLOSE operations. To interrupt the operation call the function -wolfSSH_SFTP_Interrupt. (See the API documentation of this function for more -information on what it does) +- `WS_SUCCESS` +- a negative error code on failure -**Return Values:** +**See Also** -**WS_SUCCESS** : on success. -All other return values should be considered error cases. +- `wolfSSH_SFTP_Put()` +- `wolfSSH_SFTP_Interrupt()` -**Parameters:** +### wolfSSH_SFTP_Put() -**ssh** - pointer to WOLFSSH structure used for connection -**from** - file name to get -**to** - file name to place result at -**resume** - flag to try resume of operation. 1 for yes 0 for no -**statusCb** - callback function to get status -**Example:** -``` +```c #include -``` -``` -int wolfSSH_SFTP_Get(WOLFSSH* ssh , char* from , char* to , -byte resume , -WS_STATUS_CB* statusCb ); + +int wolfSSH_SFTP_Put(WOLFSSH* ssh, char* from, char* to, + byte resume, WS_STATUS_CB* statusCb); ``` -**See Also:** +**Description** -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +Uploads a local file to the peer. This is a high-level helper that performs the OPEN, WRITE, and CLOSE operations. A transfer in progress can be interrupted with wolfSSH_SFTP_Interrupt(). -``` -static void myStatusCb(WOLFSSH* sshIn, long bytes, char* -name) -{ -char buf[80]; -WSNPRINTF(buf, sizeof(buf), "Processed %8ld\t bytes -\r", bytes); -WFPUTS(buf, fout); -(void)name; -(void)sshIn; -} -... -WOLFSSH* ssh; -char* from[NAME_SZ]; -char* to[NAME_SZ]; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -if (wolfSSH_SFTP_Get( ssh , from , to , 0 , & myStatusCb ) != -WS_SUCCESS) { -//handle error case -} -``` +**Parameters** -### wolfSSH_SFTP_Put() +- `ssh` - pointer to the wolfSSH session +- `from` - the local file name to push +- `to` - the remote path to write the file to +- `resume` - non-zero to resume a previously interrupted transfer, 0 otherwise +- `statusCb` - callback invoked with transfer progress, or `NULL` +**Return Values** +- `WS_SUCCESS` +- a negative error code on failure -**Synopsis:** +**See Also** -**Description:** +- `wolfSSH_SFTP_Get()` +- `wolfSSH_SFTP_Interrupt()` -Function for performing put operation which pushes a file local file to a peers directory. -This is a high level function that performs OPEN, WRITE, and CLOSE operations. -To interrupt the operation call the function wolfSSH_SFTP_Interrupt. -(See the API documentation of this function for more information on what it does) +## SFTP Server Functions -**Return Values:** -**WS_SUCCESS** on success. -All other return values should be considered error cases. -**Parameters:** +### wolfSSH_SFTP_read() -**ssh** - pointer to WOLFSSH structure used for connection -**from** - file name to push -**to** - file name to place result at -**resume** - flag to try resume of operation. 1 for yes 0 for no -**statusCb** - callback function to get status -**Example:** -``` +```c #include -int wolfSSH_SFTP_Put(WOLFSSH* ssh , char* from , char* to , -byte resume , WS_STATUS_CB* statusCb ); -``` - -**See Also:** -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() - -``` -static void myStatusCb(WOLFSSH* sshIn, long bytes, char* -name) -{ -char buf[80]; -WSNPRINTF(buf, sizeof(buf), "Processed %8ld\t bytes -\r", bytes); -WFPUTS(buf, fout); -(void)name; -(void)sshIn; -} -... -``` -``` -WOLFSSH* ssh; -char* from[NAME_SZ]; -char* to[NAME_SZ]; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -if (wolfSSH_SFTP_Put(ssh, from, to, 0, &myStatusCb) != -WS_SUCCESS) { -//handle error case -} +int wolfSSH_SFTP_read(WOLFSSH* ssh); ``` -## SFTP Server Functions +**Description** +The main server-side SFTP entry point. Reads from the I/O buffer and dispatches to the appropriate internal handler based on the SFTP packet type received. Call this from the server loop to service SFTP requests. +**Parameters** -### wolfSSH_SFTP_read() +- `ssh` - pointer to the wolfSSH session + +**Return Values** +- `WS_SUCCESS` +- a negative error code on failure +**See Also** -**Synopsis:** +- `wolfSSH_SFTP_accept()` +- `wolfSSH_SFTP_PendingSend()` -**Description:** +### wolfSSH_SFTP_PendingSend() -Main SFTP server function that handles incoming packets. This function tries to read -from the I/O buffer and calls internal functions to depending on the SFTP packet type -received. +```c +#include -**Return Values:** +int wolfSSH_SFTP_PendingSend(WOLFSSH* ssh); +``` -**WS_SUCCESS:** on success. +**Description** -**Parameters:** +Reports whether the SFTP layer has buffered outbound data still waiting to be sent. This is useful when driving non-blocking I/O to know that another send attempt is needed. -**ssh** - pointer to WOLFSSH structure used for connection +**Parameters** -**Example:** +- `ssh` - pointer to the wolfSSH session -``` -#include -int wolfSSH_SFTP_read(WOLFSSH* ssh ); -``` +**Return Values** -**See Also:** +- non-zero if there is pending data to send +- 0 if there is no pending data -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +**See Also** -``` -WOLFSSH* ssh; -``` -``` -//set up ssh and do sftp connections -... -if (wolfSSH_SFTP_read(ssh) != WS_SUCCESS) { -//handle error case -} -``` +- `wolfSSH_SFTP_read()` diff --git a/wolfSSH/src/chapter15.md b/wolfSSH/src/chapter15.md new file mode 100644 index 00000000..744a979f --- /dev/null +++ b/wolfSSH/src/chapter15.md @@ -0,0 +1,278 @@ +# wolfSSH SCP API Reference + +This section describes the public application programming interface for SCP +(Secure Copy) file transfer in wolfSSH. + +All functions in this chapter require wolfSSH to be built with SCP support +(`WOLFSSH_SCP`, from `./configure --enable-scp`). + +## SCP Transfer Functions + +### wolfSSH_SCP_connect() + +```c +#include + +int wolfSSH_SCP_connect(WOLFSSH* ssh, byte* cmd); +``` + +**Description** + +Initiates an SCP session over an established SSH connection by sending the SCP +command `cmd` to the server. Called on the client side before transferring +files. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `cmd` - the SCP command to send to the server + +**Return Values** + +- `WS_SUCCESS` +- a negative error code on failure + +**See Also** + +- `wolfSSH_SCP_to()` +- `wolfSSH_SCP_from()` + +### wolfSSH_SCP_to() + +```c +#include + +int wolfSSH_SCP_to(WOLFSSH* ssh, const char* src, const char* dst); +``` + +**Description** + +Sends (uploads) the local file or directory `src` to the remote destination +`dst` over the SSH connection. Called on the client side. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `src` - path to the local source file or directory +- `dst` - destination path on the remote peer + +**Return Values** + +- `WS_SUCCESS` +- a negative error code on failure + +**See Also** + +- `wolfSSH_SCP_from()` +- `wolfSSH_SCP_connect()` + +### wolfSSH_SCP_from() + +```c +#include + +int wolfSSH_SCP_from(WOLFSSH* ssh, const char* src, const char* dst); +``` + +**Description** + +Retrieves (downloads) the remote file or directory `src` from the peer and +writes it to the local destination `dst` over the SSH connection. Called on the +client side. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `src` - path to the source file or directory on the remote peer +- `dst` - destination path on the local system + +**Return Values** + +- `WS_SUCCESS` +- a negative error code on failure + +**See Also** + +- `wolfSSH_SCP_to()` +- `wolfSSH_SCP_connect()` + +### wolfSSH_SetScpErrorMsg() + +```c +#include + +int wolfSSH_SetScpErrorMsg(WOLFSSH* ssh, const char* message); +``` + +**Description** + +Sets a custom error message string on the session, which is reported to the peer +when an SCP transfer fails. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `message` - null-terminated error message to report + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +## SCP Callbacks + +When using SCP with application-managed storage (for example, on systems without +a filesystem, or to filter transfers), the application registers send and receive +callbacks. Each callback may be given a user context pointer. + +### wolfSSH_SetScpRecv() + +```c +#include + +void wolfSSH_SetScpRecv(WOLFSSH_CTX* ctx, WS_CallbackScpRecv cb); +``` + +**Description** + +Registers the SCP receive callback on the context. The callback is invoked as +incoming files are received, allowing the application to store the data itself. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the SCP receive callback + +**Return Values** + +None + +**See Also** + +- `wolfSSH_SetScpRecvCtx()` +- `wolfSSH_SetScpSend()` + +### wolfSSH_SetScpSend() + +```c +#include + +void wolfSSH_SetScpSend(WOLFSSH_CTX* ctx, WS_CallbackScpSend cb); +``` + +**Description** + +Registers the SCP send callback on the context. The callback is invoked when the +peer requests files, allowing the application to supply the data itself. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `cb` - the SCP send callback + +**Return Values** + +None + +**See Also** + +- `wolfSSH_SetScpSendCtx()` +- `wolfSSH_SetScpRecv()` + +### wolfSSH_SetScpRecvCtx() + +```c +#include + +void wolfSSH_SetScpRecvCtx(WOLFSSH* ssh, void* ctx); +``` + +**Description** + +Sets the user context pointer passed to the SCP receive callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context pointer to pass to the receive callback + +**Return Values** + +None + +**See Also** + +- `wolfSSH_GetScpRecvCtx()` + +### wolfSSH_SetScpSendCtx() + +```c +#include + +void wolfSSH_SetScpSendCtx(WOLFSSH* ssh, void* ctx); +``` + +**Description** + +Sets the user context pointer passed to the SCP send callback. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context pointer to pass to the send callback + +**Return Values** + +None + +**See Also** + +- `wolfSSH_GetScpSendCtx()` + +### wolfSSH_GetScpRecvCtx() + +```c +#include + +void* wolfSSH_GetScpRecvCtx(WOLFSSH* ssh); +``` + +**Description** + +Returns the user context pointer previously set with wolfSSH_SetScpRecvCtx(). + +**Parameters** + +- `ssh` - pointer to the wolfSSH session + +**Return Values** + +- the SCP receive context pointer, or `NULL` if none + +**See Also** + +- `wolfSSH_SetScpRecvCtx()` + +### wolfSSH_GetScpSendCtx() + +```c +#include + +void* wolfSSH_GetScpSendCtx(WOLFSSH* ssh); +``` + +**Description** + +Returns the user context pointer previously set with wolfSSH_SetScpSendCtx(). + +**Parameters** + +- `ssh` - pointer to the wolfSSH session + +**Return Values** + +- the SCP send context pointer, or `NULL` if none + +**See Also** + +- `wolfSSH_SetScpSendCtx()` diff --git a/wolfSSH/src/chapter16.md b/wolfSSH/src/chapter16.md new file mode 100644 index 00000000..3ce33a39 --- /dev/null +++ b/wolfSSH/src/chapter16.md @@ -0,0 +1,672 @@ +# wolfSSH Additional API Reference + +This chapter documents the remaining public wolfSSH interfaces: ssh-agent +forwarding, key generation, logging, the certificate manager, and the +platform portability layer. + +## SSH Agent Functions + +These functions support ssh-agent forwarding. They require wolfSSH to be built +with agent support (`WOLFSSH_AGENT`, from `./configure --enable-agent`). + +### wolfSSH_AGENT_new() + +```c +#include + +WOLFSSH_AGENT_CTX* wolfSSH_AGENT_new(void* heap); +``` + +**Description** + +Allocates and initializes a new ssh-agent context. + +**Parameters** + +- `heap` - pointer to a heap to use for memory allocations, or `NULL` + +**Return Values** + +- pointer to the new agent context, or `NULL` on failure + +**See Also** + +- `wolfSSH_AGENT_free()` + +### wolfSSH_AGENT_free() + +```c +#include + +void wolfSSH_AGENT_free(WOLFSSH_AGENT_CTX* agent); +``` + +**Description** + +Frees an ssh-agent context previously allocated with wolfSSH_AGENT_new(). + +**Parameters** + +- `agent` - the agent context to free + +**Return Values** + +None + +**See Also** + +- `wolfSSH_AGENT_new()` + +### wolfSSH_CTX_set_agent_cb() + +```c +#include + +int wolfSSH_CTX_set_agent_cb(WOLFSSH_CTX* ctx, + WS_CallbackAgent agentCb, WS_CallbackAgentIO agentIoCb); +``` + +**Description** + +Registers the agent callback and the agent I/O callback on the context. These +callbacks let the application service agent requests and perform agent I/O. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `agentCb` - the agent callback +- `agentIoCb` - the agent I/O callback + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**See Also** + +- `wolfSSH_set_agent_cb_ctx()` + +### wolfSSH_set_agent_cb_ctx() + +```c +#include + +int wolfSSH_set_agent_cb_ctx(WOLFSSH* ssh, void* ctx); +``` + +**Description** + +Sets the user context pointer passed to the agent callbacks. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `ctx` - user context pointer to pass to the agent callbacks + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +### wolfSSH_CTX_AGENT_enable() + +```c +#include + +int wolfSSH_CTX_AGENT_enable(WOLFSSH_CTX* ctx, byte isEnabled); +``` + +**Description** + +Enables or disables ssh-agent forwarding for sessions created from the context. + +**Parameters** + +- `ctx` - pointer to the wolfSSH context +- `isEnabled` - non-zero to enable agent forwarding, 0 to disable + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**See Also** + +- `wolfSSH_AGENT_enable()` + +### wolfSSH_AGENT_enable() + +```c +#include + +int wolfSSH_AGENT_enable(WOLFSSH* ssh, byte isEnabled); +``` + +**Description** + +Enables or disables ssh-agent forwarding for a single session. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `isEnabled` - non-zero to enable agent forwarding, 0 to disable + +**Return Values** + +- `WS_SUCCESS` +- `WS_BAD_ARGUMENT` + +**See Also** + +- `wolfSSH_CTX_AGENT_enable()` + +### wolfSSH_AGENT_Relay() + +```c +#include + +int wolfSSH_AGENT_Relay(WOLFSSH* ssh, + const byte* msg, word32* msgSz, byte* rsp, word32* rspSz); +``` + +**Description** + +Relays an agent protocol message to the agent and returns the agent's response. +On input `rspSz` holds the size of the `rsp` buffer; on output it holds the size +of the response written. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `msg` - the agent message to relay +- `msgSz` - pointer to the size of the message +- `rsp` - buffer that receives the agent's response +- `rspSz` - on input the response buffer size, set on output to the response size + +**Return Values** + +- `WS_SUCCESS` +- a negative error code on failure + +### wolfSSH_AGENT_SignRequest() + +```c +#include + +int wolfSSH_AGENT_SignRequest(WOLFSSH* ssh, + const byte* digest, word32 digestSz, + byte* sig, word32* sigSz, + const byte* keyBlob, word32 keyBlobSz, word32 flags); +``` + +**Description** + +Requests that the agent sign the given `digest` using the key identified by +`keyBlob`. The resulting signature is written to `sig`. + +**Parameters** + +- `ssh` - pointer to the wolfSSH session +- `digest` - the digest to sign +- `digestSz` - size of the digest +- `sig` - buffer that receives the signature +- `sigSz` - on input the signature buffer size, set on output to the signature size +- `keyBlob` - the public key blob identifying which key to sign with +- `keyBlobSz` - size of the key blob +- `flags` - signature request flags + +**Return Values** + +- `WS_SUCCESS` +- a negative error code on failure + +## Key Generation Functions + +These functions generate SSH key pairs. They require wolfSSH to be built with +key generation support (`WOLFSSH_KEYGEN`, from `./configure --enable-keygen`), +and the corresponding algorithm must be enabled in wolfCrypt. + +### wolfSSH_MakeRsaKey() + +```c +#include + +int wolfSSH_MakeRsaKey(byte* out, word32 outSz, word32 size, word32 e); +``` + +**Description** + +Generates an RSA key pair of `size` bits using public exponent `e`, writing the +encoded key to `out`. + +**Parameters** + +- `out` - buffer that receives the generated key +- `outSz` - size of the output buffer +- `size` - RSA key size in bits (for example, 2048) +- `e` - RSA public exponent (for example, 65537) + +**Return Values** + +- the number of bytes written on success +- a negative error code on failure + +**See Also** + +- `wolfSSH_MakeEcdsaKey()` + +### wolfSSH_MakeEcdsaKey() + +```c +#include + +int wolfSSH_MakeEcdsaKey(byte* out, word32 outSz, word32 size); +``` + +**Description** + +Generates an ECDSA key pair for the curve of the given `size` in bits (for +example, 256 for NIST P-256), writing the encoded key to `out`. + +**Parameters** + +- `out` - buffer that receives the generated key +- `outSz` - size of the output buffer +- `size` - ECC curve size in bits (for example, 256, 384, or 521) + +**Return Values** + +- the number of bytes written on success +- a negative error code on failure + +**See Also** + +- `wolfSSH_MakeRsaKey()` +- `wolfSSH_MakeEd25519Key()` + +### wolfSSH_MakeEd25519Key() + +```c +#include + +int wolfSSH_MakeEd25519Key(byte* out, word32 outSz, word32 size); +``` + +**Description** + +Generates an Ed25519 key pair, writing the encoded key to `out`. + +**Parameters** + +- `out` - buffer that receives the generated key +- `outSz` - size of the output buffer +- `size` - key size in bits (256 for Ed25519) + +**Return Values** + +- the number of bytes written on success +- a negative error code on failure + +**See Also** + +- `wolfSSH_MakeEcdsaKey()` + +## Logging Functions + +These functions control wolfSSH debug logging. The logging code is compiled in +when wolfSSH is built with `DEBUG_WOLFSSH` (from `./configure --enable-debug`) +or with `WOLFSSH_SSHD`. + +### wolfSSH_SetLoggingCb() + +```c +#include + +void wolfSSH_SetLoggingCb(wolfSSH_LoggingCb logF); +``` + +**Description** + +Registers a callback that receives log messages, each with its log level and +message text, instead of the default logging output. + +**Parameters** + +- `logF` - the logging callback + +**Return Values** + +None + +**See Also** + +- `wolfSSH_LogEnabled()` + +### wolfSSH_LogEnabled() + +```c +#include + +int wolfSSH_LogEnabled(void); +``` + +**Description** + +Reports whether logging is currently enabled. + +**Parameters** + +None + +**Return Values** + +- non-zero if logging is enabled +- 0 if logging is disabled + +### wolfSSH_Log() + +```c +#include + +void wolfSSH_Log(enum wolfSSH_LogLevel level, const char* const fmt, ...); +``` + +**Description** + +Writes a printf-style formatted log message at the given level. The log levels, +from lowest to highest, are `WS_LOG_DEBUG`, `WS_LOG_INFO`, `WS_LOG_WARN`, +`WS_LOG_ERROR`, and `WS_LOG_USER`, plus the per-subsystem levels `WS_LOG_SFTP`, +`WS_LOG_SCP`, `WS_LOG_AGENT`, and `WS_LOG_CERTMAN`. + +**Parameters** + +- `level` - the `wolfSSH_LogLevel` for the message +- `fmt` - printf-style format string +- `...` - arguments for the format string + +**Return Values** + +None + +**See Also** + +- `wolfSSH_SetLoggingCb()` + +## Certificate Manager Functions + +The certificate manager verifies X.509 certificates for certificate-based +authentication. These functions require wolfSSH to be built with certificate +support (`WOLFSSH_CERTS`, from `./configure --enable-certs`). + +### wolfSSH_CERTMAN_new() + +```c +#include + +WOLFSSH_CERTMAN* wolfSSH_CERTMAN_new(void* heap); +``` + +**Description** + +Allocates and initializes a new certificate manager. + +**Parameters** + +- `heap` - pointer to a heap to use for memory allocations, or `NULL` + +**Return Values** + +- pointer to the new certificate manager, or `NULL` on failure + +**See Also** + +- `wolfSSH_CERTMAN_free()` + +### wolfSSH_CERTMAN_free() + +```c +#include + +void wolfSSH_CERTMAN_free(WOLFSSH_CERTMAN* cm); +``` + +**Description** + +Frees a certificate manager previously allocated with wolfSSH_CERTMAN_new(). + +**Parameters** + +- `cm` - the certificate manager to free + +**Return Values** + +None + +**See Also** + +- `wolfSSH_CERTMAN_new()` + +### wolfSSH_CERTMAN_LoadRootCA_buffer() + +```c +#include + +int wolfSSH_CERTMAN_LoadRootCA_buffer(WOLFSSH_CERTMAN* cm, + const unsigned char* rootCa, word32 rootCaSz); +``` + +**Description** + +Loads a trusted root CA certificate from a buffer into the certificate manager. +Loaded roots are used to verify certificates presented by a peer. + +**Parameters** + +- `cm` - the certificate manager +- `rootCa` - buffer containing the root CA certificate +- `rootCaSz` - size of the root CA buffer + +**Return Values** + +- `WS_SUCCESS` +- a negative error code on failure + +**See Also** + +- `wolfSSH_CERTMAN_VerifyCerts_buffer()` + +### wolfSSH_CERTMAN_VerifyCerts_buffer() + +```c +#include + +int wolfSSH_CERTMAN_VerifyCerts_buffer(WOLFSSH_CERTMAN* cm, + const unsigned char* cert, word32 certSz, word32 certCount); +``` + +**Description** + +Verifies a chain of `certCount` certificates contained in the buffer against the +root CAs loaded into the certificate manager. + +**Parameters** + +- `cm` - the certificate manager +- `cert` - buffer containing the certificate chain +- `certSz` - size of the certificate buffer +- `certCount` - number of certificates in the chain + +**Return Values** + +- `WS_SUCCESS` +- a negative error code on failure + +**See Also** + +- `wolfSSH_CERTMAN_LoadRootCA_buffer()` + +## Portability Functions + +These functions form part of the wolfSSH platform portability layer, which +abstracts filesystem and string operations across supported targets. They are +primarily used internally and when porting wolfSSH to a new platform; the exact +set available depends on the target build configuration. + +### wfopen() + +```c +#include + +int wfopen(WFILE** f, const char* filename, const char* mode); +``` + +**Description** + +Portable file-open wrapper. Opens `filename` using the access `mode` and stores +the resulting file handle in `f`. + +**Parameters** + +- `f` - receives the opened file handle +- `filename` - path of the file to open +- `mode` - access mode string (as for the C library `fopen`) + +**Return Values** + +- 0 on success +- non-zero on failure + +### wstrnstr() + +```c +#include + +char* wstrnstr(const char* s1, const char* s2, unsigned int n); +``` + +**Description** + +Finds the first occurrence of the substring `s2` within the first `n` bytes of +`s1`. + +**Parameters** + +- `s1` - the string to search +- `s2` - the substring to find +- `n` - maximum number of bytes of `s1` to search + +**Return Values** + +- pointer to the first occurrence of `s2` in `s1`, or `NULL` if not found + +### wstrncat() + +```c +#include + +char* wstrncat(char* s1, const char* s2, size_t n); +``` + +**Description** + +Appends up to `n` bytes of the string `s2` to the end of `s1`. + +**Parameters** + +- `s1` - destination string, appended to in place +- `s2` - source string to append +- `n` - maximum number of bytes to append + +**Return Values** + +- pointer to the destination string `s1` + +### wstrdup() + +```c +#include + +char* wstrdup(const char* s1, void* heap, int type); +``` + +**Description** + +Duplicates the string `s1`, allocating the copy from the given `heap`. + +**Parameters** + +- `s1` - the string to duplicate +- `heap` - heap used for the allocation +- `type` - allocation type hint + +**Return Values** + +- pointer to the duplicated string, or `NULL` on failure + +### WS_FindFirstFileA() + +**Availability** + +Available on Windows builds (`USE_WINDOWS_API`). + +```c +#include + +void* WS_FindFirstFileA(const char* fileName, + char* realFileName, size_t realFileNameSz, int* isDir, void* heap); +``` + +**Description** + +Begins a directory enumeration for `fileName`, returning a find handle and the +first matching entry. `isDir` is set to indicate whether the entry is a +directory. + +**Parameters** + +- `fileName` - the directory or search pattern to enumerate +- `realFileName` - buffer that receives the matched file name +- `realFileNameSz` - size of the `realFileName` buffer +- `isDir` - output set non-zero if the entry is a directory +- `heap` - heap used for allocations + +**Return Values** + +- an opaque find handle on success, or `NULL` on failure + +**See Also** + +- `WS_FindNextFileA()` + +### WS_FindNextFileA() + +**Availability** + +Available on Windows builds (`USE_WINDOWS_API`). + +```c +#include + +int WS_FindNextFileA(void* findHandle, + char* realFileName, size_t realFileNameSz); +``` + +**Description** + +Continues a directory enumeration started with WS_FindFirstFileA(), returning the +next matching entry. + +**Parameters** + +- `findHandle` - the find handle returned by WS_FindFirstFileA() +- `realFileName` - buffer that receives the matched file name +- `realFileNameSz` - size of the `realFileName` buffer + +**Return Values** + +- non-zero if another entry was returned +- 0 when there are no more entries + +**See Also** + +- `WS_FindFirstFileA()` diff --git a/wolfSSH/src/chapter17.md b/wolfSSH/src/chapter17.md new file mode 100644 index 00000000..5975d020 --- /dev/null +++ b/wolfSSH/src/chapter17.md @@ -0,0 +1,100 @@ +# wolfSSH Preprocessor Guard Macros + +Many wolfSSH features, algorithms, and functions are controlled by build-time +preprocessor macros. This chapter is a reference for the macros that are +intended to be set by applications. They are defined at build time through the +compiler command line (for example `CPPFLAGS`/`CFLAGS`), or by the `./configure` +options described in the "Building wolfSSH" chapter. + +## Algorithm-Disable Macros + +Each of the following `WOLFSSH_NO_*` macros disables one algorithm (or a family +of algorithms). In an autotools build these are normally set automatically based +on which algorithms are enabled in wolfCrypt; they may also be defined manually +to remove an algorithm from wolfSSH. + +Two algorithm families are "soft-disabled" by default: they are compiled in and +still work, but are not advertised during key exchange unless re-enabled. + +| Macro | Effect | +|--------------------------------------|------------------------------------| +| `WOLFSSH_NO_SHA1_SOFT_DISABLE` | SHA-1 algorithms are compiled in but not advertised during KEX by default. Define this to advertise SHA-1 algorithms by default. | +| `WOLFSSH_NO_AES_CBC_SOFT_DISABLE` | AES-CBC algorithms are compiled in but not advertised during KEX by default. Define this to advertise AES-CBC algorithms by default. | +| `WOLFSSH_NO_SHA1` | Disables SHA-1 in HMAC and digital signatures. | +| `WOLFSSH_NO_HMAC_SHA1` | Disables HMAC-SHA1. | +| `WOLFSSH_NO_HMAC_SHA1_96` | Disables HMAC-SHA1-96. | +| `WOLFSSH_NO_HMAC_SHA2_256` | Disables HMAC-SHA2-256. | +| `WOLFSSH_NO_HMAC_SHA2_512` | Disables HMAC-SHA2-512. | +| `WOLFSSH_NO_DH_GROUP1_SHA1` | Disables DH group 1 (Oakley 1) with SHA-1. | +| `WOLFSSH_NO_DH_GROUP14_SHA1` | Disables DH group 14 (Oakley 14) with SHA-1. | +| `WOLFSSH_NO_DH_GROUP14_SHA256` | Disables DH group 14 with SHA-256. | +| `WOLFSSH_NO_DH_GROUP16_SHA512` | Disables DH group 16 with SHA-512. | +| `WOLFSSH_NO_DH_GEX_SHA256` | Disables DH group exchange with SHA-256. | +| `WOLFSSH_NO_DH` | Disables all DH key agreement. | +| `WOLFSSH_NO_ECDH_SHA2_NISTP256` | Disables ECDH key exchange with NIST P-256. | +| `WOLFSSH_NO_ECDH_SHA2_NISTP384` | Disables ECDH key exchange with NIST P-384. | +| `WOLFSSH_NO_ECDH_SHA2_NISTP521` | Disables ECDH key exchange with NIST P-521. | +| `WOLFSSH_NO_ECDH` | Disables all ECDH key agreement. | +| `WOLFSSH_NO_CURVE25519_SHA256` | Disables Curve25519 key exchange. | +| `WOLFSSH_NO_NISTP256_MLKEM768_SHA256` | Disables the NIST P-256 with ML-KEM-768 post-quantum hybrid key exchange. | +| `WOLFSSH_NO_NISTP384_MLKEM1024_SHA384` | Disables the NIST P-384 with ML-KEM-1024 post-quantum hybrid key exchange. | +| `WOLFSSH_NO_CURVE25519_MLKEM768_SHA256` | Disables the Curve25519 with ML-KEM-768 post-quantum hybrid key exchange. | +| `WOLFSSH_NO_RSA` | Disables RSA server and user authentication. | +| `WOLFSSH_NO_SSH_RSA_SHA1` | Disables RSA server authentication using SHA-1. | +| `WOLFSSH_NO_ECDSA` | Disables ECDSA server and user authentication. | +| `WOLFSSH_NO_ECDSA_SHA2_NISTP256` | Disables ECDSA authentication with NIST P-256. | +| `WOLFSSH_NO_ECDSA_SHA2_NISTP384` | Disables ECDSA authentication with NIST P-384. | +| `WOLFSSH_NO_ECDSA_SHA2_NISTP521` | Disables ECDSA authentication with NIST P-521. | +| `WOLFSSH_NO_AES_CBC` | Disables AES-CBC encryption. | +| `WOLFSSH_NO_AES_CTR` | Disables AES-CTR encryption. | +| `WOLFSSH_NO_AES_GCM` | Disables AES-GCM encryption. | +| `WOLFSSH_NO_AEAD` | Disables all AEAD ciphers. | + +## Feature-Enable Macros + +These macros turn whole subsystems on. In an autotools build each is defined by +the corresponding `./configure` option shown below. The relevant API for most of +these features is documented in the API reference chapters. + +| Macro | Enables | Configure option | +|--------------------------------|---------------------|------------------------------| +| `WOLFSSH_SFTP` | SFTP support | `--enable-sftp` | +| `WOLFSSH_SCP` | SCP support | `--enable-scp` | +| `WOLFSSH_FWD` | TCP/IP port forwarding | `--enable-fwd` | +| `WOLFSSH_AGENT` | ssh-agent forwarding | `--enable-agent` | +| `WOLFSSH_CERTS` | X.509 certificate support | `--enable-certs` | +| `WOLFSSH_TPM` | TPM 2.0 host-key support | `--enable-tpm` | +| `WOLFSSH_SSHD` | wolfsshd daemon | `--enable-sshd` | +| `WOLFSSH_SHELL` | echoserver shell support | `--enable-shell` | +| `WOLFSSH_KEYGEN` | key generation API | `--enable-keygen` | +| `WOLFSSH_KEYBOARD_INTERACTIVE` | keyboard-interactive authentication | `--enable-keyboard-interactive` | +| `WOLFSSH_SSHCLIENT` | wolfSSH client application | `--enable-sshclient` | +| `WOLFSSH_TERM` | PTY / terminal handling | on by default (`--disable-term` to remove) | +| `WOLFSSH_SMALL_STACK` | reduced stack usage for constrained targets | `--enable-smallstack` | + +The following macros adjust behavior rather than enabling a subsystem: + +| Macro | Effect | +|--------------------------------------|--------------------------------------------------| +| `WOLFSSH_NO_DEFAULT_LOGGING_CB` | Omits the built-in default logging callback. | +| `WOLFSSH_NO_TIMESTAMP` | Omits timestamps from log output. | +| `WOLFSSH_NO_SYMLINK_CHECK` | Disables the SFTP symbolic-link safety check. | +| `WOLFSSH_NO_SFTP_BUFFER_ZERO` | Skips zeroing SFTP transfer buffers between operations. | + +## Tuning and Value Macros + +These macros take a numeric value rather than acting as an on/off switch. Define +them at build time to override the default. + +| Macro | Meaning | Default | +|-------------------------------------|-----------------------------------|--------------| +| `DEFAULT_WINDOW_SZ` | Initial channel window size, in bytes. | 131072 (128 KB) | +| `DEFAULT_MAX_PACKET_SZ` | Maximum channel packet size, in bytes. | 32768 | +| `DEFAULT_HIGHWATER_MARK` | Default data highwater mark, in bytes, before a rekey is triggered. | about 1 GB | +| `WOLFSSH_DEFAULT_MSG_HIGHWATER_MARK` | Default packet-count highwater mark before a rekey is triggered. | 0x80000000 | +| `WOLFSSH_MR_ROUNDS` | Miller-Rabin rounds used when the client checks the server's DH group-exchange prime. | 8 | +| `WOLFSSH_KEY_QUANTITY_REQ` | Number of keys required in an OpenSSH-style key wrapper. | 1 | +| `WOLFSSH_MAX_FILENAME` | Maximum filename length, in bytes. | 256 | +| `WOLFSSH_MAX_SFTP_RW` | Maximum SFTP read/write chunk size, in bytes. | 32768 | +| `WOLFSSH_MAX_SFTP_RECV` | Maximum SFTP receive size, in bytes. | 32768 | +| `WOLFSSH_MAX_SFTP_NAME` | Maximum size of an SFTP name list, in bytes. | 1048576 (1 MB) |