Skip to content
fabricators docs
On this page

Protect persisted secrets and verify SMTP connections

Share an encrypted key ring and resolve mailbox settings at runtime without restarting.

Status: released in Foundation 0.13.0. No mailbox store, tenant permissions or application frontend is supplied here.

Responsibilities

Foundation Consuming product
ISecretProtector, stable purpose hierarchy and size bounds Authorized scope identifiers and the secret records
AddFoundationDataProtection and certificate configuration Certificate acquisition, lifetime, permissions and retention
AddFoundationDataProtectionEf<TContext> Stable key-ring context, provider, mapping, migrations and backup
Connection verification and SMTP protocol/TLS/authentication Current mailbox ownership, grants and settings resolution
Stable redacted transport failures Authorized UI actions, audit and user-facing messages

Fabricators.Application contains the provider-neutral secret/verification ports. Fabricators.Security.DataProtection implements protection without EF or an HTTP host. Its optional .EntityFrameworkCore adapter uses Microsoft's key-ring repository against a host-owned DbContext implementing IDataProtectionKeyContext. The two Microsoft packages are pinned to the selected .NET/EF 10 patch line.

Register a persistent key ring

csharp
using Fabricators.Security.DataProtection.EntityFrameworkCore;

services.AddDbContext<ProductKeyRingContext>(options =>
    options.UseNpgsql(connectionStringFromSecureConfiguration));
services.AddFoundationDataProtectionEf<ProductKeyRingContext>(
    environment,
    options =>
    {
        options.ApplicationName = "product-cloud";
        options.KeyEncryptionCertificate = loadedCertificate;
        options.DecryptionCertificates = retainedCertificates;
    });

The context exposes DbSet<DataProtectionKey> DataProtectionKeys. Generate and apply its mapping/migration through the product's normal deployment mechanism. The library does not create tables, run migrations or change product histories. Use a stable platform key-ring database, not a context whose database selection depends on the current request's tenant. API and worker replicas that need to decrypt the same secrets use the same application name, storage and certificates.

AddFoundationDataProtection returns IDataProtectionBuilder for other explicit repositories such as PersistKeysToFileSystem. Missing explicit persistence or a conflicting application-name override fails options validation. A certificate with a private RSA key of at least 2048 bits is required by default. The host owns its lifetime and must retain it while the provider needs it.

Only Development may opt into AllowUnencryptedKeysInDevelopment; the default remains false there too. Production, Staging and unknown environments cannot use that opt-in to bypass certificate requirements. Removing key encryption after registration also fails validation. Certificate protection prevents a database read from exposing the raw master keys; the key-ring store still needs restricted write access. It is not protection against arbitrary database modification.

These defaults follow the working Microsoft EF repository and its certificate/key-retention configuration.

Protect records with explicit scope

csharp
using Fabricators.Application.Security.Secrets;

var scope = new SecretProtectionScope("product-cloud",
    ["tenant", tenantId, "mailbox", connectionId, "smtp-password.v1"]);
string protectedValue = protector.Protect(scope, runtimePassword);
// Store protectedValue with the authorized connection record.
string runtimeValue = protector.Unprotect(scope, protectedValue);

Every segment is passed separately to Data Protection. Authority and purposes are stable and case-sensitive, without normalization or flattened concatenation. Use 1–16 purpose segments, each 1–200 characters, without control characters or malformed Unicode. Authority follows the same segment bounds. Choose scopes from trusted server context: knowing a scope or ciphertext is not an authorization grant.

Existing record-format and purpose-chain migrations are product-owned. Foundation does not supply legacy profiles, autodetection or a second decryption fallback. See host compatibility before replacing an existing reader.

Valid plaintext is preserved, including empty strings, Unicode and whitespace. Bounds are 262144 UTF-16 code units for plaintext and 2097152 characters for ciphertext. Oversize/malformed input fails; tampering, wrong scopes/application names and missing keys never return plaintext or ciphertext as a fallback. Protect OAuth refresh/access-token payloads through the same port with distinct purposes. No secret values are logged or cached by this adapter.

