> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-center/kilo-mioty-service-center/security/security-basics.md).

# Noções Básicas de Segurança

Noções básicas de segurança do KiloCenter — credenciais predefinidas a alterar, caminhos dos certificados TLS e reforço mínimo para implementações partilhadas.

### Objetivo

Estabeleça uma base segura para implementações do KiloCenter.

### Credenciais predefinidas

O desenvolvimento local inclui credenciais de conveniência que devem ser alteradas para qualquer ambiente partilhado ou de produção:

| Serviço     | Predefinido                                        | Observações                                          |
| ----------- | -------------------------------------------------- | ---------------------------------------------------- |
| PostgreSQL  | utilizador `kilocenter`, palavra-passe `altera-me` | Alterar em `config.yaml` e Docker Compose            |
| broker MQTT | utilizador `admin`, palavra-passe `KiloCenter`     | Alterar na configuração do Mosquitto e `config.yaml` |

### TLS para a comunicação entre a estação base e o centro de aplicações

O BSSCI requer TLS 1.2 ou superior. O SCACI requer TLS 1.3 ou superior. Todas as ligações ao KC-Core usam encriptação TLS.

#### Modelo de confiança da CA

O KiloCenter usa uma Autoridade de Certificação (CA) autoassinada para emitir todos os certificados:

| Certificado               | Finalidade                                      | Validade predefinida | Localização               |
| ------------------------- | ----------------------------------------------- | -------------------- | ------------------------- |
| certificado CA            | Raiz de confiança; distribuído às estações base | 20 anos              | `certificates/ca.crt`     |
| chave privada da CA       | Assina certificados de servidor e cliente       | --                   | `certificates/ca.key`     |
| Certificado do servidor   | ouvintes TLS BSSCI/SCACI do KC-Core             | 1 ano                | `certificates/server.crt` |
| Chave privada do servidor | handshake TLS                                   | --                   | `certificates/server.key` |
| Certificado do cliente    | TLS mútuo por estação base (opcional)           | 1 ano                | Gerado sob pedido         |

As estações base confiam na **certificado CA**, e não em certificados de servidor individuais. Isto significa que os certificados de servidor podem ser renovados sem mexer nas estações base, desde que a mesma CA os assine.

Se regenerar a CA, todos os certificados de servidor e cliente existentes tornam-se inválidos e têm de ser reemitidos. Faça uma cópia de segurança de `ca.key` de forma segura.

#### Geração de certificados

**Gerar certificados da CA + do servidor (configuração inicial)**

Não é necessário o toolchain Go no anfitrião — use o `certgen` serviço compose:

```bash
docker compose run --rm certgen
```

> **Propriedade dos arquivos (Linux):** Se os arquivos gerados pertencerem ao root, execute novamente com `UID=$(id -u) GID=$(id -g)` como prefixo.

Para um FQDN de produção:

```bash
docker compose run --rm certgen -dir /app/certificates -days 365 -server bssci.example.com
```

Isto cria quatro ficheiros em `KC-Core/certificates/`:

* `ca.crt` e `ca.key` -- certificado CA e chave privada
* `server.crt` e `server.key` -- certificado do servidor e chave privada

O certificado do servidor inclui automaticamente `localhost`, `127.0.0.1`, `0.0.0.0`, e todos os IPs da rede local como Nomes Alternativos do Assunto (SANs).

**Gerar um certificado de cliente**

```bash
docker compose run --rm certgen \
    -dir /app/certificates -client-only -client 70-B3-D5-9C-D0-00-09-E6
```

**Referência do certgen**

