Class CertificateManager

A class to manage SSL certificates used by this proxy server.

Inheritance

object

CertificateManager

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Titanium.Web.Proxy.Network

Assembly: Titanium.Web.Proxy.dll

Syntax

public sealed class CertificateManager : IDisposable

Properties

AreInteractiveRootStoreMutationsSuppressed

True when Root-store Add/Remove should be skipped to avoid modal CryptUI prompts (static flag, CI env, or TITANIUM_SKIP_ROOT_STORE_UI=1).

Declaration

public static bool AreInteractiveRootStoreMutationsSuppressed { get; }

Property Value

Type	Description
bool

CertificateCacheTimeOutMinutes

Minutes certificates should be kept in cache when not used.

Declaration

public int CertificateCacheTimeOutMinutes { get; set; }

Property Value

Type	Description
int

CertificateEngine

Selects the certificate generation engine. Default is BouncyCastle on all platforms. On non-Windows runtimes, DefaultWindows is coerced to BouncyCastle; both BouncyCastle engines are supported.

Declaration

public CertificateEngine CertificateEngine { get; set; }

Property Value

Type	Description
CertificateEngine

CertificateGraceDays

Number of days by which the certificate's NotBefore timestamp is backdated relative to the current UTC time. A small backdate (the default is 2 days) compensates for minor clock-skew between the proxy machine and clients; it is not necessary to backdate by a year.

The total certificate lifetime is CertificateValidDays + CertificateGraceDays. Chrome 70+ and iOS 14+ cap this at 398 days for TLS leaf certificates.

Declaration

public int CertificateGraceDays { get; set; }

Property Value

Type	Description
int

CertificateStorage

The fake certificate cache storage. The default implementation stores leaf certificates in a crts subdirectory of the per-user Titanium.Web.Proxy directory (%LocalAppData% on Windows, ApplicationData on Linux/macOS). Implement ICertificateCache and assign a concrete class here to customize.

Declaration

public ICertificateCache CertificateStorage { get; set; }

Property Value

Type	Description
ICertificateCache

CertificateValidDays

Number of days generated HTTPS leaf certificates are valid for, measured forward from the moment of creation. The certificate's NotBefore is set to UtcNow - CertificateGraceDays, so the effective total validity window (NotAfter − NotBefore) equals CertificateValidDays + CertificateGraceDays.

Chrome 70+ and iOS 14+ reject certificates whose total validity window exceeds 398 days. To stay within that limit, keep CertificateValidDays + CertificateGraceDays <= 398. The default value of 396, combined with the default grace of 2, equals exactly 398 days total.

Declaration

public int CertificateValidDays { get; set; }

Property Value

Type	Description
int

DisableWildCardCertificates

When true, issue per-host certificates instead of *.parent.tld wildcards. Default false (wildcards enabled where applicable).

Declaration

public bool DisableWildCardCertificates { get; set; }

Property Value

Type	Description
bool

IntermediateCertificates

Additional certificates to send to clients as part of the TLS certificate chain. Use this when RootCertificate is an intermediate CA rather than the trust anchor: set this to the ordered list of intermediate certificates between the signing certificate and the client-trusted root so that clients can build a complete verified chain. When RootCertificate is not self-signed it is automatically included in the chain even if this collection is empty; any certificates in this collection are appended after it.

Declaration

public X509Certificate2Collection? IntermediateCertificates { get; set; }

Property Value

Type	Description
X509Certificate2Collection

LastOsTrustResult

Last OS/browser trust outcome from TrustRootCertificate(bool) / related helpers.

Declaration

public CertificateOsTrustResult? LastOsTrustResult { get; }

Property Value

Type	Description
CertificateOsTrustResult

LeafCertificateKeyAlgorithm

Key algorithm for generated leaf certificates. Honoured by the BouncyCastle engines; the Windows engine always issues RSA. Defaults to Rsa2048.

Switching to EcdsaP256 makes generating a certificate for a not-yet-seen host roughly fifty times cheaper, which is the single largest cost the proxy adds to a first visit. Only clients that accept ECDSA server certificates can be intercepted afterwards.

Declaration

public CertificateKeyAlgorithm LeafCertificateKeyAlgorithm { get; set; }

Property Value

Type	Description
CertificateKeyAlgorithm

