Go to the latest version of this document.

# ``twisted`.`conch`.`ssh`.`keys`.`Key``

class documentation

`class Key: (source)`

Constructor: `Key(keyObject)`

View In Hierarchy

An object representing a key. A key can be either a public or private key. A public key can verify a signature; a private key can create or verify a signature. To generate a string that can be stored on disk, use the toString method. If you have a private key, but want the string representation of the public key, use Key.public().toString().

Class Method | `fromFile` | Load a key from a file.
Class Method | `fromString` | Return a Key object corresponding to the string data. type is optionally the type of string, matching a _fromString_* method. Otherwise, the _guessStringType() classmethod will be used to guess a type...
Method | `__eq__` | Return True if other represents an object with the same key.
Method | `__init__` | Initialize with a private or public `cryptography.hazmat.primitives.asymmetric` key.
Method | `__repr__` | Return a pretty representation of this object.
Method | `application.setter` | Modifies the application value for OpenSSH sk SSH key types.
Method | `blob` | Return the public key blob for this key. The blob is the over-the-wire format for public keys.
Method | `data` | Return the values of the public key as a dictionary.
Method | `fingerprint` | The fingerprint of a public key consists of the output of the message-digest algorithm in the specified format. Supported formats include `FingerprintFormats.MD5_HEX` and `FingerprintFormats.SHA256_BASE64`...
Method | `isPublic` | Check if this instance is a public key.
Method | `isSecurityKey` | Return True if key is an OpenSSH security key.
Method | `privateBlob` | Return the private key blob for this key. The blob is the over-the-wire format for private keys:
Method | `public` | Returns a version of this key containing only the public key data. If this is a public key, this may or may not be the same object as self.
Method | `sign` | Sign some data with this key.
Method | `size` | Return the size of the object we wrap.
Method | `sshType` | Get the type of the object we wrap as defined in the SSH protocol, defined in RFC 4253, Section 6.6 and RFC 8332, section 4 (this is a public key format name, not a public key algorithm name). Currently this can only be b'ssh-rsa', b'ssh-dss', b'ecdsa-sha2-[identifier]' or b'ssh-ed25519'.
Method | `supportedSignatureAlgorithms` | Get the public key signature algorithms supported by this key.
Method | `toString` | Create a string representation of this key. If the key is a private key and you want the representation of its public key, use `key.public().toString()`. type maps to a _toString_* method.
Method | `type` | Return the type of the object we wrap. Currently this can only be 'RSA', 'DSA', 'EC', or 'Ed25519'.
Method | `verify` | Verify a signature using this key.
Property | `application` | Returns the application value for OpenSSH sk SSH keys and None for other key types.
Class Method | `_fromDSAComponents` | Build a key from DSA numerical components.
Class Method | `_fromECComponents` | Build a key from EC components.
Class Method | `_fromECEncodedPoint` | Build a key from an EC encoded point.
Class Method | `_fromEd25519Components` | Build a key from Ed25519 components.
Class Method | `_fromPrivateOpenSSH_PEM` | Return a private key object corresponding to this OpenSSH private key string, in the old PEM-based format.
Class Method | `_fromPrivateOpenSSH_v1` | Return a private key object corresponding to this OpenSSH private key string, in the "openssh-key-v1" format introduced in OpenSSH 6.5.
Class Method | `_fromRSAComponents` | Build a key from RSA numerical components.
Class Method | `_fromString_AGENTV3` | Return a private key object corresponsing to the Secure Shell Key Agent v3 format.
Class Method | `_fromString_BLOB` | Return a public key object corresponding to this public key blob. The format of a RSA public key blob is:
Class Method | `_fromString_PRIVATE_BLOB` | Return a private key object corresponding to this private key blob. The blob formats are as follows:
Class Method | `_fromString_PRIVATE_LSH` | Return a private key corresponding to this LSH private key string. The LSH private key string format is:
Class Method | `_fromString_PRIVATE_OPENSSH` | Return a private key object corresponding to this OpenSSH private key string. If the key is encrypted, passphrase MUST be provided. Providing a passphrase for an unencrypted key is an error.
Class Method | `_fromString_PUBLIC_LSH` | Return a public key corresponding to this LSH public key string. The LSH public key string format is:
Class Method | `_fromString_PUBLIC_OPENSSH` | Return a public key object corresponding to this OpenSSH public key string. The format of an OpenSSH public key string is:
Class Method | `_guessStringType` | Guess the type of key in data. The types map to _fromString_* methods.
Method | `_getHashAlgorithm` | Return a hash algorithm for this key type given an SSH signature algorithm name, or `None` if no such hash algorithm is defined for this key type.
Method | `_toPrivateOpenSSH_PEM` | Return a private OpenSSH key string, in the old PEM-based format.
Method | `_toPrivateOpenSSH_v1` | Return a private OpenSSH key string, in the "openssh-key-v1" format introduced in OpenSSH 6.5.
Method | `_toPublicOpenSSH` | Return a public OpenSSH key string.
Method | `_toString_AGENTV3` | Return a private Secure Shell Agent v3 key. See _fromString_AGENTV3 for the key format.
Method | `_toString_LSH` | Return a public or private LSH key. See _fromString_PUBLIC_LSH and _fromString_PRIVATE_LSH for the key formats.
Method | `_toString_OPENSSH` | Return a public or private OpenSSH string. See `_fromString_PUBLIC_OPENSSH` and `_fromPrivateOpenSSH_PEM` for the string formats.
Instance Variable | `_application` | Undocumented
Instance Variable | `_keyObject` | Undocumented
Instance Variable | `_sk` | Undocumented

