Key handling

Parent key class

Common API for all public and private keys.

paramiko.pkey.load_private_key(key_str, password=None)

Create a key object by reading a private key from a string. If the private key is encrypted and password is not None, the given password will be used to decrypt the key (otherwise PasswordRequiredException is thrown).

The key type is auto-detected and an instance of the appropriate PKey type is returned. This is now the recommended API to load private keys, instead of instantiating a *Key class directly.

Parameters

  • key_str (str) – string containing the key

  • password (str) – an optional password to use to decrypt the key, if it’s encrypted

Returns

PKey based on the type detected

Raises

PasswordRequiredException – if the private key is encrypted, and password is None

Raises

SSHException – if the key file is invalid

New in version 2.8.

paramiko.pkey.load_private_key_file(filename, password=None)

Create a key object by reading a private key from file. If the private key is encrypted and password is not None, the given password will be used to decrypt the key (otherwise PasswordRequiredException is thrown).

The key type is auto-detected and an instance of the appropriate PKey subclass is returned. This is now the recommended API to load private keys, instead of instantiating a *Key class directly.

Parameters

  • filename (str) – path to the file to load

  • password (str) – an optional password to use to decrypt the key, if it’s encrypted

Returns

PKey based on the given private key

Raises

IOError – if there was an error opening or reading the file

Raises

PasswordRequiredException – if the private key file is encrypted, and password is None

Raises

SSHException – if the key file is invalid

New in version 2.8.

paramiko.pkey.register_pkey_type(cls)

Decorator for PKey subclasses to register their types for parsing.

New in version 2.8.

class paramiko.pkey.PKey(msg=None, data=None, filename=None, password=None)

Base class for keys.

LEGACY_TYPE = None

Subclasses set this to identify the key type in FORMAT_ORIGINAL files. Examples: "RSA", "EC"

OPENSSH_TYPE_PREFIX = None

Subclasses set this to identify the key type in FORMAT_OPENSSH files. Examples: "ssh-rsa", "ecdsa-sha2-"

__init__(msg=None, data=None, filename=None, password=None)

Create a new instance of this key type.

Parameters

  • msg (Message) – an optional SSH Message containing a public key of this type.

  • data (bytes) – an optional bytestring containing a public key of this type

  • filename (str) – an optional private key filename to load

  • password (str) – an optional passphrase for decrypting the private key file

Raises

SSHException – if a key cannot be created from the data or msg given, or no key was passed in.

asbytes()

Return bytes of an SSH Message made up of the public part(s) of this key. This bytestring is suitable for passing to the constructor to re-create the public key object later.

__eq__(other)

Compare this key to another. Returns True if this key is equivalent to the given key, or False if they are different. Only the public parts of the key are compared, so a public key will compare equal to its corresponding private key.

Parameters

other (PKey) – key to compare to.

get_name()

Return the name of this private key implementation.

Returns

name of this private key type, in SSH terminology, as a str (for example, "ssh-rsa").

get_bits()

Return the number of significant bits in this key. This is useful for judging the relative security of a key.

Returns

bits in the key (as an int)

can_sign()

Return True if this key has the private part necessary for signing data.

get_fingerprint_sha256_b64()

Return a SHA256 fingerprint of the public part of this key, base64 encoded without ‘=’ padding. Nothing secret is revealed.

Returns

a 43-character str

New in version 2.9.

get_fingerprint_md5()

Return an MD5 fingerprint of the public part of this key. Nothing secret is revealed.

Returns

a 16-byte bytes

New in version 2.9.

get_fingerprint()

An alias for get_fingerprint_md5. This may be changed or removed in a later major release.

Returns

a 16-byte bytes

get_base64()

Return a base64 string containing the public part of this key. Nothing secret is revealed. This format is compatible with that used to store public key files or recognized host keys.

Returns

a base64 string containing the public part of the key.

sign_ssh_data(data)

Sign a blob of data with this private key, and return a Message representing an SSH signature message.

Parameters

data (str) – the data to sign.

Returns

an SSH signature message.

verify_ssh_sig(data, msg)

Given a blob of data, and an SSH message representing a signature of that data, verify that it was signed with this key.

Parameters

  • data (str) – the data that was signed.

  • msg (Message) – an SSH signature message

Returns

True if the signature verifies correctly; False otherwise.

