> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/gateway/tls-certificates.md).

# TLS ve certificate

Kangal server certificate'larını, hostname-to-certificate eşlemelerini ve CA certificate'larını gateway configuration olarak saklar. Bu kaynakları Kangal configuration bundle'ını kullanan data plane veya edge bileşenine TLS materyali sağlamak için kullanın.

## TLS kaynak türleri

| Kaynak         | Amaç                                                                    | Private key içerir |
| -------------- | ----------------------------------------------------------------------- | ------------------ |
| Certificate    | TLS kimliğini sunmak için kullanılan server certificate ve private key. | Evet               |
| SNI            | `api.example.com` gibi bir hostname'i certificate ile eşler.            | Hayır              |
| CA certificate | TLS veya authentication policy tarafından kullanılan trust anchor.      | Hayır              |

Certificate, CA certificate ve SNI eşlemeleri data-plane configuration bundle'ına eklenir. Serving edge bu kaynakları kullanacak ve TLS'i sonlandıracak şekilde yapılandırılmalıdır. Her değişiklikten sonra bundle ACK durumunu ve public listener'ın sunduğu certificate'ı doğrulayın.

## Certificate yüklemeden önce

PEM formatındaki certificate chain ile eşleşen PEM formatındaki private key'i hazırlayın. Leaf certificate'ı ilk sıraya, client'ların ihtiyaç duyduğu intermediate certificate'ları ardından yerleştirin. PKI politikanız özellikle gerektirmiyorsa root CA'yı sunulan chain'e eklemeyin.

Operatörler yüklemeden önce certificate chain'i, certificate/key eşleşmesini, geçerlilik ve sona erme tarihlerini ve sunulan her hostname için SAN kapsamını doğrulamalıdır.

Certificate'ı inceleyin:

```bash
openssl x509 -in tls.crt -noout -subject -issuer -serial -dates \
  -ext subjectAltName
```

Certificate ile key'in public key değerlerini karşılaştırın:

```bash
umask 077

openssl x509 -in tls.crt -pubkey -noout \
  | openssl pkey -pubin -outform DER \
  | openssl sha256

openssl pkey -in tls.key -pubout -outform DER \
  | openssl sha256
```

İki SHA-256 değeri eşleşmelidir. Chain'i trust bundle ile de doğrulayın:

```bash
openssl verify -CAfile root-ca.pem -untrusted intermediate-ca.pem tls.crt
```

## Certificate yükleme

### Console adımları

1. Bir gateway açın ve **Certificates** bölümünü seçin.
2. **Create certificate** seçeneğini seçin.
3. Kalıcı ve anlaşılır bir ad girin.
4. Certificate chain'i certificate alanına yapıştırın.
5. Eşleşen private key'i key alanına yapıştırın.
6. Kaydedin ve sunulacak her hostname için bir SNI eşlemesi oluşturun.

Certificate adları tenant başına benzersizdir. Hostname ve environment içeren bir adlandırma standardı kullanın; örneğin `api-example-com-prod`.

### Admin API

```bash
umask 077
set -e
certificate_payload="$(mktemp)"
trap 'rm -f "$certificate_payload"' EXIT

export KANGAL_ADMIN_URL="https://control.example.com"
export KANGAL_TOKEN="replace-with-admin-token"
export KANGAL_TENANT_ID="tenant_123"
export KANGAL_GATEWAY_ID="gateway_123"

jq -n \
  --arg tenant_id "$KANGAL_TENANT_ID" \
  --arg name "api-example-com-prod" \
  --rawfile cert_pem tls.crt \
  --rawfile key_pem tls.key \
  '{tenant_id: $tenant_id, name: $name, cert_pem: $cert_pem, key_pem: $key_pem}' \
  > "$certificate_payload"

curl -sS -X POST \
  "$KANGAL_ADMIN_URL/api/v1/admin/gateways/$KANGAL_GATEWAY_ID/certificates" \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary "@$certificate_payload"

rm -f "$certificate_payload"
trap - EXIT
```

Response, PEM değerleri yerine şu metadata alanlarını döndürür:

