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:

Dica: para projetos novos, use AES, CBC, IV aleatório ligado e uma chave de 32 caracteres. Os exemplos abaixo usam uma chave de demonstração (1234567890123456): nunca use essa chave em produção.

1.2 Criptografar um valor (aba String)

  1. Abra o painel e deixe a aba String selecionada.
  2. Em Operação, escolha Encrypt.
  3. Escolha o Algoritmo e o Mode e, se quiser, ligue Usar random IV.
  4. Digite a Key (a chave secreta).
  5. No campo Value, escreva o valor que quer proteger, por exemplo a senha do banco.
  6. 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)

  1. Em Operação, escolha Decrypt.
  2. Use o mesmo algoritmo, mode, IV aleatório e chave da criptografia.
  3. 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.

  1. Abra a aba YAML.
  2. Escolha Encrypt, o algoritmo, o mode, o IV aleatório e digite a Key.
  3. Selecione o arquivo em Arquivo YAML ou cole o conteúdo no campo Conteúdo.
  4. Clique em Processar YAML. Todos os valores do tipo chave: valor viram ![...]. Comentários, listas e linhas vazias são mantidos.
  5. 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==]
Dica: o painel criptografa todos os valores do arquivo. Para proteger só o que é sensível (senhas, tokens, chaves de API), coloque essas propriedades em um arquivo separado, por exemplo 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.

Atenção: este formato não foi validado contra a opção 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==]"
Atenção: um espaço depois do ] 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:

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 rodaComo informar
Anypoint StudioRun 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 ManagerVeja 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çãoComo escrever o nome
Table Viewsecure::db.password (sem escapar os dois-pontos)
Text Viewsecure\:\:db.password (escape os dois-pontos com barra invertida)
Importante: segundo a documentação da MuleSoft, ao sobrescrever uma propriedade segura no Runtime Manager o valor não deve estar criptografado. O formato ![...] 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

  1. Execute a aplicação com a chave informada.
  2. Dispare o fluxo (por exemplo, uma chamada HTTP) e verifique se a conexão com o banco ou a resposta usa o valor correto.
  3. Se algo falhar, consulte a seção de erros comuns abaixo.

3 Erros comuns e como resolver

SintomaCausa provávelSolução
Erro ao descriptografar ou valor ilegívelChave diferente da usada no painelUse exatamente a mesma chave, sem espaços sobrando no início ou no fim.
Mesmo erro, com a chave corretaAlgoritmo, mode ou IV aleatório diferentesConfira algorithm, mode e useRandomIVs no <secure-properties:encrypt>.
Falha em um valor específicoEspaço depois do ] ou valor sem aspas no YAMLEscreva "![...]" entre aspas e sem espaços sobrando.
Aparece o texto ${secure::...} literalConfig não carregado ou arquivo com nome erradoConfira o file do config e se o arquivo está em src/main/resources.
Propriedade não encontradaFaltou o prefixo secure::Use ${secure::nome} para tudo que está no arquivo seguro.
Chave inválida no painelMenos de 16 caracteres (24 para DESede)Use uma chave maior. Para AES-256, use exatamente 32 caracteres.
Acentos ou símbolos no lugar erradoChave com caracteres especiaisA 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

Referência oficial: Secure Configuration Properties (docs.mulesoft.com).