Écrire le code de la fonction de CloudFront connexion pour la validation mutuelle du protocole TLS (afficheur)

CloudFront Les fonctions de connexion vous permettent d'écrire des JavaScript fonctions légères pour la validation des certificats mTLS et une logique d'authentification personnalisée. Le code de votre fonction de connexion peut valider les certificats clients, implémenter des règles d'authentification spécifiques à l'appareil, gérer des scénarios de révocation de certificats et prendre des allow/deny décisions concernant les connexions TLS sur des sites périphériques du monde entier. CloudFront

Les fonctions de connexion constituent un moyen puissant d'étendre CloudFront la validation intégrée des certificats à votre propre logique métier. Contrairement aux fonctions de demande et de réponse du visualiseur qui traitent les données HTTP, les fonctions de connexion fonctionnent au niveau de la couche TLS et ont accès aux informations de certificat, aux adresses IP des clients et aux détails de connexion TLS. Ils sont donc idéaux pour mettre en œuvre des modèles de sécurité zéro confiance, des systèmes d'authentification des appareils et des politiques de validation de certificats personnalisées qui vont au-delà de la validation PKI standard.

Le code de votre fonction de connexion s'exécute dans un environnement isolé et sécurisé avec des temps de démarrage inférieurs à la milliseconde et peut évoluer pour gérer des millions de connexions par seconde. Le runtime est optimisé pour les charges de travail de validation des certificats et fournit une intégration intégrée aux opérations de recherche de données en temps réel, permettant des scénarios d'authentification sophistiqués tels que la vérification de la liste de révocation des certificats et la validation de la liste d'autorisation des appareils. CloudFront KeyValueStore

Pour vous aider à écrire un code de fonction de connexion efficace, consultez les rubriques suivantes. Pour des exemples de code complets et des didacticiels étape par étape, consultez les sections didacticielles de ce guide et explorez les exemples de fonctions de connexion disponibles dans la CloudFront console.

CloudFront Cas d'utilisation et objectifs de la fonction de connexion

Avant d'écrire votre fonction de CloudFront connexion, déterminez soigneusement le type de logique de validation de certificat ou d'authentification que vous devez implémenter. Les fonctions de connexion sont conçues pour des cas d'utilisation spécifiques qui nécessitent une validation personnalisée allant au-delà de la vérification standard des certificats PKI. Comprendre votre cas d'utilisation vous permet de concevoir un code efficace qui répond à vos exigences de sécurité tout en maintenant des performances optimales.

Les cas d'utilisation courants de la fonction de connexion incluent :

• Gestion des révocations de certificats  : mettez en œuvre des politiques personnalisées pour gérer les certificats révoqués, notamment des délais de grâce pour la rotation des certificats, des exceptions réseau fiables pour les périphériques internes ou des scénarios d'accès d'urgence dans lesquels les certificats révoqués peuvent nécessiter un accès temporaire.

• Support mTLS en option  : gérez à la fois les connexions mTLS et non MTLS avec différentes politiques d'authentification, ce qui vous permet de renforcer la sécurité des clients qui prennent en charge les certificats tout en maintenant la compatibilité avec les clients existants.

• IP-based authentification  : associez la validation des certificats à la vérification des adresses IP des clients pour renforcer la sécurité, par exemple en restreignant l'accès depuis des régions géographiques spécifiques, des réseaux d'entreprise ou des plages d'adresses IP malveillantes connues.

• Multi-tenant validation des certificats  : implémentez des règles de validation spécifiques au locataire dans lesquelles différentes autorités de certification ou différents critères de validation s'appliquent en fonction des attributs de l'émetteur du certificat client ou du sujet.

• Time-based contrôle d'accès  : appliquez des restrictions temporelles selon lesquelles les certificats ne sont valides que pendant des heures, des périodes de maintenance ou des périodes ouvrables spécifiques, même si le certificat lui-même n'a pas expiré.

Les fonctions de connexion s' CloudFront exécutent après avoir effectué la validation standard des certificats (vérification de la chaîne de confiance, contrôles d'expiration et validation de signature) mais avant l'établissement de la connexion TLS. Ce calendrier vous donne la possibilité d'ajouter des critères de validation personnalisés tout en bénéficiant CloudFront de la validation des certificats intégrée. Votre fonction reçoit les résultats de la validation standard et peut prendre des décisions éclairées quant à l'autorisation ou au refus de la connexion sur la base de critères standard et personnalisés.

