samsungpaycodec

README

Samsung Pay Codec

Go module to decrypt Samsung Pay tokens as received from the SDK.

[!NOTE]
This is not an official Samsung project.

Although the code is tested with decent coverage, the project is provided without guarantees. It has not been production-battled and only been used for illustration. Feedback is needed.

The module contains 2 main interfaces:

• KeyProvider: returns the private key when given the key ID. The module contains 2 implementations of this interface:

  • Filesystem key provider: which reads the PKCS8 PEM files from the specified root directory

  • Static key provider: which takes a list of keys in the constructor

• Decryptor: decrypts the payload using the key it receives from the key provider. The module contains only the JWE decryptor using RSA keys.

Mechanism

The merchant or their respective PSP (payment service provider) must first generate key pair and a CSR (certificate signing request) with the key. They, then, create a Service on the Samsung Pay Developers portal and upload the CSR generated earlier. During a transaction, Samsung Pay server generates a short-lived TLS certificate using the CSR and signs it with Samsung private key. The signed certificate is then sent to the device to encrypt the token using the embedded public key (after validating the certificate chain, but this is done by on-device Samsung Pay facilities for you). The encrypted token is then given to the merchant/PSP (service ID owner). The service ID owner is expected to decrypt the token using the private key of the CSR.

In-App Payments Verification

How does Samsung Pay know the app requesting payments is not spoofed?

When the in-app service profile is created on the Samsung Pay Developers portal, the developer receives a service ID which they ought to use with the Samsung Pay SDK when requesting the payment. What if the service ID falls into the hands of fraudsters or hackers?

The service ID is not a secret. It is an identifier. When creating the service profile, the developer enters the application/package ID and is instructed to upload the production APK of their app. When the merchant app interacts with the Samsung Pay SDK, Samsung Wallet app checks the caller app package ID and verifies its signature matches the signature of the APK uploaded by the developer on the portal. Therefore, a rogue app that is side-loaded on the phone cannot pass the verification checks of the Samsung Wallet. The mechanism proves to Samsung Pay the caller app has access to the Samsung Pay Developer portal and to have access to the signed APK of the merchant.

Web Checkout Verification

How does Samsung Pay know the website requesting payments is not spoofed? What if a rogue network admin deploys a DNS server within the network that serves a phishing site on the payment page known to host Samsung Pay payment flow?

When creating the service profile, the developer enters the authorized service domain names (FQDN) that will host the Samsung Pay JS SDK. When loaded the SDK checks the page is hosted on HTTPS and that the host name is configured by the developers as an authorized domain name for Samsung Pay operations. This proves to Samsung Pay that the site developer has control over the DNS and the service profile access.

Documentation

Index

• func GetMockAmex(key *rsa.PrivateKey, amount, currency string) (jwe string, plaintext []byte)
• func GetMockAmexWithPublicKey(key *rsa.PublicKey, amount, currency string) (jwe string, plaintext []byte)
• func GetMockMastercard(key *rsa.PrivateKey, amount, currency string) (jwe string, plaintext []byte)
• func GetMockMastercardWithPublicKey(key *rsa.PublicKey, amount, currency string) (jwe string, plaintext []byte)
• func GetMockVisa(key *rsa.PrivateKey, amount, currency string) (jwe string, plaintext []byte)
• func GetMockVisaWithPublicKey(key *rsa.PublicKey, amount, currency string) (jwe string, plaintext []byte)
• func Kid(key PrivateKey) string
• func KidFromPublic(key crypto.PublicKey) string
• type Decryptor
  • func NewJWEDecryptor(version string, provider KeyProvider) (Decryptor, error)
• type KeyAdder
• type KeyProvider
  • func NewFilesystemKeyProvider(root string) (KeyProvider, error)
  • func NewMemoryKeyProvider(keys ...PrivateKey) KeyProvider
• type PrivateKey

Functions

func GetMockAmex

func GetMockAmex(key *rsa.PrivateKey, amount, currency string) (jwe string, plaintext []byte)

