Struct PrivateKey 

pub struct PrivateKey { /* private fields */ }

SSH private key.

Implementations

impl PrivateKey

pub fn new(key_data: KeypairData, comment: impl Into<Comment>) -> Result<Self>

Available on crate feature alloc only.

Create a new unencrypted private key with the given keypair data and comment.

On no_alloc platforms, use PrivateKey::try_from(key_data) instead.

Errors

Returns Error::Encrypted if the key is encrypted.

pub fn from_openssh(pem: impl AsRef<[u8]>) -> Result<Self>

Parse an OpenSSH-formatted PEM private key.

OpenSSH-formatted private keys begin with the following:

-----BEGIN OPENSSH PRIVATE KEY-----

Errors

Returns Error::Encoding in the event of an encoding error.

pub fn from_ppk( ppk: impl AsRef<str>, passphrase: Option<String>, ) -> Result<Self>

Available on crate feature ppk only.

Parse a PuTTY PPK private key.

PPK-formatted private keys begin with the following:

PuTTY-User-Key-File-<VERSION>: <ALGORITHM>

Errors

Returns Error::Encoding in the event of an encoding error.

pub fn from_bytes(bytes: &[u8]) -> Result<Self>

Parse a raw binary SSH private key.

Errors

Returns Error::Encoding in the event of an encoding error.

pub fn encode_openssh<'o>( &self, line_ending: LineEnding, out: &'o mut [u8], ) -> Result<&'o str>

Encode OpenSSH-formatted (PEM) private key.

Errors

Returns Error::Encoding in the event of an encoding error.

pub fn to_openssh(&self, line_ending: LineEnding) -> Result<Zeroizing<String>>

Available on crate feature alloc only.

Encode an OpenSSH-formatted PEM private key, allocating a self-zeroizing String for the result.

Errors

Returns Error::Encoding in the event of an encoding error.

pub fn to_bytes(&self) -> Result<Zeroizing<Vec<u8>>>

Available on crate feature alloc only.

Serialize SSH private key as raw bytes.

Errors

Returns Error::Encoding in the event of an encoding error.

pub fn sign( &self, namespace: &str, hash_alg: HashAlg, msg: &[u8], ) -> Result<SshSig>

Available on crate feature alloc only.

Sign the given message using this private key, returning an SshSig.

These signatures can be produced using ssh-keygen -Y sign. They’re encoded as PEM and begin with the following:

-----BEGIN SSH SIGNATURE-----

See PROTOCOL.sshsig for more information.

Usage

See also: PublicKey::verify.

use ssh_key::{PrivateKey, HashAlg, SshSig};

// Message to be signed.
let message = b"testing";

// Example domain/namespace used for the message.
let namespace = "example";

// Private key to use when computing the signature.
// WARNING: don't actually hardcode private keys in source code!!!
let encoded_private_key = r#"
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
QyNTUxOQAAACCzPq7zfqLffKoBDe/eo04kH2XxtSmk9D7RQyf1xUqrYgAAAJgAIAxdACAM
XQAAAAtzc2gtZWQyNTUxOQAAACCzPq7zfqLffKoBDe/eo04kH2XxtSmk9D7RQyf1xUqrYg
AAAEC2BsIi0QwW2uFscKTUUXNHLsYX4FxlaSDSblbAj7WR7bM+rvN+ot98qgEN796jTiQf
ZfG1KaT0PtFDJ/XFSqtiAAAAEHVzZXJAZXhhbXBsZS5jb20BAgMEBQ==
-----END OPENSSH PRIVATE KEY-----
"#;

let private_key = encoded_private_key.parse::<PrivateKey>()?;
let signature = private_key.sign(namespace, HashAlg::default(), message)?;
// assert!(private_key.public_key().verify(namespace, message, &signature).is_ok());

Errors

Propagates errors from SshSig::sign.

pub fn sign_digest<D: AssociatedHashAlg + Digest>( &self, namespace: &str, digest: D, ) -> Result<SshSig>

Available on crate feature alloc only.

Sign the given message Digest using this private key, returning an SshSig.

These signatures can be produced using ssh-keygen -Y sign.

For more information, see PrivateKey::sign.

