API Developer Portal

Chiffrement de la charge utile

Pour des raisons de sécurité, toutes les demandes envoyées à nos interfaces API de paiement et toutes les réponses provenant de celles-ci, ainsi que les champs partagés via notre interface API de validation de compte, doivent être chiffrées. Nous prenons en charge le chiffrement d'enveloppe avec AES-256-GCM. Cette page explique le processus.

Endpoints Summary

post

/issued-device-administration/client-data-encryption-key/get

Étape 1 : Obtenir la clé publique

La première étape du processus de chiffrement consiste à nous demander une clé publique et son numéro de clé. Vous devez ensuite stocker ces informations en toute sécurité et surveiller la date d'expiration de la clé. Les clés publiques expirent au bout de 120 jours.

Voici quelques points à prendre en compte lors de l'envoi de votre requête :

En-têtes obligatoires

a) x-api-key – Utilisez la clé API que nous vous avons fournie par courriel pour l'environnement concerné.
b) x-fapi-financial-id – Ceci est l'identifiant unique de BMO. Il doit toujours être 001.
c) x-request-id – Ceci est l'identifiant unique de votre demande.
d) x-app-cat-id – En vous référant au tableau ci-dessous, utilisez la valeur correspondant à l'interface API de paiement que vous utilisez. Si vous avez l'intention d'utiliser plusieurs interfaces API de paiement, veuillez choisir uniquement l'une des valeurs applicables.

Api	x-app-cat-id
Paiements ACH	80613
Service de virement automatisé (SVA)	87335
Virements télégraphiques	87102
Paiements instantanés	87679

Paramètres du corps de texte

a) applicationCatalogueId – Utilisez la même valeur que celle que vous avez choisie pour l'en-tête x-app-cat-id ci-dessus.
b) Key alias – Respectez le format alias/EXT-ENC-{API KEY} en utilisant la clé API correspondant à l'environnement concerné.

Post

/issued-device-administration/client-data-encryption-key/get

Essayez-le

Request

Code Samples

Headers

Content-Type

string

Example

application/json

x-fapi-financial-id required

string

x-fapi-customer-last-logged-time

string

x-fapi-customer-ip-address

string

x-fapi-customer-user-agent

string

x-fapi-interaction-id

string

x-client-id

string

Authorization

string

x-request-id required

string

x-api-key

string

x-app-cat-id required

string

Body

body required

Request Body

Response

Table JSON

RetrieveClientKeyResponse { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

Étape 2 : Générer la clé de chiffrement du contenu (CEK)

Il est maintenant temps de créer une clé de chiffrement de contenu (CEK) symétrique de 32 octets et de la stocker en toute sécurité.

Étape 3 : Générer le vecteur d'initialisation (IV)

Créez un vecteur d'initialisation (IV) de 12 octets. Vous pouvez ensuite y ajouter des « données d'authentification supplémentaires » (AAD). Les AAD sont facultatives dans nos environnements et peuvent prendre la forme de n'importe quelle chaîne de caractères fixe.

Étape 4 : Chiffrer votre message

Maintenant que votre CEK et votre IV sont prêts, chiffrons votre charge utile :

Assurez-vous que le message d'entrée que vous souhaitez chiffrer est au format chaîne/texte.
- JSON object should be in JSON string.
- Default encoding should be UTF-8.
Comme algorithme de chiffrement symétrique CEK, sélectionnez AES-256-GCM.
Appliquez l'algorithme de chiffrement, la clé CEK et l'IV au message d'entrée pour générer le tampon du message chiffré.
Appliquez le codage Base64 au tampon de message chiffré pour générer un texte chiffré au format chaîne/texte.
Étape 5: Appliquez le codage Base64 à l'AuthTag.
Ajoutez la charge utile chiffrée et encodée en Base64 ainsi que l'AuthTag encodé en Base64 en utilisant le caractère « | » comme délimiteur (Base64{EncryptedPayload} + « | » + Base64{AuthTag}), puis incluez le tout dans la section « data » de la charge utile de votre requête.

Étape 5 : Générer l'en-tête x-crypto-key

Avant de pouvoir partager votre charge utile chiffrée, vous devez générer votre en-tête x-crypto-key. L'en-tête comprendra jusqu'à 5 parties pour AES-256-GCM, toutes concaténées pour former l'en-tête final. Une fois généré, vous transmettrez ensuite la clé x-crypto-key dans l'en-tête de vos demandes API avec la charge utile chiffrée.

Pour la partie 1, appliquez le codage Base64 au numéro de clé de la clé publique que vous avez récupérée auprès de nous précédemment.
Pour la partie 2, chiffrez la clé CEK que vous avez générée précédemment à l'aide de la clé publique. Assurez-vous que le remplissage est défini sur RSA_PKCS1_OAEP_PADDING (AES-256-GCM). Appliquez ensuite le codage Base64 à la clé CEK chiffrée. Nous prenons en charge les algorithmes SHA-1 et SHA-256 pour le hachage OAEP.
Pour la partie 3, hachez votre CEK à l'aide de l'algorithme SHA-256. Appliquez ensuite un encodage Base64 au CEK haché.
Pour la partie 4, ajoutez l'IV que vous avez généré précédemment ainsi que l'AAD facultatif. Appliquez ensuite l'encodage Base64.
Pour la partie 5, identifiez le mode de remplissage utilisé dans le chiffrement de l'enveloppe du CEK. Cette partie est facultative.
Pour l'en-tête x-crypto-key final, concaténez toutes les parties en utilisant « . » (point simple) comme délimiteur.
- a. Exemple de format final si le hachage OAEP (hachage par défaut ou SHA-1) est utilisé pour chiffrer le CEK: Base64(keyid).Base64(encrypted CEK).base64(hashed CEK).Base64(IV).GCM
- b. Exemple de format final si le hachage OAEP SHA-256 est utilisé pour chiffrer le CEK: Base64(keyid).Base64(encrypted CEK).base64(hashed CEK).Base64(IV).GCM-256

Étape 6: Déchiffrer votre réponse

Enfin, il est temps de déchiffrer notre réponse API. Voici comment procéder :

Nous chiffrons le contenu de la réponse à l'aide de l'algorithme AES‑256‑GCM en utilisant la même clé de chiffrement du contenu (CEK) et le même vecteur d'initialisation (IV) que ceux que vous avez utilisés pour chiffrer votre requête initiale.
Vous trouverez la réponse chiffrée dans l'élément « data ». La valeur se compose de 2 éléments encodés en Base64, séparés par un délimiteur « | ».
- Texte chiffré (Ciphertext)
- AuthTag
Séparez la valeur au niveau du délimiteur « | » pour obtenir le texte chiffré (Ciphertext) et l'AuthTag.
Déchiffrez le texte chiffré (Ciphertext) à l'aide de l'algorithme AES-GCM en fournissant:
- Clé CEK initiale
- IV initiale
- AuthTag extrait
- Données d'authentification associées (AAD) facultatives, si le protocole l'exige