Produces a JWE and plaintext of an American Express test DPAN. Uses the test card listed on MPGS documentation: https://ap-gateway.mastercard.com/api/documentation/integrationGuidelines/supportedFeatures/pickPaymentMethod/devicePayments/SamsungPay.html?locale=en_US

func GetMockAmexWithPublicKey

func GetMockAmexWithPublicKey(key *rsa.PublicKey, amount, currency string) (jwe string, plaintext []byte)

Produces a JWE and plaintext of an American Express test DPAN. Uses the test card listed on MPGS documentation: https://ap-gateway.mastercard.com/api/documentation/integrationGuidelines/supportedFeatures/pickPaymentMethod/devicePayments/SamsungPay.html?locale=en_US

func GetMockMastercard

func GetMockMastercard(key *rsa.PrivateKey, amount, currency string) (jwe string, plaintext []byte)

Produces a JWE and plaintext of a Mastercard test DPAN. Uses the test card listed on MPGS documentation: https://ap-gateway.mastercard.com/api/documentation/integrationGuidelines/supportedFeatures/pickPaymentMethod/devicePayments/SamsungPay.html?locale=en_US

func GetMockMastercardWithPublicKey

func GetMockMastercardWithPublicKey(key *rsa.PublicKey, amount, currency string) (jwe string, plaintext []byte)

Produces a JWE and plaintext of a Mastercard test DPAN. Uses the test card listed on MPGS documentation: https://ap-gateway.mastercard.com/api/documentation/integrationGuidelines/supportedFeatures/pickPaymentMethod/devicePayments/SamsungPay.html?locale=en_US

func GetMockVisa

func GetMockVisa(key *rsa.PrivateKey, amount, currency string) (jwe string, plaintext []byte)

Produces a JWE and plaintext of a Visa test DPAN. Uses the test card listed on MPGS documentation: https://ap-gateway.mastercard.com/api/documentation/integrationGuidelines/supportedFeatures/pickPaymentMethod/devicePayments/SamsungPay.html?locale=en_US

func GetMockVisaWithPublicKey

func GetMockVisaWithPublicKey(key *rsa.PublicKey, amount, currency string) (jwe string, plaintext []byte)

Produces a JWE and plaintext of a Visa test DPAN. Uses the test card listed on MPGS documentation: https://ap-gateway.mastercard.com/api/documentation/integrationGuidelines/supportedFeatures/pickPaymentMethod/devicePayments/SamsungPay.html?locale=en_US

func Kid

func Kid(key PrivateKey) string

Kid calculates the Kid of the private key as the base64 of the SHA-256 of the public key component

func KidFromPublic

func KidFromPublic(key crypto.PublicKey) string

KidFromPublic is the base64 of the SHA-256 of the public key

Types

type Decryptor

type Decryptor interface {
	Decrypt3DSData(payload []byte) (plain []byte, err error)
}

func NewJWEDecryptor

func NewJWEDecryptor(version string, provider KeyProvider) (Decryptor, error)

A factory function to produce JWE decryptors compliant to the stated version spec and using `provider` for key retrieval

type KeyAdder

type KeyAdder interface {
	AddKey(PrivateKey) error
}

KeyAdder is a helper interface to signal the provider's ability to add keys.

type KeyProvider

type KeyProvider interface {
	GetKey(kid string) PrivateKey
}

KeyProvider is a generic interface for an implementation fetching the private key from backing storage given `kid`.

func NewFilesystemKeyProvider

func NewFilesystemKeyProvider(root string) (KeyProvider, error)

Expects a directory path containing private keys formatted as PKCS8 PEM

func NewMemoryKeyProvider

func NewMemoryKeyProvider(keys ...PrivateKey) KeyProvider

The static key provider is an in-memory key provider

type PrivateKey

type PrivateKey interface {
	Public() crypto.PublicKey
	Equal(x crypto.PrivateKey) bool
}

Per: https://pkg.go.dev/crypto#PrivateKey