* `id`
* `tenant_id`
* `name`
* `cert_digest`
* `previous_cert_digest`
* `rotation_version`
* `rotated_at`

Dönen `id` değerini kaydedin; SNI eşlemeleri bu değeri `certificate_id` olarak kullanır.

## Hostname'i SNI ile eşleme

Certificate'ın sunulacağı her hostname için bir SNI kaynağı oluşturun:

```bash
export KANGAL_CERTIFICATE_ID="certificate_123"

curl -sS -X POST \
  "$KANGAL_ADMIN_URL/api/v1/admin/gateways/$KANGAL_GATEWAY_ID/snis" \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "'"$KANGAL_TENANT_ID"'",
    "name": "api.example.com",
    "certificate_id": "'"$KANGAL_CERTIFICATE_ID"'",
    "labels": {"environment": "production"},
    "tags": ["public"],
    "metadata": {"owner": "platform"}
  }'
```

Certificate aynı gateway ve tenant'a ait olmalıdır. Aynı hostname ve certificate ile yinelenen istek mevcut eşlemeyi döndürür. Aynı hostname'i farklı bir certificate ile eşleme isteği `409 Conflict` döndürür.

Custom-domain otomasyonu tarafından yönetilen hostname'leri custom-domain akışından yönetin. Böylece certificate yenileme ve SNI sahipliği aynı kaynak üzerinden sürdürülür.

SNI eşlemesi TLS hostname için certificate materyalini seçer. Route `snis` alanları ise request matcher'dır; bunları route seçiminin de TLS server name'e bağlı olması gerektiğinde kullanın.

## Certificate rotasyonu

Yeni certificate ve key'i doğruladıktan sonra rotation işlemini kullanın:

```bash
umask 077
set -e
rotation_payload="$(mktemp)"
trap 'rm -f "$rotation_payload"' EXIT

export KANGAL_CERTIFICATE_ID="certificate_123"

jq -n \
  --arg name "api-example-com-prod" \
  --arg rotated_by "platform-rotation" \
  --rawfile cert_pem tls-new.crt \
  --rawfile key_pem tls-new.key \
  '{name: $name, cert_pem: $cert_pem, key_pem: $key_pem, rotated_by: $rotated_by}' \
  > "$rotation_payload"

curl -sS -X POST \
  "$KANGAL_ADMIN_URL/api/v1/admin/gateways/$KANGAL_GATEWAY_ID/certificates/$KANGAL_CERTIFICATE_ID/rotate" \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary "@$rotation_payload"

rm -f "$rotation_payload"
trap - EXIT
```

Rotation için hem `cert_pem` hem `key_pem` zorunludur. İşlem aktif materyali değiştirir, `rotation_version` değerini artırır, önceki digest'i kaydeder ve rotation history'ye bir kayıt ekler. Mevcut SNI kaynakları aynı certificate ID'sine başvurmaya devam eder.

Değişikliği configuration rollout ve edge reload süreciyle koordine edin. Yeni listener doğrulanana kadar önceki certificate ve key'i onaylı secret backup sürecinizde saklayın.

Canlı endpoint'i doğrulayın:

```bash
openssl s_client -connect api.example.com:443 \
  -servername api.example.com -showcerts </dev/null
```

Sunulan certificate fingerprint'ini yeni materyalle karşılaştırın:

```bash
openssl x509 -in tls-new.crt -noout -fingerprint -sha256
```

## CA certificate ekleme

CA certificate'ları trust materyalidir ve private key içermez. Client-certificate authentication policy veya başka bir TLS consumer CA'ya ihtiyaç duyduğunda oluşturun:

```bash
curl -sS -X POST \
  "$KANGAL_ADMIN_URL/api/v1/admin/gateways/$KANGAL_GATEWAY_ID/ca-certificates" \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg tenant_id "$KANGAL_TENANT_ID" \
    --arg name "partner-client-ca" \
    --rawfile cert_pem partner-ca.crt \
    '{tenant_id: $tenant_id, name: $name, cert_pem: $cert_pem,
      labels: {purpose: "client-auth"}}')"
```

