Tutorial Custom Hsm Enrollment Group X509

This page contains Windows bias

About This Page

This page is part of the Azure documentation. It contains code examples and configuration instructions for working with Azure services.

View on GitHub 📚 View on Microsoft Learn

Bias Analysis

Detected Bias Types

windows_first

powershell_heavy

windows_tools

missing_linux_example

Summary

The documentation demonstrates a strong Windows bias. All code and command-line examples are presented using Windows tools (cmd, Visual Studio, Windows command prompt), with explicit instructions for Windows environments. Linux and macOS users are repeatedly referred to external SDK documentation, rather than being provided with equivalent, inline instructions or examples. Windows-specific tools (Visual Studio, certmgr.msc, .pfx files, etc.) are mentioned and used exclusively or before any mention of cross-platform or Linux alternatives. In several sections, only Windows command-line syntax is shown, and Linux equivalents are omitted.

Recommendations

For each programming language, provide explicit, step-by-step Linux (and macOS, if possible) instructions and examples alongside the Windows ones, rather than referring users to external SDK documentation.
Include Linux/macOS command-line equivalents (e.g., bash, sh) for all git, build, and environment variable commands, not just Windows cmd.
When referencing tools like Visual Studio or certmgr.msc, also mention and provide instructions for common Linux alternatives (e.g., gcc/clang, OpenSSL, update-ca-certificates, etc.).
For certificate management, show how to import certificates into Linux trust stores (e.g., using update-ca-certificates or manual copying to /usr/local/share/ca-certificates) as well as Windows certificate store.
For .NET, Node.js, Python, and Java, provide sample commands for running and building on Linux (e.g., dotnet, npm, python, mvn) and note any OS-specific differences.
Where environment variables are set (e.g., set VAR=val in cmd), also show the export VAR=val syntax for bash.
Add a 'Platform differences' or 'Linux/macOS instructions' callout in each major section, especially where Windows-specific steps are described.
Ensure all file paths and command syntax are shown in both Windows (\) and Unix (/) formats.

Create Pull Request

Scan History

Date	Scan	Status	Result
2026-01-14 00:00	#250	in_progress	Clean
2026-01-13 00:00	#246	completed	Clean
2026-01-11 00:00	#240	completed	Clean
2026-01-10 00:00	#237	completed	Clean
2026-01-09 00:34	#234	completed	Clean
2026-01-08 00:53	#231	completed	Clean
2026-01-06 18:15	#225	cancelled	Clean
2025-09-15 00:00	#112	completed	Clean
2025-08-17 00:01	#83	cancelled	Clean
2025-07-13 21:37	#48	completed	Clean
2025-07-12 23:44	#41	cancelled	Biased
2025-07-09 13:09	#3	cancelled	Clean
2025-07-08 04:23	#2	cancelled	Biased

