Scrivi il codice della funzione di CloudFront connessione per la convalida reciproca del TLS (viewer)

CloudFront Le funzioni di connessione consentono di scrivere JavaScript funzioni leggere per la convalida dei certificati MTL e la logica di autenticazione personalizzata. Il codice Connection Function può convalidare i certificati client, implementare regole di autenticazione specifiche del dispositivo, gestire scenari di revoca dei certificati e allow/deny prendere decisioni per le connessioni TLS nelle edge location di tutto il mondo. CloudFront

Le funzioni di connessione offrono un modo efficace per estendere la convalida CloudFront dei certificati integrata con la propria logica aziendale. A differenza delle funzioni di richiesta e risposta del visualizzatore che elaborano i dati HTTP, le funzioni di connessione operano a livello TLS e hanno accesso alle informazioni sui certificati, agli indirizzi IP dei client e ai dettagli della connessione TLS. Ciò le rende ideali per implementare modelli di sicurezza zero-trust, sistemi di autenticazione dei dispositivi e politiche di convalida dei certificati personalizzate che vanno oltre la convalida PKI standard.

Il codice della funzione di connessione viene eseguito in un ambiente sicuro e isolato con tempi di avvio inferiori al millisecondo ed è scalabile per gestire milioni di connessioni al secondo. Il runtime è ottimizzato per i carichi di lavoro di convalida dei certificati e offre un'integrazione integrata CloudFront KeyValueStore per le operazioni di ricerca dei dati in tempo reale, abilitando scenari di autenticazione sofisticati come il controllo degli elenchi di revoca dei certificati e la convalida delle liste consentite dei dispositivi.

Per aiutarti a scrivere un codice efficace per le funzioni di connessione, consulta i seguenti argomenti. Per esempi di codice e step-by-step tutorial completi, consulta le sezioni del tutorial di questa guida ed esplora gli esempi di Connection Function disponibili nella CloudFront console.

CloudFront Casi d'uso e scopi della funzione di connessione

Prima di scrivere la funzione di CloudFront connessione, stabilite attentamente il tipo di convalida dei certificati o la logica di autenticazione che dovete implementare. Le funzioni di connessione sono progettate per casi d'uso specifici che richiedono una convalida personalizzata oltre al controllo standard dei certificati PKI. La comprensione del caso d'uso consente di progettare codice efficiente che soddisfi i requisiti di sicurezza mantenendo al contempo prestazioni ottimali.

I casi d'uso di Common Connection Function includono:

Le funzioni di connessione vengono CloudFront eseguite dopo aver eseguito la convalida standard dei certificati (verifica della catena di fiducia, controlli di scadenza e convalida delle firme) ma prima che venga stabilita la connessione TLS. Questa tempistica offre la flessibilità necessaria per aggiungere criteri di convalida personalizzati, beneficiando al contempo della convalida dei certificati integrata. CloudFront La tua funzione riceve i risultati della convalida standard e può prendere decisioni informate sull'opportunità di consentire o negare la connessione in base a criteri standard e personalizzati.

Durante la progettazione della funzione di connessione, considerate le implicazioni prestazionali della logica di convalida. Le funzioni hanno un limite di esecuzione di 5 millisecondi, quindi le operazioni complesse devono essere ottimizzate in termini di velocità. KeyValueStore Utilizzatele per ricerche rapide dei dati anziché calcoli complessi e strutturate la logica di convalida in modo che fallisca rapidamente per i certificati non validi.

CloudFront Funzione di connessione, struttura degli eventi e formato di risposta.

CloudFront Le funzioni di connessione ricevono una struttura degli eventi diversa rispetto alle funzioni di richiesta e risposta del visualizzatore. Invece dei request/response dati HTTP, le funzioni di connessione ricevono informazioni sul certificato e sulla connessione che è possibile utilizzare per prendere decisioni di autenticazione.

Struttura degli eventi per le funzioni di connessione

Le funzioni di connessione ricevono un oggetto evento che contiene informazioni sul certificato e sulla connessione. La struttura degli eventi della funzione è illustrata di seguito:

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

Di seguito è riportato un esempio della struttura degli oggetti dell'evento:

{
  "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=="
}

Formato di risposta di Connection Functions

La funzione di connessione deve restituire un oggetto di risposta che indichi se consentire o negare la connessione. Usa i metodi di supporto per prendere decisioni sulla connessione:

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

A differenza delle funzioni di richiesta e risposta del visualizzatore, Connection Functions non può modificare le richieste o le risposte HTTP. Possono solo consentire o negare la connessione TLS.

CloudFront Funzioni di runtime di Connection Functions JavaScript

CloudFront Connection Functions utilizza CloudFront Functions JavaScript runtime 2.0, che fornisce un ambiente sicuro e ad alte prestazioni ottimizzato specificamente per i carichi di lavoro di convalida dei certificati. Il runtime è progettato per iniziare in meno di millisecondi e gestire milioni di esecuzioni simultanee sulla rete edge globale. CloudFront

L'ambiente di runtime include un supporto linguistico completo: JavaScript

Le funzioni di connessione sono ottimizzate per garantire prestazioni elevate negli scenari di convalida dei certificati. Il runtime gestisce automaticamente la gestione della memoria, la raccolta dei rifiuti e la pulizia delle risorse per garantire prestazioni costanti su milioni di connessioni simultanee. Tutte le operazioni sono progettate per essere deterministiche e veloci, con il completamento delle KeyValueStore ricerche in genere in microsecondi.

