adcs-rs

adcs-rs contains Rust crates for the MS-WCCE and MS-WSTEP protocols, which may be used to interact with Active Directory Certificate Services (AD CS).

Related projects include certreq, Windows' certificate request utility, and Certipy.

Introduction

From "What is Active Directory Certificate Services?":

Active Directory Certificate Services (AD CS) is a Windows Server role for issuing and managing public key infrastructure (PKI) certificates used in secure communication and authentication protocols.

Programmatically interacting with AD CS can be useful for automation—for example, to automate the enrollment and renewal of certificates. These interactions are facilitated by protocols published and maintained by Microsoft. adcs-rs implements two of these protocols in Rust:

• MS-WCCE: Windows Client Certificate Enrollment Protocol
• MS-WSTEP: WS-Trust X.509v3 Token Enrollment Extensions Protocol

These protocols—as well as the adcs-rs crates that implement them—are composable. For example, if the Certificate Enrollment Web Service (CES) has been set up, certificate enrollment may occur over HTTPS with the following method:

• MS-WCCE is used to create certificate requests
• MS-WSTEP is used to send these certificate requests, query enrollment status, and retrieve enrolled certificates

use wcce_rs::{
    attributes::EnrollmentNameValuePair,
    cms::{CmsCertificateRequest, CmsCertificateRequestBuildError},
    extensions::CertificateTemplate,
    pkcs10::{CertificateRequest, CertificateRequestBuildError, ExtendedKeyUsage, KeyUsage},
    signing::{SigningCertificate, SigningKey},
};
use wstep_rs::{
    request::{WstepRequest, WstepRequestSerializationError},
    response::{WstepResponse, WstepResponseError},
};

// ...

// Create a PKCS #10 certificate signing request (CSR)
let csr = CertificateRequest::builder()
    .add_key_usage(KeyUsage::DigitalSignature)
    .add_extended_key_usage(ExtendedKeyUsage::ClientAuth)
    .add_extended_key_usage(ExtendedKeyUsage::SmartCardLogon)
    .add_extension(&CertificateTemplate {
        template_oid,
        major_version,
        minor_version,
    })
    .build(&csr_signing_key)?;

// Wrap the CSR in a cryptographic message syntax (CMS) certificate request to add additional request parameters
let cms = CmsCertificateRequest::builder()
    .add_signed_name_value_pair(&EnrollmentNameValuePair::RequesterName {
        domain_account: &requester_name,
    })
    .build(&csr, &csr_signing_key, &csr_signing_cert)?;

/// Submit the CMS CSR over HTTP using SOAP
let soap = WstepRequest::new_issue_x509v3(
    &cms,
    &format!("urn:uuid:{}", &Uuid::new_v4()),
    Some(&adcs_ces_uri),
    None,
)
.serialize_request()?;

let request = http_client
    .post(&adcs_ces_uri)
    .header(CONTENT_TYPE, WstepRequest::SOAP_CONTENT_TYPE)
    .body(soap)
    .build()?;

// ...

let parsed_response = WstepResponse::new_from_soap_xml_str(&response_body)?;
match parsed_response.requested_token() {
    // Do something with the requested security token (certificate)
    Ok(token) => todo!(),
    // Inspect the fault returned by the server
    Err(fault) => todo!(),
}

Crates

The following protocols are supported. Each protocol is implemented in its own crate:

Crate	Protocol	Description	Support
wcce-rs	MS-WCCE	Rust implementation of the Windows Client Certificate Enrollment Protocol	✔
wstep-rs	MS-WSTEP	Rust implementation of the WS-Trust X.509v3 Token Enrollment Extensions Protocol	✔

Related Protocols

The following list of related protocols have not been implemented by adcs-rs. This list is non-exhaustive:

Protocol	Description	Notes
MS-CAESO	Certificate Autoenrollment System Overview	Superset of MS-WCCE and MS-WSTEP
MS-CRTD	Certificate Templates Structure
MS-ICPR	ICertPassage Remote Protocol	Subset of MS-WCCE
MS-XCEP	Certificate Enrollment Policy Protocol

Usage

For MS-WCCE support, add wcce-rs to your dependencies in Cargo.toml. This crate comes with no additional features to enable:

[dependencies]
wcce-rs = "0.1.3"

For MS-WSTEP support, add wstep-rs to your dependencies in Cargo.toml. This crate comes with no additional features to enable:

[dependencies]
wstep-rs = "0.1.3"

History

These libraries were developed by the D. E. Shaw group for secure, high-performance infrastructure engineering.

License

This project is released under a BSD-3-Clause license.

We love contributions! Before you can contribute, please sign and submit this Contributor License Agreement (CLA). This CLA is in place to protect all users of this project.