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
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
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
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.