L'ambiente di runtime è completamente isolato tra le esecuzioni delle funzioni, garantendo che non vi siano perdite di dati tra le diverse connessioni client. Ogni esecuzione di funzione inizia con uno stato pulito e non ha accesso ai risultati di esecuzione precedenti o ai dati dei client provenienti da altre connessioni.

CloudFront Metodi di supporto per Connection Function e APIs

CloudFront Connection Functions fornisce metodi di supporto specializzati progettati per semplificare le decisioni di convalida dei certificati e migliorare l'osservabilità. Questi metodi sono ottimizzati per il flusso di lavoro di convalida delle connessioni e si integrano perfettamente con i sistemi CloudFront di registrazione e monitoraggio delle connessioni.

Questi metodi forniscono un'interfaccia chiara e dichiarativa per prendere decisioni sulla connessione e registrare le informazioni pertinenti per il monitoraggio e il debug. Lo allow/deny schema assicura che l'intento della funzione sia chiaro e che CloudFront possa ottimizzare la gestione della connessione in base alla decisione presa dall'utente. I dati di registrazione personalizzati sono immediatamente disponibili nei registri di CloudFront connessione e possono essere utilizzati con strumenti di analisi dei log per il monitoraggio della sicurezza e informazioni operative.

Chiama sempre connection.allow () o connection.deny () prima del completamento della funzione. Se non viene chiamato nessuno dei due metodi, CloudFront negherà la connessione per impostazione predefinita come precauzione di sicurezza.

CloudFront Integrazione della funzione di connessione KeyValueStore

CloudFront Le funzioni di connessione possono essere utilizzate CloudFront KeyValueStore per eseguire ricerche di dati ultraveloci per scenari di convalida dei certificati. KeyValueStore è particolarmente potente per Connection Functions perché fornisce un accesso ai dati globale e alla fine coerente con tempi di ricerca in microsecondi in tutte le edge location. CloudFront Ciò lo rende ideale per mantenere elenchi di revoca dei certificati, elenchi di dispositivi consentiti, configurazioni dei tenant e altri dati di convalida che devono essere accessibili durante gli handshake TLS.

KeyValueStore l'integrazione è progettata specificamente per flussi di lavoro di convalida delle connessioni ad alte prestazioni:

KeyValueStore le operazioni sono asincrone e devono essere utilizzate con la sintassi async/await. KeyValueStore Ha un limite di dimensione totale di 10 MB e supporta fino a 10 milioni di coppie chiave-valore. KeyValueStore i dati alla fine sono coerenti in tutte le edge location, con gli aggiornamenti che in genere si propagano in pochi secondi.

Per prestazioni ottimali, strutturate le KeyValueStore chiavi in modo da ridurre al minimo le operazioni di ricerca. Utilizza i numeri di serie dei certificati come chiavi per un semplice controllo delle revoce oppure crea chiavi composite che combinano l'hash dell'emittente e il numero di serie per ambienti con più CA. Considera i compromessi tra complessità e KeyValueStore capacità delle chiavi durante la progettazione della struttura dei dati.

Usa async e await

Le funzioni di connessione supportano le operazioni asincrone utilizzando la async/await sintassi, essenziale quando si lavora con operazioni o altre attività asincrone. KeyValueStore Lo async/await schema assicura che la funzione attenda il completamento delle KeyValueStore ricerche prima di prendere decisioni sulla connessione, mantenendo al contempo le caratteristiche ad alte prestazioni richieste per l'elaborazione dell'handshake TLS.

async/await L'uso corretto è fondamentale per Connection Functions perché le KeyValueStore operazioni, sebbene molto veloci, sono comunque operazioni di rete che richiedono il coordinamento dell'infrastruttura distribuita. CloudFront Il runtime gestisce automaticamente la risoluzione delle promesse e garantisce il completamento della funzione entro il limite di esecuzione di 5 millisecondi.

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

Da utilizzare sempre async/await quando si chiamano KeyValueStore metodi o altre operazioni asincrone. Il runtime Connection Function gestisce automaticamente la risoluzione delle promesse e garantisce il corretto flusso di esecuzione entro i rigorosi vincoli temporali dell'elaborazione dell'handshake TLS. Evita di usare .then () o pattern di callback, poiché async/await offre una gestione degli errori più pulita e prestazioni migliori nell'ambiente Connection Function.

Quando progettate funzioni di connessione asincrone, strutturate il codice in modo da ridurre al minimo il numero di KeyValueStore operazioni ed eseguitele il prima possibile nella logica di convalida. Ciò garantisce le massime prestazioni e riduce il rischio di problemi di timeout durante i periodi di traffico intenso. Prendi in considerazione la possibilità di raggruppare i controlli di convalida correlati e di utilizzare il KeyValueStore metodo più efficiente (exists () vs get ()) per il tuo caso d'uso.

Esempi di codice delle funzioni di connessione

Gli esempi seguenti mostrano modelli comuni di Connection Function per diversi scenari di convalida. Utilizzate questi esempi come punti di partenza per le vostre implementazioni di Connection Function.

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