Schreiben Sie den CloudFront Verbindungsfunktionscode für die gegenseitige TLS-Validierung (Viewer)

CloudFront Mit Verbindungsfunktionen können Sie einfache JavaScript Funktionen für die mTLS-Zertifikatsvalidierung und benutzerdefinierte Authentifizierungslogik schreiben. Ihr Verbindungsfunktionscode kann Client-Zertifikate validieren, gerätespezifische Authentifizierungsregeln implementieren, Zertifikatswiderrufsszenarien handhaben und allow/deny Entscheidungen für TLS-Verbindungen an CloudFront Edge-Standorten weltweit treffen.

Verbindungsfunktionen bieten eine leistungsstarke Möglichkeit, die integrierte Zertifikatsvalidierung um Ihre eigene Geschäftslogik zu erweitern CloudFront. Im Gegensatz zu Funktionen für Viewer-Anforderung und Viewer-Antwort, die HTTP-Daten verarbeiten, arbeiten Verbindungsfunktionen auf der TLS-Ebene und haben Zugriff auf Zertifikatsinformationen, Client-IP-Adressen und TLS-Verbindungsdetails. Dadurch eignen sie sich ideal für die Implementierung von Zero-Trust-Sicherheitsmodellen, Geräteauthentifizierungssystemen und benutzerdefinierten Richtlinien zur Zertifikatsvalidierung, die über die standardmäßige PKI-Validierung hinausgehen.

Ihr Verbindungsfunktionscode wird in einer sicheren, isolierten Umgebung mit Startzeiten von unter einer Millisekunde ausgeführt und kann so skaliert werden, dass er Millionen von Verbindungen pro Sekunde verarbeitet. Die Runtime ist für Workloads zur Zertifikatsvalidierung optimiert und bietet eine integrierte Integration CloudFront KeyValueStore für Datensuchvorgänge in Echtzeit, wodurch anspruchsvolle Authentifizierungsszenarien wie die Überprüfung von Zertifikatssperrlisten und die Überprüfung von Zulassungslisten für Geräte ermöglicht werden.

Informationen zum Schreiben eines effektiven Verbindungsfunktionscodes finden Sie in den folgenden Themen. Vollständige Codebeispiele und step-by-step Tutorials finden Sie in den Abschnitten mit den Tutorials in diesem Handbuch sowie in den Beispielen für Verbindungsfunktionen, die in der CloudFront Konsole verfügbar sind.

CloudFront Anwendungsfälle und Zwecke der Verbindungsfunktion

Bevor Sie Ihre CloudFront Verbindungsfunktion schreiben, sollten Sie sorgfältig festlegen, welche Art von Zertifikatsvalidierungs- oder Authentifizierungslogik Sie implementieren müssen. Verbindungsfunktionen sind für bestimmte Anwendungsfälle konzipiert, die eine benutzerdefinierte Validierung erfordern, die über die standardmäßige PKI-Zertifikatsprüfung hinausgeht. Wenn Sie Ihren Anwendungsfall verstehen, können Sie effizienten Code entwerfen, der Ihre Sicherheitsanforderungen erfüllt und gleichzeitig eine optimale Leistung gewährleistet.

Zu den häufigsten Anwendungsfällen für Verbindungsfunktionen gehören:

Verbindungsfunktionen werden nach der CloudFront Standardvalidierung des Zertifikats (Überprüfung der Vertrauenskette, Ablaufprüfungen und Signaturvalidierung) ausgeführt, jedoch bevor die TLS-Verbindung hergestellt wird. Dieser Zeitplan gibt Ihnen die Flexibilität, benutzerdefinierte Validierungskriterien hinzuzufügen und gleichzeitig von CloudFront der integrierten Zertifikatsvalidierung zu profitieren. Ihre Funktion erhält die Ergebnisse der Standardvalidierung und kann anhand von Standard- und benutzerdefinierten Kriterien fundierte Entscheidungen darüber treffen, ob die Verbindung zugelassen oder verweigert werden soll.

Berücksichtigen Sie beim Entwerfen Ihrer Verbindungsfunktion die Auswirkungen Ihrer Validierungslogik auf die Leistung. Funktionen haben ein Ausführungslimit von 5 Millisekunden, daher sollten komplexe Operationen im Hinblick auf die Geschwindigkeit optimiert werden. Verwenden Sie diese KeyValueStore Option eher für schnelle Datenabfragen als für komplexe Berechnungen. Strukturieren Sie Ihre Validierungslogik so, dass sie bei ungültigen Zertifikaten schnell fehlschlägt.

CloudFront Verbindungsfunktion, Ereignisstruktur und Antwortformat

