NAME

Crypt::MultiKey::PKey::SSHAgentSignature - Use signature from ssh-agent as a password to encrypt/decrypt the private key

DESCRIPTION

Ideally, we could ask ssh-agent to decrypt some data that had been encrypted with the public key, but that is not possible because the Agent only signs messages. SSH operates on a principle of proving the ownership of the private key via signed challenges, rather than using the private key for actual encryption/decryption.

So, the only way to use a SSH Agent to decrypt resources on a remote server is to give it a challenge to be signed by a deterministic (non-random-salted) signing algorithm, and then use the signature as if it were a password. This is less cryptographically ideal than a proper public/private exchange with a remote service, but better and more convenient than typing a regular password into a terminal, so it seemed worth including.

Note that this means the SSH Agent must be available for the initial creation of the serialized PKey file. It also means that anyone with the agent_challenge and access to that SSH Agent can retrieve this password at any time.

Also note that only keys of type RSA, DSA, or x25519 use a deterministic signing algorithm. ECDSA signing adds random salt to each signature, making it unusable as a password.

ATTRIBUTES

agent

Lazy-built instance of Crypt::MultiKey::SSHAgentClient. You can use this object to specify a custom SSH socket or path to the ssh-add and ssh-keygen commands.

has_agent

True if the agent has been lazy-built, or assigned

usable_agent_keys

Call ->agent->list_keys and filter for key types with a deterministic signature algorithm. (ssh-rsa, ssh-dsa, ssh-ed25519)

agent_pubkey

Specifies which SSH public key (as a string of the Base64 of the OpenSSH public key format) was used to encrypt the private half of this PKey. This is assigned during "encrypt_private" and used during "decrypt_private".

kdf_salt

A string of random salt (base64) which is combined with the public half of this PKey and used as the data to be signed by the SSH agent. (the signature from the agent is then combined with this salt again to produce the password for decryption)

METHODS

can_obtain_private

Returns true if the resources needed for obtaining the private half of the PKey are available. For SSHAgentSignature, this means that the SSH agent is available and "ssh-add -L" includes the "agent_pubkey". Returns undef on a permanent error like if no ssh-agent can be contacted.

obtain_private

Attempts to contact the agent and ask it to repeat the signature that is used as the password for decrypting the private half of this PKey. It either decrypts the private half of this key, or croaks.

encrypt_private

$pkey->encrypt_private($ssh_pubkey);
$pkey->encrypt_private($ssh_fingerprint);
$pkey->encrypt_private(qr/ssh_key_comment_pattern/);
$pkey->encrypt_private; # chooses the best/first key available

This differs from the base class in that the SSH Agent must be available, and the optional parameter you specify indicates which of the Agent's public keys to use.

VERSION

version 0.000_001

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Michael Conrad.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.