classmethod from_private_key_file(filename, password=None)

Create a key object by reading a private key file. If the private key is encrypted and password is not None, the given password will be used to decrypt the key (otherwise PasswordRequiredException is thrown). Through the magic of Python, this factory method will exist in all subclasses of PKey (such as RSAKey or DSSKey), but is useless on the abstract PKey class.

Note

It is recommended to use the key-type-agnostic load_private_key_file function instead.

Parameters

  • filename (str) – name of the file to read

  • password (str) – an optional password to use to decrypt the key file, if it’s encrypted

Returns

a new PKey based on the given private key

Raises

IOError – if there was an error reading the file

Raises

PasswordRequiredException – if the private key file is encrypted, and password is None

Raises

SSHException – if the key file is invalid

classmethod from_private_key(file_obj, password=None)

Create a key object by reading a private key from a file (or file-like) object. If the private key is encrypted and password is not None, the given password will be used to decrypt the key (otherwise PasswordRequiredException is thrown).

Note

It is recommended to use the key-type-agnostic load_private_key function instead.

Parameters

  • file_obj – the file-like object to read from

  • password (str) – an optional password to use to decrypt the key, if it’s encrypted

Returns

a new PKey based on the given private key

Raises

IOError – if there was an error reading the key

Raises

PasswordRequiredException – if the private key file is encrypted, and password is None

Raises

SSHException – if the key file is invalid

write_private_key_file(filename, password=None)

Write private key contents into a file. If the password is not None, the key is encrypted before writing.

Parameters

  • filename (str) – name of the file to write

  • password (str) – an optional password to use to encrypt the key file

Raises

IOError – if there was an error writing the file

Raises

SSHException – if the key is invalid

write_private_key(file_obj, password=None)

Write private key contents into a file (or file-like) object. If the password is not None, the key is encrypted before writing.

Parameters

  • file_obj – the file-like object to write into

  • password (str) – an optional password to use to encrypt the key

Raises

IOError – if there was an error writing to the file

Raises

SSHException – if the key is invalid

load_certificate(value)

Supplement the private key contents with data loaded from an OpenSSH public key (.pub) or certificate (-cert.pub) file, a string containing such a file, or a Message object.

The .pub contents adds no real value, since the private key file includes sufficient information to derive the public key info. For certificates, however, this can be used on the client side to offer authentication requests to the server based on certificate instead of raw public key.

See: https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.certkeys

Note: very little effort is made to validate the certificate contents, that is for the server to decide if it is good enough to authenticate successfully.

class paramiko.pkey.PublicBlob(type_, blob, comment=None)

OpenSSH plain public key or OpenSSH signed public key (certificate).

Tries to be as dumb as possible and barely cares about specific per-key-type data.

Note

Most of the time you’ll want to call from_file, from_string or from_message for useful instantiation.

__init__(type_, blob, comment=None)

Create a new public blob of given type and contents.

Parameters

  • type (str) – Type indicator, eg ssh-rsa.

  • blob – The blob bytes themselves.

  • comment (str) – A comment, if one was given (e.g. file-based.)

classmethod from_file(filename)

Create a public blob from a -cert.pub-style file on disk.

classmethod from_string(string)

Create a public blob from a -cert.pub-style string.

classmethod from_message(message)

Create a public blob from a network Message.

Specifically, a cert-bearing pubkey auth packet, because by definition OpenSSH-style certificates ‘are’ their own network representation.”

__eq__(other)

Return self==value.

DSA (DSS)

DSS keys.

class paramiko.dsskey.DSSKey(msg=None, data=None, filename=None, password=None, vals=None, file_obj=None, _raw=None)

Representation of a DSS key which can be used to sign and verify SSH2 data.

__init__(msg=None, data=None, filename=None, password=None, vals=None, file_obj=None, _raw=None)

Create a new instance of this key type.

Parameters

  • msg (Message) – an optional SSH Message containing a public key of this type.

  • data (bytes) – an optional bytestring containing a public key of this type

  • filename (str) – an optional private key filename to load

  • password (str) – an optional passphrase for decrypting the private key file

Raises

SSHException – if a key cannot be created from the data or msg given, or no key was passed in.

asbytes()

Return bytes of an SSH Message made up of the public part(s) of this key. This bytestring is suitable for passing to the constructor to re-create the public key object later.

can_sign()