@classmethod
def fromFile(cls, filename, type=None, passphrase=None): (source)

Load a key from a file.

Parameters
filename | The path to load key data from.
type:`str` or `None` | A string describing the format the key data is in, or `None` to attempt detection of the type.
passphrase:`bytes` or `None` | The passphrase the key is encrypted with, or `None` if there is no encryption.

Returns
`Key` | The loaded key.

@classmethod
def fromString(cls, data, type=None, passphrase=None): (source)

Return a Key object corresponding to the string data. type is optionally the type of string, matching a _fromString_* method. Otherwise, the _guessStringType() classmethod will be used to guess a type. If the key is encrypted, passphrase is used as the decryption key.

Parameters
data:`bytes` | The key data.
type:`str` or `None` | A string describing the format the key data is in, or `None` to attempt detection of the type.
passphrase:`bytes` or `None` | The passphrase the key is encrypted with, or `None` if there is no encryption.

Returns
`Key` | The loaded key.

def __eq__(self, other: `object`) -> `bool`: (source)

Return True if other represents an object with the same key.

def __init__(self, keyObject): (source)

Initialize with a private or public `cryptography.hazmat.primitives.asymmetric` key.

Parameters
keyObject:`cryptography.hazmat.primitives.asymmetric` key. | Low level key.

def __repr__(self) -> `str`: (source)

Return a pretty representation of this object.

@application.setter
def application(self, value): (source)

Modifies the application value for OpenSSH sk SSH key types.

def blob(self): (source)

Return the public key blob for this key. The blob is the over-the-wire format for public keys.

SECSH-TRANS RFC 4253 Section 6.6.

RSA keys:

        string 'ssh-rsa'
        integer e
        integer n

DSA keys:

        string 'ssh-dss'
        integer p
        integer q
        integer g
        integer y

EC keys:

        string 'ecdsa-sha2-[identifier]'
        integer x
        integer y

Where 'identifier' is the standard NIST curve name.

Ed25519 keys:

        string 'ssh-ed25519'
        string a

sk-ecdsa-sha2-nistp256@openssh.com keys:

        string              "sk-ecdsa-sha2-nistp256@openssh.com"
        string              curve name
        ec_point    Q
        string              application (user-specified, but typically "ssh:")

sk-ssh-ed25519@openssh.com keys:

        string              "sk-ssh-ed25519@openssh.com"
        string              public key
        string              application (user-specified, but typically "ssh:")

The security key formats are specified at https://github.com/openssh/openssh-portable/blob/80993390bed15bbd1c348f3352e55d0db01ca0fd/PROTOCOL.u2f.

Returns
`bytes` | Undocumented

def data(self) -> `dict[str, Any]`: (source)

Return the values of the public key as a dictionary.