Lors de la conception de votre fonction de connexion, tenez compte des implications de votre logique de validation en termes de performances. Les fonctions ayant une limite d'exécution de 5 millisecondes, les opérations complexes doivent être optimisées en termes de vitesse. Utilisez-le KeyValueStore pour des recherches de données rapides plutôt que pour des calculs complexes, et structurez votre logique de validation pour qu'elle échoue rapidement en cas de certificats non valides.

CloudFront Structure des événements et format de réponse de la fonction de connexion

CloudFront Les fonctions de connexion reçoivent une structure d'événements différente de celle des fonctions de demande et de réponse des spectateurs. Au lieu des request/response données HTTP, les fonctions de connexion reçoivent des informations de certificat et de connexion que vous pouvez utiliser pour prendre des décisions d'authentification.

Rubriques

• Structure des événements pour Connection Functions

• Format de réponse des fonctions de connexion

Structure des événements pour Connection Functions

Les fonctions de connexion reçoivent un objet d'événement contenant des informations de certificat et de connexion. La structure des événements de la fonction est illustrée ci-dessous :

{
  "clientCertificate": {
    "certificates": {
      "leaf": {
        "serialNumber": "string",
        "issuer": "string",
        "subject": "string",
        "validity": {
          "notBefore": "string",
          "notAfter": "string"
        },
        "sha256Fingerprint": "string",
        "ocspEndpoint": "string",
        "san": "string",
        "spki": "string",
        "sanHex": "string"
      },
      "intermediates": [
        {
          "serialNumber": "string",
          "issuer": "string",
          "subject": "string",
          "validity": {
            "notBefore": "string",
            "notAfter": "string"
          },
          "sha256Fingerprint": "string",
          "ocspEndpoint": "string",
          "san": "string",
          "spki": "string",
          "sanHex": "string"
        }
      ]
    }
  },
  "clientIp": "string",
  "endpoint": "string",
  "distributionId": "string",
  "connectionId": "string"
}

Vous trouverez ci-dessous un exemple de structure d'objet d'événement :

{
  "clientCertificate": {
    "certificates": {
      "leaf": {
        "serialNumber": "00:9e:2a:af:16:56:e5:47:25:7d:2e:38:c3:f9:9d:57:fa",
        "issuer": "C=US, O=Ram, OU=Edge, ST=WA, CN=mTLS-CA, L=Snoqualmie",
        "subject": "C=US, O=Ram, OU=Edge, ST=WA, CN=mTLS-CA, L=Snoqualmie",
        "validity": {
          "notBefore": "2025-09-10T23:43:10Z",
          "notAfter": "2055-09-11T00:43:02Z"
        },
        "sha256Fingerprint": "_w6bJ7aOAlGOj7NUhJxTfsfee-ONg_xop3_PTgTJpqs=",
        "ocspEndpoint": "http://ocsp.example.com",
        "san": "DNS:api.example.com,DNS:www.example.com,URI:urn:example:client:123,IP Address:192.168.1.100,email:[e-mail]",
        "spki": "30820122300d06092a864886f70d01010105000382010f003082010a0282010100b8efe87db798500320936...",
        "sanHex": "3058820f6170692e6578616d706c652e636f6d820f7777772e6578616d706c652e636f6d8619..."
      },
      "intermediates": [
        {
          "serialNumber": "00:d4:04:a5:fd:cb:20:37:54",
          "issuer": "C=US, O=Example Corp, CN=Example Root CA",
          "subject": "C=US, O=Example Corp, CN=Example Intermediate CA",
          "validity": {
            "notBefore": "2024-01-01T00:00:00Z",
            "notAfter": "2034-01-01T23:59:59Z"
          },
          "sha256Fingerprint": "3a8c6b...",
          "ocspEndpoint": "http://ocsp.example.com/intermediate",
          "san": "DNS:ca.example.com,URI:urn:ca:intermediate:001",
          "spki": "30820122300d06092a864886f70d01010105000382010f003082010a0282010100b389dd513b0f1f14cac1...",
          "sanHex": "302b820e63612e6578616d706c652e636f6d..."
        }
      ]
    }
  },
  "clientIp": "192.0.2.1",
  "endpoint": "d3lch071jze0cb.cloudfront.net",
  "distributionId": "E1NXS4MQZH501R",
  "connectionId": "NpvTe1925xfj24a67sPQr7ae42BIq03FGhJJKfrQYWZcWZFp96SIIg=="
}