Return True if this key has the private part necessary for signing data.

static generate(bits=1024, progress_func=None)

Generate a new private DSS key. This factory function can be used to generate a new host key or authentication key.

Parameters

  • bits (int) – number of bits the generated key should be.

  • progress_func – Unused

Returns

new DSSKey private key

get_bits()

Return the number of significant bits in this key. This is useful for judging the relative security of a key.

Returns

bits in the key (as an int)

get_name()

Return the name of this private key implementation.

Returns

name of this private key type, in SSH terminology, as a str (for example, "ssh-rsa").

sign_ssh_data(data)

Sign a blob of data with this private key, and return a Message representing an SSH signature message.

Parameters

data (str) – the data to sign.

Returns

an SSH signature message.

verify_ssh_sig(data, msg)

Given a blob of data, and an SSH message representing a signature of that data, verify that it was signed with this key.

Parameters

  • data (str) – the data that was signed.

  • msg (Message) – an SSH signature message

Returns

True if the signature verifies correctly; False otherwise.

write_private_key(file_obj, password=None)

Write private key contents into a file (or file-like) object. If the password is not None, the key is encrypted before writing.

Parameters

  • file_obj – the file-like object to write into

  • password (str) – an optional password to use to encrypt the key

Raises

IOError – if there was an error writing to the file

Raises

SSHException – if the key is invalid

write_private_key_file(filename, password=None)

Write private key contents into a file. If the password is not None, the key is encrypted before writing.

Parameters

  • filename (str) – name of the file to write

  • password (str) – an optional password to use to encrypt the key file

Raises

IOError – if there was an error writing the file

Raises

SSHException – if the key is invalid

RSA

RSA keys.

class paramiko.rsakey.RSAKey(msg=None, data=None, filename=None, password=None, key=None, file_obj=None, _raw=None)

Representation of an RSA key which can be used to sign and verify SSH2 data.

__init__(msg=None, data=None, filename=None, password=None, key=None, file_obj=None, _raw=None)

Create a new instance of this key type.

Parameters

  • msg (Message) – an optional SSH Message containing a public key of this type.

  • data (bytes) – an optional bytestring containing a public key of this type

  • filename (str) – an optional private key filename to load

  • password (str) – an optional passphrase for decrypting the private key file

Raises

SSHException – if a key cannot be created from the data or msg given, or no key was passed in.

asbytes()

Return bytes of an SSH Message made up of the public part(s) of this key. This bytestring is suitable for passing to the constructor to re-create the public key object later.

can_sign()

Return True if this key has the private part necessary for signing data.

static generate(bits, progress_func=None)

Generate a new private RSA key. This factory function can be used to generate a new host key or authentication key.

Parameters

  • bits (int) – number of bits the generated key should be.

  • progress_func – Unused

Returns

new RSAKey private key

get_bits()

Return the number of significant bits in this key. This is useful for judging the relative security of a key.

Returns

bits in the key (as an int)

get_name()

Return the name of this private key implementation.

Returns

name of this private key type, in SSH terminology, as a str (for example, "ssh-rsa").

sign_ssh_data(data)

Sign a blob of data with this private key, and return a Message representing an SSH signature message.

Parameters

data (str) – the data to sign.

Returns

an SSH signature message.

verify_ssh_sig(data, msg)

Given a blob of data, and an SSH message representing a signature of that data, verify that it was signed with this key.

Parameters

  • data (str) – the data that was signed.

  • msg (Message) – an SSH signature message

Returns

True if the signature verifies correctly; False otherwise.

write_private_key(file_obj, password=None)

Write private key contents into a file (or file-like) object. If the password is not None, the key is encrypted before writing.

Parameters

  • file_obj – the file-like object to write into

  • password (str) – an optional password to use to encrypt the key

Raises

IOError – if there was an error writing to the file

Raises

SSHException – if the key is invalid

write_private_key_file(filename, password=None)

Write private key contents into a file. If the password is not None, the key is encrypted before writing.

Parameters

  • filename (str) – name of the file to write

  • password (str) – an optional password to use to encrypt the key file

Raises

IOError – if there was an error writing the file

Raises

SSHException – if the key is invalid

ECDSA

ECDSA keys

class paramiko.ecdsakey.ECDSAKey(msg=None, data=None, filename=None, password=None, vals=None, file_obj=None, validate_point=True, _raw=None)

