Skip to content

USBank

USBank is a static VB module implementing the US Bank ePay admin single-sign-on (SSO) cryptographic handshake. It orchestrates hybrid AES/RSA encryption and RSA digital signing of a session-transfer payload using X.509 certificates resolved from the local machine's Windows certificate store. Certificate distinguished names are composed at runtime from configuration-supplied parameters, enabling per-environment certificate selection without code changes. See BR-003.

Purpose

  • Orchestrate the US Bank ePay SSO cryptographic handshake (GetSSOData): AES-encrypt the payload, RSA-wrap the symmetric key, and RSA-sign the ciphertext.
  • Resolve X.509 certificate distinguished names from configuration-driven key/value pairs.
  • Load X.509 certificates from the local machine Windows certificate store by distinguished name.
  • Provide Base64 conversion for byte arrays (ToBase64 extension).

Context

  • Namespace: SAIF.Services.WebServices.Epay
  • Assembly/package: SAIF.Services.WebServices.Epay (SAIF.BOF.Services.WebServices.Epay.nupkg)
  • Type kind: VB Module — equivalent to a static, non-inheritable class with no instance state.
  • Source: Services\SAIF.Services.WebServices.Epay\WebService\USBank.vb

Public members

Member Signature Purpose
GetSSOData Public Function GetSSOData(sessionTransferData As String) As AdminSingleSignOnData Orchestrates the full SSO encryption/signing handshake: AES-encrypts the payload, RSA-wraps the AES key with the US Bank certificate, RSA-signs the ciphertext with the SAIF admin certificate, and returns an AdminSingleSignOnData DTO. Throws ApplicationException("USBank Cert not found.") or ApplicationException("SAIF cert not found.") if either required certificate is not found. See BR-001.
GetSAIFCertDistinguishedName Public Function GetSAIFCertDistinguishedName() As String Returns the distinguished name (DN) for the SAIF (non-admin) authentication certificate, built from the usBankEPayAuthenticationCertDN configuration setting via GetCertificateParameters. See BR-003.
LoadSAIFCert Friend Function LoadSAIFCert(Optional validOnly As Boolean = False) As X509Certificate2 Assembly-internal. Loads the SAIF authentication certificate from LocalMachine\My by the DN returned by GetSAIFCertDistinguishedName. Returns Nothing if the certificate is not found. Not called by GetSSOData in the current code.**
ToBase64 Friend Function ToBase64(bytes As Byte()) As String Assembly-internal extension method on Byte(). Converts a byte array to a Base64-encoded string; returns an empty string ("") when bytes is Nothing.

Behavioral notes

  • GetSSOData enforces BR-001: it throws ApplicationException("USBank Cert not found.") if the US Bank SSO certificate cannot be resolved from LocalMachine\Root, and ApplicationException("SAIF cert not found.") if the SAIF admin authentication certificate cannot be resolved from LocalMachine\My.
  • Certificate DN composition enforces BR-003: all three certificate lookups resolve DNs through the private helper GetCertificateParameters, which calls AppGlobal.EnvironmentService.GetConfigSetting and JSON-deserializes the result using System.Web.Script.Serialization.JavaScriptSerializer.*
  • GetSSOData discards the raw AES symmetric key from memory immediately after RSA-wrapping it (symmetricKey = Nothing), limiting in-memory exposure of cleartext key material. See BR-002.
  • SAIF.Framework.Security.Cryptography (SAIFCrypto) and AppGlobal.EnvironmentService are not defined in this library's source; their full internals are not documented here.**
  • Private helpers (LoadUSBankCert, GetSAIFAdminCertDistinguishedName, LoadSaifAdminCert, GetCertificateParameters) are not part of the public or Friend surface; they are documented here only to support understanding of GetSSOData behavior.

Constraints and usage notes

  • This is a VB Module — it has no instance state and cannot be instantiated or inherited.
  • Callers must ensure all three certificate-DN configuration keys (usBankEPaySSOCertDN, usBankEPayAuthenticationCertDN, usBankEPayAuthenticationAdminCertDN) are present in the environment configuration store and contain valid JSON-encoded DN dictionaries; a missing or malformed key causes JavaScriptSerializer.Deserialize to throw before certificate lookup occurs.
  • The required certificates must be pre-deployed to the local machine's Windows certificate store (LocalMachine\Root for the US Bank cert, LocalMachine\My for SAIF certs) before GetSSOData is called.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

  • Services\SAIF.Services.WebServices.Epay\WebService\USBank.vb