Crate sspi

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;

fn main() {
    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 result = ntlm
        .initialize_security_context()
        .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)
        .execute()
        .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

builders	The builders are required to compose and execute some of the Sspi methods.
internal

Structs

AcceptSecurityContextResult	Contains data returned by calling the execute method of the AcceptSecurityContextBuilder structure. The builder is returned by calling the accept_security_context method.
AcquireCredentialsHandleResult	Contains data returned by calling the execute method of the AcquireCredentialsHandleBuilder structure. The builder is returned by calling the acquire_credentials_handle method.
AuthIdentity	Allows you to pass a particular user name and password to the run-time library for the purpose of authentication
CertTrustErrorStatus	Flags representing the error status codes used in CertTrustStatus.
CertTrustInfoStatus	Flags representing the info status codes used in CertTrustStatus.
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.
ClientRequestFlags	Indicate requests for the context. Not all packages can support all requirements. Bit flags can be combined by using bitwise-OR operations.
ClientResponseFlags	Indicate the attributes of the established context.
ContextNames	Indicates the name of the user associated with a security context. query_context_names function returns this structure.
ContextSizes	Indicates the sizes of important structures used in the message support functions. query_context_sizes function returns this structure.
DecryptionFlags	Indicate the quality of protection. Returned by the decrypt_message method.
EncryptionFlags	Indicate the quality of protection. Used in the encrypt_message method.
Error	Holds the ErrorKind and the description of the SSPI-related error.
InitializeSecurityContextResult	Contains data returned by calling the execute method of the InitializeSecurityContextBuilder structure. The builder is returned by calling the initialize_security_context method.
Ntlm	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.
PackageCapabilities	Set of bit flags that describes the capabilities of the security package. It is possible to combine them.
PackageInfo	General security principal information
SecurityBuffer	Describes a buffer allocated by a transport application to pass to a security package.
ServerRequestFlags	Specify the attributes required by the server to establish the context. Bit flags can be combined by using bitwise-OR operations.
ServerResponseFlags	Indicate the attributes of the established context.

Enums

CredentialUse	A flag that indicates how the credentials are used.
DataRepresentation	The data representation, such as byte ordering, on the target.
ErrorKind	The kind of an SSPI related error. Enables to specify an error based on its type.
SecurityBufferType	Bit flags that indicate the type of buffer.
SecurityPackageType	Represents the security principal in use.
SecurityStatus	The success status of SSPI-related operation.

Traits

Sspi	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.
SspiEx

Functions

enumerate_security_packages	Returns an array of PackageInfo structures that provide information about the security packages available to the client.
query_security_package_info	Retrieves information about a specified security package. This information includes credentials and contexts.

Type Definitions

Result

Representation of SSPI-related result operation. Makes it easier to return a Result with SSPI-related Error.