API pro KeyTab¶

Import, správa, discovery a vynucování šifrové politiky Kerberos KeyTab souborů

Verze dokumentu: 1.0.41
Poslední aktualizace: 2026-04-26

Dostupnost funkce

Správa KeyTab je dostupná od MazeVault v1.0.36 a musí být povolena proměnnou MAZEVAULT_KEYTAB_ENABLED=true. Viz Proměnné prostředí.

Přehled endpointů¶

Metoda	Endpoint	Popis
POST	`/api/v1/keytabs`	Import keytab souboru
GET	`/api/v1/keytabs`	Seznam keytabů
GET	`/api/v1/keytabs/:id`	Získání keytabu podle ID
PUT	`/api/v1/keytabs/:id`	Aktualizace metadat nebo binárních dat
DELETE	`/api/v1/keytabs/:id`	Smazání keytabu
GET	`/api/v1/keytabs/:id/download`	Stažení binárního souboru keytabu
GET	`/api/v1/keytabs/:id/history`	Historie verzí keytabu
POST	`/api/v1/keytabs/:id/check-compliance`	Kontrola souladu šifer keytabu
POST	`/api/v1/keytabs/refresh-compliance`	Obnovení souladu všech keytabů
GET	`/api/v1/keytabs/cipher-policy`	Získání šifrové politiky organizace
PUT	`/api/v1/keytabs/cipher-policy`	Aktualizace šifrové politiky organizace
GET	`/api/v1/keytabs/discovered`	Seznam keytabů nalezených agentem
POST	`/api/v1/keytabs/discovered/:id/import`	Import nalezeného keytabu do správy
GET	`/api/v1/keytabs/dashboard`	Statistiky keytab dashboardu

Import keytabu¶

Nahraje a zaregistruje nový Kerberos keytab soubor. Binární obsah musí být zakódován v base64. MazeVault keytab automaticky zparsuje a extrahuje principal, realm, KVNO a typy šifer.

POST /api/v1/keytabs HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "app-service-keytab",
  "keytab_data": "<binární keytab zakódovaný v base64>",
  "expires_at": "2027-04-01T00:00:00Z",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "notes": "Servisní účet pro fakturační aplikaci"
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`name`	string	✅	Čitelný název (max 255 znaků)
`keytab_data`	string	✅	Binární soubor keytabu zakódovaný v base64
`expires_at`	string (ISO 8601)	—	Datum expirace; používáno pro upozornění a reporty
`project_id`	string (UUID)	—	Přiřadí keytab k projektu
`notes`	string	—	Volný text pro poznámky ke keytabu (max 1024 znaků)

Odpověď `201 Created`¶

{
  "id": "kt_550e8400-e29b-41d4-a716-446655440010",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "app-service-keytab",
  "principal": "app-svc@CORP.EXAMPLE.COM",
  "realm": "CORP.EXAMPLE.COM",
  "kvno": 5,
  "encryption_types": ["aes256-cts-hmac-sha1-96", "aes128-cts-hmac-sha1-96"],
  "status": "active",
  "cipher_compliance": "compliant",
  "source": "import",
  "storage_mode": "full",
  "offload_status": "local",
  "version": 1,
  "entry_count": 2,
  "keytab_hash": "e3b0c44298fc1c149afbf4c8996fb924",
  "expires_at": "2027-04-01T00:00:00Z",
  "notes": "Servisní účet pro fakturační aplikaci",
  "created_at": "2026-04-26T10:00:00Z",
  "updated_at": "2026-04-26T10:00:00Z"
}

Soulad šifer

Po importu MazeVault automaticky zkontroluje typy šifer keytabu oproti šifrové politice organizace. Pole cipher_compliance odráží výsledek (compliant, warning nebo non_compliant).

Seznam keytabů¶

GET /api/v1/keytabs?page=1&limit=25 HTTP/1.1
Authorization: Bearer <token>

Parametry dotazu¶

Parametr	Typ	Popis
`project_id`	string (UUID)	Filtrovat podle projektu
`status`	string	Filtrovat podle stavu (`active`, `disabled`, `expired`)
`cipher_compliance`	string	Filtrovat podle souladu šifer (`compliant`, `warning`, `non_compliant`)
`realm`	string	Filtrovat podle Kerberos realmu
`principal`	string	Filtrovat podle principálu (částečná shoda)
`source`	string	Filtrovat podle zdroje (`import`, `discovered`, `agent`)
`page`	integer	Číslo stránky (výchozí: 1)
`limit`	integer	Položek na stránku (výchozí: 25, max: 100)