| Opção          | Predefinido | Descrição                                                                        |
| -------------- | ----------- | -------------------------------------------------------------------------------- |
| `-dir`         | `certs`     | Diretório de saída para os ficheiros de certificados                             |
| `-server`      | `localhost` | Nome do anfitrião do servidor (usado como CN e SAN)                              |
| `-days`        | `365`       | Validade do certificado do servidor/cliente em dias                              |
| `-ca-years`    | `20`        | Validade do certificado da CA em anos                                            |
| `-ca-only`     | `falso`     | Gerar apenas o certificado da CA                                                 |
| `-server-only` | `falso`     | Gerar apenas o certificado do servidor (a CA já deve existir)                    |
| `-client-only` | `falso`     | Gerar apenas um certificado de cliente (a CA já deve existir)                    |
| `-client`      | (vazio)     | Nome do cliente para o certificado de cliente (por exemplo, EUI da estação base) |

**Cenários comuns**

**Renovar apenas o certificado do servidor (a CA já existe):**

```bash
docker compose run --rm certgen \
    -dir /app/certificates -server bssci.example.com -server-only
```

#### Rotação de certificados

**Via compose** (recomendado para automatização):

```bash
docker compose run --rm certgen \
    -dir /app/certificates -server bssci.example.com -server-only
docker compose restart kilocenter
```

**Via interface gráfica** (renovação pós-instalação):

1. Abra o KC-Web e navegue até **Certificados**.
2. Clica em **Renovar certificados do servidor** e confirme.
3. Reinicie o KC-Core para carregar os novos certificados.

**Após a rotação:**

1. Reinicie o KC-Core para carregar os novos certificados.
2. Verifique se as reconexões das estações base são bem-sucedidas.
3. Se a CA tiver sido alterada, redistribua `ca.crt` para todas as estações base.

#### Configuração de certificados

O KC-Core carrega certificados a partir dos caminhos configurados em `config.yaml` (código-fonte de desenvolvimento) ou `config/config.docker.yaml` (contentor):

```yaml
protocolo:
  bsci_tls:
    enabled: true
    cert_file: "certificates/server.crt"
    key_file: "certificates/server.key"
    ca_file: "certificates/ca.crt"
    min_version: "1.2"
  scaci_tls:
    enabled: true
    cert_file: "certificates/server.crt"
    key_file: "certificates/server.key"
    ca_file: "certificates/ca.crt"
    min_version: "1.3"
```

Os caminhos no modo de desenvolvimento de código-fonte são relativos ao diretório de trabalho do KC-Core. O KC-Core falhará ao iniciar se estes ficheiros estiverem em falta.

### Exposição de rede

Limite quais portas estão acessíveis a partir de fora da sua rede local:

| Porta | Serviço                 | Recomendação de exposição                 |
| ----- | ----------------------- | ----------------------------------------- |
| 5000  | BSSCI                   | Apenas redes de estações base             |
| 5001  | SCACI                   | Apenas anfitriões do centro de aplicações |
| 9090  | KC-Gateway (gRPC-web)   | Redes de operadores e consumidores da API |
| 80    | KC-Web (container)      | Apenas redes de operadores                |
| 50051 | gRPC interno do KC-Core | Apenas loopback, nunca expor externamente |
| 5433  | PostgreSQL              | Apenas loopback                           |
| 6379  | Redis                   | Apenas loopback                           |
| 1883  | MQTT                    | Apenas redes de consumidores MQTT         |

### Lista de verificação de reforço de segurança

* [ ] Rode todas as credenciais predefinidas listadas acima
* [ ] Restrinja o acesso à rede às portas de gestão (50051, 5433, 6379)
* [ ] Armazene as chaves privadas dos certificados com permissões de ficheiro restritas
* [ ] Ative o registo ao nível de auditoria em ambientes de produção
* [ ] Rever `config.yaml` para quaisquer predefinições de desenvolvimento restantes

### Edição Enterprise

A Edição Enterprise acrescenta funcionalidades de segurança multi-inquilino:

* Autenticação de utilizador com validação de JWT
* Isolamento de dados ao nível da organização
* Controlo de acesso baseado em funções

Estas funcionalidades não estão disponíveis na Edição Community.


---

# 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.kiloiot.io/kilo-docs-pt/kilo-center/kilo-mioty-service-center/security/security-basics.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.