Errors

Propagates errors from SshSig::sign_digest.

pub fn sign_prehash( &self, namespace: &str, hash_alg: HashAlg, prehash: &[u8], ) -> Result<SshSig>

Available on crate feature alloc only.

Sign the given raw message prehash using this private key, returning an SshSig.

These signatures can be produced using ssh-keygen -Y sign.

For more information, see PrivateKey::sign.

Errors

Propagates errors from SshSig::sign_prehash.

pub fn read_openssh(reader: &mut impl Read) -> Result<Self>

Available on crate feature std only.

Read private key from an OpenSSH-formatted PEM source.

Errors

• Returns Error::Io on I/O errors.
• Returns Error::Encoding in the event of an encoding error.

pub fn read_openssh_file(path: impl AsRef<Path>) -> Result<Self>

Available on crate feature std only.

Read private key from an OpenSSH-formatted PEM file.

Errors

• Returns Error::Io on I/O errors.
• Returns Error::Encoding in the event of an encoding error.

pub fn write_openssh( &self, writer: &mut impl Write, line_ending: LineEnding, ) -> Result<()>

Available on crate feature std only.

Write private key as an OpenSSH-formatted PEM file.

Errors

• Returns Error::Io on I/O errors.
• Returns Error::Encoding in the event of an encoding error.

pub fn write_openssh_file( &self, path: impl AsRef<Path>, line_ending: LineEnding, ) -> Result<()>

Available on crate feature std only.

Write private key as an OpenSSH-formatted PEM file.

Errors

• Returns Error::Io on I/O errors.
• Returns Error::Encoding in the event of an encoding error.

pub fn decrypt(&self, password: impl AsRef<[u8]>) -> Result<Self>

Available on crate feature encryption only.

Attempt to decrypt an encrypted private key using the provided password to derive an encryption key.

Errors

Returns Error::Decrypted if the private key is already decrypted.

pub fn encrypt<R: TryCryptoRng + ?Sized>( &self, rng: &mut R, password: impl AsRef<[u8]>, ) -> Result<Self>

Available on crate feature encryption only.

Encrypt an unencrypted private key using the provided password to derive an encryption key.

Uses the following algorithms:

• Cipher: Cipher::Aes256Ctr
• KDF: Kdf::Bcrypt (i.e. bcrypt-pbkdf)

Errors

Returns Error::Encrypted if the private key is already encrypted.

pub fn encrypt_with_cipher<R: TryCryptoRng + ?Sized>( &self, rng: &mut R, cipher: Cipher, password: impl AsRef<[u8]>, ) -> Result<Self>

Available on crate feature encryption only.

Encrypt an unencrypted private key using the provided password to derive an encryption key for the provided Cipher.

Errors

Returns Error::Encrypted if the private key is already encrypted.

pub fn encrypt_with( &self, cipher: Cipher, kdf: Kdf, checkint: u32, password: impl AsRef<[u8]>, ) -> Result<Self>

Available on crate feature encryption only.

Encrypt an unencrypted private key using the provided cipher and KDF configuration.

Errors

Returns Error::Encrypted if the private key is already encrypted.

pub fn algorithm(&self) -> Algorithm

Get the digital signature Algorithm used by this key.

pub fn comment(&self) -> &Comment

Available on crate feature alloc only.

Comment on the key (e.g. email address).

pub fn cipher(&self) -> Cipher

Cipher algorithm (a.k.a. ciphername).

pub fn fingerprint(&self, hash_alg: HashAlg) -> Fingerprint

Compute key fingerprint.

Use Default::default() to use the default hash function (SHA-256).

pub fn is_encrypted(&self) -> bool

Is this key encrypted?

pub fn kdf(&self) -> &Kdf

Key Derivation Function (KDF) used to encrypt this key.

Returns Kdf::None if this key is not encrypted.

pub fn key_data(&self) -> &KeypairData

Keypair data.

pub fn public_key(&self) -> &PublicKey

Get the PublicKey which corresponds to this private key.

pub fn random<R: CryptoRng + ?Sized>( rng: &mut R, algorithm: Algorithm, ) -> Result<Self>

Available on crate feature rand_core only.