LeafRsaKeyPairBufferSize

How many RSA-2048 leaf private keys to keep ready in a background-refilled buffer so first visits do not pay key-generation cost on the CONNECT that needs the certificate. Defaults to 8. Set to 0 to disable buffering (keys are generated on demand).

Only applies when LeafCertificateKeyAlgorithm is Rsa2048. ECDSA P-256 keys are cheap enough that they are always generated inline. The buffer is process-wide and shared by every CertificateManager instance.

Declaration

public static int LeafRsaKeyPairBufferSize { get; set; }

Property Value

Type	Description
int

OverwritePfxFile

Overwrite Root certificate file.

true : replace an existing .pfx file if password is incorrect or if RootCertificate = null.

Declaration

public bool OverwritePfxFile { get; set; }

Property Value

Type	Description
bool

PfxFilePath

Name(path) of the Root certificate file.

Set the name or path of the .pfx file. When empty, the file is named rootCert.pfx. Relative or empty values are resolved under the per-user Titanium.Web.Proxy directory (%LocalAppData% on Windows, ApplicationData on Linux/macOS). Absolute paths are honored as-is.

Declaration

public string PfxFilePath { get; set; }

Property Value

Type	Description
string

PfxPassword

Password of the Root certificate file.

Set a password for the .pfx file

Declaration

public string PfxPassword { get; set; }

Property Value

Type	Description
string

RootCertificate

The root certificate.

Declaration

public X509Certificate2? RootCertificate { get; set; }

Property Value

Type	Description
X509Certificate2

RootCertificateIssuerName

Name of the root certificate issuer. (This is valid only when RootCertificate property is not set.)

Declaration

public string RootCertificateIssuerName { get; set; }

Property Value

Type	Description
string

RootCertificateName

Subject/CN name used when generating a root certificate. (This is valid only when RootCertificate property is not set.) If no certificate is provided then a default root certificate will be created and used. Persistence uses PfxFilePath / CertificateStorage under the per-user Titanium.Web.Proxy directory (not the process executable directory).

Declaration

public string RootCertificateName { get; set; }

Property Value

Type	Description
string

SaveFakeCertificates

When true, persist generated leaf certificates via CertificateStorage so subsequent runs can reload them instead of regenerating.

Declaration

public bool SaveFakeCertificates { get; set; }

Property Value

Type	Description
bool

StorageFlag

Adjust behaviour when certificates are saved to filesystem.

Declaration

public X509KeyStorageFlags StorageFlag { get; set; }

Property Value

Type	Description
X509KeyStorageFlags

SuppressInteractiveRootStoreMutations

When true, skip Root Add/Remove that trigger Windows CryptUI "Root Certificate Store" Yes/No dialogs (which hang headless CI and unattended dotnet test). Personal (My) mutations still run. Also treated as true when CI, GITHUB_ACTIONS, TF_BUILD, or TITANIUM_SKIP_ROOT_STORE_UI=1 is set. Opt back in for intentional interactive Install CA (e.g. local E2E-Slow Chrome) by setting this to false in a process that does not set those env vars.

Declaration

public static bool SuppressInteractiveRootStoreMutations { get; set; }

Property Value

Type	Description
bool

Methods

ApplyFastColdStartLeafSettings()

Fast first-visit MITM for modern TLS clients (browsers, current HttpClient): BouncyCastleFast, ECDSA P-256 leaves, and SaveFakeCertificates enabled. The root CA stays RSA.

Library Balanced still defaults to RSA-2048 leaves for widest compatibility. Call this from Inspector, CLI, and desktop MITM hosts where clients are known to accept ECDSA server certificates — RSA leaf generation is the dominant cold-start cost when a page hits many not-yet-seen hosts (often ~1 s per host).

Declaration

public void ApplyFastColdStartLeafSettings()

ApplyUnixSslTrustAfterStoreInstall(bool)

macOS/Linux SSL trust (Keychain / NSS). May show auth UI — keep on a pumping thread. No-op on Windows (Root store presence is trust).

Declaration

public void ApplyUnixSslTrustAfterStoreInstall(bool machineTrusted = false)

Parameters

Type	Name	Description
bool	machineTrusted

ApplyUnixSslUntrust()

