Greetings,
We run ASP.NET Zero v15.3.0 (Angular, ABP 11.2.0). The c query parameter in emailed links (account activation, password reset, email change) is encrypted with SimpleStringCipher, and our code does not assign a custom passphrase to its default instance.
Is setting a customer-specific passphrase for SimpleStringCipher expected as a deployment step? If so, what is the supported way to set it (a configuration key, or code at startup), and is it documented anywhere? Does v15.4.x change how these links are protected, for example any integrity check or expiry on the c value? If we change the passphrase on an existing install, what is the recommended procedure for values already stored with the old one (for example the SMTP password setting and tenant connection strings)?
Thank you!
1 Answer(s)
-
0
Hi @KarakTheWise
Thank you for the detailed questions. The answers below apply to v15.3.0 (ABP 11.2.0), and nothing described here changed in v15.4.0 or v15.5.0.
1. Should a custom passphrase be set, and how?
Yes. Please treat it as a required deployment step.
SimpleStringCipherships with a fixed default passphrase, salt and IV that are public in the ABP source code, and ASP.NET Zero does not override them. ABP's API documentation recommends changing the default passphrase.There is no configuration key. You set the values in code at startup, in
PreInitializeof a module that every process loads, and we recommend reading them from your secret store. Three values are involved:SimpleStringCipher.DefaultPassPhrase: thecparameter of emailed links, tenant connection strings and the SMTP password.Configuration.Settings.SettingEncryptionConfiguration.DefaultPassPhrase: settings defined withisEncrypted: true. These are the external login provider settings (Facebook, Google, Twitter, Microsoft, OpenID Connect, WS-Federation) and the LDAP password. It has the same public default value.AppConsts.DefaultPassPhrase(a constant in*.Application.Shared): theenc_auth_tokenquery-string value used by SignalR and file downloads.
Add this to both
AbpZeroTemplateWebCoreModule.PreInitialize()andAbpZeroTemplateMigratorModule.PreInitialize(). Both modules already have_appConfiguration:var passPhrase = _appConfiguration["Encryption:PassPhrase"]; if (string.IsNullOrWhiteSpace(passPhrase)) { throw new InvalidOperationException("Encryption:PassPhrase is not configured."); } SimpleStringCipher.DefaultPassPhrase = passPhrase; Configuration.Settings.SettingEncryptionConfiguration.DefaultPassPhrase = passPhrase;- Use a long random value (32 or more characters). Every Web.Host instance, the Migrator and any other process must use the same value.
- Changing the passphrase alone is enough, so leave the salt and IV as they are. If you do change the IV, note that
SimpleStringCipher.InstancecopiesDefaultInitVectorByteswhen the class is first used. You would then also have to setSimpleStringCipher.Instance.InitVectorBytes. - For
AppConsts.DefaultPassPhrase, replace the constant with your own value or read it from configuration. Web.Host does both the encryption and the decryption, so there is no data to migrate. Users get a new token at their next sign-in or token refresh.
2. Does v15.4.x change how these links are protected?
No. v15.4.0 and v15.5.0 build
cthe same way: AES-CBC with a key derived from the passphrase and a fixed salt, and a fixed IV. There is no MAC or signature and no timestamp. The v15.4 changes in this area only affected the email templates.cwas designed to hide the link parameters, not to be the security check. The checks happen on the server:- Password reset: the code is random and stored with the user. It expires on the server after
PasswordResetCodeExpirationHours(24 hours by default) and works only once. Failed attempts count toward account lockout, and the endpoint is rate-limited. All of this is already in v15.3.0. - Email activation: the code is random, stored with the user and works only once. It does not expire.
- Email change: the link does not carry a code stored on the server, so only the cipher key protects it. This is the main reason to treat a custom passphrase as mandatory. We are changing this flow so it no longer depends on the cipher [target release].
3. Changing the passphrase on an existing install
Stored values have to be re-encrypted in the same maintenance window in which the new passphrase goes live. You cannot fix them afterwards by re-entering them in the UI. The Tenants and Settings pages decrypt the old value first, and that fails with "Padding is invalid".
These are the stored values:
AbpTenants.ConnectionStringAbpSettingsrows namedAbp.Net.Mail.Smtp.Password(the host row and the tenant rows)- if you also change
SettingEncryptionConfiguration:AbpSettingsrows namedExternalLoginProvider.Facebook,.Google,.Twitter,.Microsoft,.OpenIdConnect,.WsFederation, their.Tenantvariants, andAbp.Zero.Ldap.Password
Procedure:
- Back up the database(s).
- Stop all application instances.
- Re-encrypt each non-empty value as
Encrypt(Decrypt(value, old), new). Run this exactly once, because running it again over values that are already migrated corrupts them. - Deploy the new passphrase to all processes at the same time.
- Clear the distributed cache if you use Redis. The settings cache still holds the values encrypted with the old key.
- Start the application and check that the Settings page loads, a test email is sent, a tenant with its own database opens, and external login works.
- Links emailed before the switch (activation, password reset, email change) stop working, and users request new ones.
Here is a sample routine you can run once, for example from the Migrator, before the new passphrase is deployed:
public class CipherPassPhraseRotator : DomainService { private static readonly string[] SettingNames = { EmailSettingNames.Smtp.Password }; private readonly IRepository<Tenant> _tenantRepository; private readonly IRepository<Setting, long> _settingRepository; public CipherPassPhraseRotator( IRepository<Tenant> tenantRepository, IRepository<Setting, long> settingRepository) { _tenantRepository = tenantRepository; _settingRepository = settingRepository; } public async Task RotateAsync(string oldPassPhrase, string newPassPhrase) { using var uow = UnitOfWorkManager.Begin(); using (CurrentUnitOfWork.DisableFilter(AbpDataFilters.MayHaveTenant, AbpDataFilters.SoftDelete)) { var settings = await _settingRepository.GetAllListAsync( s => SettingNames.Contains(s.Name) && s.Value != null && s.Value != ""); foreach (var setting in settings) { setting.Value = ReEncrypt(setting.Value, oldPassPhrase, newPassPhrase); } var tenants = await _tenantRepository.GetAllListAsync( t => t.ConnectionString != null && t.ConnectionString != ""); foreach (var tenant in tenants) { tenant.ConnectionString = ReEncrypt(tenant.ConnectionString, oldPassPhrase, newPassPhrase); } } await uow.CompleteAsync(); } private static string ReEncrypt(string value, string oldPassPhrase, string newPassPhrase) { var plainText = SimpleStringCipher.Instance.Decrypt(value, oldPassPhrase); return SimpleStringCipher.Instance.Encrypt(plainText, newPassPhrase); } }- If you change both passphrases to the same new value, add the setting names from the third bullet above to
SettingNames. Both use the same default salt and IV, soReEncryptworks for them without changes. - A tenant that has its own database keeps its tenant-level settings in that database. Re-encrypt those first, per tenant, using
CurrentUnitOfWork.SetTenantId(tenantId), while the old passphrase is still active. Re-encryptAbpTenants.ConnectionStringlast.
Best regards,
Markdown is supportedCopy & paste or drag & drop images (max 30 MB per image)