Generate a random key which uses the given algorithm.

Errors

Returns Error::AlgorithmUnknown if the algorithm is unsupported.

pub fn set_comment(&mut self, comment: impl Into<Comment>)

Available on crate feature alloc only.

Set the comment on the key.

Trait Implementations

impl Clone for PrivateKey

fn clone(&self) -> PrivateKey

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CtEq for PrivateKey

fn ct_eq(&self, other: &Self) -> Choice

Determine if self is equal to other in constant-time.

fn ct_ne(&self, other: &Rhs) -> Choice

Determine if self is NOT equal to other in constant-time.

impl Debug for PrivateKey

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Decode for PrivateKey

type Error = Error

Type returned in the event of a decoding error.

fn decode(reader: &mut impl Reader) -> Result<Self>

Attempt to decode a value of this type using the provided Reader.

impl Encode for PrivateKey

fn encoded_len(&self) -> Result<usize>

Get the length of this type encoded in bytes, prior to Base64 encoding.

fn encode(&self, writer: &mut impl Writer) -> Result<()>

Encode this value using the provided Writer.

fn encoded_len_prefixed(&self) -> Result<usize, Error>

Return the length of this type after encoding when prepended with a uint32 length prefix.

fn encode_prefixed(&self, writer: &mut impl Writer) -> Result<(), Error>

Encode this value, first prepending a uint32 length prefix set to Encode::encoded_len.

fn encode_vec(&self) -> Result<Vec<u8>, Error>

Available on crate feature alloc only.

Encode this value, returning a Vec<u8> containing the encoded message.

impl From<&PrivateKey> for KeyData

fn from(private_key: &PrivateKey) -> KeyData

Converts to this type from the input type.

impl From<&PrivateKey> for PublicKey

fn from(private_key: &PrivateKey) -> PublicKey

Converts to this type from the input type.

impl From<DsaKeypair> for PrivateKey

Available on crate feature alloc only.

fn from(keypair: DsaKeypair) -> PrivateKey

Converts to this type from the input type.

impl From<EcdsaKeypair> for PrivateKey

Available on crate feature ecdsa only.

fn from(keypair: EcdsaKeypair) -> PrivateKey

Converts to this type from the input type.

impl From<Ed25519Keypair> for PrivateKey

fn from(keypair: Ed25519Keypair) -> PrivateKey

Converts to this type from the input type.

impl From<PrivateKey> for KeyData

fn from(private_key: PrivateKey) -> KeyData

Converts to this type from the input type.

impl From<PrivateKey> for PublicKey

fn from(private_key: PrivateKey) -> PublicKey

Converts to this type from the input type.

impl From<RsaKeypair> for PrivateKey

Available on crate feature alloc only.

fn from(keypair: RsaKeypair) -> PrivateKey

Converts to this type from the input type.

impl From<SkEcdsaSha2NistP256> for PrivateKey

Available on crate features alloc and ecdsa only.

fn from(keypair: SkEcdsaSha2NistP256) -> PrivateKey

Converts to this type from the input type.

impl From<SkEd25519> for PrivateKey

Available on crate feature alloc only.

fn from(keypair: SkEd25519) -> PrivateKey

Converts to this type from the input type.

impl FromStr for PrivateKey

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self>

Parses a string s to return a value of this type.

impl PartialEq for PrivateKey

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PemLabel for PrivateKey

const PEM_LABEL: &'static str = "OPENSSH PRIVATE KEY"

Expected PEM type label for a given document, e.g. "PRIVATE KEY"

fn validate_pem_label(actual: &str) -> Result<(), Error>

Validate that a given label matches the expected label.

impl Signer<Signature> for PrivateKey

Available on crate feature alloc only.

fn try_sign(&self, message: &[u8]) -> Result<Signature>

Attempt to sign the given message, returning a digital signature on success, or an error if something went wrong.

fn sign(&self, msg: &[u8]) -> S

Sign the given message and return a digital signature.

impl TryFrom<KeypairData> for PrivateKey

type Error = Error

The type returned in the event of a conversion error.

fn try_from(key_data: KeypairData) -> Result<PrivateKey>

Performs the conversion.

impl Eq for PrivateKey