Returns
`dict` | Undocumented

def fingerprint(self, format=FingerprintFormats.MD5_HEX): (source)

The fingerprint of a public key consists of the output of the message-digest algorithm in the specified format. Supported formats include `FingerprintFormats.MD5_HEX` and `FingerprintFormats.SHA256_BASE64`

The input to the algorithm is the public key data as specified by [RFC4253].

The output of sha256[RFC4634] algorithm is presented to the user in the form of base64 encoded sha256 hashes. Example: `US5jTUa0kgX5ZxdqaGF0yGRu8EgKXHNmoT8jHKo1StM=`

The output of the MD5[RFC1321](default) algorithm is presented to the user as a sequence of 16 octets printed as hexadecimal with lowercase letters and separated by colons. Example: `c1:b1:30:29:d7:b8:de:6c:97:77:10:d7:46:41:63:87`

Parameters
format | Format for fingerprint generation. Consists hash function and representation format. Default is `FingerprintFormats.MD5_HEX`

Returns
`str` | the user presentation of this `Key`'s fingerprint, as a string.

Present Since
8.2

def isPublic(self): (source)

Check if this instance is a public key.

Returns
`True` if this is a public key.

def isSecurityKey(self): (source)

Return True if key is an OpenSSH security key.

def privateBlob(self): (source)

Return the private key blob for this key. The blob is the over-the-wire format for private keys:

Specification in OpenSSH PROTOCOL.agent

RSA keys:

        string 'ssh-rsa'
        integer n
        integer e
        integer d
        integer u
        integer p
        integer q

DSA keys:

        string 'ssh-dss'
        integer p
        integer q
        integer g
        integer y
        integer x

EC keys:

        string 'ecdsa-sha2-[identifier]'
        integer x
        integer y
        integer privateValue

        identifier is the NIST standard curve name.

Ed25519 keys:

        string 'ssh-ed25519'
        string a
        string k || a

def public(self): (source)

Returns a version of this key containing only the public key data. If this is a public key, this may or may not be the same object as self.

Returns
`Key` | A public key.

def sign(self, data: `bytes`, signatureType: `bytes | None` = None) -> `bytes`: (source)

Sign some data with this key.

SECSH-TRANS RFC 4253 Section 6.6.

Parameters
data:`bytes` | The data to sign.
signatureType:`bytes | None` | The SSH public key algorithm name to sign this data with, or `None` to use a reasonable default for the key.

Returns
`bytes` | A signature for the given data.

def size(self): (source)

Return the size of the object we wrap.

Returns
`int` | The size of the key.

def sshType(self): (source)

Get the type of the object we wrap as defined in the SSH protocol, defined in RFC 4253, Section 6.6 and RFC 8332, section 4 (this is a public key format name, not a public key algorithm name). Currently this can only be b'ssh-rsa', b'ssh-dss', b'ecdsa-sha2-[identifier]' or b'ssh-ed25519'.

identifier is the standard NIST curve name

Returns
`bytes` | The key type format.

def supportedSignatureAlgorithms(self): (source)

Get the public key signature algorithms supported by this key.

Returns
`list` of `bytes` | A list of supported public key signature algorithm names.

@_mutuallyExclusiveArguments([('extra', 'comment'), ('extra', 'passphrase')])
def toString(self, type, extra=None, subtype=None, comment=None, passphrase=None): (source)

Create a string representation of this key. If the key is a private key and you want the representation of its public key, use `key.public().toString()`. type maps to a _toString_* method.

Parameters
type:`str` | The type of string to emit. Currently supported values are `'OPENSSH'`, `'LSH'`, and `'AGENTV3'`.
extra:`bytes` or `unicode` or `None` | Any extra data supported by the selected format which is not part of the key itself. For public OpenSSH keys, this is a comment. For private OpenSSH keys, this is a passphrase to encrypt with. (Deprecated since Twisted 20.3.0; use `comment` or `passphrase` as appropriate instead.)
subtype:`str` or `None` | A subtype of the requested `type` to emit. Only supported for private OpenSSH keys, for which the currently supported subtypes are `'PEM'` and `'v1'`. If not given, an appropriate default is used.
comment:`bytes` or `unicode` or `None` | A comment to include with the key. Only supported for OpenSSH keys. Present since Twisted 20.3.0.
passphrase:`bytes` or `unicode` or `None` | A passphrase to encrypt the key with. Only supported for private OpenSSH keys. Present since Twisted 20.3.0.

