Struct yaca::Key

pub struct Key { /* fields omitted */ }

Type representing a cryptography key, an Initialization Vector or key generation parameters

Implementations

impl Key

pub fn generate(key_type: &KeyType, key_length: &KeyLength) -> Result<Key>

Generates a secure key, an Initialization Vector or key generation parameters

• This function is used to generate:
  • symmetric keys,
  • private asymmetric keys,
  • key generation parameters for key types that support them (DsaParams, DhParams and EcParams).
• Supported key_length for a specific key_type:
  • Symmetric/IV: use KeyLength::Bits, bits >= 8,
  • DES: use KeyLength::Bits, bits == 64, 128 or 192,
  • RSA: use KeyLength::Bits, bits >= 512,
  • DSA: use KeyLength::Bits, bits >= 512, divisble by 64,
  • DH: use KeyLength::Dh, see KeyLengthDh for more information,
  • EC: use KeyLength::Ec, see KeyLengthEc for more information.

pub fn generate_from_parameters(params: &Key) -> Result<Key>

Generates a secure private asymmetric key from parameters

• This function is used to generate private asymmetric keys based on pre-generated parameters in params.
• This function does not support RSA keys, as it's not possible to extract parameters from them.

pub fn import(
    data: &[u8],
    key_type: &KeyType,
    password: Option<&CStr>
) -> Result<Key>

Imports a key or key generation parameters

• Everywhere where either a key (of any type) or an asymmetric key is referred in the documentation of this function key generator parameters are also included.
• This function imports a key from data trying to match it to the key_type specified. It should autodetect both the key format and the file format.
• For Symmetric, Initialization Vector and DES keys RAW binary format and BASE64 encoded binary format are supported.
• For asymmetric keys PEM and DER file formats are supported.
• Asymmetric keys can be in their default ASN1 structure formats (like PKCS#1, SSleay or PKCS#3). Private asymmetric keys can also be in PKCS#8 format. Additionally it is possible to import public RSA/DSA/EC keys from X509 certificate.
• If the key is encrypted the algorithm will be autodetected and password used. If it's not known if the key is encrypted one should pass None as password and check for the Error::InvalidPassword error code.
• If the imported key will be detected as a format that does not support encryption and password was passed Error::InvalidParameter will be returned. For a list of keys and formats that do support encryption see Key::export() documentation.

pub fn export(
    &self,
    key_fmt: &KeyFormat,
    key_file_fmt: &KeyFileFormat,
    password: Option<&CStr>
) -> Result<Vec<u8>>

Exports a key or key generation parameters to arbitrary format

• Everywhere where either a key (of any type) or an asymmetric key is referred in the documentation of this function key generator parameters are also included.
• This function exports the key to an arbitrary key_format and key_file_fmt.
• For key formats two values are allowed:
  • KeyFormat::Default: this is the only option possible in case of symmetric keys (or Initialization Vector), for asymmetric keys it will export to their default ASN1 structure format (e.g. PKCS#1, SSLeay, PKCS#3).
  • KeyFormat::Pkcs8: this will only work for private asymmetric keys.
• The following file formats are supported:
  • KeyFileFormat::Raw: used only for symmetric, raw binary format,
  • KeyFileFormat::Base64: used only for symmetric, BASE64 encoded binary form,
  • KeyFileFormat::Pem: used only for asymmetric, PEM file format,
  • KeyFileFormat::Der: used only for asymmetric, DER file format.
• Encryption is supported and optional for RSA/DSA private keys in the KeyFormat::Default with KeyFileFormat::Pem format. If no password is provided the exported key will be unencrypted. The encryption algorithm used in this case is AES-256-CBC.
• Encryption is obligatory for KeyFormat::Pkcs8 format (for both, KeyFileFormat::Pem and KeyFileFormat::Der file formats). If no password is provided the Error::InvalidParameter will be returned. The encryption algorithm used in this case is AES-256-CBC. The key is generated from password using PBKDF2 with HMAC-SHA1 function and 2048 iterations.
• Encryption is not supported for the symmetric, public keys and key generation parameters in all their supported formats. If a password is provided in such case the Error::InvalidParameter will be returned.

pub fn extract_public(&self) -> Result<Key>

Extracts public key from a private one

pub fn extract_parameters(&self) -> Result<Key>

Extracts parameters from a private or a public key

• This function does not support RSA keys.

pub fn derive_dh(prv_key: &Key, pub_key: &Key) -> Result<Vec<u8>>

Derives a shared secret using Diffie-Hellman or EC Diffie-Hellman key exchange protocol

• prv_key is our private key.
• pub_key is a peer public key.
• The returned secret should not be used as a symmetric key. To produce a symmetric key pass the secret to a key derivation function (KDF) or a message digest function.
• Both the keys passed should be of DH or EC type.

pub fn derive_kdf(
    kdf: &Kdf,
    algo: &DigestAlgorithm,
    secret: &[u8],
    info: Option<&[u8]>,
    key_material_len: usize
) -> Result<Vec<u8>>

Derives a key material from shared secret

• kdf is a key derivation function
• digest is a digest algorithm used in key derivation
• secret is a shared secret that can be derived for instance from Key::derive_dh().
• The optional info parameter is ANSI X9.42 OtherInfo or ANSI X9.62 SharedInfo structure, more information can be found in ANSI X9.42/62 standard specification.
• The returned key material (of key_material_len length) or separate parts of it can be used to import a symmetric key with Key::import().

pub fn derive_pbkdf2(
    password: &CStr,
    salt: Option<&[u8]>,
    iterations: usize,
    algo: &DigestAlgorithm,
    key_bit_len: usize
) -> Result<Key>

Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm)

• password is a user password.
• optional salt can be passed.
• iterations defines number of iterations during the generation.
• algo is a digest algorithm used in key generation.
• the returned key will be of key_bit_len length.

pub fn get_type(&self) -> Result<KeyType>

Gets key's type

pub fn get_length(&self) -> Result<KeyLength>

Gets key's length

• Can be used on any symmetric (including an Initialization Vector) or asymmetric key (including key generation parameters).
• For Diffie-Hellman returns prime length in KeyLength::Bits. Values of KeyLengthDh used to generate the key/parameters in Key::generate() are not restored.
• For Elliptic Curves returns values from KeyLengthEc.

Trait Implementations

impl Drop for Key

pub fn drop(&mut self)

Executes the destructor for this type.