API, CA PEM değerini ve SHA-256 digest'ini döndürür. Aynı ad ve digest ile yinelenen istek mevcut kaynağı döndürür; aynı adla farklı materyal gönderilirse `409 Conflict` alınır.

Mutual TLS uygulamak için CA kaynağını oluşturduktan sonra client certificate isteyen ve doğrulayan authentication plugin'ini veya edge policy'yi de yapılandırın.

## Güvenli güncelleme ve silme

Certificate update işlemi `name`, `cert_pem`, `key_pem` ve `tenant_id` alanlarını kabul eder. Aktif certificate değişimlerinde rotation metadata'sını korumak için rotation işlemini tercih edin. Console edit akışı ad, certificate ve key'in tamamını ister; formu açmadan önce üçünü de hazırlayın.

SNI update işlemi `name`, `certificate_id`, `labels`, `tags` ve `metadata` alanlarını kabul eder. Hostname'i önceden doğrulanmış başka bir certificate'a taşımak için bu işlemi kullanabilirsiniz.

Certificate'ı silmeden önce ona başvuran tüm SNI kayıtlarını silin veya başka bir certificate'a yönlendirin. CA certificate silmeden önce onu kullanan tüm authentication ve edge policy'lerini güncelleyin.

## Güvenlik gereksinimleri

* Certificate API isteklerini, geçici JSON dosyalarını, terminal history'yi, audit erişimini, backup'ları ve database erişimini secret içeren yüzeyler olarak yönetin.
* Private key saklayan certificate kayıtları için encrypted database storage, encrypted backup, katı tenant-scoped authorization ve sınırlı operator erişimi kullanın.
* PEM key'lerini doğrudan shell argümanlarına eklemek yerine `--data-binary @file` veya üretilmiş JSON dosyaları kullanın.
* Private-key içeren shell akışlarını `umask 077` ile başlatın; secret içeren her geçici dosya için cleanup trap tanımlayın ve dosyayı kullanımdan hemen sonra kaldırın.
* Private key'leri labels, tags, metadata, route configuration veya support kayıtlarına eklemeyin.
* Expiry durumunu dış izleme ile takip edin ve önceki certificate sona ermeden rollout ile edge doğrulamasını tamamlayacak kadar erken rotate edin.

## Sorun giderme

### API certificate'ı kabul ediyor ancak listener kullanamıyor

OpenSSL doğrulama adımlarını yeniden çalıştırın. PEM sınırlarını, chain sırasını, key eşleşmesini, key passphrase gereksinimini, expiry tarihini, SAN kapsamını ve edge bileşeninin desteklediği algoritmaları kontrol edin.

### Client'lar yanlış certificate alıyor

Client'ın beklenen SNI hostname'i gönderdiğini, SNI kaynağındaki `certificate_id` değerinin doğru olduğunu ve serving edge'in son bundle'ı ACK edip yüklediğini doğrulayın. IP ile yapılan bağlantı yerine `openssl s_client -servername` kullanarak test edin.

### SNI oluşturma `400` döndürüyor

Certificate ve SNI tenant ID'lerinin aynı olduğunu ve certificate'ın aynı gateway'e ait olduğunu doğrulayın.

### SNI oluşturma `409` döndürüyor

Hostname başka bir certificate ile eşlenmiştir veya custom domain tarafından yönetiliyordur. İkinci bir eşleme oluşturmak yerine hostname'in sahibi olan kaynağı güncelleyin.

### Rotation metadata değişti ancak client'lar eski certificate'ı görüyor

Serving data plane veya dış edge'in yeni configuration'ı yüklediğini kontrol edin. Bundle ACK durumunu, edge reload sonucunu, DNS hedefini ve load balancer arkasındaki tüm listener'ları doğrulayın.

### Mutual TLS hiçbir client'ı kabul etmiyor

CA kaynağının etkin client-certificate authentication policy tarafından kullanıldığını, edge'in client certificate istediğini ve client'ların gerekli chain'in tamamını gönderdiğini doğrulayın.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/tr/gateway/tls-certificates.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.