Bushman.Secrets.Abstractions 1.0.0

Bushman.Secrets.Abstractions

Причина создания

В приложениях, написанных на .Net Framework, конфигурационные файлы обычно имеют формат XML. "Из коробки" эта платформа предоставляет возможность шифровать и расшифровывать секции в подобных файлах, дабы скрывать или отображать секреты: логины, пароли, строки подключения и URL различных сервисов.

Однако порой возникает необходимость хранить зашифрованные секреты и в других местах: в JSON-файлах конфигураций, в SQL базах данных, в записях CRM, в реестре Windows, а порой они могут понадобиться и в логах. Помимо этого, может возникать необходимость отправлять зашифрованные секреты по почте или через мессенджеры, а так же сохранять их в git-репозиториях (например, в составе конфигурационных файлов).

В приложениях, написанных на .NET (в отличии от .Net Framework), конфигурационные файлы обычно имеют формат JSON. "Из коробки" эта платформа не предоставляет возможность шифровать и расшифровывать секции в таких файлах. Вместо этого Microsoft рекомендует для хранения секретов использовать такие платные хранилища секретов, как Azure Key Vault или HashiCorp Vault.

Пакет Bushman.Secrets.Abstractions предоставляет абстрактную модель для создания, парсинга, шифрования, расшифровки и распаковки секретов в тексте. Реализация этой абстрактной модели находится в пакете Bushman.Secrets. Все операции шифрования и расшифровки выполняются на основе сертификатов.

Для того, чтобы при запуске приложения в объектной модели конфигурационных настроек, представленной интерфейсами Microsoft.Extensions.Configuration.IConfigurationRoot или Microsoft.Extensions.Configuration.IConfiguration выполнить распаковку всех секретов в памяти, можно использовать пакет Bushman.Extensions.Configuration.Secrets, в составе которого для интерфейса Microsoft.Extensions.Configuration.IConfiguration определён метод расширения ExpandSecrets() (см. ниже раздел Распаковка секретов в настройках приложения).

О форме записи секретов

Секреты записываются в особом формате, позволяющем без проблем идентифицировать их в тексте. Каждый секрет может находиться в одном из двух состояний: в расшифрованном или зашифрованном.

При использовании пакета Bushman.Secrets, JSON-файл с записанными в нём секретами как в качестве непосредственных значений (см. prop2 и prop4), так и в составе произвольного текста (см. prop3 и prop5), может выглядеть, например, так:

{
  "prop1": "Hello World", // Распакованное значение.
  "prop2": "%%DECRYPTED|CurrentUser|SHA512|00DD37AA6E8AA22E9B11DFC6B8B5DD9706D9FD8C|Hello World|DECRYPTED%%", // Секрет в расшифрованном состоянии.
  "prop3": "Расшифрованный секрет в составе произвольного текста: %%DECRYPTED|CurrentUser|SHA512|00DD37AA6E8AA22E9B11DFC6B8B5DD9706D9FD8C|Hello World|DECRYPTED%%. Мама мыла раму.",

  // Секрет в зашифрованном состоянии.
  "prop4": "%%ENCRYPTED|CurrentUser|SHA512|00DD37AA6E8AA22E9B11DFC6B8B5DD9706D9FD8C|cFyOsNujOBp21frIVpIwMT2hjzR6ZDsAtZfs8eWfoVcLiqDqEO+rAEXVmE6KbQMLv+pizS8O/Ri124uM7YvM8NbsKfP2AQI4G/reup5I8kmpGXGkVjevuDuQ0eo5MRbobBPIXPFtvja9zCFn3hpNk/rt243vGMCbhCdIRgXRyOGrHxNuxlB7wHDEkZ+cz68D5cLLYYTF2ctpvgqMHjU7DRg5Vm5NT3N+Rn1FuAFmTa1laBm+Db5CM3yQ1M376FbEU6fiW3xnVrd7i52BREo4T80asmjFLcIxR8R7j5nBpZcSCM4e+wmD6IJGjJDh9Pc79I/s5P2bQduczJIxWIS1mQ==|ENCRYPTED%%",
  "prop5": "Зашифрованный секрет в составе произвольного текста: %%ENCRYPTED|CurrentUser|SHA512|00DD37AA6E8AA22E9B11DFC6B8B5DD9706D9FD8C|cFyOsNujOBp21frIVpIwMT2hjzR6ZDsAtZfs8eWfoVcLiqDqEO+rAEXVmE6KbQMLv+pizS8O/Ri124uM7YvM8NbsKfP2AQI4G/reup5I8kmpGXGkVjevuDuQ0eo5MRbobBPIXPFtvja9zCFn3hpNk/rt243vGMCbhCdIRgXRyOGrHxNuxlB7wHDEkZ+cz68D5cLLYYTF2ctpvgqMHjU7DRg5Vm5NT3N+Rn1FuAFmTa1laBm+Db5CM3yQ1M376FbEU6fiW3xnVrd7i52BREo4T80asmjFLcIxR8R7j5nBpZcSCM4e+wmD6IJGjJDh9Pc79I/s5P2bQduczJIxWIS1mQ==|ENCRYPTED%%. Мама мыла раму."
}

Распаковкой секрета называется его замена в тексте на хранящееся в нём расшифрованное значение. Например, если в свойствах prop2 и prop4 приведённого выше JSON-файла выполнить распаковку секретов, то значения этих свойств станут таким же, как у свойства prop1.

Общая схема записи секрета в тексте следующая:

SecretOpenTag|SecretStorage|HashAlgorithmName|Thumbprint|Data|SecretCloseTag

где:

• SecretOpenTag - тег открытия секрета. Если секрет зашифрован, то это будет тег %%ENCRYPTED. Если расшифрован, то %%DECRYPTED.
• SecretStorage - хранилище, в котором находится нужный сертификат. Допустимые значения: LocalMachine и CurrentUser.
• HashAlgorithmName - наименование алгоритма хеширования. Допустимые значения: MD5, SHA1, SHA256, SHA384, SHA512.
• Thumbprint - отпечаток сертификата, с помощью ключей которого следует выполнять шифрование и расшифровку секрета. Это значение можно посмотреть в настройках сертификата на вкладке "Состав".
• Data - данные, сохраняемые в секрете. Если секрет не зашифрован, то этими данными будет обычный текст. Если секрет зашифрован, то в качестве значения будут записаны зашифрованные данные в формате строки base64.
• SecretCloseTag - тег закрытия секрета. Если секрет зашифрован, то это будет тег ENCRYPTED%%. Если расшифрован, то DECRYPTED%%.

В качестве разделителя полей используется |. Этот символ разрешено использовать в т.ч. и в тексте, сохраняемом в поле Data.

Примеры работы с секретами

Примеры кода смотрите в юнит-тестах проекта Bushman.Secrets.Test.

Распаковка секретов в настройках приложений

Примеры кода смотрите в юнит-тестах проекта Bushman.Extensions.Configuration.Secrets.Test.