Representation of an ECDSA key which can be used to sign and verify SSH2 data.

__init__(msg=None, data=None, filename=None, password=None, vals=None, file_obj=None, validate_point=True, _raw=None)

Create a new instance of this key type.

Parameters

  • msg (Message) – an optional SSH Message containing a public key of this type.

  • data (bytes) – an optional bytestring containing a public key of this type

  • filename (str) – an optional private key filename to load

  • password (str) – an optional passphrase for decrypting the private key file

Raises

SSHException – if a key cannot be created from the data or msg given, or no key was passed in.

asbytes()

Return bytes of an SSH Message made up of the public part(s) of this key. This bytestring is suitable for passing to the constructor to re-create the public key object later.

can_sign()

Return True if this key has the private part necessary for signing data.

classmethod generate(curve=<cryptography.hazmat.primitives.asymmetric.ec.SECP256R1 object>, progress_func=None, bits=None)

Generate a new private ECDSA key. This factory function can be used to generate a new host key or authentication key.

Parameters

progress_func – Not used for this type of key.

Returns

A new private key (ECDSAKey) object

get_bits()

Return the number of significant bits in this key. This is useful for judging the relative security of a key.

Returns

bits in the key (as an int)

get_name()

Return the name of this private key implementation.

Returns

name of this private key type, in SSH terminology, as a str (for example, "ssh-rsa").

sign_ssh_data(data)

Sign a blob of data with this private key, and return a Message representing an SSH signature message.

Parameters

data (str) – the data to sign.

Returns

an SSH signature message.

verify_ssh_sig(data, msg)

Given a blob of data, and an SSH message representing a signature of that data, verify that it was signed with this key.

Parameters

  • data (str) – the data that was signed.

  • msg (Message) – an SSH signature message

Returns

True if the signature verifies correctly; False otherwise.

write_private_key(file_obj, password=None)

Write private key contents into a file (or file-like) object. If the password is not None, the key is encrypted before writing.

Parameters

  • file_obj – the file-like object to write into

  • password (str) – an optional password to use to encrypt the key

Raises

IOError – if there was an error writing to the file

Raises

SSHException – if the key is invalid

write_private_key_file(filename, password=None)

Write private key contents into a file. If the password is not None, the key is encrypted before writing.

Parameters

  • filename (str) – name of the file to write

  • password (str) – an optional password to use to encrypt the key file

Raises

IOError – if there was an error writing the file

Raises

SSHException – if the key is invalid

Ed25519

class paramiko.ed25519key.Ed25519Key(msg=None, data=None, filename=None, password=None, file_obj=None, _raw=None)

Representation of an Ed25519 key.

Note

Ed25519 key support was added to OpenSSH in version 6.5.

New in version 2.2.

Changed in version 2.3: Added a file_obj parameter to match other key classes.

__init__(msg=None, data=None, filename=None, password=None, file_obj=None, _raw=None)

Create a new instance of this key type.

Parameters

  • msg (Message) – an optional SSH Message containing a public key of this type.

  • data (bytes) – an optional bytestring containing a public key of this type

  • filename (str) – an optional private key filename to load

  • password (str) – an optional passphrase for decrypting the private key file

Raises

SSHException – if a key cannot be created from the data or msg given, or no key was passed in.

asbytes()

Return bytes of an SSH Message made up of the public part(s) of this key. This bytestring is suitable for passing to the constructor to re-create the public key object later.

can_sign()

Return True if this key has the private part necessary for signing data.

get_bits()

Return the number of significant bits in this key. This is useful for judging the relative security of a key.

Returns

bits in the key (as an int)

get_name()

Return the name of this private key implementation.

Returns

name of this private key type, in SSH terminology, as a str (for example, "ssh-rsa").

static is_supported()

Check if the openssl version pyca/cryptography is linked against supports Ed25519 keys.

sign_ssh_data(data)

Sign a blob of data with this private key, and return a Message representing an SSH signature message.

Parameters

data (str) – the data to sign.

Returns

an SSH signature message.

verify_ssh_sig(data, msg)

Given a blob of data, and an SSH message representing a signature of that data, verify that it was signed with this key.

Parameters

  • data (str) – the data that was signed.

  • msg (Message) – an SSH signature message

Returns

True if the signature verifies correctly; False otherwise.