diff --git a/wolfSSH/header.txt b/wolfSSH/header.txt index 187c70a6..2a3faaad 100644 --- a/wolfSSH/header.txt +++ b/wolfSSH/header.txt @@ -8,7 +8,7 @@ header-includes: # Fancy page headers - \usepackage{fancyhdr} - \pagestyle{fancy} - - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2024 wolfSSL Inc.} + - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2026 wolfSSL Inc.} # Wrap long syntax highlighting code blocks - \usepackage{fvextra} - \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}} diff --git a/wolfSSH/mkdocs.yml b/wolfSSH/mkdocs.yml index c541b857..2af8479c 100644 --- a/wolfSSH/mkdocs.yml +++ b/wolfSSH/mkdocs.yml @@ -2,7 +2,7 @@ site_name: wolfSSH Manual site_url: https://wolfssl.com/ docs_dir: build/html/ site_dir: html/ -copyright: Copyright © 2022 wolfSSL Inc. +copyright: Copyright © 2026 wolfSSL Inc. nav: - "1. Introduction": index.md - "2. Building wolfSSH": chapter02.md @@ -12,12 +12,13 @@ nav: - "6. Callback Function Setup API": chapter06.md - "7. Building and Using wolfSSH SFTP": chapter07.md - "8. Port Forwarding": chapter08.md - - "9. Notes and Limitations": chapter09.md - - "10. Licensing ": chapter10.md - - "11. Support and Consulting": chapter11.md - - "12. wolfSSH Updates": chapter12.md - - "13. API Reference": chapter13.md - - "14. wolfSSL SFTP API Reference": chapter14.md + - "9. Windows Certificate Store Integration": chapter09.md + - "10. Notes and Limitations": chapter10.md + - "11. Licensing ": chapter11.md + - "12. Support and Consulting": chapter12.md + - "13. wolfSSH Updates": chapter13.md + - "14. API Reference": chapter14.md + - "15. wolfSSL SFTP API Reference": chapter15.md theme: name: null custom_dir: ../mkdocs-material/material diff --git a/wolfSSH/src/chapter09.md b/wolfSSH/src/chapter09.md index ecf164de..dad1bb89 100644 --- a/wolfSSH/src/chapter09.md +++ b/wolfSSH/src/chapter09.md @@ -1,3 +1,668 @@ -# Notes and Limitations +# Windows Certificate Store Integration -In portions of the implementation file attributes are not being considered and default attributes or mode values are used. Specifically in `wolfSSH_SFTP_Open`, getting timestamps from files, and all extended file attributes. +## Overview + +wolfSSH supports using the **Microsoft Windows Certificate Store** as a source of host keys, client authentication keys, and trusted CA certificates. This eliminates the need to manage private keys as files on disk — keys remain in the OS-managed certificate store where they are protected by the Windows security model (ACLs, TPM-backed storage, etc.). + +The feature spans four areas: + +1. **Server host-key signing** — `wolfsshd` and the echoserver can load their host key from a Windows certificate store instead of a PEM/DER file. +2. **Client authentication** — The SFTP client (and any application using the client common helpers) can authenticate to a server using a certificate and private key held in the Windows certificate store. +3. **Trusted CA loading** — `wolfsshd` can load trusted CA certificates from the Windows system store or a per-user certificate store, in addition to (or instead of) file-based CA certificates. +4. **CI test matrix** — A GitHub Actions workflow exercises all four server/client key-source combinations on Windows. + +## Build Requirements + +- **wolfSSL** compiled with `--enable-ssh` (and `--enable-keygen` if key generation is needed). +- **wolfSSH** compiled with `WOLFSSH_CERTS` defined (enabled by `--enable-certs` or `--enable-all`). +- **Windows platform** — the feature is gated on `USE_WINDOWS_API` and links against `ncrypt.lib` and `crypt32.lib`. + +The Visual Studio project files under `ide/winvs/` have been updated to link `ncrypt.lib` and `crypt32.lib` for all relevant targets (wolfssh library, echoserver, client, sftpclient, unit-test, api-test). + +All certificate-store code is conditionally compiled: + +```c +#ifdef USE_WINDOWS_API +#ifdef WOLFSSH_CERTS + /* ... cert store code ... */ +#endif /* WOLFSSH_CERTS */ +#endif /* USE_WINDOWS_API */ +``` + +On non-Windows platforms, or when `WOLFSSH_CERTS` is not defined, none of this code is compiled and the binary size is unaffected. + +The system CA loading path additionally requires `WOLFSSL_SYS_CA_CERTS` to be defined in the wolfSSL build. + +## Supported Key Types + +| Algorithm | SSH Type Name | Certificate Store Support | +|-----------|--------------|---------------------------| +| RSA | `ssh-rsa`, `rsa-sha2-256`, `rsa-sha2-512`, `x509v3-ssh-rsa` | Yes (via `NCryptSignHash` + `BCRYPT_PAD_PKCS1`) | +| ECDSA P-256 | `ecdsa-sha2-nistp256`, `x509v3-ecdsa-sha2-nistp256` | Yes (via `NCryptSignHash`, no padding) | +| ECDSA P-384 | `ecdsa-sha2-nistp384`, `x509v3-ecdsa-sha2-nistp384` | Yes | +| ECDSA P-521 | `ecdsa-sha2-nistp521`, `x509v3-ecdsa-sha2-nistp521` | Yes | + +ECC curve detection is automatic — the certificate's algorithm parameters OID is decoded to determine which NIST curve is in use. + +## Architecture + +### Private Key Abstraction (`WOLFSSH_PVT_KEY`) + +The `WOLFSSH_PVT_KEY` structure in `wolfssh/internal.h` has been extended with fields that allow a key slot to reference the Windows certificate store instead of an in-memory DER blob: + +| Field | Type | Description | +|--------------------|-------------------|-------------| +| `useCertStore` | `byte` (bitfield) | `1` if this key lives in the Windows certificate store. | +| `certStoreContext` | `void*` | Opaque pointer to the `PCCERT_CONTEXT` returned by `CertFindCertificateInStore`. Freed with `CertFreeCertificateContext` in `CtxResourceFree`. | +| `storeName` | `const wchar_t*` | Wide-string store name (e.g., `L"My"`, `L"Root"`). Heap-allocated, freed in `CtxResourceFree`. | +| `subjectName` | `const wchar_t*` | Wide-string subject/CN used for certificate lookup. Heap-allocated, freed in `CtxResourceFree`. | +| `dwFlags` | `DWORD` | Store flags such as `CERT_SYSTEM_STORE_CURRENT_USER` or `CERT_SYSTEM_STORE_LOCAL_MACHINE`. | +| `cert` / `certSz` | `byte*` / `word32` | Copy of the DER-encoded certificate. Used to extract the public key for key-exchange hashing and for presenting the certificate during authentication. | + +When `useCertStore` is set, the in-memory `key`/`keySz` fields are **not populated** — all signing operations go through the Windows CNG/CAPI path. + +### Signing Path — `SignWithCertStoreKey()` + +The static function `SignWithCertStoreKey()` in `src/internal.c` handles signing operations: + +```c +static int SignWithCertStoreKey(WOLFSSH* ssh, + const WOLFSSH_PVT_KEY* pvtKey, + const byte* data, word32 dataSz, + enum wc_HashType hashId, + byte* sig, word32* sigSz); +``` + +This function: + +1. Calls `CryptAcquireCertificatePrivateKey()` with `CRYPT_ACQUIRE_ONLY_NCRYPT_KEY_FLAG` to obtain an NCrypt key handle. +2. For **RSA** keys — calls `NCryptSignHash()` with `BCRYPT_PAD_PKCS1` and the appropriate hash algorithm identifier (`BCRYPT_SHA256_ALGORITHM`, etc.). The input is a pre-encoded PKCS#1 DigestInfo. +3. For **ECDSA** keys — calls `NCryptSignHash()` with no padding. The output is raw `r || s` (each component is half the total signature length). The caller is responsible for converting to the SSH wire format. +4. Falls back to legacy CAPI (`CryptSignHash`) if the key is not CNG-based, reversing the little-endian output to big-endian. + +`SignWithCertStoreKey` is called from three places: + +- `SignHRsa()` — server-side KEX signature (RSA) +- `SignHEcdsa()` — server-side KEX signature (ECDSA) +- `SendUserAuthRequestRsaCert()` / `BuildUserAuthRequestEccCert()` — client-side user-auth signature + +### Public Key Extraction — `ExtractPubKeyDerFromCert()` + +Since the private key never leaves the certificate store, the public key needed for key-exchange hash computation is extracted from the DER certificate using wolfCrypt's `wc_GetPubKeyDerFromCert()`: + +```c +static int ExtractPubKeyDerFromCert(const byte* certDer, word32 certDerSz, + byte** outDer, word32* outDerSz, void* heap); +``` + +This is used in `SendKexGetSigningKey()` to populate the RSA/ECC key structures with public-key-only data so the existing key-exchange hash logic works unchanged. + +## Public API + +### `wolfSSH_CTX_UsePrivateKey_fromStore()` + +```c +int wolfSSH_CTX_UsePrivateKey_fromStore(WOLFSSH_CTX* ctx, + const wchar_t* storeName, DWORD dwFlags, + const wchar_t* subjectName); +``` + +Loads a host/client private key from the Windows certificate store. Declared in `wolfssh/ssh.h` (under `USE_WINDOWS_API` and `WOLFSSH_CERTS` guards). + +**Parameters:** + +| Parameter | Description | +|---------------|-------------| +| `ctx` | wolfSSH context (server or client). | +| `storeName` | Certificate store name as a wide string (e.g., `L"My"`, `L"Root"`). | +| `dwFlags` | Store location flags: `CERT_SYSTEM_STORE_CURRENT_USER` (0x00010000) or `CERT_SYSTEM_STORE_LOCAL_MACHINE` (0x00020000). | +| `subjectName` | Subject CN (or substring) to search for, as a wide string. A `CN=` prefix is automatically stripped if the initial search fails. | + +**Behavior:** + +1. Opens the specified certificate store with `CertOpenStore(CERT_STORE_PROV_SYSTEM_W, ...)`. +2. Finds the certificate using `CertFindCertificateInStore(... CERT_FIND_SUBJECT_STR_W ...)`. +3. Determines the key type (RSA or ECDSA P-256/P-384/P-521) from the certificate's public key algorithm OID and, for ECC, the curve parameters. +4. Copies the DER certificate into the `WOLFSSH_PVT_KEY` slot and retains the `PCCERT_CONTEXT`. +5. Verifies that the private key is accessible by calling `CryptAcquireCertificatePrivateKey()` — this catches permission errors early (e.g., running as LocalSystem without key access). +6. Calls `RefreshPublicKeyAlgo()` so the new key type is advertised during key exchange. + +Returns `WS_SUCCESS` on success. Possible errors: `WS_BAD_ARGUMENT`, `WS_FATAL_ERROR` (store open/find failed), `WS_MEMORY_E`, `WS_CRYPTO_FAILED` (private key inaccessible). + +### `wolfSSH_SetCertManager()` + +```c +int wolfSSH_SetCertManager(WOLFSSH_CTX* ctx, WOLFSSL_CERT_MANAGER* cm); +``` + +Replaces the wolfSSH context's internal certificate manager with an externally-configured one. Declared in `wolfssh/certman.h`. Used by `wolfsshd` to inject a `WOLFSSL_CERT_MANAGER` that has already loaded system and/or user CA certificates via `wolfSSL_CTX_load_system_CA_certs()` or `wolfSSL_CTX_load_windows_user_CA_certs()`. + +The function increments the reference count on `cm` via `wolfSSL_CertManager_up_ref()`, so the caller retains ownership and can free the source SSL context independently. + +### `wolfSSH_ParseCertStoreSpec()` + +```c +int wolfSSH_ParseCertStoreSpec(const char* spec, + wchar_t** wStoreName, wchar_t** wSubjectName, + DWORD* dwFlags, void* heap); +``` + +Parses a colon-delimited spec string `"store:subject:flags"` into wide-string components suitable for `wolfSSH_CTX_UsePrivateKey_fromStore()`. Declared in `wolfssh/certman.h` (under `USE_WINDOWS_API`). Used by the echoserver and SFTP client to accept a `-W` command-line argument. + +**Spec format:** `StoreName:SubjectName:Flags` + +- `StoreName` — e.g., `My`, `Root`, `Trust` +- `SubjectName` — e.g., `CN=MyServer`, `MyServer` +- `Flags` — `CURRENT_USER`, `LOCAL_MACHINE`, or a numeric DWORD value + +**Example specs:** + +- `"My:CN=WolfSSHServer:CURRENT_USER"` — personal store, current user, RSA or ECC cert with CN containing "WolfSSHServer" +- `"My:alice:LOCAL_MACHINE"` — machine store, cert with subject containing "alice" +- `"Root:MyCorp CA:CURRENT_USER"` — root store, cert with subject containing "MyCorp CA" + +## wolfsshd Configuration + +### New `sshd_config` Options + +All wolfSSH-specific options use a `wolfSSH_` prefix to avoid conflicts with OpenSSH configuration parsers. + +#### Host Key from Certificate Store + +| Option | Description | Example | +|-------------------------|-------------|---------| +| `HostKeyStore` | Certificate store name for the host key. | `My` | +| `HostKeyStoreSubject` | Subject CN to find the host certificate. | `CN=SSHServer` | +| `HostKeyStoreFlags` | Store location: `CURRENT_USER` or `LOCAL_MACHINE`. | `CURRENT_USER` | + +When `HostKeyStore` and `HostKeyStoreSubject` are both set, `wolfsshd` loads the host key from the Windows certificate store instead of from the `HostKey` file path. If they are not set, the traditional `HostKey` file path is used as a fallback. + +#### System CA Certificates + +| Option | Description | Values | +|-------------------------------------|----------------------------------------------------------|--------------| +| `wolfSSH_TrustedSystemCAKeys` | Load CA certificates from the operating system's default trust store. | `yes` / `no` | + +When set to `yes`, `wolfsshd` calls `wolfSSL_CTX_load_system_CA_certs()` to populate the certificate manager with the OS-trusted root CAs. Requires wolfSSL built with `WOLFSSL_SYS_CA_CERTS`. + +#### User CA Store (Windows) + +| Option | Description | Values/Default | +|-----------------------------------------|-------------------------------------------------|-------------------------------------------| +| `wolfSSH_TrustedUserCaStore` | Load user CA certificates from a Windows certificate store. | `yes` / `no` | +| `wolfSSH_WinUserStores` | Certificate store provider type. | Default: `CERT_STORE_PROV_SYSTEM` | +| `wolfSSH_WinUserDwFlags` | Store location flags. | Default: `CERT_SYSTEM_STORE_CURRENT_USER` | +| `wolfSSH_WinUserPvPara` | Store name parameter (the "pvPara" argument to `CertOpenStore`). | Default: `MY` | + +When `wolfSSH_TrustedUserCaStore` is `yes`, `wolfsshd` calls `wolfSSL_CTX_load_windows_user_CA_certs()` with the configured store parameters. The loaded CAs are then injected into the wolfSSH certificate manager via `wolfSSH_SetCertManager()`. + +### Example `sshd_config` + +``` +# Use certificate store for host key +HostKeyStore My +HostKeyStoreSubject CN=WolfSSHD-Host +HostKeyStoreFlags CURRENT_USER + +# Trust system CAs for client certificate verification +wolfSSH_TrustedSystemCAKeys yes + +# Also trust certs from a custom user store +wolfSSH_TrustedUserCaStore yes +wolfSSH_WinUserStores CERT_STORE_PROV_SYSTEM +wolfSSH_WinUserDwFlags CERT_SYSTEM_STORE_CURRENT_USER +wolfSSH_WinUserPvPara MY +``` + +## Example / Tool Usage + +### Echoserver (`-W` flag) + +The echoserver accepts a `-W` flag (or the `WOLFSSH_CERT_STORE` environment variable) to load the host key from the certificate store: + +``` +echoserver.exe -W "My:CN=WolfSSHServer:CURRENT_USER" +``` + +This is equivalent to: + +``` +set WOLFSSH_CERT_STORE=My:CN=WolfSSHServer:CURRENT_USER +echoserver.exe +``` + +When `-W` is used, the echoserver skips loading file-based host keys and skips the `ChangeToWolfSshRoot()` directory search. + +### SFTP Client (`-W` flag) + +The SFTP client accepts a `-W` flag for client certificate authentication: + +``` +wolfsftp.exe -u testuser -h 127.0.0.1 -p 22222 -W "My:CN=TestUser:CURRENT_USER" +``` + +This loads the client's private key and certificate from the specified store. The certificate is presented as an `x509v3-ssh-rsa` or `x509v3-ecdsa-sha2-*` public key type during authentication. No `-i` (private key file) or `-J` (certificate file) flags are needed. + +### Client Common Helpers + +The client common library (`examples/client/common.c`) provides two helper functions for applications: + +```c +int ClientSetPrivateKeyFromStore(WOLFSSH_CTX* ctx, + const wchar_t* storeName, DWORD dwFlags, const wchar_t* subjectName); + +int ClientSetupCertStoreAuth(WOLFSSH_CTX* ctx); +``` + +`ClientSetPrivateKeyFromStore` calls `wolfSSH_CTX_UsePrivateKey_fromStore()`, and `ClientSetupCertStoreAuth` wires up the global auth-callback variables (`userPublicKey`, `userPublicKeyType`, etc.) so that `ClientUserAuth` presents the certificate for public-key authentication. + +## Use Case Examples + +### Server Loading a Host Key from the Certificate Store + +```c +#include +#include +#include + +WOLFSSH_CTX* ctx; +int ret; + +wolfSSH_Init(); +ctx = wolfSSH_CTX_new(WOLFSSH_ENDPOINT_SERVER, NULL); + +/* Load the host key from "My" store for the current user. + * The certificate with subject containing "SSHHostKey" must already + * be imported into the store with its private key. */ +ret = wolfSSH_CTX_UsePrivateKey_fromStore(ctx, + L"My", /* store name */ + CERT_SYSTEM_STORE_CURRENT_USER, /* current user's personal store */ + L"SSHHostKey"); /* subject CN substring */ +if (ret != WS_SUCCESS) { + printf("Failed to load host key from cert store: %d\n", ret); +} + +/* Proceed with normal server setup: set callbacks, accept connections... */ +``` + +### Server Loading a Host Key from the Local Machine Store + +```c +/* For a Windows service running as LocalSystem, the host certificate + * is typically in the Local Machine store. The service account must + * have permission to access the private key. */ +ret = wolfSSH_CTX_UsePrivateKey_fromStore(ctx, + L"My", /* store name */ + CERT_SYSTEM_STORE_LOCAL_MACHINE, /* machine-wide store */ + L"CN=wolfsshd.example.com"); /* CN= prefix is auto-stripped */ +``` + +### Client Loading a Key for Certificate Authentication + +```c +WOLFSSH_CTX* ctx; + +ctx = wolfSSH_CTX_new(WOLFSSH_ENDPOINT_CLIENT, NULL); + +/* Load the client identity from the current user's personal store */ +ret = wolfSSH_CTX_UsePrivateKey_fromStore(ctx, + L"My", + CERT_SYSTEM_STORE_CURRENT_USER, + L"alice"); /* matches cert with subject containing "alice" */ +if (ret != WS_SUCCESS) { + fprintf(stderr, "Cert store key load failed: %d\n", ret); + return ret; +} + +/* The CTX now holds the certificate DER and a reference to the + * private key in the Windows cert store. During SSH handshake, + * signing operations use NCryptSignHash transparently. */ +``` + +### Loading System and User CAs into wolfSSH + +```c +#include +#include +#include + +WOLFSSH_CTX* sshCtx; +WOLFSSL_CTX* sslCtx; +int ret; + +sshCtx = wolfSSH_CTX_new(WOLFSSH_ENDPOINT_SERVER, NULL); + +/* Create a temporary wolfSSL context to load CA certificates */ +sslCtx = wolfSSL_CTX_new(wolfSSLv23_server_method()); + +/* Load the OS-trusted root CAs (requires WOLFSSL_SYS_CA_CERTS) */ +if (wolfSSL_CTX_load_system_CA_certs(sslCtx) != WOLFSSL_SUCCESS) { + fprintf(stderr, "Failed to load system CAs\n"); +} + +/* On Windows, also load from a user certificate store */ +if (wolfSSL_CTX_load_windows_user_CA_certs(sslCtx, + "CERT_STORE_PROV_SYSTEM", /* store provider */ + "CERT_SYSTEM_STORE_CURRENT_USER", /* dwFlags */ + "MY" /* pvPara (store name) */ + ) != WOLFSSL_SUCCESS) { + fprintf(stderr, "Failed to load user CAs\n"); +} + +/* Transfer the loaded CAs into wolfSSH's certificate manager */ +ret = wolfSSH_SetCertManager(sshCtx, + wolfSSL_CTX_GetCertManager(sslCtx)); +if (ret != WS_SUCCESS) { + fprintf(stderr, "Failed to set cert manager: %d\n", ret); +} + +/* The temporary SSL context can be freed; the cert manager + * is kept alive by the wolfSSH CTX's reference. */ +wolfSSL_CTX_free(sslCtx); +``` + +### Parsing a Spec String and Loading a Key + +```c +#include +#include + +const char* spec = "My:CN=MySSHServer:CURRENT_USER"; +wchar_t* wStoreName = NULL; +wchar_t* wSubjectName = NULL; +DWORD dwFlags = 0; +int ret; + +/* Parse the colon-separated spec into wide-string components */ +ret = wolfSSH_ParseCertStoreSpec(spec, &wStoreName, &wSubjectName, + &dwFlags, NULL); +if (ret != WS_SUCCESS) { + fprintf(stderr, "Invalid cert store spec\n"); + return ret; +} + +/* Use the parsed components to load the key */ +ret = wolfSSH_CTX_UsePrivateKey_fromStore(ctx, wStoreName, dwFlags, + wSubjectName); + +/* Caller must free the allocated wide strings */ +WFREE(wStoreName, NULL, DYNTYPE_TEMP); +WFREE(wSubjectName, NULL, DYNTYPE_TEMP); + +if (ret != WS_SUCCESS) { + fprintf(stderr, "Failed to load key from store: %d\n", ret); +} +``` + +### End-to-End Server and Client with Certificate Store Keys + +**Prerequisites — importing certificates into the Windows store:** + +```powershell +# Import a PFX (PKCS#12) containing the server certificate + private key +# into the current user's "My" (Personal) store: +$pfx = Get-PfxData -FilePath .\server-cert.pfx ` + -Password (ConvertTo-SecureString "password" -AsPlainText -Force) +Import-PfxCertificate -FilePath .\server-cert.pfx ` + -CertStoreLocation Cert:\CurrentUser\My ` + -Password (ConvertTo-SecureString "password" -AsPlainText -Force) + +# Import the client certificate + private key: +Import-PfxCertificate -FilePath .\client-cert.pfx ` + -CertStoreLocation Cert:\CurrentUser\My ` + -Password (ConvertTo-SecureString "password" -AsPlainText -Force) + +# Import the CA certificate into the trusted root store: +Import-Certificate -FilePath .\ca-cert.der ` + -CertStoreLocation Cert:\CurrentUser\Root + +# Verify the imports: +Get-ChildItem Cert:\CurrentUser\My | Where-Object { $_.Subject -match "SSHServer" } +Get-ChildItem Cert:\CurrentUser\My | Where-Object { $_.Subject -match "TestClient" } +``` + +**Server code:** + +```c +#include + +int main(void) +{ + WOLFSSH_CTX* ctx; + WOLFSSH* ssh; + int ret; + + wolfSSH_Init(); + ctx = wolfSSH_CTX_new(WOLFSSH_ENDPOINT_SERVER, NULL); + + /* Load the host key from the certificate store */ + ret = wolfSSH_CTX_UsePrivateKey_fromStore(ctx, + L"My", CERT_SYSTEM_STORE_CURRENT_USER, L"SSHServer"); + if (ret != WS_SUCCESS) { + fprintf(stderr, "Host key load failed: %d\n", ret); + return 1; + } + + /* Set your user-auth callback, then accept connections as usual */ + wolfSSH_SetUserAuth(ctx, myUserAuthCallback); + ssh = wolfSSH_new(ctx); + + /* ... bind, listen, accept, wolfSSH_accept(ssh), etc. ... */ + + wolfSSH_free(ssh); + wolfSSH_CTX_free(ctx); + wolfSSH_Cleanup(); + return 0; +} +``` + +**Client code:** + +```c +#include +#include + +int main(void) +{ + WOLFSSH_CTX* ctx; + WOLFSSH* ssh; + int ret; + + wolfSSH_Init(); + ctx = wolfSSH_CTX_new(WOLFSSH_ENDPOINT_CLIENT, NULL); + + /* Load client identity from the cert store */ + ret = wolfSSH_CTX_UsePrivateKey_fromStore(ctx, + L"My", CERT_SYSTEM_STORE_CURRENT_USER, L"TestClient"); + if (ret != WS_SUCCESS) { + fprintf(stderr, "Client key load failed: %d\n", ret); + return 1; + } + + wolfSSH_SetUserAuth(ctx, myClientAuthCallback); + ssh = wolfSSH_new(ctx); + wolfSSH_SetUserAuthCtx(ssh, myAuthContext); + + /* ... connect, wolfSSH_connect(ssh), etc. ... */ + + wolfSSH_free(ssh); + wolfSSH_CTX_free(ctx); + wolfSSH_Cleanup(); + return 0; +} +``` + +### SFTP Session Using Certificate Store (Command Line) + +```bat +REM Start the echoserver with a cert-store host key +echoserver.exe -W "My:CN=SSHServer:CURRENT_USER" -p 22222 + +REM In another terminal, connect with the SFTP client using a cert-store client key +wolfsftp.exe -h 127.0.0.1 -p 22222 -u testuser -W "My:CN=TestClient:CURRENT_USER" +``` + +Inside the SFTP session: + +``` +wolfSSH sftp> ls +. +.. +Documents +Desktop +wolfSSH sftp> pwd +/home/testuser +wolfSSH sftp> put localfile.txt remotefile.txt +wolfSSH sftp> quit +``` + +### wolfsshd with Certificate Store Host Key and System CA Trust + +This demonstrates the daemon configuration for a production-like deployment where the host key is in the Local Machine store and client certificates are verified against the OS trust store. + +**`sshd_config`:** + +``` +Port 22 +ListenAddress 0.0.0.0 + +# Host key from the Local Machine certificate store +HostKeyStore My +HostKeyStoreSubject CN=sshd.example.com +HostKeyStoreFlags LOCAL_MACHINE + +# Accept client X.509 certificates signed by any OS-trusted CA +wolfSSH_TrustedSystemCAKeys yes + +# Also accept client certs signed by CAs in the current user's personal store +wolfSSH_TrustedUserCaStore yes +wolfSSH_WinUserStores CERT_STORE_PROV_SYSTEM +wolfSSH_WinUserDwFlags CERT_SYSTEM_STORE_CURRENT_USER +wolfSSH_WinUserPvPara MY + +# Standard options +PasswordAuthentication yes +PermitRootLogin no +``` + +**Starting the daemon:** + +```bat +wolfsshd.exe -f sshd_config -D +``` + +The `-D` flag runs in foreground (debug) mode with logs to stderr. In production, omit `-D` to run as a Windows service. + +### Mixed Mode — File Keys for Server, Certificate Store for Client + +The server uses traditional file-based host keys while clients authenticate with certificates from the Windows store. This is useful when migrating to certificate-based auth incrementally. + +**Server `sshd_config`:** + +``` +Port 22222 +HostKey /etc/wolfssh/server-key-rsa.pem + +# Trust the enterprise CA from the system store for client cert verification +wolfSSH_TrustedSystemCAKeys yes + +# Also trust certs from a dedicated CA store +TrustedUserCAKeys /etc/wolfssh/ca-cert.pem +``` + +**Client connecting with cert store key:** + +```bat +wolfsftp.exe -h server.example.com -p 22222 -u alice -W "My:alice:CURRENT_USER" +``` + +### Custom Application Using the Parse and Load Pattern + +For applications that accept a cert store specifier as a single string (e.g., from a config file or environment variable), the parse-then-load pattern avoids manual wide-string construction: + +```c +#include +#include + +int loadKeyFromSpec(WOLFSSH_CTX* ctx, const char* spec) +{ + wchar_t* wStoreName = NULL; + wchar_t* wSubjectName = NULL; + DWORD dwFlags = 0; + int ret; + + ret = wolfSSH_ParseCertStoreSpec(spec, &wStoreName, &wSubjectName, + &dwFlags, NULL); + if (ret != WS_SUCCESS) { + fprintf(stderr, "Bad spec string: '%s'\n", spec); + return ret; + } + + ret = wolfSSH_CTX_UsePrivateKey_fromStore(ctx, wStoreName, dwFlags, + wSubjectName); + + WFREE(wStoreName, NULL, DYNTYPE_TEMP); + WFREE(wSubjectName, NULL, DYNTYPE_TEMP); + + return ret; +} + +int main(void) +{ + WOLFSSH_CTX* ctx; + const char* envSpec; + + wolfSSH_Init(); + ctx = wolfSSH_CTX_new(WOLFSSH_ENDPOINT_SERVER, NULL); + + envSpec = getenv("WOLFSSH_CERT_STORE"); + if (envSpec != NULL) { + if (loadKeyFromSpec(ctx, envSpec) != WS_SUCCESS) { + fprintf(stderr, "Failed to load key from cert store\n"); + return 1; + } + } else { + /* Fall back to file-based key loading */ + /* wolfSSH_CTX_UsePrivateKey_buffer(ctx, ...); */ + } + + /* ... rest of server setup ... */ + + wolfSSH_CTX_free(ctx); + wolfSSH_Cleanup(); + return 0; +} +``` + +### Loading System CAs Programmatically (Without sshd_config) + +For applications that are not using `wolfsshd` but still want to verify client certificates against the Windows system trust store: + +```c +#include +#include +#include + +int setupSystemCAVerification(WOLFSSH_CTX* sshCtx) +{ + WOLFSSL_CTX* sslCtx; + int ret = WS_SUCCESS; + + sslCtx = wolfSSL_CTX_new(wolfSSLv23_server_method()); + if (sslCtx == NULL) + return WS_FATAL_ERROR; + + /* Load all CAs from the OS trust store (Windows, macOS, or Linux) */ + if (wolfSSL_CTX_load_system_CA_certs(sslCtx) != WOLFSSL_SUCCESS) { + wolfSSL_CTX_free(sslCtx); + return WS_FATAL_ERROR; + } + + /* Transfer the cert manager (with its loaded CAs) into wolfSSH */ + ret = wolfSSH_SetCertManager(sshCtx, + wolfSSL_CTX_GetCertManager(sslCtx)); + + wolfSSL_CTX_free(sslCtx); + return ret; +} +``` diff --git a/wolfSSH/src/chapter10.md b/wolfSSH/src/chapter10.md index 0ffd7aa9..ecf164de 100644 --- a/wolfSSH/src/chapter10.md +++ b/wolfSSH/src/chapter10.md @@ -1,17 +1,3 @@ -# Licensing +# Notes and Limitations -## Open Source - -wolfSSL, yaSSL, wolfCrypt, yaSSH and TaoCrypt software are free software downloads and may be modified to the needs of the user as long as the user adheres to version two of the GPL License. The GPLv2 license can be found on the gnu.org website: [http://www.gnu.org/licenses/old-licenses/gpl-2.0.html](http://www.gnu.org/licenses/old-licenses/gpl-2.0.html). - -wolfSSH software is a free software download and may be modified to the needs of the user as long as the user adheres to version three of the GPL license. The GPLv3 license can be found on the gnu.org website (https://www.gnu.org/licenses/gpl.html). - -## Commercial Licensing - -Businesses and enterprises who wish to incorporate wolfSSL products into proprietary appliances or other commercial software products for re-distribution must license commercial versions. - -Please contact licensing@wolfssl.com with inquiries. - -### Support Packages - -Support packages for wolfSSL products are available on an annual basis directly from wolfSSL. With three different package options, you can compare them side-by-side and choose the package that best fits your specific needs. Please see our [Support Packages page](https://www.wolfssl.com/products/support-and-maintenance) for more details. +In portions of the implementation file attributes are not being considered and default attributes or mode values are used. Specifically in `wolfSSH_SFTP_Open`, getting timestamps from files, and all extended file attributes. diff --git a/wolfSSH/src/chapter11.md b/wolfSSH/src/chapter11.md index 3acffc4b..1c89bace 100644 --- a/wolfSSH/src/chapter11.md +++ b/wolfSSH/src/chapter11.md @@ -1,49 +1,15 @@ -# Support and Consulting +# Licensing -## How to Get Support +## Open Source -For general product support, wolfSSL maintains an online forum for the wolfSSL product family. Please post to the forums or contact wolfSSL directly with any questions. +wolfSSL, wolfCrypt, and wolfSSH software are free software downloads and may be modified to the needs of the user as long as the user adheres to version three of the GPL License. The GPLv3 license can be found on the gnu.org website: (https://www.gnu.org/licenses/gpl.html). -- wolfSSL Forums: [https://www.wolfssl.com/forums](https://www.wolfssl.com/forums) -- Email Support: support@wolfssl.com +## Commercial Licensing -For information regarding wolfSSL products, questions regarding licensing, or general comments, please contact wolfSSL by emailing **info@wolfssl.com**. +Businesses and enterprises who wish to incorporate wolfSSL products into proprietary appliances or other commercial software products for re-distribution must license commercial versions. -### Bugs Reports and Support Issues +Please contact licensing@wolfssl.com with inquiries. -If you are submitting a bug report or asking about a problem, please include the following information with your submission: +### Support Packages -1. wolfSSL version number -2. Operating System version -3. Compiler version -4. The exact error you are seeing -5. A description of how we can reproduce or try to replicate this problem - -With the above information, we will do our best to resolve your problems. Without this information, it is very hard to pinpoint the source of the problem. wolfSSL values your feedback and makes it a top priority to get back to you as soon as possible. - -## Consulting - -wolfSSL offers both on and off site consulting - providing feature additions, porting, a Competitive Upgrade Program , and design consulting. - -### Feature Additions and Porting - -We can add additional features that you may need which are not currently offered in our products on a contract or co-development basis. We also offer porting services on our products to new host languages or new operating environments. - -### Competitive Upgrade Program - -We will help you move from an outdated or expensive SSL/TLS library to wolfSSL with low cost and minimal disturbance to your code base. - -Program Outline: - -1. You need to currently be using a commercial competitor to wolfSSL. -2. You will receive up to one week of on-site consulting to switch out your old SSL library for wolfSSL. Travel expenses are not included. -3. Normally, up to one week is the right amount of time for us to make the replacement in your code and do initial testing. Additional consulting on a replacement is available as needed. -4. You will receive the standard wolfSSL royalty free license to ship with your product. - -The purpose of this program is to enable users who are currently spending too much on their embedded SSL implementation to move to wolfSSL with ease. If you are interested in learning more, then please contact us at info@wolfssl.com. - -### Design Consulting - -If your application or framework needs to be secured with SSL/TLS but you are uncertain about how the optimal design of a secured system would be structured, we can help! - -We offer design consulting for building SSL/TLS security into devices using wolfSSL. Our consultants can provide you with the following services: +Support packages for wolfSSL products are available on an annual basis directly from wolfSSL. With three different package options, you can compare them side-by-side and choose the package that best fits your specific needs. Please see our [Support Packages page](https://www.wolfssl.com/products/support-and-maintenance) for more details. diff --git a/wolfSSH/src/chapter12.md b/wolfSSH/src/chapter12.md index 823e4a79..3acffc4b 100644 --- a/wolfSSH/src/chapter12.md +++ b/wolfSSH/src/chapter12.md @@ -1,12 +1,49 @@ -# wolfSSH Updates +# Support and Consulting -## Product Release Information +## How to Get Support -We regularly post update information on Twitter. For additional release information, you can keep track of our projects on GitHub, follow us on Facebook, or follow our daily blog. +For general product support, wolfSSL maintains an online forum for the wolfSSL product family. Please post to the forums or contact wolfSSL directly with any questions. -- wolfSSH on GitHub [https://www.github.com/wolfssl/wolfssh](https://www.github.com/wolfssl/wolfssh) -- wolfSSL on Twitter [https://twitter.com/wolfSSL](https://twitter.com/wolfSSL) -- wolfSSL on Facebook [https://www.facebook.com/wolfSSL](https://www.facebook.com/wolfSSL) -- wolfSSL on Reddit [https://www.reddit.com/r/wolfssl/](https://www.reddit.com/r/wolfssl/) -- Daily Blog [https://wolfssl.com/wolfSSL/Blog/Blog.html](https://wolfssl.com/wolfSSL/Blog/Blog.html) +- wolfSSL Forums: [https://www.wolfssl.com/forums](https://www.wolfssl.com/forums) +- Email Support: support@wolfssl.com +For information regarding wolfSSL products, questions regarding licensing, or general comments, please contact wolfSSL by emailing **info@wolfssl.com**. + +### Bugs Reports and Support Issues + +If you are submitting a bug report or asking about a problem, please include the following information with your submission: + +1. wolfSSL version number +2. Operating System version +3. Compiler version +4. The exact error you are seeing +5. A description of how we can reproduce or try to replicate this problem + +With the above information, we will do our best to resolve your problems. Without this information, it is very hard to pinpoint the source of the problem. wolfSSL values your feedback and makes it a top priority to get back to you as soon as possible. + +## Consulting + +wolfSSL offers both on and off site consulting - providing feature additions, porting, a Competitive Upgrade Program , and design consulting. + +### Feature Additions and Porting + +We can add additional features that you may need which are not currently offered in our products on a contract or co-development basis. We also offer porting services on our products to new host languages or new operating environments. + +### Competitive Upgrade Program + +We will help you move from an outdated or expensive SSL/TLS library to wolfSSL with low cost and minimal disturbance to your code base. + +Program Outline: + +1. You need to currently be using a commercial competitor to wolfSSL. +2. You will receive up to one week of on-site consulting to switch out your old SSL library for wolfSSL. Travel expenses are not included. +3. Normally, up to one week is the right amount of time for us to make the replacement in your code and do initial testing. Additional consulting on a replacement is available as needed. +4. You will receive the standard wolfSSL royalty free license to ship with your product. + +The purpose of this program is to enable users who are currently spending too much on their embedded SSL implementation to move to wolfSSL with ease. If you are interested in learning more, then please contact us at info@wolfssl.com. + +### Design Consulting + +If your application or framework needs to be secured with SSL/TLS but you are uncertain about how the optimal design of a secured system would be structured, we can help! + +We offer design consulting for building SSL/TLS security into devices using wolfSSL. Our consultants can provide you with the following services: diff --git a/wolfSSH/src/chapter13.md b/wolfSSH/src/chapter13.md index ba9107d8..823e4a79 100644 --- a/wolfSSH/src/chapter13.md +++ b/wolfSSH/src/chapter13.md @@ -1,2183 +1,12 @@ -# API Reference +# wolfSSH Updates -This section describes the public application program interfaces for the wolfSSH library. +## Product Release Information -## Error Codes +We regularly post update information on Twitter. For additional release information, you can keep track of our projects on GitHub, follow us on Facebook, or follow our daily blog. +- wolfSSH on GitHub [https://www.github.com/wolfssl/wolfssh](https://www.github.com/wolfssl/wolfssh) +- wolfSSL on Twitter [https://twitter.com/wolfSSL](https://twitter.com/wolfSSL) +- wolfSSL on Facebook [https://www.facebook.com/wolfSSL](https://www.facebook.com/wolfSSL) +- wolfSSL on Reddit [https://www.reddit.com/r/wolfssl/](https://www.reddit.com/r/wolfssl/) +- Daily Blog [https://wolfssl.com/wolfSSL/Blog/Blog.html](https://wolfssl.com/wolfSSL/Blog/Blog.html) - -### WS_ErrorCodes (enum) - - - -The following API response codes are defined in: wolfssh/wolfssh/error.h and describe the different types of errors that can occur. - -- 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_IOerrors (enum) - - - -These are the return codes the library expects to receive from a user-provided I/O callback. Otherwise the library expects the number of bytes read or written from the I/O action. - -- WS_CBIO_ERR_GENERAL (-1): General unexpected error -- WS_CBIO_ERR_WANT_READ (-2): Socket read would block, call again -- WS_CBIO_ERR_WANT_WRITE (-2): Socket write would block, call again -- 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" - -## Initialization / Shutdown - - - -### wolfSSH_Init() - - - -**Synopsis** - -**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 - -**Parameters** - -None - -**See Also** - -wolfSSH_Cleanup() - -``` -#include -int wolfSSH_Init(void); -``` - -### wolfSSH_Cleanup() - - - -**Synopsis** - -**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** - -**Parameters** - -None - -**See Also** - -wolfSSH_Init() - -``` -#include -int wolfSSH_Cleanup(void); -``` - -## Debugging output functions - - - -### wolfSSH_Debugging_ON() - - - -**Synopsis** - -**Description** - -Enables debug logging during runtime. Does nothing when debugging is disabled at build time. - -**Return Values** - -None - -**Parameters** - -None - -**See Also** - -wolfSSH_Debugging_OFF() - -``` -#include -void wolfSSH_Debugging_ON(void); -``` - -### wolfSSH_Debugging_OFF() - - - -**Synopsis** - -**Description** - -Disables debug logging during runtime. Does nothing when debugging is disabled at build time. - -**Return Values** - -None - -**Parameters** - -None - -**See Also** - -wolfSSH_Debugging_ON() - -``` -#include -void wolfSSH_Debugging_OFF(void); -``` - -## Context Functions - - - -### wolfSSH_CTX_new() - - - -**Synopsis** - -**Description** - -Creates a wolfSSH context object. This object can be configured and then used as a factory for wolfSSH session objects. - -**Return Values** - -**WOLFSSH_CTX*** – returns pointer to allocated WOLFSSH_CTX object or NULL - -**Parameters** - -**side** – indicate client side (unimplemented) or server side -**heap** – pointer to a heap to use for memory allocations - -**See Also** - -wolfSSH_wolfSSH_CTX_free() - -``` -#include -WOLFSSH_CTX* wolfSSH_CTX_new(byte side , void* heap ); -``` - -### wolfSSH_CTX_free() - - - -**Synopsis** - -**Description** - -Deallocates a wolfSSH context object. - -**Return Values** - -None - -**Parameters** - -**ctx** – the wolfSSH context used to initialize the wolfSSH session - -**See Also** - -wolfSSH_wolfSSH_CTX_new() - -``` -#include -void wolfSSH_CTX_free(WOLFSSH_CTX* ctx ); -``` - -### wolfSSH_CTX_SetBanner() - - -**Synopsis** - -**Description** - -Sets a banner message that a user can see. - -**Return Values** - -WS_BAD_ARGUMENT -WS_SUCCESS - -**Parameters** - -**ssh -** Pointer to wolfSSH session -**newBanner** - The banner message text. - -``` -#include -int wolfSSH_CTX_SetBanner(WOLFSSH_CTX* ctx , const char* -newBanner ); -``` - -### wolfSSH_CTX_UsePrivateKey_buffer() - - - -**Synopsis** - -**Description** - -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). - -**Return Values** - -**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 - -**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** - -wolfSSH_UseCert_buffer() -wolfSSH_UseCaCert_buffer() - -``` -#include -int wolfSSH_CTX_UsePrivateKey_buffer(WOLFSSH_CTX* ctx , -const byte* in , word32 inSz , int format ); -``` - -## SSH Session Functions - - - -### wolfSSH_new() - - - -**Synopsis** - -**Description** - -Creates a wolfSSH session object. It is initialized with the provided wolfSSH context. - -**Return Values** - -**WOLFSSH*** – returns pointer to allocated WOLFSSH object or NULL - -**Parameters** - -**ctx** – the wolfSSH context used to initialize the wolfSSH session - -**See Also** - -wolfSSH_free() - -``` -#include -WOLFSSH* wolfSSH_new(WOLFSSH_CTX* ctx ); -``` - -### wolfSSH_free() - - - -**Synopsis** - -**Description** - -Deallocates a wolfSSH session object. - -**Return Values** - -None - -**Parameters** - -**ssh** – session to deallocate - -**See Also** - -wolfSSH_new() - -``` -#include -void wolfSSH_free(WOLFSSH* ssh ); -``` - -### wolfSSH_set_fd() - - - -**Synopsis** - -**Description** - -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. - -**Return Values** - -#### WS_SUCCESS - -WS_BAD_ARGUMENT – one of the parameters is invalid - -**Parameters** - -**ssh** – session to set the fd -**fd** – file descriptor for the socket used by the session - -**See Also** - -wolfSSH_get_fd() - -``` -#include -int wolfSSH_set_fd(WOLFSSH* ssh , int fd ); -``` - -### wolfSSH_get_fd() - - - -**Synopsis** - -**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. - -**Return Values** - -**int** – file descriptor -**WS_BAD_ARGUEMENT** - -**Parameters** - -**ssh** – pointer to the SSL session. - -**See Also** - -wolfSSH_set_fd() - -``` -#include -int wolfSSH_get_fd(const WOLFSSH* ssh ); -``` - -## Data High Water Mark Functions - - - -### wolfSSH_SetHighwater() - - -**Synopsis** - -**Description** - -Sets the highwater mark for the ssh session. - -**Return Values** - -WS_SUCCESS -WS_BAD_ARGUMENT - -**Parameters** - -**ssh -** Pointer to wolfSSH session -**highwater** - data indicating the highwater security mark - -``` -#include -int wolfSSH_SetHighwater(WOLFSSH* ssh , word32 highwater ); -``` - -### wolfSSH_GetHighwater() - - -**Synopsis** - -**Description** - -Returns the highwater security mark - -**Return Values** - -**word32** - The highwater security mark. - -**Parameters** - -**ssh -** Pointer to wolfSSH session - -``` -#include -word32 wolfSSH_GetHighwater(WOLFSSH* ssh ); -``` - -### wolfSSH_SetHighwaterCb() - - -**Synopsis** - -**Description** - -The wolfSSH_SetHighwaterCb function sets the highwater security mark for the SSH session as well as the high water call back. - -**Return Values** - -none - -**Parameters** - -**ctx** – The wolfSSH context used to initialize the wolfSSH session. -**highwater** - The highwater security mark. -**cb** - The call back highwater function. - -``` -#include -void wolfSSH_SetHighwaterCb(WOLFSSH_CTX* ctx , word32 highwater , -WS_CallbackHighwater cb ); -``` - -### wolfSSH_SetHighwaterCtx() - - -**Synopsis** - -**Description** - -The wolfSSH_SetHighwaterCTX function sets the highwater security mark for the given context. - -**Return Values** - -none - -**Parameters** - -**ssh -** pointer to wolfSSH session -**ctx** - pointer to highwater security mark in the wolfSSH context. - -``` -#include -void wolfSSH_SetHighwaterCtx(WOLFSSH* ssh, void* ctx); -``` - -### wolfSSH_GetHighwaterCtx() - - -**Synopsis** - -**Description** - -The wolfSSH_GetHighwaterCtx() returns the highwaterCtx security mark from the SSH session. - -**Return Values** - -**void*** - the highwater security mark -**NULL** - if there is an error with the WOLFSSH object. - -**Parameters** - -**ssh -** pointer to WOLFSSH object - -``` -#include -void wolfSSH_GetHighwaterCtx(WOLFSSH* ssh ); -``` - -## Error Checking - - - -### wolfSSH_get_error() - - - -**Synopsis** - -**Description** - -Returns the error set in the wolfSSH session object. - -**Return Values** - -WS_ErrorCodes (enum) - -**Parameters** - -**ssh** – pointer to WOLFSSH object - -**See Also** - -wolfSSH_get_error_name() - -``` -#include -int wolfSSH_get_error(const WOLFSSH* ssh ); -``` - -### wolfSSH_get_error_name() - - - -**Synopsis** - -**Description** - -Returns the name of the error set in the wolfSSH session object. - -**Return Values** - -**const char*** – error name string - -**Parameters** - -**ssh** – pointer to WOLFSSH object - -**See Also** - -wolfSSH_get_error() - -``` -#include -const char* wolfSSH_get_error_name(const WOLFSSH* ssh ); -``` - -### wolfSSH_ErrorToName() - - -**Synopsis** - -**Description** - -Returns the name of an error when called with an error number in the parameter. - -**Return Values** - -**const char*** – name of error string - -**Parameters** - -**err** - the int value of the error - -``` -#include -const char* wolfSSH_ErrorToName(int err ); -``` - -## I/O Callbacks - - - -### wolfSSH_SetIORecv() - - -**Synopsis** - -**Description** - -This function registers a receive callback for wolfSSL to get input data. - -**Return Values** - -None - -**Parameters** - -**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. - -``` -#include -void wolfSSH_SetIORecv(WOLFSSH_CTX* ctx , WS_CallbackIORecv cb ); -``` - -### wolfSSH_SetIOSend() - - -**Synopsis** - -**Description** - -This function registers a send callback for wolfSSL to write output data. - -**Return Values** - -None - -**Parameters** - -**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. - -``` -#include -void wolfSSH_SetIOSend(WOLFSSH_CTX* ctx , WS_CallbackIOSend cb ); -``` - -### wolfSSH_SetIOReadCtx() - - -**Synopsis** - -**Description** - -This function registers a context for the SSH session receive callback function. - -**Return Values** - -None - -**Parameters** - -**ssh** – pointer to WOLFSSH object -**ctx** – pointer to the context to be registered with the SSH session ( **ssh** ) receive callback -function. - -``` -#include -void wolfSSH_SetIOReadCtx(WOLFSSH* ssh , void* ctx ); -``` - -### wolfSSH_SetIOWriteCtx() - - -**Synopsis** - -**Description** - -This function registers a context for the SSH session’s send callback function. - -**Return Values** - -None - -**Parameters** - -**ssh** – pointer to WOLFSSH session. -**ctx** – pointer to be registered with the SSH session’s ( **ssh** ) send callback function. - -``` -#include -void wolfSSH_SetIOWriteCtx(WOLFSSH* ssh , void* ctx ); -``` - -### wolfSSH_GetIOReadCtx() - - -**Synopsis** - -**Description** - -This function return the ioReadCtx member of the WOLFSSH structure. - -**Return Values** - -**Void*** - pointer to the ioReadCtx member of the WOLFSSH structure. - -**Parameters** - -**ssh** – pointer to WOLFSSH object - -``` -#include -void* wolfSSH_GetIOReadCtx(WOLFSSH* ssh ); -``` - -### wolfSSH_GetIOWriteCtx() - - -**Synopsis** - -**Description** - -This function returns the ioWriteCtx member of the WOLFSSH structure. - -**Return Values** - -**Void*** – pointer to the ioWriteCtx member of the WOLFSSH structure. - -**Parameters** - -**ssh** – pointer to WOLFSSH object - -``` -#include -void* wolfSSH_GetIOWriteCtx(WOLFSSH* ssh ); -``` - -## User Authentication - - - -### wolfSSH_SetUserAuth() - - -**Synopsis** - -**Description** - -The wolfSSH_SetUserAuth() function is used to set the user authentication for the -current wolfSSH context if the context does not equal NULL. - -**Return Values** - -None - -**Parameters** - -**ctx** – pointer to the wolfSSH context -**cb** – call back function for the user authentication - -``` -#include -void wolfSSH_SetUserAuth(WOLFSSH_CTX* ctx , -WS_CallbackUserAuth cb ) -``` - -### wolfSSH_SetUserAuthCtx() - - -**Synopsis** - -**Description** - -The wolfSSH_SetUserAuthCtx() function is used to set the value of the user -authentication context in the SSH session. - -**Return Values** - -None - -**Parameters** - -**ssh** – pointer to WOLFSSH object -**userAuthCtx** – pointer to the user authentication context - -``` -#include -void wolfSSH_SetUserAuthCtx(WOLFSSH* ssh , void* -userAuthCtx ) -``` - -### wolfSSH_GetUserAuthCtx() - - -**Synopsis** - -**Description** - -The wolfSSH_GetUserAuthCtx() function is used to return the pointer to the user -authentication context. - -**Return Values** - -**Void*** – pointer to the user authentication context -**Null** – returns if ssh is equal to NULL - -**Parameters** - -**ssh** – pointer to WOLFSSH object - -``` -#include -void* wolfSSH_GetUserAuthCtx(WOLFSSH* ssh ) -``` - -### wolfSSH_SetKeyboardAuthPrompts() - - -**Synopsis** - -**Description** - -The wolfSSH_SetKeyboardAuthPrompts() function is used to setup the callback -which will provide the server with the prompts to send to the client. - -**Return Values** - -None - -**Parameters** - -**ctx** - pointer to the wolfSSH context -**cb** - callback function to provide the keyboard prompts - -``` -#include -void wolfSSH_SetKeyboardAuthPrompts(WOLFSSH_CTX* ctx, - WS_CallbackKeyboardAuthPrompts cb) -``` - -### wolfSSH_SetKeyboardAuthCtx() - - -**Synopsis** - -**Description** - -The wolfSSH_SetKeyboardAuthCtx() function is used to setup the user context -for the wolfSSH_SetKeyboardAuthPrompts() function. - -**Return Values** - -None - -**Parameters** - -**ssh** - pointer to the WOLFSSH object -**keyboardAuthCtx* - pointer to the user context data - -``` -#include -void wolfSSH_SetKeyboardAuthCtx(WOLFSSH* ssh, void* keyboardAuthCtx) -``` - -## Set Username - - - -### wolfSSH_SetUsername() - - -**Synopsis** - -**Description** - -Sets the username required for the SSH connection. - -**Return Values** - -WS_BAD_ARGUMENT -WS_SUCCESS -WS_MEMORY_E - -**Parameters** - -**ssh -** Pointer to wolfSSH session -**username** - The input username for the SSH connection. - -``` -#include -int wolfSSH_setUsername(WOLFSSH* ssh , const char* username ); -``` - -## Connection Functions - -### wolfSSH_accept() - - - -**Synopsis** - -**Description** - -wolfSSH_accept is called on the server side and waits for an SSH client to initiate the -SSH handshake. - -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. - -If the underlying I/O is blocking, wolfSSH_accept() will only return once the handshake -has been finished or an error occurred. - -**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 - -**Parameters** - -**ssh** – pointer to the wolfSSH session - -**See Also** - -wolfSSH_stream_read() - -``` -#include -int wolfSSH_accept(WOLFSSH* ssh); -``` - -### wolfSSH_connect() - - -**Synopsis** - -**Description** - -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. - -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. - -If the underlying I/O is blocking, wolfSSH_connect() will only return once the handshake -has been finished or an error occurred. - -**Return Values** - -**WS_BAD_ARGUMENT -WS_FATAL_ERROR -WS_SUCCESS** - This will return if the call is successful. - -**Parameters** - -**ssh** - Pointer to wolfSSH session - -``` -#include -int wolfSSH_connect(WOLFSSH* ssh); -``` - -### wolfSSH_shutdown() - - -**Synopsis** - -**Description** - -Closes and disconnects the SSH channel. - -**Return Values** - -**WS_BAD_ARGUMENT** - returned if the parameter is NULL -**WS_SUCCES** - returns when everything has been correctly shutdown - -**Parameters** - -**ssh -** Pointer to wolfSSH session - -``` -#include -int wolfSSH_shutdown(WOLFSSH* ssh); -``` - -### wolfSSH_stream_read() - - - -**Synopsis** - -**Description** - -wolfSSH_stream_read reads up to **bufSz** bytes from the internal decrypted data stream -buffer. The bytes 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, 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. - -If the underlying I/O is blocking, wolfSSH_stream_read() will only return when data is -available or an error occurred. - -**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 - -**Parameters** - -**ssh** – pointer to the wolfSSH session - -``` -#include -int wolfSSH_stream_read(WOLFSSH* ssh , -byte* buf , word32 bufSz ); -``` - -**buf** – buffer where wolfSSH_stream_read() will place the data -**bufSz** – size of the buffer - -**See Also** - -wolfSSH_accept() -wolfSSH_stream_send() - - -### wolfSSH_stream_send() - - - -**Synopsis** - -**Description** - -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. - -**Return Values** - -**>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 - -**Parameters** - -**ssh** – pointer to the wolfSSH session -**buf** – buffer wolfSSH_stream_send() will send - -``` -#include -int wolfSSH_stream_send(WOLFSSH* ssh , byte* buf , word32 -bufSz ); -``` - -**bufSz** – size of the buffer - -**See Also** - -wolfSSH_accept() -wolfSSH_stream_read() - - -### wolfSSH_stream_exit() - - -**Synopsis** - -**Description** - -This function is used to exit the SSH stream. - -**Return Values** - -**WS_BAD_ARGUMENT** - returned if a parameter value is NULL -**WS_SUCCESS** - returns if function was a success - -**Parameters** - -**ssh** – Pointer to wolfSSH session -**status** – the status of the SSH connection - -``` -#include -int wolfSSH_stream_exit(WOLFSSH* ssh, int status); -``` - -### wolfSSH_TriggerKeyExchange() - - -**Synopsis** - -**Description** - -Triggers key exchange process. Prepares and sends packet of allocated handshake -info. - -**Return Values** - -**WS_BAD_ARGUEMENT** – if **ssh** is NULL -**WS_SUCCESS** - -**Parameters** - -**ssh** – pointer to the wolfSSH session - -``` -#include -int wolfSSH_TriggerKeyExchange(WOLFSSH* ssh ); -``` - -## Channel Callbacks - -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. - -``` -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 - -**Synopsis** - -``` -#include -int wolfSSH_CTX_SetChannelOpenCb(WOLFSSH_CTX* ctx, - WS_CallbackChannelOpen 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. - -**Return Values** - -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** - - -### wolfSSH_CTX_SetChannelOpenRespCb - -**Synopsis** - -``` -#include -int wolfSSH_CTX_SetChannelOpenRespCb(WOLFSSH_CTX* ctx, - WS_CallbackChannelOpen confCb, - WS_CallbackChannelOpen failCb); -``` - -**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. - -**Return Values** - -* **WS_SUCCESS** - Setting callbacks in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** - - -### wolfSSH_CTX_SetChannelReqShellCb - -**Synopsis** - -``` -#include -int wolfSSH_CTX_SetChannelReqShellCb(WOLFSSH_CTX* ctx, - WS_CallbackChannelReq cb); -``` - -**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_. - -**Return Values** - -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** - - -### wolfSSH_CTX_SetChannelReqSubsysCb - -**Synopsis** - -``` -#include -int wolfSSH_CTX_SetChannelReqSubsysCb(WOLFSSH_CTX* ctx, - WS_CallbackChannelReq cb); -``` - -**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. - -**Return Values** - -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** - - -### wolfSSH_CTX_SetChannelReqExecCb - -**Synopsis** - -``` -#include -int wolfSSH_CTX_SetChannelReqExecCb(WOLFSSH_CTX* ctx, - WS_CallbackChannelReq cb); -``` - -**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_. - -**Return Values** - -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** - - -### wolfSSH_CTX_SetChannelEofCb - -**Synopsis** - -``` -#include -int wolfSSH_CTX_SetChannelEof(WOLFSSH_CTX* ctx, - WS_CallbackChannelEof cb); -``` - -**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. - -**Return Values** - -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** - - -### wolfSSH_CTX_SetChannelCloseCb - -**Synopsis** - -``` -#include -int wolfSSH_CTX_SetChannelClose(WOLFSSH_CTX* ctx, - WS_CallbackChannelClose cb); -``` - -**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. - -**Return Values** - -* **WS_SUCCESS** - Setting callback in _ctx_ was successful -* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** - - -### wolfSSH_SetChannelOpenCtx - -**Synopsis** - -``` -#include -int wolfSSH_SetChannelOpenCtx(WOLFSSH* ssh, void* ctx); -``` - -**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. - -**Return Values** - -* **WS_SUCCESS** - Setting context in _ssh_ was successful -* **WS_SSH_NULL_E** - _ssh_ is **NULL** - - -### wolfSSH_SetChannelReqCtx - -**Synopsis** - -``` -#include -int wolfSSH_SetChannelReqCtx(WOLFSSH* ssh, void* ctx); -``` - -**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. - -**Return Values** - -* **WS_SUCCESS** - Setting context in _ssh_ was successful -* **WS_SSH_NULL_E** - _ssh_ is **NULL** - - -### wolfSSH_SetChannelEofCtx - -**Synopsis** - -``` -#include -int wolfSSH_SetChannelEofCtx(WOLFSSH* ssh, void* ctx); -``` - -**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. - -**Return Values** - -* **WS_SUCCESS** - Setting context in _ssh_ was successful -* **WS_SSH_NULL_E** - _ssh_ is **NULL** - - -### wolfSSH_SetChannelCloseCtx - -**Synopsis** - -``` -#include -int wolfSSH_SetChannelCloseCtx(WOLFSSH* ssh, void* ctx); -``` - -**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. - -**Return Values** - -* **WS_SUCCESS** - Setting context in _ssh_ was successful -* **WS_SSH_NULL_E** - _ssh_ is **NULL** - - -### wolfSSH_GetChannelOpenCtx - -**Synopsis** - -``` -#include -void* wolfSSH_GetChannelOpenCtx(WOLFSSH* ssh); -``` - -**Description** - -Gets the context from the wolfSSH _ssh_ object used when the callback for the -Channel Open (**SSH_MSG_CHANNEL_OPEN**) message. - -**Return Values** - -* pointer to the context data - - -### wolfSSH_GetChannelReqCtx - -**Synopsis** - -``` -#include -void* wolfSSH_GetChannelReqCtx(WOLFSSH* ssh); -``` - -**Description** - -Gets the context from the wolfSSH _ssh_ object used when the callback for the -Channel Request (**SSH_MSG_CHANNEL_REQUEST**) message. - -**Return Values** - -* pointer to the context data - - -### wolfSSH_GetChannelEofCtx - -**Synopsis** - -``` -#include -void* wolfSSH_GetChannelEofCtx(WOLFSSH* ssh); -``` - -**Description** - -Gets the context from the wolfSSH _ssh_ object used when the callback for the -Channel EOF (**SSH_MSG_CHANNEL_EOF**) message. - -**Return Values** - -* pointer to the context data - - -### wolfSSH_GetChannelCloseCtx - -**Synopsis** - -``` -#include -void* wolfSSH_GetChannelCloseCtx(WOLFSSH* ssh); -``` - -**Description** - -Gets the context from the wolfSSH _ssh_ object used when the callback for the -Channel Close (**SSH_MSG_CHANNEL_CLOSE**) message. - -**Return Values** - -* pointer to the context data - - -### wolfSSH_ChannelGetSessionType - -**Synopsis** - -``` -#include -WS_SessionType wolfSSH_ChannelGetSessionType(const WOLFSSH_CHANNEL* channel); -``` - -**Description** - -Returns the **WS_SessionType** for the specified _channel_. - -**Return Values** - -* **WS_SessionType** - type for the session - - -### wolfSSH_ChannelGetSessionCommand - -**Synopsis** - -``` -#include -const char* wolfSSH_ChannelGetSessionCommand(const WOLFSSH_CHANNEL* channel); -``` - -**Description** - -Returns a pointer to the command the user wishes to execute over the specified -_channel_. - -**Return Values** - -* **const char*** - pointer to the string holding the command sent by the user - - -## Testing Functions - - -### wolfSSH_GetStats() - - -**Synopsis** - -**Description** - -Updates **txCount** , **rxCount** , **seq** , and **peerSeq** with their respective **ssh** session -statistics. - -**Return Values** - -none - -**Parameters** - -**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 - -``` -#include -void wolfSSH_GetStats(WOLFSSH* ssh , word32* txCount , word32* -rxCount , -word32* seq , word32* peerSeq ) -``` - -### wolfSSH_KDF() - - -**Synopsis** - -**Description** - -This is used so that the API test can do known answer tests for the key derivation. - -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**. - -``` -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** - -**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 - -``` -#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 ); -``` - -**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** - - -## Session Functions - - - -### wolfSSH_GetSessionType() - - -**Synopsis** - -**Description** - -The wolfSSH_GetSessionType() is used to return the type of session - -**Return Values** - -WOLFSSH_SESSION_UNKNOWN -WOLFSSH_SESSION_SHELL -WOLFSSH_SESSION_EXEC -WOLFSSH_SESSION_SUBSYSTEM - -**Parameters** - -**ssh -** pointer to wolfSSH session - -``` -#include -WS_SessionType wolfSSH_GetSessionType(const WOLFSSH* ssh ); -``` - -### wolfSSH_GetSessionCommand() - - -**Synopsis** - -**Description** - -This function is used to return the current command in the session. - -**Return Values** - -**const char*** - Pointer to command - -**Parameters** - -**ssh -** pointer to wolfSSH session - -``` -#include -const char* wolfSSH_GetSessionCommand(const WOLFSSH* ssh ); -``` - -## Port Forwarding Functions - - - -### wolfSSH_ChannelFwdNew() - - -**Synopsis** - -**Description** - -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_. - -**Return Values** - -**WOLFSSH_CHAN*** – NULL on error or new channel record - -**Parameters** - -**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 - -``` -#include -WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNew(WOLFSSH* ssh , -const char* host , word32 hostPort , -const char* origin , word32 originPort ); -``` - -### wolfSSH_ChannelFree() - - -**Synopsis** - -**Description** - -Releases the memory allocated for the channel _channel_. The channel is removed from -its session’s channel list. - -**Return Values** - -**int** – error code - -**Parameters** - -**channel** – wolfSSH channel to free - -``` -#include -int wolfSSH_ChannelFree(WOLFSSH_CHANNEL* channel ); -``` - -### wolfSSH_worker() - - -**Synopsis** - -**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: - -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. - -**Return Values** - -**int** – error or status -**WS_CHANNEL_RXD** – data has been received on a channel and the ID is set - -**Parameters** - -**ssh** – pointer to the wolfSSH session -**id** – pointer to the location to save the ID value - -``` -#include -int wolfSSH_worker(WOLFSSH* ssh , word32* channelId ); -``` - -### wolfSSH_ChannelGetId() - - -**Synopsis** - -**Description** - -Given a channel, returns the ID or peer’s ID for the channel. - -**Return Values** - -**int** – error code - -**Parameters** - -**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) - -``` -#include -int wolfSSH_ChannelGetId(WOLFSSH_CHANNEL* channel , -word32* id , byte peer ); -``` - -### wolfSSH_ChannelFind() - - -**Synopsis** - -**Description** - -Given a session _ssh_ , find the channel associated with _id_. - -**Return Values** - -**WOLFSSH_CHANNEL*** – pointer to the channel, NULL if the ID isn’t in the list - -**Parameters** - -**ssh** – wolfSSH session -**id** – channel ID to find -**peer** – either self (my channel ID) or peer (my peer’s channel ID) - -``` -#include -WOLFSSH_CHANNEL* wolfSSH_ChannelFind(WOLFSSH* ssh , -word32 id , byte peer ); -``` - -### wolfSSH_ChannelRead() - - -**Synopsis** - -**Description** - -Copies data out of a channel object. - -**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 - -**Parameters** - -**channel** – pointer to the wolfSSH channel -**buf** – buffer where wolfSSH_ChannelRead will place the data -**bufSz** – size of the buffer - -``` -#include -int wolfSSH_ChannelRead(WOLFSSH_CHANNEL* channel , -byte* buf , word32 bufSz ); -``` - -### wolfSSH_ChannelSend() - - -**Synopsis** - -**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. - -**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 - -**Parameters** - -**channel** – pointer to the wolfSSH channel -**buf** – buffer wolfSSH_ChannelSend() will send -**bufSz** – size of the buffer - -``` -#include -int* wolfSSH_ChannelSend(WOLFSSH_CHANNEL* channel , -const byte* buf , word32 bufSz ); -``` - -### wolfSSH_ChannelExit() - - -**Synopsis** - -**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.) - -**Return Values** - -**int** – error code - -**Parameters** - -**channel** – wolfSSH session channel - -``` -#include -int wolfSSH_ChannelExit(WOLFSSH_CHANNEL* channel ); -``` - -### wolfSSH_ChannelNext() - - -**Synopsis** - -**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. - -**Return Values** - -**WOLFSSH_CHANNEL*** – pointer to either the first channel, next channel, or NULL - -**Parameters** - -**ssh** – wolfSSH session -**channel** – wolfSSH session channel - -``` -#include -WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNew(WOLFSSH* ssh , -WOLFSSH_CHANNEL* channel ); -``` - - -## Key Load Functions - - -### wolfSSH_ReadKey_buffer() - -**Synopsis** - -``` -#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 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_. - -**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 - - -### wolfSSH_ReadKey_file() - -**Synopsis** - -``` -#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 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 - - -## 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 - -**Synopsis** - -``` -#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** - successful -* **WS_SSH_CTX_NULL_E** - provided CTX was null -* **WS_SSH_NULL_E** - provide SSH was null - - -### wolfSSH Get Algo List - -**Synopsis** - -``` -#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 - -**Synopsis** - -``` -#include - -int wolfSSH_CheckAlgoName(const char* name); -``` - -**Description** - -Given a single algorithm _name_ checks to see if it is valid. - -**Return Values** - -* **WS_SUCCESS** - _name_ is a valid algorithm name -* **WS_INVALID_ALGO_ID** - _name_ is an invalid algorithm name - - -### wolfSSH Query Algorithms - -**Synopsis** - -``` -#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 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. - -**Return Values** - -Returns a constant string with the name of an algorithm. Null indicates the -end of the list. diff --git a/wolfSSH/src/chapter14.md b/wolfSSH/src/chapter14.md index 0b0794d9..ba9107d8 100644 --- a/wolfSSH/src/chapter14.md +++ b/wolfSSH/src/chapter14.md @@ -1,1233 +1,2183 @@ -# wolfSSL SFTP API Reference +# API Reference + +This section describes the public application program interfaces for the wolfSSH library. + +## Error Codes + + + +### WS_ErrorCodes (enum) + + + +The following API response codes are defined in: wolfssh/wolfssh/error.h and describe the different types of errors that can occur. + +- 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_IOerrors (enum) + + + +These are the return codes the library expects to receive from a user-provided I/O callback. Otherwise the library expects the number of bytes read or written from the I/O action. + +- WS_CBIO_ERR_GENERAL (-1): General unexpected error +- WS_CBIO_ERR_WANT_READ (-2): Socket read would block, call again +- WS_CBIO_ERR_WANT_WRITE (-2): Socket write would block, call again +- 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" + +## Initialization / Shutdown + + + +### wolfSSH_Init() + + + +**Synopsis** + +**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 + +**Parameters** + +None + +**See Also** + +wolfSSH_Cleanup() + +``` +#include +int wolfSSH_Init(void); +``` + +### wolfSSH_Cleanup() + + + +**Synopsis** + +**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** + +**Parameters** + +None + +**See Also** + +wolfSSH_Init() + +``` +#include +int wolfSSH_Cleanup(void); +``` + +## Debugging output functions + + + +### wolfSSH_Debugging_ON() + + + +**Synopsis** + +**Description** + +Enables debug logging during runtime. Does nothing when debugging is disabled at build time. + +**Return Values** + +None + +**Parameters** + +None + +**See Also** + +wolfSSH_Debugging_OFF() + +``` +#include +void wolfSSH_Debugging_ON(void); +``` + +### wolfSSH_Debugging_OFF() + + + +**Synopsis** + +**Description** + +Disables debug logging during runtime. Does nothing when debugging is disabled at build time. + +**Return Values** + +None + +**Parameters** + +None + +**See Also** + +wolfSSH_Debugging_ON() + +``` +#include +void wolfSSH_Debugging_OFF(void); +``` + +## Context Functions + + + +### wolfSSH_CTX_new() + + + +**Synopsis** + +**Description** + +Creates a wolfSSH context object. This object can be configured and then used as a factory for wolfSSH session objects. + +**Return Values** + +**WOLFSSH_CTX*** – returns pointer to allocated WOLFSSH_CTX object or NULL + +**Parameters** + +**side** – indicate client side (unimplemented) or server side +**heap** – pointer to a heap to use for memory allocations + +**See Also** + +wolfSSH_wolfSSH_CTX_free() + +``` +#include +WOLFSSH_CTX* wolfSSH_CTX_new(byte side , void* heap ); +``` + +### wolfSSH_CTX_free() + + + +**Synopsis** + +**Description** + +Deallocates a wolfSSH context object. + +**Return Values** + +None + +**Parameters** + +**ctx** – the wolfSSH context used to initialize the wolfSSH session + +**See Also** + +wolfSSH_wolfSSH_CTX_new() + +``` +#include +void wolfSSH_CTX_free(WOLFSSH_CTX* ctx ); +``` + +### wolfSSH_CTX_SetBanner() + + +**Synopsis** + +**Description** + +Sets a banner message that a user can see. + +**Return Values** + +WS_BAD_ARGUMENT +WS_SUCCESS + +**Parameters** + +**ssh -** Pointer to wolfSSH session +**newBanner** - The banner message text. + +``` +#include +int wolfSSH_CTX_SetBanner(WOLFSSH_CTX* ctx , const char* +newBanner ); +``` + +### wolfSSH_CTX_UsePrivateKey_buffer() + + + +**Synopsis** + +**Description** + +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). + +**Return Values** + +**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 + +**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** + +wolfSSH_UseCert_buffer() +wolfSSH_UseCaCert_buffer() + +``` +#include +int wolfSSH_CTX_UsePrivateKey_buffer(WOLFSSH_CTX* ctx , +const byte* in , word32 inSz , int format ); +``` + +## SSH Session Functions + + + +### wolfSSH_new() + + + +**Synopsis** + +**Description** + +Creates a wolfSSH session object. It is initialized with the provided wolfSSH context. + +**Return Values** + +**WOLFSSH*** – returns pointer to allocated WOLFSSH object or NULL + +**Parameters** + +**ctx** – the wolfSSH context used to initialize the wolfSSH session + +**See Also** + +wolfSSH_free() + +``` +#include +WOLFSSH* wolfSSH_new(WOLFSSH_CTX* ctx ); +``` + +### wolfSSH_free() + + + +**Synopsis** + +**Description** + +Deallocates a wolfSSH session object. + +**Return Values** + +None + +**Parameters** + +**ssh** – session to deallocate + +**See Also** + +wolfSSH_new() + +``` +#include +void wolfSSH_free(WOLFSSH* ssh ); +``` + +### wolfSSH_set_fd() + + + +**Synopsis** + +**Description** + +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. + +**Return Values** + +#### WS_SUCCESS + +WS_BAD_ARGUMENT – one of the parameters is invalid + +**Parameters** + +**ssh** – session to set the fd +**fd** – file descriptor for the socket used by the session + +**See Also** + +wolfSSH_get_fd() + +``` +#include +int wolfSSH_set_fd(WOLFSSH* ssh , int fd ); +``` + +### wolfSSH_get_fd() + + + +**Synopsis** + +**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. + +**Return Values** + +**int** – file descriptor +**WS_BAD_ARGUEMENT** + +**Parameters** + +**ssh** – pointer to the SSL session. + +**See Also** + +wolfSSH_set_fd() + +``` +#include +int wolfSSH_get_fd(const WOLFSSH* ssh ); +``` + +## Data High Water Mark Functions + + + +### wolfSSH_SetHighwater() + + +**Synopsis** + +**Description** + +Sets the highwater mark for the ssh session. + +**Return Values** + +WS_SUCCESS +WS_BAD_ARGUMENT + +**Parameters** + +**ssh -** Pointer to wolfSSH session +**highwater** - data indicating the highwater security mark + +``` +#include +int wolfSSH_SetHighwater(WOLFSSH* ssh , word32 highwater ); +``` + +### wolfSSH_GetHighwater() + + +**Synopsis** + +**Description** + +Returns the highwater security mark + +**Return Values** + +**word32** - The highwater security mark. + +**Parameters** + +**ssh -** Pointer to wolfSSH session + +``` +#include +word32 wolfSSH_GetHighwater(WOLFSSH* ssh ); +``` + +### wolfSSH_SetHighwaterCb() + + +**Synopsis** + +**Description** + +The wolfSSH_SetHighwaterCb function sets the highwater security mark for the SSH session as well as the high water call back. + +**Return Values** + +none + +**Parameters** + +**ctx** – The wolfSSH context used to initialize the wolfSSH session. +**highwater** - The highwater security mark. +**cb** - The call back highwater function. + +``` +#include +void wolfSSH_SetHighwaterCb(WOLFSSH_CTX* ctx , word32 highwater , +WS_CallbackHighwater cb ); +``` + +### wolfSSH_SetHighwaterCtx() + + +**Synopsis** + +**Description** + +The wolfSSH_SetHighwaterCTX function sets the highwater security mark for the given context. + +**Return Values** + +none + +**Parameters** + +**ssh -** pointer to wolfSSH session +**ctx** - pointer to highwater security mark in the wolfSSH context. + +``` +#include +void wolfSSH_SetHighwaterCtx(WOLFSSH* ssh, void* ctx); +``` + +### wolfSSH_GetHighwaterCtx() + + +**Synopsis** + +**Description** + +The wolfSSH_GetHighwaterCtx() returns the highwaterCtx security mark from the SSH session. + +**Return Values** + +**void*** - the highwater security mark +**NULL** - if there is an error with the WOLFSSH object. + +**Parameters** + +**ssh -** pointer to WOLFSSH object + +``` +#include +void wolfSSH_GetHighwaterCtx(WOLFSSH* ssh ); +``` + +## Error Checking + + + +### wolfSSH_get_error() + + + +**Synopsis** + +**Description** + +Returns the error set in the wolfSSH session object. + +**Return Values** + +WS_ErrorCodes (enum) + +**Parameters** + +**ssh** – pointer to WOLFSSH object + +**See Also** + +wolfSSH_get_error_name() + +``` +#include +int wolfSSH_get_error(const WOLFSSH* ssh ); +``` + +### wolfSSH_get_error_name() + + + +**Synopsis** + +**Description** + +Returns the name of the error set in the wolfSSH session object. + +**Return Values** + +**const char*** – error name string + +**Parameters** + +**ssh** – pointer to WOLFSSH object + +**See Also** + +wolfSSH_get_error() + +``` +#include +const char* wolfSSH_get_error_name(const WOLFSSH* ssh ); +``` + +### wolfSSH_ErrorToName() + + +**Synopsis** + +**Description** + +Returns the name of an error when called with an error number in the parameter. + +**Return Values** + +**const char*** – name of error string + +**Parameters** + +**err** - the int value of the error + +``` +#include +const char* wolfSSH_ErrorToName(int err ); +``` + +## I/O Callbacks + + + +### wolfSSH_SetIORecv() + + +**Synopsis** + +**Description** + +This function registers a receive callback for wolfSSL to get input data. + +**Return Values** + +None + +**Parameters** + +**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. + +``` +#include +void wolfSSH_SetIORecv(WOLFSSH_CTX* ctx , WS_CallbackIORecv cb ); +``` + +### wolfSSH_SetIOSend() + + +**Synopsis** + +**Description** + +This function registers a send callback for wolfSSL to write output data. + +**Return Values** + +None + +**Parameters** + +**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. + +``` +#include +void wolfSSH_SetIOSend(WOLFSSH_CTX* ctx , WS_CallbackIOSend cb ); +``` + +### wolfSSH_SetIOReadCtx() + + +**Synopsis** + +**Description** + +This function registers a context for the SSH session receive callback function. + +**Return Values** + +None + +**Parameters** + +**ssh** – pointer to WOLFSSH object +**ctx** – pointer to the context to be registered with the SSH session ( **ssh** ) receive callback +function. + +``` +#include +void wolfSSH_SetIOReadCtx(WOLFSSH* ssh , void* ctx ); +``` + +### wolfSSH_SetIOWriteCtx() + + +**Synopsis** + +**Description** + +This function registers a context for the SSH session’s send callback function. + +**Return Values** + +None + +**Parameters** + +**ssh** – pointer to WOLFSSH session. +**ctx** – pointer to be registered with the SSH session’s ( **ssh** ) send callback function. + +``` +#include +void wolfSSH_SetIOWriteCtx(WOLFSSH* ssh , void* ctx ); +``` + +### wolfSSH_GetIOReadCtx() + + +**Synopsis** + +**Description** + +This function return the ioReadCtx member of the WOLFSSH structure. + +**Return Values** + +**Void*** - pointer to the ioReadCtx member of the WOLFSSH structure. + +**Parameters** + +**ssh** – pointer to WOLFSSH object + +``` +#include +void* wolfSSH_GetIOReadCtx(WOLFSSH* ssh ); +``` + +### wolfSSH_GetIOWriteCtx() + + +**Synopsis** + +**Description** + +This function returns the ioWriteCtx member of the WOLFSSH structure. + +**Return Values** + +**Void*** – pointer to the ioWriteCtx member of the WOLFSSH structure. + +**Parameters** + +**ssh** – pointer to WOLFSSH object + +``` +#include +void* wolfSSH_GetIOWriteCtx(WOLFSSH* ssh ); +``` + +## User Authentication + + + +### wolfSSH_SetUserAuth() + + +**Synopsis** + +**Description** + +The wolfSSH_SetUserAuth() function is used to set the user authentication for the +current wolfSSH context if the context does not equal NULL. + +**Return Values** + +None + +**Parameters** + +**ctx** – pointer to the wolfSSH context +**cb** – call back function for the user authentication + +``` +#include +void wolfSSH_SetUserAuth(WOLFSSH_CTX* ctx , +WS_CallbackUserAuth cb ) +``` + +### wolfSSH_SetUserAuthCtx() + + +**Synopsis** + +**Description** + +The wolfSSH_SetUserAuthCtx() function is used to set the value of the user +authentication context in the SSH session. + +**Return Values** + +None + +**Parameters** + +**ssh** – pointer to WOLFSSH object +**userAuthCtx** – pointer to the user authentication context + +``` +#include +void wolfSSH_SetUserAuthCtx(WOLFSSH* ssh , void* +userAuthCtx ) +``` + +### wolfSSH_GetUserAuthCtx() + + +**Synopsis** + +**Description** + +The wolfSSH_GetUserAuthCtx() function is used to return the pointer to the user +authentication context. + +**Return Values** + +**Void*** – pointer to the user authentication context +**Null** – returns if ssh is equal to NULL + +**Parameters** + +**ssh** – pointer to WOLFSSH object + +``` +#include +void* wolfSSH_GetUserAuthCtx(WOLFSSH* ssh ) +``` + +### wolfSSH_SetKeyboardAuthPrompts() + + +**Synopsis** + +**Description** + +The wolfSSH_SetKeyboardAuthPrompts() function is used to setup the callback +which will provide the server with the prompts to send to the client. + +**Return Values** + +None + +**Parameters** + +**ctx** - pointer to the wolfSSH context +**cb** - callback function to provide the keyboard prompts + +``` +#include +void wolfSSH_SetKeyboardAuthPrompts(WOLFSSH_CTX* ctx, + WS_CallbackKeyboardAuthPrompts cb) +``` + +### wolfSSH_SetKeyboardAuthCtx() + + +**Synopsis** + +**Description** + +The wolfSSH_SetKeyboardAuthCtx() function is used to setup the user context +for the wolfSSH_SetKeyboardAuthPrompts() function. + +**Return Values** + +None + +**Parameters** + +**ssh** - pointer to the WOLFSSH object +**keyboardAuthCtx* - pointer to the user context data + +``` +#include +void wolfSSH_SetKeyboardAuthCtx(WOLFSSH* ssh, void* keyboardAuthCtx) +``` + +## Set Username + + + +### wolfSSH_SetUsername() + + +**Synopsis** + +**Description** + +Sets the username required for the SSH connection. + +**Return Values** + +WS_BAD_ARGUMENT +WS_SUCCESS +WS_MEMORY_E + +**Parameters** + +**ssh -** Pointer to wolfSSH session +**username** - The input username for the SSH connection. + +``` +#include +int wolfSSH_setUsername(WOLFSSH* ssh , const char* username ); +``` ## Connection Functions +### wolfSSH_accept() + + + +**Synopsis** + +**Description** + +wolfSSH_accept is called on the server side and waits for an SSH client to initiate the +SSH handshake. + +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. + +If the underlying I/O is blocking, wolfSSH_accept() will only return once the handshake +has been finished or an error occurred. + +**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 +**Parameters** -### wolfSSH_SFTP_accept() +**ssh** – pointer to the wolfSSH session +**See Also** +wolfSSH_stream_read() -**Synopsis:** +``` +#include +int wolfSSH_accept(WOLFSSH* ssh); +``` -**Description:** +### wolfSSH_connect() -Function to handle an incoming connection request from a client. -**Return Values:** +**Synopsis** -Returns WS_SFTP_COMPLETE on success. +**Description** -**Parameters:** +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. -**ssh** - pointer to WOLFSSH structure used for connection +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. -**Example:** +If the underlying I/O is blocking, wolfSSH_connect() will only return once the handshake +has been finished or an error occurred. + +**Return Values** + +**WS_BAD_ARGUMENT +WS_FATAL_ERROR +WS_SUCCESS** - This will return if the call is successful. + +**Parameters** + +**ssh** - Pointer to wolfSSH session ``` -#include -int wolfSSH_SFTP_accept(WOLFSSH* ssh ); -``` -``` -WOLFSSH* ssh; +#include +int wolfSSH_connect(WOLFSSH* ssh); ``` + +### wolfSSH_shutdown() + + +**Synopsis** + +**Description** + +Closes and disconnects the SSH channel. + +**Return Values** + +**WS_BAD_ARGUMENT** - returned if the parameter is NULL +**WS_SUCCES** - returns when everything has been correctly shutdown + +**Parameters** + +**ssh -** Pointer to wolfSSH session + ``` -//create new WOLFSSH structure -... +#include +int wolfSSH_shutdown(WOLFSSH* ssh); ``` + +### wolfSSH_stream_read() + + + +**Synopsis** + +**Description** + +wolfSSH_stream_read reads up to **bufSz** bytes from the internal decrypted data stream +buffer. The bytes 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, 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. + +If the underlying I/O is blocking, wolfSSH_stream_read() will only return when data is +available or an error occurred. + +**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 + +**Parameters** + +**ssh** – pointer to the wolfSSH session + ``` -if (wolfSSH_SFTP_accept(ssh) != WS_SUCCESS) { -//handle error case -} +#include +int wolfSSH_stream_read(WOLFSSH* ssh , +byte* buf , word32 bufSz ); ``` -**See Also:** - -wolfSSH_SFTP_free() -wolfSSH_new() -wolfSSH_SFTP_connect() +**buf** – buffer where wolfSSH_stream_read() will place the data +**bufSz** – size of the buffer -### wolfSSH_SFTP_connect() +**See Also** +wolfSSH_accept() +wolfSSH_stream_send() -**Synopsis:** +### wolfSSH_stream_send() -**Description:** -Function for initiating a connection to a SFTP server. -**Return Values:** +**Synopsis** -**WS_SFTP_COMPLETE:** on success. +**Description** -**Parameters:** +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. -**ssh** - pointer to WOLFSSH structure to be used for connection +**Return Values** -**Example:** +**>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 -**See Also:** +**Parameters** -wolfSSH_SFTP_accept() -wolfSSH_new() -wolfSSH_free() +**ssh** – pointer to the wolfSSH session +**buf** – buffer wolfSSH_stream_send() will send ``` -#include -int wolfSSH_SFTP_connect(WOLFSSH* ssh ); -``` -``` -WOLFSSH* ssh; -``` -``` -//after creating a new WOLFSSH structrue -``` -``` -wolfSSH_SFTP_connect(ssh); +#include +int wolfSSH_stream_send(WOLFSSH* ssh , byte* buf , word32 +bufSz ); ``` -### wolfSSH_SFTP_negotiate() +**bufSz** – size of the buffer +**See Also** +wolfSSH_accept() +wolfSSH_stream_read() -**Synopsis:** -**Description:** +### wolfSSH_stream_exit() -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. -**Return Values:** +**Synopsis** -Returns WS_SUCCESS on success. +**Description** -**Parameters:** +This function is used to exit the SSH stream. -**ssh** - pointer to WOLFSSH structure used for connection +**Return Values** -**Example:** +**WS_BAD_ARGUMENT** - returned if a parameter value is NULL +**WS_SUCCESS** - returns if function was a success -**See Also:** +**Parameters** -wolfSSH_SFTP_free() +**ssh** – Pointer to wolfSSH session +**status** – the status of the SSH connection ``` -#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 -} +#include +int wolfSSH_stream_exit(WOLFSSH* ssh, int status); ``` -wolfSSH_new() -wolfSSH_SFTP_connect() -wolfSSH_SFTP_accept() +### wolfSSH_TriggerKeyExchange() -## Protocol Level Functions +**Synopsis** +**Description** +Triggers key exchange process. Prepares and sends packet of allocated handshake +info. -### wolfSSH_SFTP_RealPath() +**Return Values** +**WS_BAD_ARGUEMENT** – if **ssh** is NULL +**WS_SUCCESS** +**Parameters** -**Synopsis:** +**ssh** – pointer to the wolfSSH session -**Description:** +``` +#include +int wolfSSH_TriggerKeyExchange(WOLFSSH* ssh ); +``` -Function to send REALPATH packet to peer. It gets the name of the file returned from -peer. +## Channel Callbacks -**Return Values:** +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 a pointer to a WS_SFTPNAME structure on success and NULL on error. +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 WOLFSSH structure used for connection -**dir** - directory / file name to get real path of +### Callback Function Prototypes -**Example:** +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 -WS_SFTPNAME* wolfSSH_SFTP_RealPath(WOLFSSH* ssh , char* -dir ); +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_SFTP_accept() -wolfSSH_SFTP_connect() +**Synopsis** ``` -WOLFSSH* ssh ; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -if (wolfSSH_SFTP_read( ssh ) != WS_SUCCESS) { -//handle error case -} +#include +int wolfSSH_CTX_SetChannelOpenCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelOpen cb); ``` -### wolfSSH_SFTP_Close() +**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. +**Return Values** -**Synopsis:** +* **WS_SUCCESS** - Setting callback in _ctx_ was successful +* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** -**Description:** -Function to to send a close packet to the peer. +### wolfSSH_CTX_SetChannelOpenRespCb -**Return Values:** +**Synopsis** + +``` +#include +int wolfSSH_CTX_SetChannelOpenRespCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelOpen confCb, + WS_CallbackChannelOpen failCb); +``` -**WS_SUCCESS** on success. +**Description** -**Parameters:** +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. -**ssh** - pointer to WOLFSSH structure used for connection -**handle** - handle to try and close -**handleSz** - size of handle buffer +**Return Values** -**Example:** +* **WS_SUCCESS** - Setting callbacks in _ctx_ was successful +* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** -``` -#include -int wolfSSH_SFTP_Close(WOLFSSH* ssh , byte* handle , word32 -handleSz ); -``` -**See Also:** +### wolfSSH_CTX_SetChannelReqShellCb -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +**Synopsis** ``` -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 -} +#include +int wolfSSH_CTX_SetChannelReqShellCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelReq cb); ``` -### wolfSSH_SFTP_Open() +**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_. +**Return Values** -**Synopsis:** +* **WS_SUCCESS** - Setting callback in _ctx_ was successful +* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** -**Description:** -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. +### wolfSSH_CTX_SetChannelReqSubsysCb -Available reasons for open: -WOLFSSH_FXF_READ -WOLFSSH_FXF_WRITE -WOLFSSH_FXF_APPEND -WOLFSSH_FXF_CREAT -WOLFSSH_FXF_TRUNC -WOLFSSH_FXF_EXCL +**Synopsis** -**Return Values:** +``` +#include +int wolfSSH_CTX_SetChannelReqSubsysCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelReq cb); +``` -**WS_SUCCESS** on success. +**Description** -**Parameters:** +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. -**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 +**Return Values** -``` -#include -int wolfSSH_SFTP_Open(WOLFSSH* ssh , char* dir , word32 -reason , -WS_SFTP_FILEATRB* atr , byte* handle , word32* handleSz ) ; -``` +* **WS_SUCCESS** - Setting callback in _ctx_ was successful +* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** -**Example:** -**See Also:** +### wolfSSH_CTX_SetChannelReqExecCb -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +**Synopsis** ``` -WOLFSSH* ssh ; -char name[NAME_SIZE]; -byte handle[HANDLE_SIZE]; -word32 handleSz = HANDLE_SIZE; -WS_SFTP_FILEATRB atr; -``` +#include +int wolfSSH_CTX_SetChannelReqExecCb(WOLFSSH_CTX* ctx, + WS_CallbackChannelReq cb); ``` -//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_SendReadPacket() -**Synopsis:** +**Description** -**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_. -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. +**Return Values** -**Return Values:** +* **WS_SUCCESS** - Setting callback in _ctx_ was successful +* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** -Returns the number of bytes read on success. -A negative value is returned on failure. -**Parameters:** +### wolfSSH_CTX_SetChannelEofCb -**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 - -**Example:** +**Synopsis** ``` -#include -int wolfSSH_SFTP_SendReadPacket(WOLFSSH* ssh , byte* -handle , word32 -handleSz , word64 ofst , byte* out , word32 outSz ); +#include +int wolfSSH_CTX_SetChannelEof(WOLFSSH_CTX* ctx, + WS_CallbackChannelEof cb); ``` -**See Also:** +**Description** -wolfSSH_SFTP_SendWritePacket() -wolfSSH_SFTP_Open() +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. -``` -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 -``` +**Return Values** + +* **WS_SUCCESS** - Setting callback in _ctx_ was successful +* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** -### wolfSSH_SFTP_SendWritePacket() +### wolfSSH_CTX_SetChannelCloseCb +**Synopsis** -**Synopsis:** +``` +#include +int wolfSSH_CTX_SetChannelClose(WOLFSSH_CTX* ctx, + WS_CallbackChannelClose cb); +``` -**Description:** +**Description** -Function to send a write packet to the peer. -The buffer handle should contain the result of a previous call to -wolfSSH_SFTP_Open(). +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. -**Return Values:** +**Return Values** -Returns the number of bytes written on success. -A negative value is returned on failure. +* **WS_SUCCESS** - Setting callback in _ctx_ was successful +* **WS_SSH_CTX_NULL_E** - _ctx_ is **NULL** -**Parameters:** -**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 +### wolfSSH_SetChannelOpenCtx -**Example:** +**Synopsis** ``` -#include -int wolfSSH_SFTP_SendWritePacket(WOLFSSH* ssh , byte* -handle , word32 -handleSz , word64 ofst , byte* out , word32 outSz ); +#include +int wolfSSH_SetChannelOpenCtx(WOLFSSH* ssh, void* ctx); ``` -**See Also:** +**Description** -wolfSSH_SFTP_SendReadPacket() -wolfSSH_SFTP_Open() +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. -``` -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 -``` +**Return Values** -### wolfSSH_SFTP_STAT() +* **WS_SUCCESS** - Setting context in _ssh_ was successful +* **WS_SSH_NULL_E** - _ssh_ is **NULL** +### wolfSSH_SetChannelReqCtx -**Synopsis:** +**Synopsis** -**Description:** +``` +#include +int wolfSSH_SetChannelReqCtx(WOLFSSH* ssh, void* ctx); +``` -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. +**Description** -**Return Values:** +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. -**WS_SUCCESS** on success. +**Return Values** -**Parameters:** +* **WS_SUCCESS** - Setting context in _ssh_ was successful +* **WS_SSH_NULL_E** - _ssh_ is **NULL** -**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 -**Example:** +### wolfSSH_SetChannelEofCtx + +**Synopsis** ``` -#include -int wolfSSH_SFTP_STAT(WOLFSSH* ssh , char* dir , -WS_SFTP_FILEATRB* atr); +#include +int wolfSSH_SetChannelEofCtx(WOLFSSH* ssh, void* ctx); ``` -**See Also:** +**Description** -wolfSSH_SFTP_LSTAT() -wolfSSH_SFTP_connect() +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. -``` -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 -} -``` +**Return Values** -### wolfSSH_SFTP_LSTAT() +* **WS_SUCCESS** - Setting context in _ssh_ was successful +* **WS_SSH_NULL_E** - _ssh_ is **NULL** -**Synopsis:** -**Description:** +### wolfSSH_SetChannelCloseCtx -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. +**Synopsis** -**Return Values:** +``` +#include +int wolfSSH_SetChannelCloseCtx(WOLFSSH* ssh, void* ctx); +``` -WS_SUCCESS on success. +**Description** -**Parameters:** +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. -**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 +**Return Values** -Example: +* **WS_SUCCESS** - Setting context in _ssh_ was successful +* **WS_SSH_NULL_E** - _ssh_ is **NULL** -``` -#include -int wolfSSH_SFTP_LSTAT(WOLFSSH* ssh , char* dir , -WS_SFTP_FILEATRB* atr ); -``` -**See Also:** +### wolfSSH_GetChannelOpenCtx -wolfSSH_SFTP_STAT() -wolfSSH_SFTP_connect() +**Synopsis** ``` -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 -} +#include +void* wolfSSH_GetChannelOpenCtx(WOLFSSH* ssh); ``` -### wolfSSH_SFTPNAME_free() +**Description** -**Synopsis:** +Gets the context from the wolfSSH _ssh_ object used when the callback for the +Channel Open (**SSH_MSG_CHANNEL_OPEN**) message. -**Description:** +**Return Values** -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. +* pointer to the context data -**Return Values:** -None +### wolfSSH_GetChannelReqCtx -**Parameters:** +**Synopsis** -**name** - structure to be free’d +``` +#include +void* wolfSSH_GetChannelReqCtx(WOLFSSH* ssh); +``` -**Example:** +**Description** -**See Also:** +Gets the context from the wolfSSH _ssh_ object used when the callback for the +Channel Request (**SSH_MSG_CHANNEL_REQUEST**) message. -``` -#include -``` -### void wolfSSH_SFTPNAME_free(WS_SFTPNMAE* name ); +**Return Values** + +* pointer to the context data + + +### wolfSSH_GetChannelEofCtx + +**Synopsis** ``` -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); -} +#include +void* wolfSSH_GetChannelEofCtx(WOLFSSH* ssh); ``` -wolfSSH_SFTPNAME_list_free +**Description** -wolfSSH_SFTPNAME_list_free() +Gets the context from the wolfSSH _ssh_ object used when the callback for the +Channel EOF (**SSH_MSG_CHANNEL_EOF**) message. +**Return Values** +* pointer to the context data -**Synopsis:** -**Description:** +### wolfSSH_GetChannelCloseCtx -Function to free a all WS_SFTPNAME nodes in a list. +**Synopsis** -**Return Values:** +``` +#include +void* wolfSSH_GetChannelCloseCtx(WOLFSSH* ssh); +``` -None +**Description** -**Parameters:** +Gets the context from the wolfSSH _ssh_ object used when the callback for the +Channel Close (**SSH_MSG_CHANNEL_CLOSE**) message. -**name** - head of list to be free’d +**Return Values** -**Example:** +* pointer to the context data -``` -#include -void wolfSSH_SFTPNAME_list_free(WS_SFTPNMAE* name ); -``` -**See Also:** +### wolfSSH_ChannelGetSessionType -wolfSSH_SFTPNAME_free() +**Synopsis** ``` -WOLFSSH* ssh; -WS_SFTPNAME* name; -``` -``` -//set up ssh and do sftp connections -... +#include +WS_SessionType wolfSSH_ChannelGetSessionType(const WOLFSSH_CHANNEL* channel); ``` + +**Description** + +Returns the **WS_SessionType** for the specified _channel_. + +**Return Values** + +* **WS_SessionType** - type for the session + + +### wolfSSH_ChannelGetSessionCommand + +**Synopsis** + ``` -name = wolfSSH_SFTP_LS(ssh, path); -if (name != NULL) { -wolfSSH_SFTPNAME_list_free(name); -} +#include +const char* wolfSSH_ChannelGetSessionCommand(const WOLFSSH_CHANNEL* channel); ``` -## Reget / Reput Functions +**Description** -### wolfSSH_SFTP_SaveOfst() +Returns a pointer to the command the user wishes to execute over the specified +_channel_. +**Return Values** +* **const char*** - pointer to the string holding the command sent by the user -**Synopsis:** -**Description:** +## Testing Functions -Function to save an offset for an interrupted get or put command. The offset can be -recovered by calling wolfSSH_SFTP_GetOfst -**Return Values:** +### wolfSSH_GetStats() -Returns WS_SUCCESS on success. -**Parameters:** +**Synopsis** -**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 +**Description** -Example: +Updates **txCount** , **rxCount** , **seq** , and **peerSeq** with their respective **ssh** session +statistics. -``` -#include -int wolfSSH_SFTP_SaveOfst(WOLFSSH* ssh , char* from , char* -to , -word64 ofst ); -``` +**Return Values** + +none -**See Also:** +**Parameters** -wolfSSH_SFTP_GetOfst() -wolfSSH_SFTP_Interrupt() +**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 ``` -WOLFSSH* ssh; -char from[NAME_SZ]; -char to[NAME_SZ]; -word64 ofst; +#include +void wolfSSH_GetStats(WOLFSSH* ssh , word32* txCount , word32* +rxCount , +word32* seq , word32* peerSeq ) ``` + +### wolfSSH_KDF() + + +**Synopsis** + +**Description** + +This is used so that the API test can do known answer tests for the key derivation. + +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**. + ``` -//set up ssh and do sftp connections -... +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** + +**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 + ``` -if (wolfSSH_SFTP_SaveOfst(ssh, from, to, ofst) != -WS_SUCCESS) { -//handle error case -} +#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 ); ``` -### wolfSSH_SFTP_GetOfst() - +**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** -**Synopsis:** +## Session Functions -**Description:** -Function to retrieve an offset for an interrupted get or put command. -**Return Values:** +### wolfSSH_GetSessionType() -Returns offset value on success. If not stored offset is found then 0 is returned. -**Parameters:** +**Synopsis** -**ssh** - pointer to WOLFSSH structure for connection -**from** - NULL terminated string of source path -**to** - NULL terminated string with destination path +**Description** -**Example:** +The wolfSSH_GetSessionType() is used to return the type of session -``` -#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 -``` +**Return Values** -**See Also:** +WOLFSSH_SESSION_UNKNOWN +WOLFSSH_SESSION_SHELL +WOLFSSH_SESSION_EXEC +WOLFSSH_SESSION_SUBSYSTEM -wolfSSH_SFTP_SaveOfst() -wolfSSH_SFTP_Interrup() +**Parameters** -### wolfSSH_SFTP_ClearOfst() +**ssh -** pointer to wolfSSH session +``` +#include +WS_SessionType wolfSSH_GetSessionType(const WOLFSSH* ssh ); +``` +### wolfSSH_GetSessionCommand() -**Synopsis:** -**Description:** +**Synopsis** -Function to clear all stored offset values. +**Description** -**Return Values:** +This function is used to return the current command in the session. -**WS_SUCCESS** on success +**Return Values** -**Parameters:** +**const char*** - Pointer to command -**ssh** - pointer to WOLFSSH structure +**Parameters** -**Example:** +**ssh -** pointer to wolfSSH session ``` -#include -int wolfSSH_SFTP_ClearOfst(WOLFSSH* ssh); +#include +const char* wolfSSH_GetSessionCommand(const WOLFSSH* ssh ); ``` -**See Also:** +## Port Forwarding Functions -wolfSSH_SFTP_SaveOfst() -wolfSSH_SFTP_GetOfst() -### wolfSSH_SFTP_Interrupt() +### wolfSSH_ChannelFwdNew() -**Synopsis:** +**Synopsis** -**Description:** +**Description** -Function to set interrupt flag and stop a get/put command. +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_. -**Return Values:** +**Return Values** -None - -**Parameters:** +**WOLFSSH_CHAN*** – NULL on error or new channel record -**ssh** - pointer to WOLFSSH structure +**Parameters** -**Example:** +**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 ``` -WOLFSSH* ssh; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -if (wolfSSH_SFTP_ClearOfst(ssh) != WS_SUCCESS) { -//handle error -} -``` -``` -#include -void wolfSSH_SFTP_Interrupt(WOLFSSH* ssh); +#include +WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNew(WOLFSSH* ssh , +const char* host , word32 hostPort , +const char* origin , word32 originPort ); ``` -**See Also:** +### wolfSSH_ChannelFree() -wolfSSH_SFTP_SaveOfst() -wolfSSH_SFTP_GetOfst() -``` -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); -``` +**Synopsis** -## Command Functions +**Description** +Releases the memory allocated for the channel _channel_. The channel is removed from +its session’s channel list. +**Return Values** -### wolfSSH_SFTP_Remove() +**int** – error code +**Parameters** +**channel** – wolfSSH channel to free -**Synopsis:** +``` +#include +int wolfSSH_ChannelFree(WOLFSSH_CHANNEL* channel ); +``` -**Description:** +### wolfSSH_worker() -Function for sending a “remove” packet across the channel. -The file name passed in as “f” is sent to the peer for removal. -**Return Values:** +**Synopsis** -**WS_SUCCESS** : returns WS_SUCCESS on success. +**Description** -**Parameters:** +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: -**ssh** - pointer to WOLFSSH structure used for connection -**f** - file name to be removed +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. -**Example:** +**Return Values** + +**int** – error or status +**WS_CHANNEL_RXD** – data has been received on a channel and the ID is set + +**Parameters** + +**ssh** – pointer to the wolfSSH session +**id** – pointer to the location to save the ID value ``` -#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); +#include +int wolfSSH_worker(WOLFSSH* ssh , word32* channelId ); ``` -**See Also:** +### wolfSSH_ChannelGetId() -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() -### wolfSSH_SFTP_MKDIR() +**Synopsis** +**Description** +Given a channel, returns the ID or peer’s ID for the channel. -**Synopsis:** +**Return Values** -**Description:** +**int** – error code -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. +**Parameters** -**Return Values:** +**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) -**WS_SUCCESS** : returns WS_SUCCESS on success. +``` +#include +int wolfSSH_ChannelGetId(WOLFSSH_CHANNEL* channel , +word32* id , byte peer ); +``` -**Parameters:** +### wolfSSH_ChannelFind() -ssh - pointer to WOLFSSH structure used for connection -dir - NULL terminated directory to be created -atr - attributes to be used with directory creation -**Example:** +**Synopsis** -``` -#include -int wolfSSH_SFTP_MKDIR(WOLFSSH* ssh , char* dir , -WS_SFTP_FILEATRB* -atr ); -``` +**Description** -**See Also:** +Given a session _ssh_ , find the channel associated with _id_. -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +**Return Values** -### wolfSSH_SFTP_RMDIR() +**WOLFSSH_CHANNEL*** – pointer to the channel, NULL if the ID isn’t in the list +**Parameters** +**ssh** – wolfSSH session +**id** – channel ID to find +**peer** – either self (my channel ID) or peer (my peer’s channel ID) -**Synopsis:** +``` +#include +WOLFSSH_CHANNEL* wolfSSH_ChannelFind(WOLFSSH* ssh , +word32 id , byte peer ); +``` -**Description:** +### wolfSSH_ChannelRead() -Function for sending a “rmdir” packet across the channel. The directory name passed in -as “dir” is sent to the peer for deletion. -**Return Values:** +**Synopsis** -**WS_SUCCESS** : returns WS_SUCCESS on success. +**Description** -**Parameters:** +Copies data out of a channel object. -**ssh** - pointer to WOLFSSH structure used for connection -**dir** - NULL terminated directory to be remove +**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 + +**Parameters** + +**channel** – pointer to the wolfSSH channel +**buf** – buffer where wolfSSH_ChannelRead will place the data +**bufSz** – size of the buffer ``` -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 ); +#include +int wolfSSH_ChannelRead(WOLFSSH_CHANNEL* channel , +byte* buf , word32 bufSz ); ``` -**Example:** +### wolfSSH_ChannelSend() -**See Also:** -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +**Synopsis** -``` -WOLFSSH* ssh; -int ret; -char* dir[DIR_SZ]; -``` -``` -//set up ssh and do sftp connections -... -``` -``` -ret = wolfSSH_SFTP_RMDIR(ssh, dir); -``` +**Description** -### wolfSSH_SFTP_Rename() +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. +**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 -**Synopsis:** +**Parameters** -**Description:** +**channel** – pointer to the wolfSSH channel +**buf** – buffer wolfSSH_ChannelSend() will send +**bufSz** – size of the buffer -Function for sending a “rename” packet across the channel. This tries to have a peer file -renamed from “old” to “nw”. +``` +#include +int* wolfSSH_ChannelSend(WOLFSSH_CHANNEL* channel , +const byte* buf , word32 bufSz ); +``` -**Return Values:** +### wolfSSH_ChannelExit() -**WS_SUCCESS** : returns WS_SUCCESS on success. -**Parameters:** +**Synopsis** -**ssh** - pointer to WOLFSSH structure used for connection -**old** - Old file name -**nw** - New file name +**Description** -**Example:** +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.) -``` -#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); -``` +**Return Values** -**See Also:** +**int** – error code -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +**Parameters** -### wolfSSH_SFTP_LS() +**channel** – wolfSSH session channel +``` +#include +int wolfSSH_ChannelExit(WOLFSSH_CHANNEL* channel ); +``` +### wolfSSH_ChannelNext() -**Synopsis:** -**Description:** +**Synopsis** -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. +**Description** -**Return Values:** +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. -On Success, returns a pointer to a list of WS_SFTPNAME structures. -NULL on failure. +**Return Values** -**Parameters:** +**WOLFSSH_CHANNEL*** – pointer to either the first channel, next channel, or NULL -**ssh** - pointer to WOLFSSH structure used for connection -**dir** - directory to list +**Parameters** -**Example:** +**ssh** – wolfSSH session +**channel** – wolfSSH session channel ``` -#include -WS_SFTPNAME* wolfSSH_SFTP_LS(WOLFSSH* ssh , char* dir ); +#include +WOLFSSH_CHANNEL* wolfSSH_ChannelFwdNew(WOLFSSH* ssh , +WOLFSSH_CHANNEL* channel ); ``` -**See Also:** -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() -wolfSSH_SFTPNAME_list_free() +## Key Load Functions + + +### wolfSSH_ReadKey_buffer() + +**Synopsis** ``` -WOLFSSH* ssh; -int ret; -char* dir[DIR_SZ]; -WS_SFTPNAME* name; -WS_SFTPNAME* tmp; -``` -``` -//set up ssh and do sftp connections -... +#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 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_. + +**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 + + +### wolfSSH_ReadKey_file() + +**Synopsis** + ``` -name = wolfSSH_SFTP_LS(ssh, dir); -tmp = name; -while (tmp != NULL) { -printf("%s\n", tmp->fName); -tmp = tmp->next; -} -wolfSSH_SFTPNAME_list_free(name); +#include + +int wolfSSH_ReadKey_file(const char* name, + byte** out, word32* outSz, + const byte** outType, word32* outTypeSz, + byte* isPrivate, void* heap); ``` -### wolfSSH_SFTP_Get() +**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** -**Synopsis:** +* **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 -**Description:** -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) +## Key Exchange Algorithm Configuration -**Return Values:** +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. -**WS_SUCCESS** : on success. -All other return values should be considered error cases. +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. -**Parameters:** +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. -**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:** +### wolfSSH Set Algo Lists -``` -#include -``` -``` -int wolfSSH_SFTP_Get(WOLFSSH* ssh , char* from , char* to , -byte resume , -WS_STATUS_CB* statusCb ); -``` +**Synopsis** -**See Also:** +``` +#include -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +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); -``` -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 -} +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_SFTP_Put() +**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. -**Synopsis:** +`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. -**Description:** +**Return Values** -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) +* **WS_SUCCESS** - successful +* **WS_SSH_CTX_NULL_E** - provided CTX was null +* **WS_SSH_NULL_E** - provide SSH was null -**Return Values:** -**WS_SUCCESS** on success. -All other return values should be considered error cases. +### wolfSSH Get Algo List -**Parameters:** +**Synopsis** -**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 +``` +#include -**Example:** +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); -``` -#include -int wolfSSH_SFTP_Put(WOLFSSH* ssh , char* from , char* to , -byte resume , WS_STATUS_CB* statusCb ); +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); ``` -**See Also:** +**Description** -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +These functions act as getters for the various algorithm lists set in the +wolfSSH _ctx_ or _ssh_ objects. -``` -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 -} -``` +`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. -## SFTP Server Functions +**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_SFTP_read() +### wolfSSH_CheckAlgoName +**Synopsis** +``` +#include -**Synopsis:** +int wolfSSH_CheckAlgoName(const char* name); +``` -**Description:** +**Description** -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. +Given a single algorithm _name_ checks to see if it is valid. -**Return Values:** +**Return Values** -**WS_SUCCESS:** on success. +* **WS_SUCCESS** - _name_ is a valid algorithm name +* **WS_INVALID_ALGO_ID** - _name_ is an invalid algorithm name -**Parameters:** -**ssh** - pointer to WOLFSSH structure used for connection +### wolfSSH Query Algorithms -**Example:** +**Synopsis** ``` -#include -int wolfSSH_SFTP_read(WOLFSSH* ssh ); +#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); ``` -**See Also:** +**Description** -wolfSSH_SFTP_accept() -wolfSSH_SFTP_connect() +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. -``` -WOLFSSH* ssh; -``` -``` -//set up ssh and do sftp connections -... -if (wolfSSH_SFTP_read(ssh) != WS_SUCCESS) { -//handle error case -} -``` +**Return Values** +Returns a constant string with the name of an algorithm. Null indicates the +end of the list.