Internal Dream Consistency low-level crypto helper package used by security, service authentication, and internal API-to-API communication libraries.
DreamConsistency.Crypto is an internal foundational crypto package.
It provides reusable low-level helpers for hashing, HMAC signing, secure comparison,
random generation, Base64 URL encoding, and root key resolution.
This package is intended to support higher-level security packages such as
DreamConsistency.Security.ServiceAuth. It should not contain business logic,
API-specific authorization rules, tenant logic, or product-specific security behavior.
| Property | Current Decision |
|---|---|
| Package ID | DreamConsistency.Crypto |
| Initial Documented Release | 1.0.0 |
| Target Framework | .NET Standard 2.1 |
| NuGet Feed | https://nuget.dreamconsistency.com/v3/index.json |
| Package Hosting | BaGetter on Dream Consistency Hub server. |
| Release Pipeline | DreamConsistency.Crypto - NuGet Release |
| Jenkins Folder | DreamConsistency - Packages |
| Versioning | Semantic Versioning: MAJOR.MINOR.PATCH |
| Visibility | Internal Dream Consistency package. |
The purpose of this package is to provide a small, reusable crypto foundation for internal Dream Consistency services and libraries.
| Area | Responsibility |
|---|---|
| Root Key Resolution | Provides a compatibility-friendly way to resolve root keys without exposing secrets in consuming code. |
| HMAC-SHA256 | Provides helper methods for creating and verifying Base64-encoded HMAC-SHA256 signatures. |
| SHA256 Hashing | Provides helper methods for computing SHA256 hashes in Base64 or hexadecimal form. |
| Secure Comparison | Provides fixed-time comparison helpers for signature and sensitive value checks. |
| Secure Random | Provides cryptographically secure random byte and string generation helpers. |
| Base64 URL Encoding | Provides URL-safe Base64 encoding and decoding helpers. |
This package should stay small and stable. Higher-level authentication behavior belongs in
DreamConsistency.Security.ServiceAuth, not in this package.
RootKeyProvider keeps backward compatibility with existing code that already uses
static root key resolution.
The preferred implementation order is:
New projects should configure root key resolution from application configuration.
Example configuration shape:
Local development should use dotnet user-secrets or local environment variables.
Server environments should use Docker secrets, environment variables, or protected server-side configuration.
Consuming projects must include the internal Dream Consistency NuGet feed.
Install the package:
Or add it directly to the project file:
Existing compatibility usage:
HMAC-SHA256 signing usage:
SHA256 hashing usage:
Secure random usage:
| Allowed in Package | Not Allowed in Package |
|---|---|
| HMAC helpers | Real production secrets |
| SHA256 helpers | Hardcoded service credentials |
| Secure random helpers | AccessControl business logic |
| Secure comparison helpers | Legislator-specific logic |
| Base64 URL helpers | Hestino-specific logic |
| Key provider abstraction and compatibility helpers | Authorization rules for specific APIs |
| Low-level crypto utilities | Connection strings, API keys, private keys, or certificates |
| Topic | Decision |
|---|---|
| Secret Storage | Secrets must be stored outside Git and outside NuGet artifacts. |
| Local Development | Use dotnet user-secrets or local environment variables. |
| DEV Server | Use Docker secrets, environment variables, or protected server configuration. |
| PROD Server | Use separate production secrets. DEV and PROD must not share the same key values. |
| Legacy Embedded Keys | Allowed only as temporary migration fallback. Should be disabled after migration. |
| Key Rotation | For signing keys, introduce a new key and support old/new validation during migration. |
| AES / Encrypted Data | Changing encryption keys requires a key-ring or migration strategy to avoid losing access to old encrypted data. |
DreamConsistency.Crypto provides low-level cryptographic helpers.
DreamConsistency.Security.ServiceAuth should use this package to implement
the actual internal API-to-API authentication protocol.
ServiceAuth should own the HTTP protocol. Crypto should only provide the reusable crypto primitives.
Package releases are done manually through Jenkins after changes are merged to master.
1.0.0 is already published, the next release must be 1.0.1,
1.1.0, or another valid SemVer version.
| Setting | Value |
|---|---|
| Jenkins Folder | DreamConsistency - Packages |
| Job Name | DreamConsistency.Crypto - NuGet Release |
| Repository | git@bitbucket.org:skyrocket_novisad/dreamconsistency.crypto.git |
| Branch | master |
| Jenkinsfile | Jenkinsfile |
| Build Agent | mcr.microsoft.com/dotnet/sdk:10.0 |
| BaGetter Credential | dreamconsistency-nuget-api-key |
| Bitbucket Credential | Dream Consistency Core Architecture Project Access Key |
The package uses Semantic Versioning.
| Version Type | Example | Meaning |
|---|---|---|
| Patch | 1.0.1 |
Bug fix with no breaking changes. |
| Minor | 1.1.0 |
New helper or feature with no breaking changes. |
| Major | 2.0.0 |
Breaking changes, such as removing legacy embedded key fallback. |
| Phase | Action |
|---|---|
| Phase 1 | Publish migration-compatible DreamConsistency.Crypto 1.0.0. |
| Phase 2 | Keep existing static API: RootKeyProvider.ProvideRootKey(...). |
| Phase 3 | Add runtime secrets to local development, DEV servers, QA servers, and PROD servers. |
| Phase 4 | Deploy services gradually. Services with runtime secrets use the new path. |
| Phase 5 | Disable legacy embedded fallback after all services have runtime secrets. |
| Phase 6 | Remove legacy fallback in a future major release, for example 2.0.0. |
| Risk / Note | Decision |
|---|---|
| Hardcoded secrets | Do not add real secrets to the package. Use runtime configuration instead. |
| Breaking old projects | Keep the static RootKeyProvider API during the migration period. |
| Key rotation | Plan separate DEV and PROD key rotation. Do not reuse production keys locally. |
| ServiceAuth dependency | DreamConsistency.Security.ServiceAuth can depend on this package for HMAC and hashing helpers. |
| Scope creep | Do not turn this package into an authentication or authorization framework. |
Detailed developer documentation should be maintained in the repository README.md.
This Wiki page is the central operational reference for package ownership, boundaries,
release flow, migration rules, and security decisions.
| Date | Change | Author |
|---|---|---|
| 2026-07-06 | Initial documentation page created for DreamConsistency.Crypto. |
Branko |
| 2026-07-06 | Migration-compatible root key provider approach documented. | Branko |