keyring
v25.5.0
A biblioteca de chaveiros Python fornece uma maneira fácil de acessar o serviço de chaveiro do sistema em python. Ele pode ser usado em qualquer aplicativo que precise de armazenamento seguro de senhas.
Estes back-ends de chaveiro recomendados são suportados:
Outras implementações de chaveiro estão disponíveis por meio de back-ends de terceiros.
No Linux, o backend do KWallet depende do dbus-python, que nem sempre é instalado corretamente ao usar o pip (é necessária compilação). Para melhores resultados, instale dbus-python como um pacote de sistema.
O chaveiro do macOS oferece suporte ao macOS 11 (Big Sur) e posterior requer Python 3.8.7 ou posterior com o binário "universal2". Consulte #525 para obter detalhes.
O uso básico do chaveiro é bastante simples: basta chamar keyring.set_password e keyring.get_password :
>>> importar chaveiro
>>> keyring.set_password("sistema", "nome de usuário", "senha")
>>> keyring.get_password("sistema", "nome de usuário")
'senha'
Keyring fornece um comando keyring que é instalado com o pacote. Depois de instalar o chaveiro na maioria dos ambientes, o comando deverá estar disponível para definir, obter e excluir senhas. Para obter mais informações de uso, invoque sem argumentos ou com --help assim:
$ chaveiro --help $ chaveiro definir nome de usuário do sistema Senha para 'nome de usuário' em 'sistema': $ keyring obtém nome de usuário do sistema senha
A funcionalidade da linha de comando também é exposta como um pacote executável, adequado para invocar do Python da seguinte forma:
$ python -m chaveiro --help $ python -m chaveiro definir nome de usuário do sistema Senha para 'nome de usuário' em 'sistema': $ python -m chaveiro obtém nome de usuário do sistema senha
Se instalado através de um gerenciador de pacotes (apt, pacman, nix, homebrew, etc), essas conclusões do shell podem já ter sido distribuídas com o pacote (nenhuma ação necessária).
O Keyring fornece preenchimento de guia se o completion extra estiver instalado:
$ pip install 'chaveiro[conclusão]'
Em seguida, gere conclusões de shell, algo como:
$ chaveiro --print-completion bash | sudo tee /usr/share/bash-completion/completions/keyring $ chaveiro --print-completion zsh | sudo tee /usr/share/zsh/site-functions/_keyring $ chaveiro --print-completion tcsh | sudo tee /etc/profile.d/keyring.csh
Nota : o caminho /usr/share é principalmente para GNU/Linux. Para outros sistemas operacionais, considere:
Depois de instalar as conclusões do shell, habilite-as seguindo as instruções recomendadas do seu shell. por exemplo:
. /usr/share/bash-completion/bash_completion em ~/.bashrc .autoload -Uz compinit && compinit apareça em ~/.zshrc e grep -w keyring ~/.zcompdump para verificar se o chaveiro aparece, indicando que foi instalado corretamente. A lib do chaveiro python contém implementações para vários back-ends. A biblioteca tentará escolher automaticamente o backend mais adequado para o ambiente atual. Os usuários também podem especificar o chaveiro preferido em um arquivo de configuração ou chamando a função set_keyring() .
A configuração é armazenada em um arquivo chamado “keyringrc.cfg” encontrado em um local específico da plataforma. Para determinar onde o arquivo de configuração está armazenado, execute keyring diagnose .
Para especificar um back-end de chaveiro, defina a opção default-keyring como o caminho completo da classe desse back-end, como keyring.backends.macOS.Keyring .
Se keyring-path for indicado, o keyring adicionará esse caminho ao caminho de pesquisa do módulo Python antes de carregar o backend.
Por exemplo, esta configuração pode ser usada para carregar o SimpleKeyring do módulo simplekeyring no diretório ./demo (não implementado):
[back-end] keyring padrão=simplekeyring.SimpleKeyring caminho do chaveiro = demonstração
Além dos back-ends fornecidos pelo pacote principal de chaveiros para os casos de uso mais comuns e seguros, há implementações adicionais de back-end de chaveiros disponíveis para outros casos de uso. Basta instalá-los para disponibilizá-los:
keyring<24 ). A interface para o backend é definida por keyring.backend.KeyringBackend . Todo backend deve derivar dessa classe base e definir um atributo priority e três funções: get_password() , set_password() e delete_password() . A função get_credential() pode ser definida se desejado.
Consulte o módulo backend para obter mais detalhes sobre a interface desta classe.
O Keyring emprega pontos de entrada para permitir que qualquer pacote de terceiros implemente backends sem qualquer modificação no próprio keyring. Aqueles interessados em criar novos back-ends são incentivados a criar novos pacotes de terceiros no namespace keyrings , de maneira modelada pelo pacote keyrings.alt. Consulte o arquivo setup.cfg nesse projeto para obter dicas sobre como criar os pontos de entrada necessários. Back-ends que forem essenciais podem ser considerados para inclusão na biblioteca principal, embora a facilidade de instalação desses pacotes de terceiros deva significar que as extensões podem estar prontamente disponíveis.
Para criar uma extensão para Keyring, envie uma solicitação pull para que sua extensão seja mencionada como uma extensão disponível.
O Keyring também permite a configuração programática do back-end chamando a API set_keyring() . O backend indicado será posteriormente usado para armazenar e recuperar senhas.
Para invocar set_keyring :
# define uma nova classe de chaveiro que estende o KeyringBackend
importar chaveiro.backend
classe TestKeyring(keyring.backend.KeyringBackend):
"""Um chaveiro de teste que sempre gera a mesma senha
"""
prioridade = 1
def set_password(self, nome do serviço, nome de usuário, senha):
passar
def get_password(self, nome do serviço, nome de usuário):
retornar "senha do TestKeyring"
def delete_password(self, nome do serviço, nome de usuário):
passar
# define o chaveiro para o chaveiro lib
keyring.set_keyring(TestKeyring())
# invoca a biblioteca do chaveiro
tentar:
keyring.set_password("demo-service", "tarek", "passexample")
print("senha armazenada com sucesso")
exceto keyring.errors.PasswordSetError:
print("falha ao armazenar senha")
print("senha", keyring.get_password("demo-service", "tarek"))
Em muitos casos, a desinstalação do chaveiro nunca será necessária. Especialmente no Windows e no macOS, o comportamento do chaveiro geralmente é degenerado, o que significa que ele retornará valores vazios ao chamador, permitindo que o chamador retorne a algum outro comportamento.
Em alguns casos, o comportamento padrão do chaveiro é indesejável e seria preferível desabilitar totalmente o comportamento do chaveiro. Existem vários mecanismos para desativar o chaveiro:
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring no ambiente e o back-end Null (degenerado) será usado. Esta abordagem afeta todos os usos do Keyring onde essa variável está definida.keyring --disable ou python -m keyring --disable . Essa abordagem afeta todos os usos do chaveiro desse usuário. O chaveiro fornece um mecanismo para alterar o comportamento do chaveiro por meio de variáveis de ambiente. Cada back-end implementa um KeyringBackend.set_properties_from_env , que quando invocado encontrará todas as variáveis de ambiente começando com KEYRING_PROPERTY_{NAME} e definirá uma propriedade para cada {NAME.lower()} no chaveiro. Este método é invocado durante a inicialização do chaveiro padrão/configurado.
Este mecanismo pode ser usado para definir alguns valores úteis em vários chaveiros, incluindo:
A seguir está uma transcrição completa para instalar o chaveiro em um ambiente virtual no Ubuntu 16.04. Nenhum arquivo de configuração foi usado:
$ sudo apt instalar python3-venv libdbus-glib-1-dev
$cd/tmp
$pyvenvpy3
$ fonte py3/bin/ativar
$ pip instalar -U pip
$ pip instalar armazenamento secreto dbus-python
$ pip instalar chaveiro
$ píton
>>> importar chaveiro
>>> chaveiro.get_keyring()
<objeto keyring.backends.SecretService.Keyring em 0x7f9b9c971ba8>
>>> keyring.set_password("sistema", "nome de usuário", "senha")
>>> keyring.get_password("sistema", "nome de usuário")
'senha'
É possível usar o backend SecretService em sistemas Linux sem servidor X11 disponível (apenas D-Bus é necessário). Nesse caso:
Instale o daemon do GNOME Keyring.
Inicie uma sessão D-Bus, por exemplo, execute dbus-run-session -- sh e execute os seguintes comandos dentro desse shell.
Execute gnome-keyring-daemon com a opção --unlock . A descrição dessa opção diz:
Leia uma senha do stdin e use-a para desbloquear o chaveiro de login ou crie-a se o chaveiro de login não existir.
Quando esse comando for iniciado, digite uma senha em stdin e pressione Ctrl+D (fim dos dados). Depois disso, o daemon irá para o segundo plano (use a opção --foreground para bloquear).
Agora você pode usar o backend SecretService do Keyring. Lembre-se de executar seu aplicativo na mesma sessão D-Bus que o daemon.
Também é possível usar o chaveiro com o backend SecretService em contêineres Docker. Tudo o que você precisa fazer é instalar as dependências necessárias e adicionar o sinalizador --privileged para evitar erros de Operação não permitida ao tentar desbloquear o chaveiro do sistema.
A seguir está uma transcrição completa para instalar o chaveiro em um contêiner Ubuntu 18:04:
docker run -it -d --privileged ubuntu:18.04
$ apt-get atualização
$ apt install -y gnome-keyring python3-venv python3-dev
$ python3 -m venv venv
$ source venv/bin/activate # crie um ambiente virtual para evitar poluir seu sistema
$ pip3 instalar --upgrade pip
$ pip3 instalar chaveiro
$ dbus-run-session -- sh # isso o colocará em um novo shell D-bus
$ echo 'somecredstorepass' | gnome-keyring-daemon --unlock # desbloqueia o chaveiro do sistema
$ píton
>>> importar chaveiro
>>> chaveiro.get_keyring()
<objeto keyring.backends.SecretService.Keyring em 0x7f9b9c971ba8>
>>> keyring.set_password("sistema", "nome de usuário", "senha")
>>> keyring.get_password("sistema", "nome de usuário")
'senha'
O chaveiro lib tem algumas funções:
get_keyring() : Retorna a implementação do chaveiro atualmente carregado.get_password(service, username) : Retorna a senha armazenada no chaveiro ativo. Se a senha não existir, retornará None.get_credential(service, username) : Retorna um objeto de credencial armazenado no chaveiro ativo. Este objeto contém pelo menos atributos username e password para o serviço especificado, onde o username retornado pode ser diferente do argumento.set_password(service, username, password) : Armazena a senha no chaveiro.delete_password(service, username) : Exclui a senha armazenada no chaveiro. Se a senha não existir, uma exceção será gerada. Em todos os casos, os parâmetros ( service , username , password ) devem ser texto Unicode.
A biblioteca do chaveiro gera as seguintes exceções:
keyring.errors.KeyringError : Classe de erro base para todas as exceções na biblioteca do chaveiro.keyring.errors.InitError : gerado quando o chaveiro não pode ser inicializado.keyring.errors.PasswordSetError : gerado quando a senha não pode ser definida no chaveiro.keyring.errors.PasswordDeleteError : gerado quando a senha não pode ser excluída do chaveiro. Python keyring lib é um projeto de comunidade aberta e recebe colaboradores com entusiasmo.
Cada back-end integrado pode ter considerações de segurança a serem entendidas antes de usar esta biblioteca. Os autores de ferramentas ou bibliotecas que utilizam keyring são incentivados a considerar essas preocupações.
Tal como acontece com qualquer lista de preocupações de segurança conhecidas, esta lista não é exaustiva. Problemas adicionais podem ser adicionados conforme necessário.
keyring do mesmo executável Python sem que o sistema operacional solicite uma senha ao usuário. Para fazer com que qualquer segredo específico solicite uma senha sempre que for acessado, localize a credencial usando o aplicativo Keychain Access e, nas configurações Access Control , remova Python da lista de aplicativos permitidos.Este projeto utiliza releases automatizados e integração contínua. O fluxo de trabalho simples é marcar um commit e enviá-lo ao Github. Se passar nos testes de CI, será automaticamente implantado no PyPI.
Outras coisas a considerar ao fazer um lançamento:
Os testes são executados continuamente no Github Actions.
Para executar os testes localmente, instale e invoque tox.
O projeto foi baseado na ideia de Tarek Ziade neste post. Kang Zhang inicialmente o executou como um projeto Google Summer of Code, e Tarek orientou Kang neste projeto.
Disponível como parte da assinatura Tidelift.
Este projeto e os mantenedores de milhares de outros pacotes estão trabalhando com o Tidelift para fornecer uma assinatura empresarial que cubra todo o código aberto que você usa.
Saber mais.
