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

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

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

Methods

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.

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

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.

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 into the local-machine stores. Defaults to false — user-only trust is the recommended default for interactive apps; machine trust needs elevation (or a privileged service account) and otherwise fails silently.

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.

Implements

IDisposable