Flagged Code Snippets

    mkdir certs csr newcerts private
    touch index.txt
    openssl rand -hex 16 > serial

    cd .\azure-iot-sdk-node\provisioning\device\samples
    npm install

    cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=c:/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/Debug/custom_hsm_example.lib ..
    -- Building for: Visual Studio 17 2022
    -- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.22000.
    -- The C compiler identification is MSVC 19.32.31329.0
    -- The CXX compiler identification is MSVC 19.32.31329.0
    
    ...

    -- Configuring done
    -- Generating done
    -- Build files have been written to: C:/azure-iot-sdk-c/cmake

    # OpenSSL root CA configuration file.

    [ ca ]
    default_ca = CA_default

    [ CA_default ]
    # Directory and file locations.
    dir               = .
    certs             = $dir/certs
    crl_dir           = $dir/crl
    new_certs_dir     = $dir/newcerts
    database          = $dir/index.txt
    serial            = $dir/serial
    RANDFILE          = $dir/private/.rand

    # The root key and root certificate.
    private_key       = $dir/private/azure-iot-test-only.root.ca.key.pem
    certificate       = $dir/certs/azure-iot-test-only.root.ca.cert.pem

    # For certificate revocation lists.
    crlnumber         = $dir/crlnumber
    crl               = $dir/crl/azure-iot-test-only.intermediate.crl.pem
    crl_extensions    = crl_ext
    default_crl_days  = 30

    # SHA-1 is deprecated, so use SHA-2 instead.
    default_md        = sha256

    name_opt          = ca_default
    cert_opt          = ca_default
    default_days      = 375
    preserve          = no
    policy            = policy_loose

    [ policy_strict ]
    # The root CA should only sign intermediate certificates that match.
    countryName             = optional
    stateOrProvinceName     = optional
    organizationName        = optional
    organizationalUnitName  = optional
    commonName              = supplied
    emailAddress            = optional

    [ policy_loose ]
    # Allow the intermediate CA to sign a more diverse range of certificates.
    countryName             = optional
    stateOrProvinceName     = optional
    localityName            = optional
    organizationName        = optional
    organizationalUnitName  = optional
    commonName              = supplied
    emailAddress            = optional

    [ req ]
    default_bits        = 2048
    distinguished_name  = req_distinguished_name
    string_mask         = utf8only

    # SHA-1 is deprecated, so use SHA-2 instead.
    default_md          = sha256

    # Extension to add when the -x509 option is used.
    x509_extensions     = v3_ca

    [ req_distinguished_name ]
    # See <https://en.wikipedia.org/wiki/Certificate_signing_request>.
    countryName                     = Country Name (2 letter code)
    stateOrProvinceName             = State or Province Name
    localityName                    = Locality Name
    0.organizationName              = Organization Name
    organizationalUnitName          = Organizational Unit Name
    commonName                      = Common Name
    emailAddress                    = Email Address

    # Optionally, specify some defaults.
    countryName_default             = US
    stateOrProvinceName_default     = WA
    localityName_default            =
    0.organizationName_default      = My Organization
    organizationalUnitName_default  =
    emailAddress_default            =

    [ v3_ca ]
    # Extensions for a typical CA.
    subjectKeyIdentifier = hash
    authorityKeyIdentifier = keyid:always,issuer
    basicConstraints = critical, CA:true
    keyUsage = critical, digitalSignature, cRLSign, keyCertSign

    [ v3_intermediate_ca ]
    # Extensions for a typical intermediate CA.
    subjectKeyIdentifier = hash
    authorityKeyIdentifier = keyid:always,issuer
    basicConstraints = critical, CA:true
    keyUsage = critical, digitalSignature, cRLSign, keyCertSign

    [ usr_cert ]
    # Extensions for client certificates.
    basicConstraints = CA:FALSE
    nsComment = "OpenSSL Generated Client Certificate"
    subjectKeyIdentifier = hash
    authorityKeyIdentifier = keyid,issuer
    keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
    extendedKeyUsage = clientAuth

    [ server_cert ]
    # Extensions for server certificates.
    basicConstraints = CA:FALSE
    nsComment = "OpenSSL Generated Server Certificate"
    subjectKeyIdentifier = hash
    authorityKeyIdentifier = keyid,issuer:always
    keyUsage = critical, digitalSignature, keyEncipherment
    extendedKeyUsage = serverAuth

    [ crl_ext ]
    # Extension for CRLs.
    authorityKeyIdentifier=keyid:always

    [ ocsp ]
    # Extension for OCSP signing certificates.
    basicConstraints = CA:FALSE
    subjectKeyIdentifier = hash
    authorityKeyIdentifier = keyid,issuer
    keyUsage = critical, digitalSignature
    extendedKeyUsage = critical, OCSPSigning

    dotnet run -- -s <id-scope> -c <your-certificate-folder>\certs\device-01-full-chain.cert.pfx -p 1234

    set PROVISIONING_HOST=global.azure-devices-provisioning.net
    set PROVISIONING_IDSCOPE=<id-scope>

    set PROVISIONING_HOST=global.azure-devices-provisioning.net
    set PROVISIONING_IDSCOPE=<ID scope for your DPS resource>

    set X509_CERT_FILE=<your-certificate-folder>\certs\device-01-full-chain.cert.pem
    set X509_KEY_FILE=<your-certificate-folder>\private\device-01.key.pem

Document Details

About This Page

Bias Analysis

Scan History

Flagged Code Snippets