macOS/Linux Keychain/NSS untrust. May show auth UI — keep on a pumping thread.

Declaration

public void ApplyUnixSslUntrust()

ClearRootCertificate()

Clear the root certificate and cache.

Declaration

public void ClearRootCertificate()

CreateRootCertificate(bool)

Attempts to create a RootCertificate.

Declaration

public bool CreateRootCertificate(bool persistToFile = true)

Parameters

Type	Name	Description
bool	persistToFile	if set to true try to load/save the certificate from rootCert.pfx.

Returns

Type	Description
bool	true if succeeded, else false.

CreateServerCertificate(string)

Creates a server certificate signed by the root certificate.

Declaration

public Task<X509Certificate2?> CreateServerCertificate(string certificateName)

Parameters

Type	Name	Description
string	certificateName

Returns

Type	Description
Task<X509Certificate2>

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

EnsureRootCertificate()

Ensure certificates are setup (creates root if required). Also makes root certificate trusted based on initial setup from proxy constructor for user/machine trust.

Declaration

public void EnsureRootCertificate()

EnsureRootCertificate(bool, bool, bool)

Ensure certificates are setup (creates root if required). Also makes root certificate trusted based on provided parameters.

Declaration

public void EnsureRootCertificate(bool userTrustRootCertificate, bool machineTrustRootCertificate, bool trustRootCertificateAsAdmin = false)

Parameters

Type	Name	Description
bool	userTrustRootCertificate	Trust in the current-user stores. Prefer true for interactive MITM; false for fully opt-in trust.
bool	machineTrustRootCertificate	Also trust in local-machine stores (needs elevation). Implies user trust. Prefer false unless installing for a service / all users.
bool	trustRootCertificateAsAdmin	Elevate via UAC when installing (Windows only). Defaults to false.

InstallNssCertutilAndRetryUserTrust()

Installs NSS certutil (Linux package or macOS Homebrew) after user consent, then retries user SSL trust.

Declaration

public CertificateOsTrustResult InstallNssCertutilAndRetryUserTrust()

Returns

Type	Description
CertificateOsTrustResult

InstallRootIntoCertificateStores(bool)

Installs the root into Personal + Trusted Root stores only (Windows CryptUI Yes/No on Root Add). Does not prune orphans or run Unix Keychain/NSS trust — UI callers should finish those off the dispatcher after CryptUI returns so Avalonia does not show Not Responding.

Declaration

public bool InstallRootIntoCertificateStores(bool machineTrusted = false)

Parameters

Type	Name	Description
bool	machineTrusted

Returns

Type	Description
bool	True when the user Root store entry was newly added.

IsOsRootStillPresent()

True when a Titanium root (current hash or known CN) remains in login or System keychain.

Declaration

public bool IsOsRootStillPresent()

Returns

Type	Description
bool

IsRootCertificateMachineTrusted()

Determines whether the root certificate is machine trusted.

Declaration

public bool IsRootCertificateMachineTrusted()

Returns

Type	Description
bool

IsRootCertificateUserTrusted()

Determines whether the root certificate is trusted.

Declaration

public bool IsRootCertificateUserTrusted()

Returns

Type	Description
bool

IsRootInLoginKeychain()

Best-effort: true when the current root appears in the macOS login keychain. Does not imply SSL Always Trust — use VerifyOsUserSslTrust().

Declaration

public bool IsRootInLoginKeychain()

Returns

Type	Description
bool

ListSameCommonNameRootThumbprints(StoreLocation, string?)

Read-only: Root-store thumbprints matching RootCertificateName. Uses FindBySubjectName (not a full store enumeration) so interactive Clear/reinstall does not sit on Busy for tens of seconds on large Windows Root stores.

Declaration

public IReadOnlyList<string> ListSameCommonNameRootThumbprints(StoreLocation storeLocation, string? keepThumbprint = null)

Parameters

Type	Name	Description
StoreLocation	storeLocation
string	keepThumbprint

Returns

Type	Description
IReadOnlyList<string>

LoadRootCertificate()

Loads the root certificate via CertificateStorage (default: per-user Titanium.Web.Proxy directory, file name from PfxFilePath or rootCert.pfx).

Declaration

public X509Certificate2? LoadRootCertificate()

Returns

Type	Description
X509Certificate2