CloudFront Verbindungsfunktionen erhalten eine andere Ereignisstruktur als Viewer-Anforderungs- und Viewer-Antwortfunktionen. Anstelle von request/response HTTP-Daten empfangen Verbindungsfunktionen Zertifikat- und Verbindungsinformationen, anhand derer Sie Authentifizierungsentscheidungen treffen können.

Ereignisstruktur für Verbindungsfunktionen

Verbindungsfunktionen empfangen ein Ereignisobjekt, das Zertifikat und Verbindungsinformationen enthält. Die Ereignisstruktur der Funktion ist unten dargestellt:

{
  "clientCertificate": {
    "certificates": {
      "leaf": {
        "serialNumber": "string",
        "issuer": "string",
        "subject": "string",
        "validity": {
          "notBefore": "string",
          "notAfter": "string",
        },
        "sha256Fingerprint": "string"
      }
    }
  },
  "clientIp": "string",
  "endpoint": "string",
  "distributionId": "string",
  "connectionId": "string"
}

Im Folgenden finden Sie ein Beispiel für die Ereignisobjektstruktur:

{
  "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="
      }
    }
  },
  "clientIp": "127.0.0.1",
  "endpoint": "d3lch071jze0cb.cloudfront.net",
  "distributionId": "E1NXS4MQZH501R",
  "connectionId": "NpvTe1925xfj24a67sPQr7ae42BIq03FGhJJKfrQYWZcWZFp96SIIg=="
}

Antwortformat der Verbindungsfunktionen

Ihre Verbindungsfunktion muss ein Antwortobjekt zurückgeben, das angibt, ob die Verbindung zugelassen oder verweigert werden soll. Verwenden Sie die Hilfsmethoden, um Verbindungsentscheidungen zu treffen:

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();
    }
}

Im Gegensatz zu Funktionen für Viewer-Anfragen und Viewer-Antworten können Verbindungsfunktionen HTTP-Anfragen oder -Antworten nicht ändern. Sie können die TLS-Verbindung nur zulassen oder verweigern.

CloudFront Verbindungsfunktionen, JavaScript Laufzeitfunktionen

CloudFront Connection Functions verwenden die CloudFront Functions JavaScript Runtime 2.0, die eine sichere und leistungsstarke Umgebung bietet, die speziell für Workloads zur Zertifikatsvalidierung optimiert wurde. Die Runtime ist so konzipiert, dass sie in weniger als einer Millisekunde startet und Millionen von gleichzeitigen Ausführungen im globalen Edge-Netzwerk verarbeitet. CloudFront

Die Laufzeitumgebung bietet umfassende Sprachunterstützung: JavaScript

Die Verbindungsfunktionen sind für Hochleistungsszenarien zur Zertifikatsvalidierung optimiert. Die Runtime kümmert sich automatisch um die Speicherverwaltung, die Speicherbereinigung und die Ressourcenbereinigung, um eine konsistente Leistung über Millionen von gleichzeitigen Verbindungen hinweg sicherzustellen. Alle Operationen sind so konzipiert, dass sie deterministisch und schnell ablaufen, wobei KeyValueStore Suchvorgänge in der Regel innerhalb von Mikrosekunden abgeschlossen werden.

Die Laufzeitumgebung ist zwischen den Funktionsausführungen vollständig isoliert, wodurch sichergestellt wird, dass keine Daten zwischen verschiedenen Client-Verbindungen verloren gehen. Jede Funktionsausführung beginnt mit einem fehlerfreien Zustand und hat keinen Zugriff auf frühere Ausführungsergebnisse oder Client-Daten von anderen Verbindungen.

CloudFront Hilfsmethoden für Verbindungsfunktionen und APIs

CloudFront Verbindungsfunktionen stellen spezielle Hilfsmethoden bereit, die Entscheidungen zur Validierung von Zertifikaten vereinfachen und die Beobachtbarkeit verbessern sollen. Diese Methoden sind für den Workflow zur Verbindungsvalidierung optimiert und lassen sich nahtlos CloudFront in die Verbindungsprotokollierungs- und Überwachungssysteme integrieren.

Diese Methoden bieten eine saubere, deklarative Oberfläche für Verbindungsentscheidungen und die Protokollierung relevanter Informationen für die Überwachung und das Debuggen. Das allow/deny Muster stellt sicher, dass die Absicht Ihrer Funktion klar ist und dass die Verbindungsverarbeitung auf der Grundlage Ihrer Entscheidung optimiert werden CloudFront kann. Benutzerdefinierte Protokollierungsdaten sind sofort in CloudFront Verbindungsprotokollen verfügbar und können zusammen mit Protokollanalysetools für die Sicherheitsüberwachung und betriebliche Einblicke verwendet werden.

Rufen Sie immer entweder connection.allow () oder connection.deny () auf, bevor Ihre Funktion abgeschlossen ist. Wenn keine der Methoden aufgerufen wird, CloudFront wird die Verbindung standardmäßig aus Sicherheitsgründen verweigert.