Returns
`bytes` | Undocumented

def type(self) -> `Literal['RSA', 'DSA', 'EC', 'Ed25519']`: (source)

Return the type of the object we wrap. Currently this can only be 'RSA', 'DSA', 'EC', or 'Ed25519'.

Returns
`str` | Undocumented

Raises
`RuntimeError` | If the object type is unknown.

def verify(self, signature, data): (source)

Verify a signature using this key.

Parameters
signature:`bytes` | The signature to verify.
data:`bytes` | The signed data.

Returns
`bool` | `True` if the signature is valid.

@property
application = (source)

Returns the application value for OpenSSH sk SSH keys and None for other key types.

@classmethod
def _fromDSAComponents(cls, y, p, q, g, x=None): (source)

Build a key from DSA numerical components.

Parameters
y:`int` | The 'y' DSA variable.
p:`int` | The 'p' DSA variable.
q:`int` | The 'q' DSA variable.
g:`int` | The 'g' DSA variable.
x:`int` or `None` | The 'x' DSA variable (optional for a public key)

Returns
`Key` | A DSA key constructed from the values as given.

@classmethod
def _fromECComponents(cls, x, y, curve, privateValue=None): (source)

Build a key from EC components.

Parameters
x:`int` | The affine x component of the public point used for verifying.
y:`int` | The affine y component of the public point used for verifying.
curve:`bytes` | NIST name of elliptic curve.
privateValue:`int` | The private value.

@classmethod
def _fromECEncodedPoint(cls, encodedPoint, curve, privateValue=None): (source)

Build a key from an EC encoded point.

Parameters
encodedPoint:`bytes` | The public point encoded as in SEC 1 v2.0 section 2.3.3.
curve:`bytes` | NIST name of elliptic curve.
privateValue:`int` | The private value.

@classmethod
def _fromEd25519Components(cls, a, k=None): (source)

Build a key from Ed25519 components.

Parameters

a:`bytes`

The Ed25519 public key, as defined in RFC 8032 section

k:`bytes`

The Ed25519 private key, as defined in RFC 8032 section

@classmethod
def _fromPrivateOpenSSH_PEM(cls, data, passphrase): (source)

Return a private key object corresponding to this OpenSSH private key string, in the old PEM-based format.

The format of a PEM-based OpenSSH private key string is:

        -----BEGIN <key type> PRIVATE KEY-----
        [Proc-Type: 4,ENCRYPTED
        DEK-Info: DES-EDE3-CBC,<initialization value>]
        <base64-encoded ASN.1 structure>
        ------END <key type> PRIVATE KEY------

The ASN.1 structure of a RSA key is:

        (0, n, e, d, p, q)

The ASN.1 structure of a DSA key is:

        (0, p, q, g, y, x)

The ASN.1 structure of a ECDSA key is:

        (ECParameters, OID, NULL)

Parameters
data:`bytes` | The key data.
passphrase:`bytes` or `None` | The passphrase the key is encrypted with, or `None` if it is not encrypted.

Returns
`twisted.conch.ssh.keys.Key` | A new key.

Raises
`BadKeyError` | if * a passphrase is provided for an unencrypted key * the ASN.1 encoding is incorrect
`EncryptedKeyError` | if * a passphrase is not provided for an encrypted key

@classmethod
def _fromPrivateOpenSSH_v1(cls, data, passphrase): (source)

Return a private key object corresponding to this OpenSSH private key string, in the "openssh-key-v1" format introduced in OpenSSH 6.5.

The format of an openssh-key-v1 private key string is:

        -----BEGIN OPENSSH PRIVATE KEY-----
        <base64-encoded SSH protocol string>
        -----END OPENSSH PRIVATE KEY-----

The SSH protocol string is as described in PROTOCOL.key.

Parameters
data:`bytes` | The key data.
passphrase:`bytes` or `None` | The passphrase the key is encrypted with, or `None` if it is not encrypted.

Returns
`twisted.conch.ssh.keys.Key` | A new key.