Odpověď `200 OK`¶

{
  "data": [
    {
      "id": "kt_550e8400-e29b-41d4-a716-446655440010",
      "name": "app-service-keytab",
      "principal": "app-svc@CORP.EXAMPLE.COM",
      "realm": "CORP.EXAMPLE.COM",
      "kvno": 5,
      "encryption_types": ["aes256-cts-hmac-sha1-96"],
      "status": "active",
      "cipher_compliance": "compliant",
      "source": "import",
      "version": 1,
      "entry_count": 2,
      "expires_at": "2027-04-01T00:00:00Z",
      "created_at": "2026-04-26T10:00:00Z",
      "updated_at": "2026-04-26T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 25
}

Získání keytabu¶

GET /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010 HTTP/1.1
Authorization: Bearer <token>

Odpověď `200 OK`¶

Vrátí kompletní objekt KeyTabResponse. Binární data keytabu nejsou součástí této odpovědi. Pro stažení binárního souboru použijte endpoint Stažení keytabu.

Kompletní seznam polí viz odpověď Import keytabu.

Aktualizace keytabu¶

Aktualizuje metadata keytabu nebo nahrazuje binární soubor. Při změně binárního obsahu je automaticky vytvořen nový záznam verze.

PUT /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010 HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "app-service-keytab-v2",
  "keytab_data": "<nový binární keytab zakódovaný v base64>",
  "expires_at": "2028-04-01T00:00:00Z",
  "notes": "Aktualizováno po roční rotaci klíčů Kerberos",
  "status": "active"
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`name`	string	—	Nový zobrazovaný název
`keytab_data`	string	—	Nový binární soubor keytabu zakódovaný v base64
`expires_at`	string (ISO 8601)	—	Nové datum expirace
`notes`	string	—	Aktualizované poznámky
`status`	string	—	Nový stav (`active`, `disabled`)

Odpověď `200 OK`¶

Vrátí aktualizovaný objekt KeyTabResponse s inkrementovanou hodnotou version.

Smazání keytabu¶

Provede soft-delete keytabu. Keytab není trvale odstraněn a lze ho dohledat v auditním logu.

DELETE /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010 HTTP/1.1
Authorization: Bearer <token>

Odpověď `204 No Content`¶

Stažení keytabu¶

Vrátí surový binární soubor keytabu. Odpověď je binární soubor s Content-Type: application/octet-stream.

GET /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010/download HTTP/1.1
Authorization: Bearer <token>

Odpověď `200 OK`¶

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="app-service-keytab.keytab"

<binární data keytabu>

Řízení přístupu

Stažení binárních dat keytabu vyžaduje zvýšená oprávnění. Všechna stažení jsou zaznamenána v auditním logu.

Historie verzí keytabu¶

Vrátí kompletní seznam verzí keytabu, seřazený od nejnovější.

GET /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010/history HTTP/1.1
Authorization: Bearer <token>

Odpověď `200 OK`¶

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "keytab_id": "kt_550e8400-e29b-41d4-a716-446655440010",
    "version": 2,
    "encryption_types": ["aes256-cts-hmac-sha1-96"],
    "kvno": 6,
    "keytab_hash": "a665a45920422f9d417e4867efdc4fb8",
    "changed_by": "550e8400-e29b-41d4-a716-446655440099",
    "change_reason": "Roční rotace klíčů Kerberos",
    "created_at": "2027-04-01T08:00:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440021",
    "keytab_id": "kt_550e8400-e29b-41d4-a716-446655440010",
    "version": 1,
    "encryption_types": ["aes256-cts-hmac-sha1-96", "aes128-cts-hmac-sha1-96"],
    "kvno": 5,
    "keytab_hash": "e3b0c44298fc1c149afbf4c8996fb924",
    "changed_by": "550e8400-e29b-41d4-a716-446655440099",
    "change_reason": "Počáteční import",
    "created_at": "2026-04-26T10:00:00Z"
  }
]

Kontrola souladu šifer¶