CloudFront Integration der Verbindungsfunktion KeyValueStore

CloudFront Verbindungsfunktionen können verwendet werden CloudFront KeyValueStore , um ultraschnelle Datenabfragen für Szenarien zur Zertifikatsvalidierung durchzuführen. KeyValueStore ist besonders leistungsstark für Verbindungsfunktionen, da es einen globalen, letztlich konsistenten Datenzugriff mit Suchzeiten im Mikrosekundenbereich an allen Edge-Standorten ermöglicht. CloudFront Dadurch eignet es sich ideal für die Verwaltung von Zertifikatssperrlisten, Gerätelisten, Mandantenkonfigurationen und anderen Validierungsdaten, auf die bei TLS-Handshakes zugegriffen werden muss.

KeyValueStore Die Integration wurde speziell für leistungsstarke Workflows zur Verbindungsvalidierung entwickelt:

KeyValueStore Operationen sind asynchron und müssen mit der Async/Await-Syntax verwendet werden. Der KeyValueStore hat eine Gesamtgrößenbeschränkung von 10 MB und unterstützt bis zu 10 Millionen Schlüssel-Wert-Paare. KeyValueStore Die Daten sind letztendlich an allen Edge-Standorten konsistent, wobei sich Aktualisierungen in der Regel innerhalb von Sekunden verbreiten.

Um eine optimale Leistung zu erzielen, sollten Sie Ihre KeyValueStore Schlüssel so strukturieren, dass die Anzahl der Suchvorgänge minimiert wird. Verwenden Sie die Seriennummern von Zertifikaten als Schlüssel für die einfache Sperrprüfung oder erstellen Sie zusammengesetzte Schlüssel, die den Hashwert und die Seriennummer des Ausstellers für Umgebungen mit mehreren Zertifizierungsstellen kombinieren. Berücksichtigen Sie beim Entwerfen Ihrer Datenstruktur die Kompromisse zwischen Schlüsselkomplexität und KeyValueStore Kapazität.

Verwenden Sie asynchron und warten Sie

Verbindungsfunktionen unterstützen asynchrone Operationen mithilfe von async/await Syntax, was für die Arbeit mit KeyValueStore Operationen oder anderen asynchronen Aufgaben unerlässlich ist. Das async/await Muster stellt sicher, dass Ihre Funktion wartet, bis die KeyValueStore Suchvorgänge abgeschlossen sind, bevor sie Verbindungsentscheidungen trifft. Gleichzeitig werden die für die TLS-Handshake-Verarbeitung erforderlichen Hochleistungseigenschaften beibehalten.

Die richtige async/await Verwendung ist für Verbindungsfunktionen von entscheidender Bedeutung, da KeyValueStore Operationen zwar sehr schnell sind, aber dennoch Netzwerkvorgänge sind, die eine Koordination innerhalb CloudFront der verteilten Infrastruktur erfordern. Die Runtime kümmert sich automatisch um die Auflösung von Zusagen und stellt sicher, dass Ihre Funktion innerhalb des Ausführungslimits von 5 Millisekunden abgeschlossen wird.

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();
}

Wird immer verwendet async/await , wenn KeyValueStore Methoden oder andere asynchrone Operationen aufgerufen werden. Die Laufzeit der Verbindungsfunktion verarbeitet die Auflösung von Zusagen automatisch und gewährleistet den ordnungsgemäßen Ablauf der Ausführung innerhalb der strengen Zeitbeschränkungen der TLS-Handshake-Verarbeitung. Vermeiden Sie die Verwendung von .then () oder Callback-Mustern, da async/await für eine sauberere Fehlerbehandlung und eine bessere Leistung in der Verbindungsfunktionsumgebung sorgt.

Strukturieren Sie Ihren Code beim Entwerfen asynchroner Verbindungsfunktionen so, dass die Anzahl der KeyValueStore Operationen minimiert wird, und führen Sie sie so früh wie möglich in Ihrer Validierungslogik aus. Dies gewährleistet eine maximale Leistung und reduziert das Risiko von Timeout-Problemen in Zeiten mit hohem Datenaufkommen. Erwägen Sie, die zugehörigen Validierungsprüfungen zu stapeln und die effizienteste KeyValueStore Methode (exists () vs get ()) für Ihren Anwendungsfall zu verwenden.

Codebeispiele für Verbindungsfunktionen

In den folgenden Beispielen werden gängige Verbindungsfunktionsmuster für verschiedene Überprüfungsszenarien veranschaulicht. Verwenden Sie diese Beispiele als Ausgangspunkt für Ihre eigenen Implementierungen von Verbindungsfunktionen.

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();
}

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();
    }
}