For certificate rotation, use the new certificate for key encryption and retain old private certificates in DecryptionCertificates. Existing keys remain stored and Data Protection records their IDs in protected values. Keep those keys and certificates for the required recovery period. This does not automatically re-encrypt all historical rows or migrate an existing filesystem key ring into the database. Preserve/import the existing ring and application name in a reviewed product deployment before changing an already deployed storage backend.

Verify and submit without restarting

csharp
services.AddScoped<IMailConnectionAuthority, ProductMailAuthority>();
services.AddScoped<ISmtpConnectionSettingsSource, ProductSmtpSettings>();
services.AddFabricatorsConnectedSmtp();

MailConnectionVerification result = await verifier.VerifyAsync(connectionId, token);
await sender.SubmitAsync(connectionId, message, token);

verifier is IConnectedMailConnectionVerifier; sender is IConnectedMailTransport. The product authority resolves the current connection and requires MailCapability.VerifyConnection for verification. Send permission alone does not grant verification. The SMTP adapter rechecks authority before resolving settings/credentials and again after token acquisition, before network I/O. Resolver arguments and previous successful probes do not grant access.

ProductSmtpSettings reads the authorized record and calls ISecretProtector to return runtime-only SmtpConnectionSettings. Update its stored host, port, credentials, TLS policy and connection revision normally; subsequent operations resolve them again through the same services, without a restart. Revoke/rotate the connection through the product authority. Do not cache admission or retain a decrypted settings snapshot in a process singleton. Global Host:Mail startup settings are not the SaaS tenant's mailbox-store model.

Verification connects, performs the selected TLS validation and authentication, then disconnects. It never sends MAIL, RCPT or DATA. Anonymous, password and connection-bound delegated/application OAuth profiles follow the same rules as submission. MailConnectionVerification reports the connection/revision/provider and completion time; it is not a delivery or send-as-permission guarantee. Graph verification is not supplied by this increment.

The direct SmtpMailTransport.VerifyConnectionAsync(token) method also verifies its supplied options without sending a message. High-level SaaS integrations should use the connection-bound verifier so live grants/revisions are enforced. Raw options and endpoint selection must come from an authorized server operation, not an unauthenticated network-probe API.

MailConnectionVerificationException contains a stable MailFailure, with no inner SMTP reply, password or token. Unsupported provider/unavailable selector returns Unavailable; authentication failures return AuthenticationRequired. Cancellation propagates. The existing submission ambiguity rules still apply only after actual message submission starts. See connected mail for sender checks, submission acceptance and TLS policies.

Version 0.16.0 preserves Diagnostics through both submission and verification: safe cause enums distinguish TLS, socket, protocol, authentication, configuration, timeout and I/O; a socket error carries its numeric SocketError code. SMTP reply status codes also survive verification. Log these structured properties when operational context is needed. Raw MailKit messages/inner exceptions remain excluded because providers may echo credentials or message data. UnknownOutcome still means that automatic resubmission may duplicate an accepted message.

Verification boundary

Tests use actual Data Protection and EF persistence with SQLite/PostgreSQL, independent providers, encrypted stored XML, retained-certificate/key rotation, scope/tamper/unknown-key rejection and concurrent PostgreSQL replicas. Real SMTP and TLS fixtures check probes, rejected authentication, no message commands, revocation during OAuth-token acquisition and encrypted database settings changed between calls to the same verifier/sender. No external recipient or customer mailbox is contacted; physical deployment/certificate provisioning stays product-owned.

Foundation CI/Publish caches restored NuGet dependencies by OS and lockfiles. Independent package consumers retain isolated caches and restore our freshly packed archives from a local feed; these checks do not pull Foundation archives from GitHub Packages. Remote cache hits require a subsequent workflow run.

↑ ↓ to move↵ to openSearching fabricators .NET foundation v0.19.0