rsa-public-key-verification
table-of-contents
- introduction
- project-structure
- core-components
- architecture-overview
- detailed-component-analysis
- dependency-analysis
- performance-considerations
- troubleshooting-guide
- conclusion
- appendix-best-practices-and-example-paths
introduction
this document is for security engineers and backend developers, systematically explaining the implementation principles, interface design, middleware integration methods, and security best practices of the rsa public key verification system in this repository. key coverage includes:
- rsa digital signature verification process and pss algorithm usage
- public-private key pair generation and management (including pem/ssh public key parsing)
- timestamp and nonce (random number) replay prevention mechanism
- middleware integration and signature verification failure handling
- key rotation strategy and certificate chain verification extension suggestions
- security best practices (key storage, integrity verification, replay protection)
project-structure
core modules related to rsa verification are distributed as follows:
- authentication-and-interface-layer:-defines-interfaces-and-configurations,-error-constants,-token-generation,-etc
- middleware-layer:-http-layer-rsa-verification-middleware,-responsible-for-request-header-parsing,-signature-verification,-replay-prevention-and-caching
- in-memory-implementation:-nonce-storage,-public-key-provider,-signature-cache-in-memory-implementations
- bootstrap-and-assembly:-application-startup,-middleware-registration-and-named-middleware-management
- interfaces-and-configuration
- noncestore:-random-number-storage-and-existence-check,-used-for-replay-prevention
- publickeyprovider:-provides-rsa-public-key-by-client-id
- signaturecache:-caches-signature-verification-results,-improves-performance
- rsaauthconfig:-authentication-configuration-(request-header-key-names,-time-window,-component-instances)
- in-memory-implementation
- memorynoncestore:-memory-based-random-number-storage-with-expiration-cleanup
- memorypublickeyprovider:-memory-public-key-mapping,-supports-concurrent-read-write
- memorysignaturecache:-memory-signature-cache-with-expiration-cleanup
- middleware
- rsaclientauthmiddleware/configurablersaclientauthmiddleware:-http-middleware,-completes-header-parsing,-timestamp-validation,-nonce-validation,-signature-verification,-caching-and-context-injection
- newrsaclientauthmiddleware/newconfigurablersaclientauthmiddlewarefrompem:-convenient-factories,-support-pem/ssh-public-key-parsing
- error-constants:-unified-authentication-error-types
- token-generation-(complementary-to-rsa-verification):-jwt-token-generation-and-refresh
the-following-diagram-shows-the-complete-process-from-http-request-entry,-to-middleware-executing-rsa-verification,-caching-and-replay-prevention,-to-subsequent-handlers.
interfaces-and-configuration-(pkg/auth/rsa.go)
- noncestore:-provides-set/exists,-used-to-record-random-numbers-and-their-expiration-times,-preventing-replay
- publickeyprovider:-returns-corresponding-rsa-public-key-according-to-clientid
- signaturecache:-provides-get/set,-caches-verification-results,-reduces-repeated-calculations
- rsaauthconfig:-centralized-configuration-of-request-header-key-names,-time-window,-component-instances;-provides-default-configuration
- memorynoncestore
- data-structure:-map[string]time.time
- concurrency-control:-rwmutex
- cleanup-strategy:-timer-scans-and-deletes-expired-items-every-10-minutes
- memorypublickeyprovider
- data-structure:-map[string]*rsa.publickey
- concurrency-control:-rwmutex
- dynamic-addition:-addpublickey-supports-runtime-addition-of-client-public-keys
- memorysignaturecache
- data-structure:-map[string]cacheentry(valid,-expiration)
- concurrency-control:-rwmutex
- cleanup-strategy:-timer-scans-and-deletes-expired-items-every-10-minutes
- key-functional-points
- header-parsing:-x-client-id,-x-client-signature,-x-nonce,-x-timestamp
- cache-acceleration:-query-cache-using-"clientid:signature:nonce:timestamp"-as-key
- timestamp-validation:-parse-to-unix-seconds,-difference-from-current-time-not-exceeding-timewindow
- nonce-validation:-check-if-exists-and-not-expired,-avoid-replay
- public-key-retrieval:-through-publickeyprovider.getpublickey(clientid)
- data-construction:-clientid-+-nonce-+-timestamp-+-request-body
- signature-decoding-and-verification:-base64->-sha256->-rsa-pss-verify
- after-success-write-random-number-and-cache,-failure-returns-corresponding-error
- public-key-parsing
- supports-pem-(pkix),-ssh-public-key-parsing,-compatible-with-multiple-formats
- factory-functions
- rsaclientauthmiddleware/newrsaclientauthmiddleware:-directly-pass-public-key-mapping-or-pem-string-mapping
- configurablersaclientauthmiddleware/newconfigurablersaclientauthmiddlewarefrompem:-supports-custom-configuration
-
error-types
- unauthorized-client,-missing-authentication-info,-invalid-signature,-invalid-timestamp,-expired-timestamp,-invalid-nonce,-duplicate-request,-failed-to-read-request-body,-request-verification-failed
-
unit-test-coverage
- normal-flow,-missing-headers,-invalid-clientid,-invalid-signature,-expired-timestamp,-configurable-middleware,-replay-attack-(duplicate-request)
-
token-generator-interface-and-implementation:-supports-generating-access/refresh-token-pairs,-supports-refreshing-tokens
-
jwt-claims:-contains-registered-claims-and-business-fields-(userid,-roles)
-
principal-information:-stores-current-user-principal-in-context
-
relationship-with-rsa-verification:-jwt-and-rsa-verification-can-be-used-in-parallel,-responsible-for-different-levels-of-identity-and-integrity-guarantee-respectively
-
authorization:-centrally-manages-token-generator-and-middleware-collection,-supports-named-middleware-registration-and-retrieval
-
app:-application-startup,-http-server,-signal-handling-and-graceful-shutdown,-facilitates-middleware-registration-at-startup-phase
-
middleware-depends-on-interfaces:-through-rsaauthconfig-inject-noncestore,-signaturecache,-publickeyprovider,-achieve-loose-coupling
-
in-memory-implementation-as-default-implementation,-facilitates-rapid-integration-and-testing
-
public-key-parsing-supports-pem/ssh,-enhances-compatibility-with-existing-infrastructure
-
error-constants-centrally-defined,-facilitates-unified-handling-and-logging
-
caching-strategy
- signaturecache:-using-"clientid:signature:nonce:timestamp"-as-key,-after-hit-directly-allow,-significantly-reducing-verification-overhead-for-duplicate-requests
- cleanup-cycle:-scan-once-every-10-minutes,-balancing-memory-usage-and-accuracy
-
concurrent-safety
- three-types-of-in-memory-implementations-all-use-rwmutex,-better-performance-in-read-heavy-write-light-scenarios
-
io-and-hash
- request-body-only-read-once-and-reset,-avoiding-subsequent-handlers-being-unable-to-read
- sha256-hash-and-rsa-pss-verification-are-both-cpu-intensive,-suggest-combining-with-caching-and-rate-limiting-strategies
-
common-errors-and-positioning
- missing-headers:-confirm-if-request-contains-x-client-id,-x-client-signature,-x-nonce,-x-timestamp
- invalid-signature:-check-if-signature-is-base64-encoded,-whether-signature-data-is-consistent-with-construction-rules-(clientid-+-nonce-+-timestamp-+-body)
- timestamp-expired:-confirm-client-time-synchronization,-whether-timewindow-setting-is-reasonable
- duplicate-request:-nonce-already-exists-and-not-expired,-check-if-client-reuses-same-nonce
- client-not-found:-confirm-if-public-key-mapping-contains-this-clientid
-
logs-and-observability
- record-key-steps-in-middleware-(parse-headers,-timestamp-validation,-nonce-validation,-signature-verification,-cache-hit/miss),-facilitates-problem-positioning
-
unit-test-reference
- can-reference-test-cases-to-construct-minimum-reproducible-scenarios,-gradually-eliminate-problems
this-rsa-public-key-verification-system-provides-configurable,-extensible-http-middleware-with-replay-prevention-capability-through-clear-interface-abstraction-and-in-memory-implementation.-its-core-advantages-are:
- clear-responsibility-separation-and-pluggable-design
- complete-replay-prevention-and-caching-mechanism
- good-support-for-multiple-public-key-formats
- seamless-integration-with-application-startup-and-middleware-registration
in-production-environments,-suggest-combining-with-persistent-storage,-key-rotation-and-certificate-chain-verification-extensions-to-further-improve-security-and-maintainability.
appendix-best-practices-and-example-paths
rsa-signature-algorithm-and-key-length
- signature-algorithm:-use-rsa-pss-(pss-mode-has-stronger-security)
- hash-algorithm:-sha-256
- key-length:-suggest-using-2048-bits-and-above;-if-pursuing-higher-security-level,-can-adopt-3072-or-4096-bits
- selection-basis:-balance-between-performance-and-security;-2048-bits-is-sufficiently-secure-and-performs-well-in-most-scenarios
example-paths
- signature-and-verification-process-reference:-rsa_perm.go
- default-time-window-and-header-key-names-reference:-rsa.go
public-private-key-pair-generation-and-management
- generation:-use-standard-library-or-tools-to-generate-rsa-private-key-and-public-key
- distribution:-distribute-public-key-to-clients;-store-private-key-securely-in-controlled-environment
- update:-dynamically-add-new-public-keys-through-publickeyprovider's-addpublickey,-achieve-smooth-transition
example-paths
- public-key-provider-interface-and-dynamic-addition:-rsa.go,-rsa_impl.go
certificate-chain-verification-mechanism-(extension-suggestion)
- current-implementation-supports-direct-public-key-verification;-if-certificate-chain-verification-is-needed,-can-encapsulate-certificate-chain-parsing-and-validation-logic-on-top-of-publickeyprovider
- suggest-introducing-certificate-revocation-list-(crl)-or-online-certificate-status-protocol-(ocsp)-to-enhance-certificate-validity-checking
example-paths
- public-key-parsing-compatible-with-pem/ssh:-rsa_perm.go
middleware-integration-and-key-rotation
- integration:-register-middleware-through-authorization,-or-directly-mount-on-routes
- key-rotation:-first-add-new-public-key,-then-gradually-replace-old-public-key,-finally-clean-up-historical-public-keys
example-paths
- middleware-registration-and-named-middleware:-auth.go
- public-key-dynamic-addition:-rsa_impl.go
signature-integrity-check-and-replay-attack-protection
- integrity:-ensure-data-has-not-been-tampered-through-sha256-hash-and-rsa-pss-verification
- replay-protection:-dual-protection-of-nonce-storage-and-timestamp-window
example-paths
- timestamp-and-nonce-validation:-rsa_perm.go
- nonce-storage-and-cleanup:-rsa_impl.go
actual-code-examples-(example-paths)
- verify-client-signature-(middleware-usage):-rsa_perm.go
- handle-signature-verification-failure-(error-return):-rsa_perm.go,-errors.go
- handle-certificate-update-(dynamic-addition-of-public-key):-rsa_impl.go
- multi-level-signature-verification-(extensible-idea):-stack-multi-level-public-key-strategies-on-top-of-publickeyprovider-(such-as-by-tenant/version-dimension)