How pkasila/gorm-crypto works
Main architectural components
• Library Initialization: Core functions (e.g., gormcrypto.Init, gormcrypto.InitWithFallbacks, gormcrypto.InitSigning) that setup the encryption/signing mechanism.
• Encryption Algorithms: Located in the “algorithms” directory, these components include implementations for different encryption strategies (RSA, AES256CBC, AES256GCM).
• Signing Algorithms: Found under the “signing” directory with subcomponents that implement signature generation and verification using ECDSA and Ed25519.
• Helpers: Utility functions for key generation and conversion in the “helpers” directory. They are used by both encryption and signing modules.
• Serialization: In the “serialization” directory, components here (such as JSON serialization) are responsible for converting values to and from a storable format.
• Integration with GORM: The library’s usage examples in the README show how types like EncryptedValue and SignedValue are attached to model definitions (as part of a full-stack application's data layer).
Interactions and relationships
• The Initialization Component communicates with the chosen Encryption algorithm (or a fallback chain) and/or Signing algorithm, while also tying in the Serialization mechanism.
• Encryption algorithms depend on key pairs and configuration provided by the Helpers.
• The Encryption and Signing modules interact with the model layer via custom types (EncryptedValue, SignedValue) which act as data wrappers ensuring encryption/decryption and signing/verification of sensitive data.
• Data flows from the application (e.g., when creating a DB record) into the encryption/signing modules, serializes the data, and then the GORM layer persists it into the database.
Architectural patterns and design principles
• Modularity: The project is clearly divided into modules (algorithms, signing, helpers, serialization) that can be independently developed or swapped (as demonstrated by the fallback mechanism).
• Pluggable Algorithms: The design allows choosing between different encryption algorithms and signing algorithms, emphasizing extensibility.
• Single Responsibility: Each directory/component has a focused responsibility (e.g., helpers for key management, serialization for JSON conversion).
Relevant technologies/frameworks
• Go (language and module system with go.mod and go.sum).
• GORM ORM (the library integrates specifically with GORM as seen in usage examples).
• Cryptographic algorithms: RSA, AES256GCM, AES256CBC for encryption and ECDSA, Ed25519 for signing.
• JSON serialization for data interchange.
• Since it is a library that integrates with GORM in a full-stack application, visually emphasize the separation between the core cryptographic functionality (encryption, signing, serialization) and the data persistence layer (GORM as the database layer).
• Initialization stage as the entry point where the user’s application configures the library by selecting encryption or signing strategies.
• Fallback mechanics as alternative paths, indicating that multiple algorithms can be chained to provide redundancy or graceful key rotation.
Additional detail
• For each encryption/signing method, show how keys are generated/loaded (via the helpers) and then passed to the respective algorithm modules.
• That the Serializer (in this case JSON) is wrapped around both encryption and signing logic to ensure that the types are correctly marshaled/unmarshaled for persistence.