Key handling¶
Parent key class¶
Common API for all public keys.
- class paramiko.pkey.PKey(msg=None, data=None)¶
Base class for public keys.
Also includes some “meta” level convenience constructors such as
from_type_string
.- __eq__(other)¶
Return self==value.
- __hash__()¶
Return hash(self).
- __init__(msg=None, data=None)¶
Create a new instance of this public key type. If
msg
is given, the key’s public part(s) will be filled in from the message. Ifdata
is given, the key’s public part(s) will be filled in from the string.- Parameters:
- Raises:
SSHException
– if a key cannot be created from thedata
ormsg
given, or no key was passed in.
- __repr__()¶
Return repr(self).
- __weakref__¶
list of weak references to the object
- property algorithm_name¶
Return the key algorithm identifier for this key.
Similar to
get_name
, but aimed at pure algorithm name instead of SSH protocol field value.
- asbytes()¶
Return a string of an SSH
Message
made up of the public part(s) of this key. This string is suitable for passing to__init__
to re-create the key object later.
- can_sign()¶
Return
True
if this key has the private part necessary for signing data.
- property fingerprint¶
Modern fingerprint property designed to be comparable to OpenSSH.
Currently only does SHA256 (the OpenSSH default).
New in version 3.2.
- static from_path(path, passphrase=None)¶
Attempt to instantiate appropriate key subclass from given file path.
- Parameters:
path (Path) – The path to load (may also be a
str
).- Returns:
A
PKey
subclass instance.- Raises:
UnknownKeyType
, if our crypto backend doesn’t know this key type.
New in version 3.2.
- 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 notNone
, the given password will be used to decrypt the key (otherwisePasswordRequiredException
is thrown).- 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, andpassword
isNone
- Raises:
SSHException
– if the key file is invalid
- 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 notNone
, the given password will be used to decrypt the key (otherwisePasswordRequiredException
is thrown). Through the magic of Python, this factory method will exist in all subclasses of PKey (such asRSAKey
orDSSKey
), but is useless on the abstract PKey class.- Parameters:
- 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, andpassword
isNone
- Raises:
SSHException
– if the key file is invalid
- static from_type_string(key_type, key_bytes)¶
Given type
str
& rawbytes
, return aPKey
subclass instance.For example,
PKey.from_type_string("ssh-ed25519", <public bytes>)
will (if successful) return a newEd25519Key
.- Parameters:
- Returns:
A
PKey
subclass instance.- Raises:
UnknownKeyType
, if no registered classes knew about this type.
New in version 3.2.
- 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.
- 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_fingerprint()¶
Return an MD5 fingerprint of the public part of this key. Nothing secret is revealed.
- Returns:
a 16-byte
string
(binary) of the MD5 fingerprint, in SSH format.
- 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"
).
- classmethod identifiers()¶
returns an iterable of key format/name strings this class can handle.
Most classes only have a single identifier, and thus this default implementation suffices; see
ECDSAKey
for one example of an override.
- 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 aMessage
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.
- sign_ssh_data(data, algorithm=None)¶
Sign a blob of data with this private key, and return a
Message
representing an SSH signature message.- Parameters:
- Returns:
an SSH signature
message
.
Changed in version 2.9: Added the
algorithm
kwarg.
- 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 (bytes) – 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:
- Raises:
IOError
– if there was an error writing the file- Raises:
SSHException
– if the key is invalid
- 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
orfrom_message
for useful instantiation, the main constructor is basically “I should be usingattrs
for this.”- __eq__(other)¶
Return self==value.
- __hash__ = None¶
- __init__(type_, blob, comment=None)¶
Create a new public blob of given type and contents.
- __ne__(other)¶
Return self!=value.
- __str__()¶
Return str(self).
- __weakref__¶
list of weak references to the object
- classmethod from_file(filename)¶
Create a public blob from a
-cert.pub
-style file on disk.
- 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.”
- classmethod from_string(string)¶
Create a public blob from a
-cert.pub
-style string.
DSA (DSS)¶
DSS keys.
- class paramiko.dsskey.DSSKey(msg=None, data=None, filename=None, password=None, vals=None, file_obj=None)¶
Representation of a DSS key which can be used to sign an verify SSH2 data.
- __init__(msg=None, data=None, filename=None, password=None, vals=None, file_obj=None)¶
Create a new instance of this public key type. If
msg
is given, the key’s public part(s) will be filled in from the message. Ifdata
is given, the key’s public part(s) will be filled in from the string.- Parameters:
- Raises:
SSHException
– if a key cannot be created from thedata
ormsg
given, or no key was passed in.
- __str__()¶
Return str(self).
- asbytes()¶
Return a string of an SSH
Message
made up of the public part(s) of this key. This string is suitable for passing to__init__
to re-create the 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.
- 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, algorithm=None)¶
Sign a blob of data with this private key, and return a
Message
representing an SSH signature message.- Parameters:
- Returns:
an SSH signature
message
.
Changed in version 2.9: Added the
algorithm
kwarg.
- 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 (bytes) – 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:
- 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)¶
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)¶
Create a new instance of this public key type. If
msg
is given, the key’s public part(s) will be filled in from the message. Ifdata
is given, the key’s public part(s) will be filled in from the string.- Parameters:
- Raises:
SSHException
– if a key cannot be created from thedata
ormsg
given, or no key was passed in.
- __str__()¶
Return str(self).
- asbytes()¶
Return a string of an SSH
Message
made up of the public part(s) of this key. This string is suitable for passing to__init__
to re-create the 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.
- 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"
).
- classmethod identifiers()¶
returns an iterable of key format/name strings this class can handle.
Most classes only have a single identifier, and thus this default implementation suffices; see
ECDSAKey
for one example of an override.
- sign_ssh_data(data, algorithm=None)¶
Sign a blob of data with this private key, and return a
Message
representing an SSH signature message.- Parameters:
- Returns:
an SSH signature
message
.
Changed in version 2.9: Added the
algorithm
kwarg.
- 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 (bytes) – 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:
- 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)¶
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)¶
Create a new instance of this public key type. If
msg
is given, the key’s public part(s) will be filled in from the message. Ifdata
is given, the key’s public part(s) will be filled in from the string.- Parameters:
- Raises:
SSHException
– if a key cannot be created from thedata
ormsg
given, or no key was passed in.
- __str__()¶
Return str(self).
- asbytes()¶
Return a string of an SSH
Message
made up of the public part(s) of this key. This string is suitable for passing to__init__
to re-create the 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"
).
- classmethod identifiers()¶
returns an iterable of key format/name strings this class can handle.
Most classes only have a single identifier, and thus this default implementation suffices; see
ECDSAKey
for one example of an override.
- sign_ssh_data(data, algorithm=None)¶
Sign a blob of data with this private key, and return a
Message
representing an SSH signature message.- Parameters:
- Returns:
an SSH signature
message
.
Changed in version 2.9: Added the
algorithm
kwarg.
- 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 (bytes) – 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:
- 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)¶
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)¶
Create a new instance of this public key type. If
msg
is given, the key’s public part(s) will be filled in from the message. Ifdata
is given, the key’s public part(s) will be filled in from the string.- Parameters:
- Raises:
SSHException
– if a key cannot be created from thedata
ormsg
given, or no key was passed in.
- asbytes()¶
Return a string of an SSH
Message
made up of the public part(s) of this key. This string is suitable for passing to__init__
to re-create the 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"
).
- sign_ssh_data(data, algorithm=None)¶
Sign a blob of data with this private key, and return a
Message
representing an SSH signature message.- Parameters:
- Returns:
an SSH signature
message
.
Changed in version 2.9: Added the
algorithm
kwarg.
- 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 (bytes) – the data that was signed.
msg (.Message) – an SSH signature message
- Returns:
True
if the signature verifies correctly;False
otherwise.