Ротация и изтриване на ключове
На тази страница
Ротация: Подновяване без прекъсване
Ротацията на ключове е критична практика за сигурност. Тя генерира нов секретен ключ, който замества стария, без да изтрива самия ключ. Старият секрет се инвалидира незабавно и окончателно.
Извършване на ротация
Ротацията решава проблем, който изтриването не може: подновяване на секрета без загуба на идентичността на ключа. Неговите ACL (списъци за контрол на достъпа), лимити на честотата и име оцеляват след операцията, така че не е необходимо да преконфигурирате нищо – само секретът се променя във вашето хранилище. Това прави редовната ротация практична; повторното създаване на ключ би изисквало преконфигуриране на всичко всеки път.
POST /auth/api-keys/{apiKeyId}/rotate
curl -X POST "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/rotate" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Поведение при ротация
- Старият секретен ключ се незабавно инвалидира – всякакви заявки, използващи го, ще върнат грешка 401
- Генерира се нов секретен ключ и се връща в отговора
- ID на ключа (
apiKeyId), името, ACL и лимитите на честотата остават непроменени - Новият секретен ключ се показва само веднъж – съхранете го незабавно
Процес на сигурна ротация
Една част от тази процедура заслужава специално внимание, защото често изненадва потребителите: старият секрет се инвалидира незабавно. Няма гратисен период, в който двата секрета да работят едновременно. Всички услуги, които все още използват старата стойност, ще се провалят в секундата след извикването. Това диктува реда на шестте стъпки по-долу: подгответе вашето хранилище преди да задействате ротацията, а не след това.
- Подгответе инфраструктурата си да приеме нов ключ (променлива на средата, хранилище)
- Извършете ротацията чрез API
- Актуализирайте секрета във вашето хранилище незабавно
- Преинсталирайте (Redeploy) услугите си с новия ключ
- Верифицирайте, че заявките успяват с новия ключ
- Верифицирайте разпространението чрез
GET /auth/api-keys/{apiKeyId}/propagation
Кога да ротирате
Три ситуации задействат ротация, всяка с различна спешност. Подозрение за изтичане изисква незабавна ротация: член на екипа с достъп до ключа напуска, лог файл, съдържащ ключ, е изложен публично или Git хранилище съдържа ключ в чист текст. В тези случаи всеки час чакане е час излагане на риск, затова ротацирайте преди да завършите анализа на инцидента. Ротацията базирана на политики е превантивна: на всеки 30, 60 или 90 дни, в зависимост от вашите изисквания за сигурност, тя ограничава живота на ключ, който може да е изтекъл незабелязано. Накрая, промените в средата – миграция на инфраструктура или смяна на доставчици – са естествена възможност да започнете отначало с чисти ключове, вместо да пренасяте стари такива в контекст, за който не са били проектирани.
Изтриване на ключ
Изтриването е окончателно и необратимо. Въпросът, който трябва да си зададете преди изтриване, не е „Този ключ компрометиран ли е?“, а „Все още ли имам нужда от този обхват на достъп?“. Ако отговорът е „да“, ви трябва ротация: тя неутрализира изложения секрет, запазвайки конфигурацията. Изтриването е оправдано само за ключ, който вече не е полезен – спрян проект, напуснал доставчик или деактивирана среда.
DELETE /auth/api-keys/{apiKeyId}
curl -X DELETE "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Последствия от изтриването
- Ключът и всички негови параметри се окончателно изтриват
- Всички заявки, използващи този ключ, ще се провалят незабавно
- Действието е необратимо – ще трябва да създадете нов ключ с нови параметри
- Историята на използване на ключа остава налична в аналитиките
Ротация срещу изтриване
| Аспект | Ротация | Изтриване |
|---|---|---|
| Ключът все още съществува | Да | Не |
| Генериран нов секрет | Да | Не |
| Запазени ACL | Да | Не |
| Запазени лимити | Да | Не |
| Обратимо | Не (старият секрет е загубен) | Не (ключът е изтрит) |
| Типична употреба | Редовно подновяване | Остарял ключ или потвърдена компрометация |
Автоматизиране на ротацията
Автоматизираната ротация има смисъл само ако записването в хранилището е част от същия скрипт, без човешка намеса между тях. В противен случай просто премествате риска: секретен ключ, генериран от машина и копиран на ръка, е по-вероятно да попадне в клипборда или историята на терминала, отколкото ключ, създаден от конзолата.
import requests
import json
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
KEY_ID = "key-123"
# Rotate
response = requests.post(
f"{MANAGEMENT_API}/auth/api-keys/{KEY_ID}/rotate",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
new_key = response.json()
new_secret = new_key.get("secret")
# Store in your vault (example with a .env file)
# In production, use Vault, AWS Secrets Manager, etc.
print(f"New key generated. Update your vault.")
Планирана ротация
Интегрирайте ротацията във вашия CI/CD пайплайн или като cron задача:
# Cron example: rotation on the 1st of each month at 3 AM
0 3 1 * * /opt/scripts/rotate-xai-keys.sh
Ключови изводи
POST /auth/api-keys/{apiKeyId}/rotateинвалидира стария секрет и генерира нов- Инвалидирането на стария секрет е незабавно и окончателно
DELETE /auth/api-keys/{apiKeyId}изтрива ключа необратимо- Предпочитайте ротация пред изтриване, за да запазите съществуващите ACL и лимити
- Автоматизирайте ротацията със скрипт и хранилище за секрети
- Винаги верифицирайте разпространението след ротация