Vyhodnotí soulad šifer jednoho keytabu s aktuální šifrovou politikou organizace a aktualizuje uložený stav cipher_compliance.

POST /api/v1/keytabs/kt_550e8400-e29b-41d4-a716-446655440010/check-compliance HTTP/1.1
Authorization: Bearer <token>

Odpověď `200 OK`¶

{
  "cipher_compliance": "warning",
  "cipher_violations": {
    "aes128-cts-hmac-sha1-96": "zastaralá šifra — naplánováno pro odebrání"
  }
}

Hodnoty stavu souladu¶

Hodnota	Význam
`compliant`	Všechny typy šifer jsou v povoleném seznamu organizace
`warning`	Jeden nebo více typů je v zastaralém seznamu, ale zatím není zablokován
`non_compliant`	Jeden nebo více typů není v povoleném seznamu (zablokováno, pokud je `enforcement_mode` nastaven na `enforce`)

Obnovení souladu všech keytabů¶

Přehodnotí soulad šifer všech keytabů v organizaci oproti aktuální šifrové politice. Vhodné spustit po aktualizaci politiky.

POST /api/v1/keytabs/refresh-compliance HTTP/1.1
Authorization: Bearer <token>

Odpověď `200 OK`¶

{
  "updated": 14
}

Získání šifrové politiky¶

Vrátí aktuální šifrovou politiku organizace pro vynucování u keytabů.

GET /api/v1/keytabs/cipher-policy HTTP/1.1
Authorization: Bearer <token>

Odpověď `200 OK`¶

{
  "id": "550e8400-e29b-41d4-a716-446655440050",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "allowed_ciphers": [
    "aes256-cts-hmac-sha1-96",
    "aes256-cts-hmac-sha384-192"
  ],
  "deprecated_ciphers": [
    "aes128-cts-hmac-sha1-96"
  ],
  "enforcement_mode": "warn",
  "created_at": "2026-04-26T10:00:00Z",
  "updated_at": "2026-04-26T10:00:00Z"
}

Aktualizace šifrové politiky¶

Nastaví seznamy povolených a zastaralých šifer a režim vynucování pro organizaci.

PUT /api/v1/keytabs/cipher-policy HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "allowed_ciphers": [
    "aes256-cts-hmac-sha1-96",
    "aes256-cts-hmac-sha384-192"
  ],
  "deprecated_ciphers": [
    "aes128-cts-hmac-sha1-96"
  ],
  "enforcement_mode": "warn"
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`allowed_ciphers`	pole řetězců	✅	Šifrové sady povolené pro spravované keytaby
`deprecated_ciphers`	pole řetězců	✅	Šifrové sady aktivující varování `warning` (musí být podmnožinou `allowed_ciphers`)
`enforcement_mode`	string	✅	`warn` — pouze označit porušení; `enforce` — odmítnout keytaby s nepovolenými šiframi

Odpověď `200 OK`¶

Vrátí aktualizovaný objekt CipherPolicyResponse.

Po aktualizaci politiky

Po aktualizaci šifrové politiky spusťte Obnovení souladu všech keytabů pro okamžité přehodnocení všech uložených keytabů.

Seznam nalezených keytabů¶

Zobrazuje keytab soubory nalezené na hostitelích agentů při automatickém skenování filesystému. Nalezené keytaby lze zkontrolovat a selektivně importovat do správy.

GET /api/v1/keytabs/discovered?page=1&limit=25 HTTP/1.1
Authorization: Bearer <token>

Parametry dotazu¶

Parametr	Typ	Popis
`page`	integer	Číslo stránky (výchozí: 1)
`limit`	integer	Položek na stránku (výchozí: 25, max: 100)

Odpověď `200 OK`¶

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440060",
      "organization_id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "550e8400-e29b-41d4-a716-446655440070",
      "file_path": "/etc/security/keytabs/app-svc.keytab",
      "principal": "app-svc@CORP.EXAMPLE.COM",
      "realm": "CORP.EXAMPLE.COM",
      "encryption_types": ["aes256-cts-hmac-sha1-96"],
      "kvno": 5,
      "file_permissions": "0600",
      "file_owner": "app-svc",
      "keytab_hash": "e3b0c44298fc1c149afbf4c8996fb924",
      "is_managed": false,
      "managed_keytab_id": null,
      "state": "discovered",
      "discovered_at": "2026-04-25T06:00:00Z",
      "last_seen_at": "2026-04-26T06:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 25
}

