Expand description
sspi-rs is a Rust implementation of Security Support Provider Interface (SSPI). It ships with platform-independent implementations of Security Support Providers (SSP), and is able to utilize native Microsoft libraries when ran under Windows.
The purpose of sspi-rs is to clean the original interface from cluttering and provide users with Rust-friendly SSPs for execution under Linux or any other platform that is able to compile Rust.
Getting started
Here is a quick example how to start working with the crate. This is the first stage of the client-server authentication performed on the client side. It includes calling several SSPI functions and choosing between our own and WinAPI implementations of NTLM SSP depending on the system:
use sspi::Sspi;
#[cfg(windows)]
use sspi::winapi::Ntlm;
#[cfg(not(windows))]
use sspi::Ntlm;
use sspi::builders::EmptyInitializeSecurityContext;
use crate::sspi::internal::SspiImpl;
let mut ntlm = Ntlm::new();
let identity = sspi::AuthIdentity {
username: "user".to_string(),
password: "password".to_string(),
domain: None,
};
let mut acq_creds_handle_result = ntlm
.acquire_credentials_handle()
.with_credential_use(sspi::CredentialUse::Outbound)
.with_auth_data(&identity)
.execute()
.expect("AcquireCredentialsHandle resulted in error");
let mut output = vec![sspi::SecurityBuffer::new(
Vec::new(),
sspi::SecurityBufferType::Token,
)];
let mut builder = EmptyInitializeSecurityContext::<<Ntlm as SspiImpl>::CredentialsHandle>::new()
.with_credentials_handle(&mut acq_creds_handle_result.credentials_handle)
.with_context_requirements(
sspi::ClientRequestFlags::CONFIDENTIALITY | sspi::ClientRequestFlags::ALLOCATE_MEMORY
)
.with_target_data_representation(sspi::DataRepresentation::Native)
.with_output(&mut output);
let result = ntlm.initialize_security_context_impl(&mut builder)
.expect("InitializeSecurityContext resulted in error");
println!("Initialized security context with result status: {:?}", result.status);It is also possible to use any of the Windows SSPs that we do not implement. Here is an example of querying all available SSPs and acquiring Negotiate SSP on Windows:
let package_name = "Negotiate";
// Get information about the specified security package
let package = sspi::winapi::query_security_package_info(sspi::SecurityPackageType::Other(package_name.to_string()))
.expect("query_security_package_info resulted in error");
// Acquire the SSP using its name
let pack = sspi::winapi::SecurityPackage::from_package_type(package.name);Modules
The builders are required to compose and execute some of the Sspi methods.
Structs
Contains data returned by calling the execute method of
the AcceptSecurityContextBuilder structure. The builder is returned by calling
the accept_security_context method.
Contains data returned by calling the execute method of
the AcquireCredentialsHandleBuilder structure. The builder is returned by calling
the acquire_credentials_handle method.
Allows you to pass a particular user name and password to the run-time library for the purpose of authentication
Flags representing the error status codes used in CertTrustStatus.
Flags representing the info status codes used in CertTrustStatus.
Contains trust information about a certificate in a certificate chain,
summary trust information about a simple chain of certificates, or summary information about an array of simple chains.
query_context_cert_trust_status function returns this structure.
Indicate requests for the context. Not all packages can support all requirements. Bit flags can be combined by using bitwise-OR operations.
Indicate the attributes of the established context.
Indicates the name of the user associated with a security context.
query_context_names function returns this structure.
Indicates the sizes of important structures used in the message support functions.
query_context_sizes function returns this structure.
Indicate the quality of protection. Returned by the decrypt_message method.
Indicate the quality of protection. Used in the encrypt_message method.
Holds the ErrorKind and the description of the SSPI-related error.
Contains data returned by calling the execute method of
the InitializeSecurityContextBuilder structure. The builder is returned by calling
the initialize_security_context method.
Specifies the NT LAN Manager (NTLM) Authentication Protocol, used for authentication between clients and servers. NTLM is used by application protocols to authenticate remote users and, optionally, to provide session security when requested by the application.
Set of bit flags that describes the capabilities of the security package. It is possible to combine them.
General security principal information
Describes a buffer allocated by a transport application to pass to a security package.
Specify the attributes required by the server to establish the context. Bit flags can be combined by using bitwise-OR operations.
Indicate the attributes of the established context.
Enums
A flag that indicates how the credentials are used.
The data representation, such as byte ordering, on the target.
The kind of an SSPI related error. Enables to specify an error based on its type.
Bit flags that indicate the type of buffer.
Represents the security principal in use.
The success status of SSPI-related operation.
Constants
Traits
This trait provides interface for all available SSPI functions. The acquire_credentials_handle,
initialize_security_context, and accept_security_context methods return Builders that make it
easier to assemble the list of arguments for the function and then execute it.
Functions
Returns an array of PackageInfo structures that provide information about the security packages available to the client.
Retrieves information about a specified security package. This information includes credentials and contexts.
Type Definitions
Representation of SSPI-related result operation. Makes it easier to return a Result with SSPI-related Error.