Raises
`BadKeyError` | if * a passphrase is provided for an unencrypted key * the SSH protocol encoding is incorrect
`EncryptedKeyError` | if * a passphrase is not provided for an encrypted key

@classmethod
def _fromRSAComponents(cls, n, e, d=None, p=None, q=None, u=None): (source)

Build a key from RSA numerical components.

Parameters
n:`int` | The 'n' RSA variable.
e:`int` | The 'e' RSA variable.
d:`int` or `None` | The 'd' RSA variable (optional for a public key).
p:`int` or `None` | The 'p' RSA variable (optional for a public key).
q:`int` or `None` | The 'q' RSA variable (optional for a public key).
u:`int` or `None` | The 'u' RSA variable. Ignored, as its value is determined by p and q.

Returns
`Key` | An RSA key constructed from the values as given.

@classmethod
def _fromString_AGENTV3(cls, data): (source)

Return a private key object corresponsing to the Secure Shell Key Agent v3 format.

The SSH Key Agent v3 format for a RSA key is:

        string 'ssh-rsa'
        integer e
        integer d
        integer n
        integer u
        integer p
        integer q

The SSH Key Agent v3 format for a DSA key is:

        string 'ssh-dss'
        integer p
        integer q
        integer g
        integer y
        integer x

Parameters
data:`bytes` | The key data.

Returns
`twisted.conch.ssh.keys.Key` | A new key.

Raises
`BadKeyError` | if the key type (the first string) is unknown

@classmethod
def _fromString_BLOB(cls, blob): (source)

Return a public key object corresponding to this public key blob. The format of a RSA public key blob is:

        string 'ssh-rsa'
        integer e
        integer n

The format of a DSA public key blob is:

        string 'ssh-dss'
        integer p
        integer q
        integer g
        integer y

The format of ECDSA-SHA2-* public key blob is:

        string 'ecdsa-sha2-[identifier]'
        integer x
        integer y

Where 'identifier' is the standard NIST curve name.

The format of an Ed25519 public key blob is:

        string 'ssh-ed25519'
        string a

The format of a sk-ecdsa-sha2-nistp256@openssh.com public key is:

        string              "sk-ecdsa-sha2-nistp256@openssh.com"
        string              curve name
        ec_point    Q
        string              application (user-specified, but typically "ssh:")

The format of a sk-ssh-ed25519@openssh.com public key is:

        string              "sk-ssh-ed25519@openssh.com"
        string              public key
        string              application (user-specified, but typically "ssh:")

The security key formats are specified at https://github.com/openssh/openssh-portable/blob/80993390bed15bbd1c348f3352e55d0db01ca0fd/PROTOCOL.u2f.

Parameters
blob:`bytes` | The key data.

Returns
`twisted.conch.ssh.keys.Key` | A new key.

Raises
`BadKeyError` | if the key type (the first string) is unknown.

@classmethod
def _fromString_PRIVATE_BLOB(cls, blob): (source)

Return a private key object corresponding to this private key blob. The blob formats are as follows:

RSA keys:

        string 'ssh-rsa'
        integer n
        integer e
        integer d
        integer u
        integer p
        integer q

DSA keys:

        string 'ssh-dss'
        integer p
        integer q
        integer g
        integer y
        integer x

EC keys:

        string 'ecdsa-sha2-[identifier]'
        string identifier
        string q
        integer privateValue

        identifier is the standard NIST curve name.

Ed25519 keys:

        string 'ssh-ed25519'
        string a
        string k || a

Parameters
blob:`bytes` | The key data.

Returns
`twisted.conch.ssh.keys.Key` | A new key.

Raises
`BadKeyError` | if * the key type (the first string) is unknown * the curve name of an ECDSA key does not match the key type

@classmethod
def _fromString_PRIVATE_LSH(cls, data): (source)

Return a private key corresponding to this LSH private key string. The LSH private key string format is:

        <s-expression: ('private-key', (<key type>, (<name>, <value>)+))>

The names for a RSA (key type 'rsa-pkcs1-sha1') key are: n, e, d, p, q. The names for a DSA (key type 'dsa') key are: y, g, p, q, x.

Parameters
data:`bytes` | The key data.