Format de réponse des fonctions de connexion

Votre fonction de connexion doit renvoyer un objet de réponse indiquant s'il faut autoriser ou refuser la connexion. Utilisez les méthodes d'assistance pour prendre des décisions de connexion :

function connectionHandler(connection) {
    // Helper methods to allow or deny connections
    if (/* some logic to determine if function should allow connection */) {
        connection.allow();
    } else {
        connection.deny();
    }
}

Contrairement aux fonctions de demande et de réponse du visualiseur, les fonctions de connexion ne peuvent pas modifier les requêtes ou les réponses HTTP. Ils peuvent uniquement autoriser ou refuser la connexion TLS.

CloudFront Fonctionnalités d' JavaScript exécution de Connection Functions

CloudFront Connection Functions utilise le JavaScript runtime CloudFront Functions 2.0, qui fournit un environnement sécurisé et performant spécialement optimisé pour les charges de travail de validation des certificats. Le runtime est conçu pour démarrer en moins de millisecondes et gérer des millions d'exécutions simultanées sur le réseau périphérique CloudFront mondial.

L'environnement d'exécution inclut une prise en charge JavaScript linguistique complète :

• Prise en charge d'ECMAScript 2020 (ES11)  : JavaScript fonctionnalités modernes, notamment le chaînage optionnel (?.) et fusion nulle (? ?)

• Built-in objets  : JavaScript objets standard tels que Object, Array, JSON, Math et Date

• Journalisation de la console  : utilisez console.log () pour déboguer et surveiller les décisions de validation des certificats. Les journaux sont disponibles en temps réel pendant les tests et peuvent aider à résoudre les problèmes liés à la logique de validation en cours de développement

• KeyValueStore intégration  : accès natif CloudFront KeyValueStore pour des opérations de recherche de données ultrarapides, permettant la vérification de la révocation des certificats en temps réel, la validation de la liste d'autorisation des appareils et la récupération de la configuration spécifique au locataire

Les fonctions de connexion sont optimisées pour des performances élevées pour les scénarios de validation de certificats. Le moteur d'exécution gère automatiquement la gestion de la mémoire, le ramassage des déchets et le nettoyage des ressources afin de garantir des performances constantes sur des millions de connexions simultanées. Toutes les opérations sont conçues pour être déterministes et rapides, les recherches se terminant généralement KeyValueStore en quelques microsecondes.

L'environnement d'exécution est complètement isolé entre les exécutions de fonctions, ce qui garantit l'absence de fuite de données entre les différentes connexions client. Chaque exécution de fonction commence par un état propre et n'a aucun accès aux résultats d'exécution précédents ni aux données client provenant d'autres connexions.

CloudFront Méthodes d'assistance et API de la fonction de connexion

CloudFront Les fonctions de connexion fournissent des méthodes d'assistance spécialisées conçues pour simplifier les décisions relatives à la validation des certificats et améliorer l'observabilité. Ces méthodes sont optimisées pour le flux de travail de validation des connexions et s'intègrent parfaitement aux systèmes d'enregistrement et CloudFront de surveillance des connexions de l'entreprise.

• connection.allow () — Autorise la connexion TLS à se poursuivre. Cette méthode indique CloudFront de terminer l'établissement de la liaison TLS et de permettre au client d'établir la connexion. Utilisez-le lorsque la validation du certificat est réussie et que toute logique d'authentification personnalisée est satisfaite

• connection.deny () — Refuse la connexion TLS et met fin à la poignée de main. Cette méthode ferme immédiatement la connexion et empêche tout trafic HTTP de circuler. Le client recevra une erreur de connexion TLS. Utilisez-le pour les certificats non valides, les échecs d'authentification ou les violations des politiques

