Manual: como usar Secure Properties no MuleSoft
Passo a passo para gerar propriedades seguras no painel e usá-las em uma aplicação Mule 4, no Anypoint Studio e no CloudHub.
1 Usando o painel
O painel criptografa e descriptografa direto no seu navegador. A chave e os valores não são enviados para nenhum servidor.
1.1 Antes de começar: decida a chave e as opções
Anote quatro informações. Elas precisam ser exatamente as mesmas na aplicação Mule, senão a descriptografia falha:
- Chave: texto secreto de no mínimo 16 caracteres. Com exatamente 32 caracteres o AES usa 256 bits; com 16, usa 128 bits.
- Algoritmo: AES, Blowfish, DES, DESede ou RC2. Na dúvida, use AES, que é o padrão do Mule.
- Mode: CBC, CFB, ECB ou OFB. O padrão do Mule é CBC.
- IV aleatório: ligado ou desligado. O padrão do Mule é desligado.
1234567890123456): nunca use essa chave em produção.1.2 Criptografar um valor (aba String)
- Abra o painel e deixe a aba String selecionada.
- Em Operação, escolha Encrypt.
- Escolha o Algoritmo e o Mode e, se quiser, ligue Usar random IV.
- Digite a Key (a chave secreta).
- No campo Value, escreva o valor que quer proteger, por exemplo a senha do banco.
- Clique em Gerar e depois no ícone de copiar, no canto direito do campo Resultado.
O resultado vem no formato que o Mule entende. Com AES, CBC, sem IV aleatório, a chave de demonstração e o valor hello world, você obtém:
![bAx40eFUVf/hIxbaV8/GaQ==]
Esse texto, com o ![ no início e o ] no final, é o que vai dentro do arquivo de propriedades.
1.3 Conferir um valor (descriptografar)
- Em Operação, escolha Decrypt.
- Use o mesmo algoritmo, mode, IV aleatório e chave da criptografia.
- Cole o valor em Value, com ou sem o
![...], e clique em Gerar.
Se a chave ou as opções estiverem diferentes, aparece uma mensagem de erro em vermelho, ou um texto sem sentido.
1.4 Criptografar um arquivo YAML inteiro (aba YAML)
Use quando você tem várias propriedades de uma vez.
- Abra a aba YAML.
- Escolha Encrypt, o algoritmo, o mode, o IV aleatório e digite a Key.
- Selecione o arquivo em Arquivo YAML ou cole o conteúdo no campo Conteúdo.
- Clique em Processar YAML. Todos os valores do tipo
chave: valorviram![...]. Comentários, listas e linhas vazias são mantidos. - Clique em Baixar resultado para salvar o arquivo.
Exemplo, antes e depois:
# antes
db:
host: localhost
password: hello world
# depois
db:
host: ![xxxxxxxxxxxxxxxxxxxxxx==]
password: ![bAx40eFUVf/hIxbaV8/GaQ==]
secure-config.yaml, e mantenha as demais em um arquivo comum.Para ler um arquivo já criptografado, escolha Decrypt, informe a mesma chave e as mesmas opções e clique em Processar YAML.
1.5 A aba "Arquivo inteiro"
Criptografa qualquer arquivo e gera um arquivo .encrypted em Base64. É útil para guardar arquivos com segurança e descriptografá-los depois aqui mesmo.
fileLevelEncryption do Mule. Para usar na aplicação Mule, prefira as abas String e YAML.2 Usando na aplicação Mule 4
Com os valores criptografados em mãos, siga os passos abaixo no seu projeto.
2.1 Adicionar o módulo Secure Configuration Properties
No Anypoint Studio: abra a Mule Palette, clique em Search in Exchange, procure por Mule Secure Configuration Property Extension e adicione ao projeto.
Direto no pom.xml: adicione a dependência abaixo e troque VERSAO pela versão mais recente listada no
Exchange.
<dependency>
<groupId>com.mulesoft.modules</groupId>
<artifactId>mule-secure-configuration-property-module</artifactId>
<version>VERSAO</version>
<classifier>mule-plugin</classifier>
</dependency>
2.2 Criar o arquivo de propriedades seguras
Em src/main/resources, crie o arquivo (por exemplo secure-config.yaml) com os valores gerados no painel. Coloque o valor entre aspas e não deixe espaços antes ou depois do ]:
db:
host: "localhost"
password: "![bAx40eFUVf/hIxbaV8/GaQ==]"
] faz a descriptografia falhar.2.3 Configurar o Secure Properties Config
No Studio: Global Elements → Create → Secure Properties Config. No XML, o resultado é este:
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:secure-properties="http://www.mulesoft.org/schema/mule/secure-properties"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/secure-properties http://www.mulesoft.org/schema/mule/secure-properties/current/mule-secure-properties.xsd">
<secure-properties:config name="Secure_Properties_Config"
file="secure-config.yaml" key="${mule.key}">
<secure-properties:encrypt algorithm="AES" mode="CBC"/>
</secure-properties:config>
</mule>
Pontos importantes:
file: o nome do arquivo criado no passo anterior.key: não escreva a chave aqui. Use um placeholder como${mule.key}, que será preenchido na execução (passo 2.5).algorithmemodeprecisam ser os mesmos escolhidos no painel (AES e CBC são os padrões).- Se você ligou Usar random IV no painel, use
<secure-properties:encrypt algorithm="AES" mode="CBC" useRandomIVs="true"/>. - A tag
<secure-properties:encrypt/>é obrigatória, mesmo quando você usa os valores padrão.
2.4 Usar as propriedades no fluxo
Para ler qualquer valor do arquivo seguro, use o prefixo secure::. Isso vale também para valores que não estão criptografados no mesmo arquivo:
<db:config name="Database_Config">
<db:my-sql-connection
host="${secure::db.host}"
port="3306"
user="app_user"
password="${secure::db.password}"
database="minha_base"/>
</db:config>
<flow name="exemplo-flow">
<set-payload value="${secure::db.password}"/>
</flow>
Propriedades normais continuam sendo lidas sem prefixo, como ${http.port}.
2.5 Informar a chave ao executar a aplicação
A chave não vai no código. Ela é passada quando a aplicação sobe, com o mesmo nome que você usou em key="${mule.key}":
| Onde roda | Como informar |
|---|---|
| Anypoint Studio | Run As → Run Configurations → aba Arguments → campo VM arguments: -Dmule.key=SUA_CHAVE |
| Mule on-premises (linha de comando) | mule -M-Dmule.key=SUA_CHAVE |
| Mule on-premises (wrapper.conf) | No $MULE_HOME/conf/wrapper.conf: wrapper.java.additional.999=-Dmule.key=SUA_CHAVE |
| CloudHub / Runtime Manager | Veja o passo 2.6 abaixo: lá a chave e as propriedades têm regras próprias. |
2.6 No CloudHub (Runtime Manager): chave e propriedades
No CloudHub 1.0 os valores criptografados (![...]) ficam dentro do arquivo YAML empacotado no .jar e não aparecem na aba Properties. No Runtime Manager você cadastra a chave e, quando precisar, sobrescreve uma propriedade.
a) Esconder a chave e as propriedades sensíveis. Liste os nomes no mule-artifact.json do projeto, no campo secureProperties (adicione o campo ao arquivo que já existe):
"secureProperties": ["secure.key", "secure::db.password"]
Os nomes listados ficam mascarados no Runtime Manager e continuam assim mesmo se forem removidos do arquivo depois. Use em key="${secure.key}" o mesmo nome que você listar aqui.
b) Cadastrar a chave. Em Runtime Manager → Applications → (sua aplicação) → Settings → aba Properties, adicione a propriedade secure.key com o valor da chave e aplique a mudança.
c) Sobrescrever uma propriedade segura (opcional). Na mesma aba Properties, escreva o nome com o prefixo secure:: e informe o valor em texto puro, sem criptografia e sem o ![ ]:
| Modo de edição | Como escrever o nome |
|---|---|
| Table View | secure::db.password (sem escapar os dois-pontos) |
| Text View | secure\:\:db.password (escape os dois-pontos com barra invertida) |
![...] só é usado dentro do arquivo YAML. A documentação não descreve colar no Runtime Manager o valor já criptografado (mesmo sem o ![ ]), então esse caminho não está garantido: teste antes em um ambiente de desenvolvimento.CloudHub 2.0: o secureProperties do mule-artifact.json não mascara valores. Em Properties (Table View), preencha New Key e New Value, clique em Protect → Protect value e depois em Apply Changes (ou Deploy Application, se ainda não estiver publicada). As propriedades do Runtime Manager têm precedência sobre as do arquivo empacotado.
Referências: Safely Hide Application Properties (CloudHub 1.0) e Protecting App Property Values (CloudHub 2.0).
2.7 Testar
- Execute a aplicação com a chave informada.
- Dispare o fluxo (por exemplo, uma chamada HTTP) e verifique se a conexão com o banco ou a resposta usa o valor correto.
- Se algo falhar, consulte a seção de erros comuns abaixo.
3 Erros comuns e como resolver
| Sintoma | Causa provável | Solução |
|---|---|---|
| Erro ao descriptografar ou valor ilegível | Chave diferente da usada no painel | Use exatamente a mesma chave, sem espaços sobrando no início ou no fim. |
| Mesmo erro, com a chave correta | Algoritmo, mode ou IV aleatório diferentes | Confira algorithm, mode e useRandomIVs no <secure-properties:encrypt>. |
| Falha em um valor específico | Espaço depois do ] ou valor sem aspas no YAML | Escreva "![...]" entre aspas e sem espaços sobrando. |
Aparece o texto ${secure::...} literal | Config não carregado ou arquivo com nome errado | Confira o file do config e se o arquivo está em src/main/resources. |
| Propriedade não encontrada | Faltou o prefixo secure:: | Use ${secure::nome} para tudo que está no arquivo seguro. |
| Chave inválida no painel | Menos de 16 caracteres (24 para DESede) | Use uma chave maior. Para AES-256, use exatamente 32 caracteres. |
| Acentos ou símbolos no lugar errado | Chave com caracteres especiais | A chave é lida em UTF-8 e o tamanho conta em bytes. Prefira letras, números e símbolos simples. |
4 Boas práticas de segurança
- Nunca coloque a chave no repositório, no XML ou em arquivo de propriedades da aplicação.
- Use uma chave diferente por ambiente (desenvolvimento, homologação, produção).
- Guarde as chaves em um cofre de senhas e injete-as só no momento do deploy.
- Criptografe apenas o que é sensível; o resto pode ficar em um arquivo comum.
- Lembre que quem consegue listar os processos do servidor (
ps) ou abrir o console Java pode ver valores já descriptografados. Restrinja o acesso à máquina. - Em projetos novos, prefira AES/CBC com IV aleatório e uma chave de 32 caracteres. DES, RC2 e o modo ECB existem só por compatibilidade.
- Propriedades seguras podem depender de outras propriedades seguras, mas não de propriedades comuns do Mule.
Referência oficial: Secure Configuration Properties (docs.mulesoft.com).