LoadRootCertificate(string, string, bool, X509KeyStorageFlags)

Manually load a Root certificate file from give path (.pfx file).

Declaration

public bool LoadRootCertificate(string pfxFilePath, string password, bool overwritePfXFile = true, X509KeyStorageFlags storageFlag = X509KeyStorageFlags.Exportable)

Parameters

Type	Name	Description
string	pfxFilePath	Set the name or path of the .pfx file. When empty, the file is named rootCert.pfx under the per-user Titanium.Web.Proxy directory. Absolute paths are honored as-is.
string	password	Set a password for the .pfx file.
bool	overwritePfXFile	true : replace an existing .pfx file if password is incorrect or if RootCertificate==null.
X509KeyStorageFlags	storageFlag

Returns

Type	Description
bool	true if succeeded, else false.

OpenMacKeychainGuidance()

Opens Keychain Access (and a temp .cer) for manual Always Trust on macOS.

Declaration

public string? OpenMacKeychainGuidance()

Returns

Type	Description
string

PruneOrphanedPersonalCertificates(StoreLocation, bool)

Personal (My) store same-CN cleanup only — typically no CryptUI. Safe off the UI thread.

Declaration

public void PruneOrphanedPersonalCertificates(StoreLocation storeLocation, bool keepCurrentThumbprint)

Parameters

Type	Name	Description
StoreLocation	storeLocation
bool	keepCurrentThumbprint

PruneOrphanedSameCommonNameCertificates(bool, bool)

Removes same-CN Root/My entries (may show Windows Root Delete CryptUI). Prefer a pumping UI thread when interactive.

Declaration

public void PruneOrphanedSameCommonNameCertificates(bool machineTrusted, bool keepCurrentThumbprint)

Parameters

Type	Name	Description
bool	machineTrusted
bool	keepCurrentThumbprint

RemoveCertificateByThumbprint(StoreName, StoreLocation, string)

Removes one certificate by thumbprint. Root Remove may show Windows CryptUI — UI thread.

Declaration

public bool RemoveCertificateByThumbprint(StoreName storeName, StoreLocation storeLocation, string thumbprint)

Parameters

Type	Name	Description
StoreName	storeName
StoreLocation	storeLocation
string	thumbprint

Returns

Type	Description
bool

RemoveTrustedRootCertificate(bool)

Removes the trusted certificates from the current-user Personal and Trusted Root stores, and optionally also from the local-machine Personal and Trusted Root stores.

Declaration

public void RemoveTrustedRootCertificate(bool machineTrusted = false)

Parameters

Type	Name	Description
bool	machineTrusted	When true, also remove from local-machine stores (needs elevation; fails silently otherwise). Pass the same value used when trusting.

RemoveTrustedRootCertificateAsAdmin(bool)

Removes the trusted certificates from user store, optionally also from machine store

Declaration

public bool RemoveTrustedRootCertificateAsAdmin(bool machineTrusted = false)

Parameters

Type	Name	Description
bool	machineTrusted

Returns

Type	Description
bool	Should also remove from machine store?

TrustRootCertificate(bool)

Trusts the root certificate in the current-user Personal and Trusted Root stores, and optionally also in the local-machine Personal and Trusted Root stores.

Declaration

public void TrustRootCertificate(bool machineTrusted = false)

Parameters

Type	Name	Description
bool	machineTrusted	When true, also install machine-wide trust (LocalMachine on Windows; System.keychain / system CA store on macOS/Linux, with an admin prompt). Defaults to false — user-only trust is the recommended default. Check LastOsTrustResult and VerifyOsUserSslTrust() after calling.

TrustRootCertificateAsAdmin(bool)

Puts the certificate to the user store, optionally also to the machine store, prompting with UAC when elevation is required. Works only on Windows.

Declaration

public bool TrustRootCertificateAsAdmin(bool machineTrusted = false)

Parameters

Type	Name	Description
bool	machineTrusted	When true, elevate to install into local-machine stores. Defaults to false (user store only).

Returns

Type	Description
bool	True if success.

VerifyOsUserSslTrust()

Re-checks macOS/Linux user SSL trust for the current root.

Declaration

public bool VerifyOsUserSslTrust()

Returns

Type	Description
bool

Implements

IDisposable