• connection.log CustomData () — Ajoutez des données personnalisées aux journaux de connexion (jusqu'à 800 octets de UTF-8 texte). Cette méthode vous permet d'inclure les résultats de validation, les détails du certificat ou la justification de la décision dans les journaux de CloudFront connexion à des fins de surveillance de la sécurité, d'audit de conformité et de dépannage

Ces méthodes fournissent une interface déclarative claire pour prendre des décisions de connexion et enregistrer les informations pertinentes pour la surveillance et le débogage. Le allow/deny modèle garantit que l'intention de votre fonction est claire et CloudFront permet d'optimiser la gestion des connexions en fonction de votre décision. Les données de journalisation personnalisées sont immédiatement disponibles dans les journaux de CloudFront connexion et peuvent être utilisées avec des outils d'analyse des journaux pour la surveillance de la sécurité et des informations opérationnelles.

Appelez toujours connection.allow () ou connection.deny () avant que votre fonction ne soit terminée. Si aucune méthode n'est appelée, la connexion CloudFront sera refusée par défaut par mesure de sécurité.

CloudFront KeyValueStore Intégration de la fonction de connexion

CloudFront Les fonctions de connexion peuvent être utilisées CloudFront KeyValueStore pour effectuer des recherches de données ultrarapides pour des scénarios de validation de certificats. KeyValueStore est particulièrement puissant pour les fonctions de connexion, car il fournit un accès global aux données, éventuellement cohérent, avec des temps de recherche de l'ordre de l'ordre de la microseconde sur tous les CloudFront emplacements périphériques. Il est donc idéal pour gérer les listes de révocation de certificats, les listes d'appareils autorisés, les configurations des locataires et d'autres données de validation qui doivent être accessibles lors des handshakes TLS.

KeyValueStore l'intégration est conçue spécifiquement pour les flux de validation de connexion performants :

• kvs Handle.exists (key) — Vérifie si une clé existe dans le KeyValueStore sans récupérer la valeur. Il s'agit de la méthode la plus efficace pour les scénarios de validation binaire tels que la vérification de la révocation des certificats, dans le cadre de laquelle il vous suffit de savoir si le numéro de série d'un certificat figure dans une liste de révocation.

• kvs Handle.get (key) — Récupère une valeur à partir de KeyValueStore pour des scénarios de validation plus complexes. Utilisez-le lorsque vous devez accéder à des données de configuration, à des règles de validation ou à des métadonnées associées à un certificat ou à un identifiant d'appareil

KeyValueStore les opérations sont asynchrones et doivent être utilisées avec async/await la syntaxe. KeyValueStore Il a une limite de taille totale de 10 Mo et prend en charge jusqu'à 10 millions de paires clé-valeur. KeyValueStore les données sont finalement cohérentes sur tous les emplacements périphériques, les mises à jour se propageant généralement en quelques secondes.

Pour des performances optimales, structurez vos KeyValueStore clés de manière à minimiser les opérations de recherche. Utilisez les numéros de série des certificats comme clés pour une simple vérification de révocation, ou créez des clés composites combinant le hachage de l'émetteur et le numéro de série pour les environnements multi-CA. Tenez compte des compromis entre complexité et KeyValueStore capacité clés lors de la conception de votre structure de données.

Utilisez async et attendez

Les fonctions de connexion prennent en charge les opérations asynchrones en utilisant async/await la syntaxe, ce qui est essentiel lorsque vous travaillez avec KeyValueStore des opérations ou d'autres tâches asynchrones. Ce async/await modèle garantit que votre fonction attend la fin des recherches avant de KeyValueStore prendre des décisions de connexion, tout en conservant les caractéristiques de haute performance requises pour le traitement des handshake TLS.

async/await L'utilisation correcte des fonctions de connexion est essentielle car les KeyValueStore opérations, bien que très rapides, restent des opérations réseau qui nécessitent une coordination au sein CloudFront de l'infrastructure distribuée. Le runtime gère automatiquement la résolution des promesses et garantit que votre fonction se termine dans la limite d'exécution de 5 millisecondes.

Exemple: Fonction de connexion asynchrone avec KeyValueStore

import cf from 'cloudfront';

async function connectionHandler(connection) {
    const kvsHandle = cf.kvs();
    
    // Async operation to check KeyValueStore for certificate revocation
    const isRevoked = await kvsHandle.exists(connection.clientCertificate.certificates.leaf.serialNumber);
    
    if (isRevoked) {
        // Log the revocation decision with certificate details
        connection.logCustomData(`REVOKED_CERT:${connection.clientCertificate.certificates.leaf.serialNumber}:${connection.clientCertificate.certificates.leaf.issuer}`);
        console.log(`Denying connection for revoked certificate: ${connection.clientCertificate.certificates.leaf.serialNumber}`);
        return connection.deny();
    }
    
    // Log successful validation for monitoring
    connection.logCustomData(`VALID_CERT:${connection.clientCertificate.certificates.leaf.serialNumber}`);
    console.log(`Allowing connection for valid certificate: ${connection.clientCertificate.certificates.leaf.serialNumber}`);
    return connection.allow();
}

À toujours utiliser async/await lors de l'appel KeyValueStore de méthodes ou d'autres opérations asynchrones. L'environnement d'exécution de la fonction de connexion gère automatiquement la résolution des promesses et garantit un flux d'exécution correct dans les strictes contraintes temporelles du traitement TLS handshake. Évitez d'utiliser .then () ou des modèles de rappel, car cela async/await permet une gestion plus claire des erreurs et de meilleures performances dans l'environnement Connection Function.

Lorsque vous concevez des fonctions de connexion asynchrones, structurez votre code de manière à minimiser le nombre d' KeyValueStore opérations et exécutez-les le plus tôt possible dans votre logique de validation. Cela garantit des performances optimales et réduit le risque de problèmes de temporisation pendant les périodes de forte affluence. Envisagez de regrouper les contrôles de validation liés aux lots et d'utiliser la KeyValueStore méthode la plus efficace (exists () contre get ()) pour votre cas d'utilisation.

Exemples de code de fonction de connexion

Les exemples suivants présentent des modèles de fonctions de connexion courants pour différents scénarios de validation. Utilisez ces exemples comme point de départ pour vos propres implémentations de fonctions de connexion.

Exemple: Validation du certificat de l'appareil

Cet exemple valide les numéros de série des appareils et les champs d'objet de certificat pour les appareils IoT, les consoles de jeu et d'autres scénarios d'authentification client :

async function connectionHandler(connection) {
    // Custom validation: check device serial number format
    const serialNumber = connection.clientCertificate.certificates.leaf.serialNumber;
    if (!serialNumber.startsWith("DEV")) {
        connection.logCustomData(`INVALID_SERIAL:${serialNumber}`);
        return connection.deny();
    }
    
    // Validate certificate subject contains required organizational unit
    const subject = connection.clientCertificate.certificates.leaf.subject;
    if (!subject.includes("OU=AuthorizedDevices")) {
        connection.logCustomData(`INVALID_OU:${subject}`);
        return connection.deny();
    }
    
    // Allow connection for valid devices
    connection.logCustomData(`VALID_DEVICE:${serialNumber}`);
    return connection.allow();
}

Cette fonction effectue plusieurs contrôles de validation au-delà de la validation standard des certificats, notamment le format du numéro de série de l'appareil et la vérification des unités organisationnelles.

Exemple: mTL en option avec authentification mixte

Cet exemple gère à la fois les connexions mTLS et non MTLS avec des politiques d'authentification différentes :

async function connectionHandler(connection) {
    if (connection.clientCertificate) {
        // mTLS connection - enhanced validation for certificate holders
        const subject = connection.clientCertificate.certificates.leaf.subject;
        connection.logCustomData(`MTLS_SUCCESS:${subject}:${connection.clientIp}`);
        console.log(`mTLS connection from: ${subject}`);
        return connection.allow();
    } else {
        // Non-mTLS connection - apply IP-based restrictions
        const clientIp = connection.clientIp;
        
        // Only allow non-mTLS from specific IP ranges
        if (clientIp.startsWith("203.0.113.") || clientIp.startsWith("198.51.100.")) {
            connection.logCustomData(`NON_MTLS_ALLOWED:${clientIp}`);
            console.log(`Non-mTLS connection allowed from: ${clientIp}`);
            return connection.allow();
        }
        
        connection.logCustomData(`NON_MTLS_DENIED:${clientIp}`);
        return connection.deny();
    }
}

Cette fonction fournit une sécurité accrue aux clients détenteurs de certificats tout en maintenant la compatibilité avec les anciens clients issus de plages IP fiables.