Crate winrm_rs 

Async WinRM (WS-Management) client for Rust.

Provides remote command execution on Windows hosts via the WinRM protocol with NTLMv2, Basic, Kerberos, and Certificate authentication support.

Architecture

The crate is structured in three layers:

• WinrmClient – high-level async API that manages shell lifecycle, command execution, and output polling. Callers interact exclusively with this type and its associated config/credential structs.

• soap (internal) – builds WS-Management XML envelopes for Create, Execute, Receive, Signal, and Delete operations, and parses the corresponding responses. Envelope construction uses raw format! strings rather than a full XML library to keep dependencies minimal.

• ntlm (internal) – implements the NTLMv2 challenge/response handshake per MS-NLMP. Only NTLMv2 is supported; NTLMv1 is intentionally excluded.

HTTP transport is provided by reqwest with rustls-tls.

Authentication methods

Method	Enum variant	Notes
HTTP Basic	AuthMethod::Basic	Credentials sent base64-encoded per request. Use only over HTTPS.
NTLMv2	AuthMethod::Ntlm	Three-step handshake (negotiate / challenge / authenticate). Default.
Kerberos	AuthMethod::Kerberos	SPNEGO Negotiate via system Kerberos. Requires kerberos feature + kinit.
Certificate	AuthMethod::Certificate	TLS client certificate. Set client_cert_pem and client_key_pem on config.

Error handling

All fallible operations return Result<T, WinrmError>. The top-level WinrmError enum wraps transport errors (reqwest::Error), SOAP faults (SoapError), NTLM failures (NtlmError), and authentication rejections. Errors are designed for programmatic matching via match and for human-readable display via their Display impls.

Shell reuse

For running multiple commands on the same host, use WinrmClient::open_shell to create a Shell that persists across commands, avoiding the overhead of shell creation and deletion per command.

Cargo features

• kerberos – Enables Kerberos authentication via cross-krb5.
• credssp – Experimental. Enables CredSSP authentication for double-hop delegation. Pulls in openssl as a C dependency (required because Microsoft’s CredSSP server has proven incompatible with rustls in-memory TLS — see src/auth/credssp.rs). The handshake is not yet fully validated end-to-end; treat as preview-quality and do not use in production.

Re-exports

A few third-party types appear in this crate’s public API and are re-exported for convenience:

• SecretString / ExposeSecret from the secrecy crate — used for the password field of WinrmCredentials.
• CancellationToken from tokio_util — used as a parameter to the *_with_cancel methods of WinrmClient so callers can cooperatively cancel in-flight operations.

Example

use winrm_rs::{WinrmClient, WinrmConfig, WinrmCredentials};

let client = WinrmClient::new(
    WinrmConfig::default(),
    WinrmCredentials::new("administrator", "password", ""),
)?;

let output = client.run_powershell("win-server", "Get-Process | ConvertTo-Json").await?;
println!("stdout: {}", String::from_utf8_lossy(&output.stdout));

Structs

CancellationToken

A token which can be used to signal a cancellation request to one or more tasks.

CommandOutput

Collected output from a completed remote command.

NeedsCredentials

Typestate marker: credentials have not yet been provided.

NtlmSession

NTLM session state for message encryption/decryption after authentication.

Ready

Typestate marker: all required fields are set and build can be called.

ReceiveOutput

Parsed output from a single WinRM Receive response.

Shell

A reusable WinRM shell session.

WinrmClient

Async WinRM (WS-Management) HTTP client.

WinrmClientBuilder

Builder for WinrmClient with compile-time state tracking.

WinrmConfig

Configuration for a WinrmClient connection.

WinrmCredentials

Credentials for WinRM authentication.

Enums

AuthMethod

Authentication method for the WinRM HTTP transport.

CredSspError

Errors from the CredSSP authentication protocol (MS-CSSP).

EncryptionMode

Controls whether NTLM message encryption (sealing) is applied to SOAP bodies.

NtlmError

Errors from the NTLM authentication protocol layer.

SoapError

Errors from SOAP envelope parsing or WS-Management fault responses.

WinrmError

Errors that can occur during WinRM operations.

Constants

RESOURCE_URI_PSRP

PowerShell remoting plugin resource URI (the default PS configuration).

Traits

ExposeSecret

Expose a reference to an inner secret

Functions

encode_powershell_command

Encode a PowerShell script as UTF-16LE base64 for use with -EncodedCommand.

Type Aliases

SecretString

Secret string type.