Returns
`twisted.conch.ssh.keys.Key` | A new key.

Raises
`BadKeyError` | if the key type is unknown

@classmethod
def _fromString_PRIVATE_OPENSSH(cls, data, passphrase): (source)

Return a private key object corresponding to this OpenSSH private key string. If the key is encrypted, passphrase MUST be provided. Providing a passphrase for an unencrypted key is an error.

Parameters
data:`bytes` | The key data.
passphrase:`bytes` or `None` | The passphrase the key is encrypted with, or `None` if it is not encrypted.

Returns
`twisted.conch.ssh.keys.Key` | A new key.

Raises
`BadKeyError` | if * a passphrase is provided for an unencrypted key * the encoding is incorrect
`EncryptedKeyError` | if * a passphrase is not provided for an encrypted key

@classmethod
def _fromString_PUBLIC_LSH(cls, data): (source)

Return a public key corresponding to this LSH public key string. The LSH public key string format is:

        <s-expression: ('public-key', (<key type>, (<name, <value>)+))>

The names for a RSA (key type 'rsa-pkcs1-sha1') key are: n, e. The names for a DSA (key type 'dsa') key are: y, g, p, q.

Parameters
data:`bytes` | The key data.

Returns
`twisted.conch.ssh.keys.Key` | A new key.

Raises
`BadKeyError` | if the key type is unknown

@classmethod
def _fromString_PUBLIC_OPENSSH(cls, data): (source)

Return a public key object corresponding to this OpenSSH public key string. The format of an OpenSSH public key string is:

        <key type> <base64-encoded public key blob>

Parameters
data:`bytes` | The key data.

Returns
`twisted.conch.ssh.keys.Key` | A new key.

Raises
`BadKeyError` | if the blob type is unknown.

@classmethod
def _guessStringType(cls, data): (source)

Guess the type of key in data. The types map to _fromString_* methods.

Parameters
data:`bytes` | The key data.

def _getHashAlgorithm(self, signatureType): (source)

Return a hash algorithm for this key type given an SSH signature algorithm name, or `None` if no such hash algorithm is defined for this key type.

def _toPrivateOpenSSH_PEM(self, passphrase=None): (source)

Return a private OpenSSH key string, in the old PEM-based format.

See _fromPrivateOpenSSH_PEM for the string format.

Parameters
passphrase:`bytes` or `None` | The passphrase to encrypt the key with, or `None` if it is not encrypted.

def _toPrivateOpenSSH_v1(self, comment=None, passphrase=None): (source)

Return a private OpenSSH key string, in the "openssh-key-v1" format introduced in OpenSSH 6.5.

See _fromPrivateOpenSSH_v1 for the string format.

Parameters
comment | Undocumented
passphrase:`bytes` or `None` | The passphrase to encrypt the key with, or `None` if it is not encrypted.

def _toPublicOpenSSH(self, comment=None): (source)

Return a public OpenSSH key string.

See _fromString_PUBLIC_OPENSSH for the string format.

Parameters
comment:`bytes` or `None` | A comment to include with the key, or `None` to omit the comment.

def _toString_AGENTV3(self, **kwargs): (source)

Return a private Secure Shell Agent v3 key. See _fromString_AGENTV3 for the key format.

Returns
`bytes` | Undocumented

def _toString_LSH(self, **kwargs): (source)

Return a public or private LSH key. See _fromString_PUBLIC_LSH and _fromString_PRIVATE_LSH for the key formats.

Returns
`bytes` | Undocumented

def _toString_OPENSSH(self, subtype=None, comment=None, passphrase=None): (source)

Return a public or private OpenSSH string. See `_fromString_PUBLIC_OPENSSH` and `_fromPrivateOpenSSH_PEM` for the string formats.

Parameters
subtype:`str` or `None` | A subtype to emit. Only supported for private keys, for which the currently supported subtypes are `'PEM'` and `'v1'`. If not given, an appropriate default is used.
comment:`bytes` | Comment for a public key.
passphrase:`bytes` | Passphrase for a private key.

Returns
`bytes` | Undocumented

_application = (source)

Undocumented

_keyObject = (source)

Undocumented

_sk: `bool` = (source)

Undocumented