Hodnoty stavu nalezeného keytabu¶

Stav	Význam
`discovered`	Nalezen agentem, dosud nezpracován
`imported`	Importován do správy MazeVault
`ignored`	Označen jako nevyžadující správu
`stale`	Již není přítomen na hostitelském počítači agenta

Import nalezeného keytabu¶

Importuje nalezený keytab do plné správy MazeVault. Agent nahraje binární soubor keytabu, který je uložen, zparsován a zkontrolován na soulad šifer.

POST /api/v1/keytabs/discovered/550e8400-e29b-41d4-a716-446655440060/import HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "app-svc-discovered",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "expires_at": "2027-04-01T00:00:00Z"
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`name`	string	—	Zobrazovaný název (výchozí je principal keytabu, pokud není zadán)
`project_id`	string (UUID)	—	Přiřadí keytab k projektu
`expires_at`	string (ISO 8601)	—	Datum expirace

Odpověď `201 Created`¶

Vrátí kompletní objekt KeyTabResponse pro nově spravovaný keytab. Pole source je nastaveno na discovered.

Dashboard keytabů¶

Vrátí agregované statistiky o všech keytabech v organizaci pro zobrazení v dashboardu.

GET /api/v1/keytabs/dashboard HTTP/1.1
Authorization: Bearer <token>

Odpověď `200 OK`¶

{
  "overview": {
    "total": 42,
    "active": 38,
    "expiring_soon": 4,
    "expired": 1,
    "disabled": 0,
    "non_compliant": 2,
    "warning": 5
  },
  "cipher_distribution": [
    {
      "cipher": "aes256-cts-hmac-sha1-96",
      "count": 38
    },
    {
      "cipher": "aes128-cts-hmac-sha1-96",
      "count": 6
    }
  ],
  "expiring_keytabs": [
    {
      "id": "kt_550e8400-e29b-41d4-a716-446655440010",
      "name": "app-service-keytab",
      "principal": "app-svc@CORP.EXAMPLE.COM",
      "expires_at": "2026-05-10T00:00:00Z",
      "days_remaining": 14
    }
  ]
}

Chybové odpovědi¶

Všechny endpointy používají standardní chybové odpovědi MazeVault:

HTTP Status	Význam
`400 Bad Request`	Neplatné tělo požadavku, chybějící povinná pole nebo nečitelný binární soubor keytabu
`401 Unauthorized`	Chybějící nebo neplatný bearer token
`403 Forbidden`	Nedostatečná oprávnění role pro požadovanou operaci
`404 Not Found`	ID keytabu nebo nalezeného keytabu neexistuje
`409 Conflict`	Keytab se stejným hashem již v organizaci existuje (duplicitní import)
`503 Service Unavailable`	Správa KeyTab je zakázána (`MAZEVAULT_KEYTAB_ENABLED=false`)

API pro KeyTab¶

Přehled endpointů¶

Import keytabu¶

Pole požadavku¶

Odpověď 201 Created¶

Seznam keytabů¶

Parametry dotazu¶

Odpověď 200 OK¶

Získání keytabu¶

Odpověď 200 OK¶

Aktualizace keytabu¶

Pole požadavku¶

Odpověď 200 OK¶

Smazání keytabu¶

Odpověď 204 No Content¶

Stažení keytabu¶

Odpověď 200 OK¶

Historie verzí keytabu¶

Odpověď 200 OK¶

Kontrola souladu šifer¶

Odpověď 200 OK¶

Hodnoty stavu souladu¶

Obnovení souladu všech keytabů¶

Odpověď 200 OK¶

Získání šifrové politiky¶

Odpověď 200 OK¶

Aktualizace šifrové politiky¶

Pole požadavku¶

Odpověď 200 OK¶

Seznam nalezených keytabů¶

Parametry dotazu¶

Odpověď 200 OK¶

Hodnoty stavu nalezeného keytabu¶

Import nalezeného keytabu¶

Pole požadavku¶

Odpověď 201 Created¶

Dashboard keytabů¶

Odpověď 200 OK¶

Chybové odpovědi¶

Viz také¶

Odpověď `201 Created`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `204 No Content`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `201 Created`¶

Odpověď `200 OK`¶