---
title: "Tunnistetietojen välityspalvelin — tekninen rakenne, uhkamalli, protokollan yksityiskohdat"
description: "Miten Clavitorin tunnistetietojen välityspalvelin toimii protokollatasolla. MITM TLS, tunnistetietojen elinkaari, virhekoodit, SSRF-suojaus ja mitä se ei suojaa."
lang: fi
url: https://clavitor.ai/fi/proxy-technical
markdown: https://clavitor.ai/fi/proxy-technical.md
translation_of: https://clavitor.ai/en/proxy-technical.md
authoritative: false
publisher: Clavitor LLC
---

> This is the Finnish translation of [Credential Proxy Technical — Architecture, threat model, protocol details](https://clavitor.ai/en/proxy-technical.md). The original English text is authoritative; where the two differ, the English version prevails.

# Tunnistetietojen välityspalvelin — tekninen: Miten välityspalvelin toimii.

Mitä vastaan se suojaa. Mitä vastaan ei.
Tämä sivu on tietoturva-arvioijille, tunkeutumistestaajille ja insinööreille, jotka arvioivat välityspalvelimen uhkamallia. Se kuvaa, mitä välityspalvelin tekee protokollatasolla, missä tunnistetiedot esiintyvät muistissa ja mitä hyökkäyspintoja jää jäljelle.

## Rakenne

Välityspalvelin on CONNECT-pohjainen HTTPS MITM -välityspalvelin. Tekoälyagentti asettaa `HTTPS_PROXY`-muuttujan osoittamaan siihen. Kun agentti tekee HTTPS-pyynnön, välityspalvelin sieppaa TLS-yhteyden, tarkastaa pyyntöotsakkeet tunnistetietoviitteiden varalta, ratkaisee ne Clavitorin holvia vasten ja välittää pyynnön injektoiduilla tunnistetiedoilla ylävirran API:lle.

Välityspalvelin kuuntelee oletusarvoisesti osoitteessa `127.0.0.1:1983` — sidecar-malli, jossa välityspalvelin ja agentti jakavat isännän. Jaetuissa käyttöönotoissa (yksi välityspalvelin palvelee useita agentteja yksityisessä verkossa, konttisidecar useille työkuormille, dedikoitu välityspalvelinisäntä) kuuntelu-rajapinta on määritettävissä `CLAVITOR_PROXY_LISTEN`-muuttujalla.

Välityspalvelin on itsenäinen Go-binääri. Ei CGO:ta. Kaikki Clavitor-protokollan kryptografia kulkee kanonisen Rust-toteutuksen kautta, joka käännetään WebAssemblyksi ja ladataan wazero:lla käynnistyksen yhteydessä.

## TLS-käsittely

Välityspalvelin luo itse allekirjoitetun ECDSA P-256 -juurivarmenteen ensimmäisellä käynnistyksellä, tallentaa sen binäärin hakemistoon tilalla `0600`. Jokaiselle ylävirran isännälle luodaan pyydettäessä lehtisertifikaatti, jonka tämä CA allekirjoittaa, ja se välimuistitaan muistiin rajallisella poistolla (1 000 isäntää). Lehtisertifikaatit ovat voimassa 24 tuntia ja ne luodaan läpinäkyvästi uudelleen 23 tunnin kohdalla istunnon aikaisen vanhentumisen estämiseksi.

Agentin on luotettava välityspalvelimen CA-sertifikaattiin. Vie se komennolla `clavitor-proxy ca`.

Ylävirran yhteydet käyttävät vähintään TLS 1.3:a ALPN-neuvottelulla HTTP/2:lle ja HTTP/1.1:lle. Järjestelmän sertifikaattivarastoa käytetään ylävirran varmennukseen. Ei sertifikaattien kiinnitystä — välityspalvelin luottaa siihen, mihin käyttöjärjestelmä luottaa.

## Credential lifecycle

Tunnistetietoja ei koskaan välimuistita, ei koskaan kirjoiteta levylle, eikä niitä säilytetä pidempään kuin yhden HTTP-pyynnön ajan.

| Vaihe | Missä tunnistetieto esiintyy | Kesto |
|-------|----------------------------|----------|
| Levossa holvissa | AES-GCM-salattu teksti holvin tietokannassa | Kunnes poistettu |
| Siirrossa välityspalvelimeen | TLS-salattu JSON-vastaus holvin API:sta | Yksi HTTP-edestakainen matka |
| Purettu välityspalvelimessa | Prosessimuisti (Go-merkkijono keossa) | Yksi HTTP-pyyntö |
| Injektoitu ylävirran pyyntöön | TLS-salattu data johdolla ylävirtaan | Yksi HTTP-pyyntö |

Välityspalvelin pitää agentin tunnistetietojen purkuavaimen (16 tavua) muistissa koko suoritusaikansa. Se ladataan salatusta sidecar-konfiguraatiosta (CLV1-muoto) käynnistyksen yhteydessä ja tyhjennetään hallitussa sammutuksessa. Avain ei koskaan poistu prosessista.

Sidecar-konfiguraatio on salattu AES-128-GCM:llä ja HMAC-SHA256:lla käyttäen deterministisiä avaimia, jotka on johdettu staattisesta siemenestä. Tämä on hämäystä, ei luottamuksellisuutta — turvallisuusraja on tiedosto-oikeudet (`0600`) ja tiedoston hallussapito. CLV1-muoto on jaettu välityspalvelimen, CLI:n ja selainlaajennuksen kesken.

## Ratkaisutilat

### Tila 1 — eksplisiittinen paikkamerkki

Agentti sisällyttää `clavitor://Entry/field` -viitteen pyyntöotsakkeeseen. Välityspalvelin etsii holvista merkintää nimen perusteella, noutaa sen, purkaa nimetyn kentän ja korvaa paikkamerkin todellisella arvolla.

Jos haku palauttaa nolla tai enemmän kuin yhden tuloksen, välityspalvelin palauttaa `502` vakaalla virhekoodilla. Paikkamerkkiä **ei koskaan** poisteta ja välitetä sellaisenaan.

### Tila 2 — URL-haku

Kun paikkamerkkiä ei ole, välityspalvelin pyytää holvista merkintöjä, joiden URL-kenttä vastaa ylävirran isäntää. Jos täsmälleen yksi osuma löytyy tunnistettavalla kentän muodolla, välityspalvelin injektoi tunnistetiedot automaattisesti.

Nolla osumaa → läpivienti (ei tunnistetietojen odotusta). Useita osumia → `502` selvennysopastuksella. Tuntematon kentän muoto → `502`.

Päätöspuu on deterministinen: paikkamerkki läsnä → ratkaise tai epäonnistu. Ei paikkamerkkiä → URL-haku tai läpivienti. Ei ole hiljaista varapolkuja, jossa epäonnistunut ratkaisu johtaa pyynnön menemiseen ylävirtaan ilman tunnistetietoja.

## Agent identity

Oletusarvoisesti holvi näkee välityspalvelimen oman agenttitunnuksen jokaisessa pyynnössä. Nopeusrajoitukset, laajuustarkistukset ja auditointimerkinnät kohdistetaan välityspalvelimeen.

Kun useat agentit jakavat yhden välityspalvelininstanssin, paikkamerkki voi sisältää agenttitunnuksen: `clavitor://agentid@Entry/field`. Välityspalvelin lähettää tämän agenttitunnuksen holviin, joka soveltaa kyseisen agentin laajuuksia ja nopeusrajoituksia ja kirjaa pääsyn sen perusteella. Agenttitunnus on 32-merkkinen heksadesimaaliarvo, joka näkyy agentin tietosivulla holvin käyttöliittymässä.

```
# Without agent ID — attributed to the proxy

Authorization: Bearer clavitor://OpenAI/key

# With agent ID — attributed to agent 0102030405060708090a0b0c0d0e0f10

Authorization: Bearer clavitor://0102030405060708090a0b0c0d0e0f10@OpenAI/key
```

| Käyttöönotto | Identiteettimalli | Eristys |
|------------|----------------|-----------|
| Yksi välityspalvelin per agentti | Välityspalvelimen ID = agentin ID (oletus) | Täysi — erillinen binääri, konfiguraatio, laajuus, nopeusrajoitukset |
| Jaettu välityspalvelin, ei agenttitunnusta URL-osoitteessa | Kaikki agentit jakavat välityspalvelimen ID:n | Jaettu laajuus ja nopeusrajoitukset |
| Jaettu välityspalvelin + `agentid@` URL-osoitteessa | Agenttikohtainen identiteetti | Agenttikohtainen laajuus, nopeusrajoitukset ja auditointi |

URL-osoitteen agenttitunnus ei ole todennusmekanismi — välityspalvelimen CVT-token todentaa yhteyden. Agenttitunnus määrittää kohdistuksen: kenen laajuudet ovat voimassa, kenen nopeusrajoitukset lasketaan, kenen auditointijälki kirjaa pääsyn. Holvi hylkää tuntemattomat agenttitunnukset selkeällä virheellä.

## Verkkoturvallisuus

### SSRF-suojaus

Oletusarvoisesti välityspalvelin estää ylävirran yhteydet yksityisiin verkkoihin (RFC 1918), pilvipalvelun instanssimetatietoihin (`169.254.169.254`), loopbackiin, link-local-osoitteisiin ja operaattoritason NAT-alueisiin. DNS ratkaistaan ensin; kaikki palautetut IP-osoitteet validoidaan ennen TCP-yhteyden muodostamista, sulkien DNS-uudelleensidonta-TOCTOU-ikkunan.

Ohita asettamalla `CLAVITOR_PROXY_ALLOW_PRIVATE=true` agenteille, jotka tavoittavat laillisesti yksityisiä API:ita.

### Kohdepinnitys

CONNECT-kohdeisäntä kaapataan tunnelin muodostamisen yhteydessä ja sitä käytetään koko tunnelin elinkaaren ajan. Myöhemmät pyynnöt tunnelin sisällä eivät voi uudelleenohjata toiseen isäntään manipuloimalla `Host`-otsaketta. Epäsuhta johtaa `502`-virheeseen.

Tämä estää agenttia muodostamasta tunnelia `api.openai.com`-osoitteeseen ja lähettämästä sitten pyyntöjä `internal-service.corp`-osoitteeseen.

## Otsakkeiden käsittely

Hop-by-hop-otsakkeet poistetaan pyynnöistä ja vastauksista RFC 7230 §6.1 mukaisesti: `Connection`, `Keep-Alive`, `Proxy-Authenticate`, `Proxy-Authorization`, `Proxy-Connection`, `TE`, `Trailers`, `Transfer-Encoding`, `Upgrade`.

`Set-Cookie` poistetaan ylävirran vastauksista, jotta estetään ylävirran palveluita istuttamasta evästeitä agentin HTTP-asiakkaaseen.

Pyyntö- ja vastausrunkojen virta kulkee läpi ilman puskurointia. Pyyntöjen rungot on rajoitettu 64 Mt:iin oletusarvoisesti (`CLAVITOR_PROXY_MAX_BODY_MB`). Vastausten rungot virtaavat ilman kovaa rajaa; lokivaroitus annetaan, kun `Content-Length` ylittää 100 Mt.

## Field-to-header mapping

URL-hakutilassa välityspalvelin vastaa holvin kenttien nimiä HTTP-otsakkeisiin:

| Kentän nimi | Injektoitu otsake |
|-------------|-----------------|
| `key`, `apikey`, `api_key`, `token`, `secret`, `bearer`, `access_token` | `Authorization: Bearer <value>` |
| `x-api-key`, `api-key` | `X-API-Key: <value>` |
| `username` + `password` (parina) | `Authorization: Basic base64(user:pass)` |
| Mikä tahansa muu | Hylätty — `ERR-PROXY-052` |

Paikkamerkkitilassa agentti hallitsee, mikä kenttä ratkaistaan ja mihin se menee. Yllä oleva vastaavuus koskee vain URL-hakutilaa.

## Error codes

Jokainen virhe tuottaa vakaan `ERR-PROXY-NNN`-koodin. Nämä koodit ovat osa välityspalvelimen julkista rajapintaa — agentit ja operaattorit voivat kohdistaa niihin hälytyksiä ja vianmääritystä varten.

| Alue | Luokka |
|-------|----------|
| `001–019` | Asennus (konfiguraatio, alustus, CA-generointi, WASM) |
| `020–029` | Daemonin elinkaari |
| `030–049` | Paikkamerkin ratkaisu (`clavitor://` URI:t) |
| `050–069` | URL-haun injektointi |
| `070–089` | Ylävirta / TLS |

## Identiteettikentät ovat saavuttamattomissa

Holvin merkinnät tukevat kolmea salauskerrosta. Holvin salaus -kentät ovat selväkielistä metatietoa. Tunnistetietojen salaus -kentät puretaan agentin avaimella. Identiteetin salaus -kentät salataan avaimella, jota palvelin ja välityspalvelin eivät ole koskaan nähneet. Vain holvin omistaja voi purkaa ne laitteistoavaimellaan.

Jos paikkamerkki viittaa identiteetillä salattuun kenttään, välityspalvelin palauttaa `ERR-PROXY-035`. Ei varapolkua, ei osittaista tulosta. Kenttä on arkkitehtonisesti saavuttamaton välityspalvelimelta.

## Mitä välityspalvelin ei suojaa

Välityspalvelimen uhkamalli on **vaarantunut taito tai kehotteen injektointi, joka saa todennetun agentin keräämään tunnistetietoja**. Holvin agenttikohtaiset nopeusrajoitukset, uniikkien merkintöjen kiintiöt ja kahden virheen lukitus ovat ensisijaisia puolustuskeinoja. Välityspalvelin lisää verkkotason toteutuspisteen, jossa tunnistetiedot ratkaistaan pyyntökohtaisesti eikä agentti koskaan säilytä niitä.

### Vaarantunut isäntä

Välityspalvelin suoritetaan samalla koneella kuin agentti. Hyökkääjä, jolla on pääkäyttäjän oikeudet, voi lukea prosessimuistia, liittää debuggerin tai siepata loopback-liikennettä. Välityspalvelin on tunnistetietojen injektointikerros, ei laitteistoturvallisuusraja.

### Tunnistetietojen vuotaminen API-vastauksen kautta

Jos ylävirran API toistaa tunnistetiedon vastauksessaan (esim. "kuka minä olen" -päätepiste), agentti näkee sen. Välityspalvelin injektoi tunnistetietoja pyyntöihin, ei vastauksiin. Se ei suodata sitä, mikä tulee takaisin.

## Lokitus

Välityspalvelin kirjaa yhden rivin per hyväksytty CONNECT ja lähettää virherivejä epäonnistumisille. Se **ei koskaan** kirjaa lokiin:

- Puretut tunnistetietojen arvot
- Täydelliset pyyntö-URL-osoitteet (kyselymerkkijonot voivat sisältää salaisuuksia — vain skeema + isäntä + polku kirjataan)
- Pyyntö- tai vastausrunkoja
- Tunnistetietojen purkuavain tai sidecar-konfiguraation sisältöä

Kun välityspalvelin havaitsee, että 400-vastaus ylävirrasta sisältää todennukseen liittyviä avainsanoja (`unauthorized`, `invalid token` jne.), se kirjaa diagnostiikkavihjeen, joka viittaa siihen, että injektoitu tunnistetieto saattaa olla vanhentunut. Vastaus välitetään muuttumattomana.

## Kryptografia

Kaikki Clavitor-protokollan kryptografia — AES-GCM-kentän purku, HKDF-avaimen johdanto, base62-koodaus, CVT-tokenin luonti, CLV1-konfiguraatiopaketin pakkaus/purku — suoritetaan yhden WebAssembly-moduulin (`clavis_crypto.wasm`) sisällä, joka ladataan [wazero:n](https://wazero.io) kautta, joka on puhdas Go-pohjainen WASM-suoritusympäristö. Ei CGO:ta. Ei Go:n uudelleentoteutusta Clavitor-primitiiveille.

WASM-moduuli käännetään samasta Rust-crate:sta (`clavis-crypto`), jota selain, CLI ja selainlaajennukset käyttävät. Yksi totuuden lähde, yksi binääri, yksi auditointipinta.

Välityspalvelin käyttää Go:n `crypto/tls`-kirjastoa TLS-liikenteeseen ja `crypto/ecdsa`:ta MITM-sertifikaattien luomiseen. Nämä ovat kuljetushuolia, eivät Clavitor-protokollan operaatioita.

## Configuration

Salaisuudet (tunnistetietojen purkuavain, agenttitunnus, laitetunnus, holvin URL) sijaitsevat salatussa CLV1-sidecar-konfiguraatiossa, joka kirjoitetaan kerran `clavitor-proxy init` -komennon aikana. Toiminnalliset kytkimet sijaitsevat ympäristömuuttujissa:

| Muuttuja | Oletus | Tarkoitus |
|----------|---------|---------|
| `CLAVITOR_PROXY_LISTEN` | `127.0.0.1` | Kuuntelu-rajapinta. Aseta `0.0.0.0` jaettuihin käyttöönottoihin tai tiettyyn rajapinnan IP-osoitteeseen. |
| `CLAVITOR_PROXY_PORT` | `1983` | Kuunteluportti |
| `CLAVITOR_PROXY_ALLOW_PRIVATE` | `false` | Salli yhteydet RFC-1918 / yksityisiin verkkoihin |
| `CLAVITOR_PROXY_MAX_BODY_MB` | `64` | Pyynnön rungon kokorajoitus |
| `CLAVITOR_PROXY_WRITE_TIMEOUT` | `300` | Vastausten kirjoitusajan rajoitus sekunneissa |
| `CLAVITOR_CONFIG` | *(suoritettavan tiedoston hakemisto)* | Ohita sidecar-konfiguraation polku |

Toiminnalliset kytkimet eivät ole salaisuuksia. Ne eivät kuulu salattuun konfiguraatioon. Ne kuuluvat sinne, missä käyttöönotto-työkalut niitä jo hallitsevat — ympäristöön.

## Tarkasta tämä itse.

Kryptografia on yksi auditoitava WASM-artefakti. Uhkamalli on dokumentoitu. Jos löydät jotain, minkä olemme jättäneet huomiotta, haluamme kuulla siitä.
[Ilmoita löydöstä](mailto:security@clavitor.ai)
[← Liiketoiminnan yleiskatsaus](https://clavitor.ai/fi/proxy)