AES module level docs and example

[AndyGauge]

Fixes #698

[sfackler]

It's a form, not the form. An obscure one at that.

[sfackler]

This should probably mention that most people looking for symmetric encryption should be using the Crypter type. This module maps to the lower-level and more obscure options that aren't covered by the Crypter interface.

[sfackler]

There are 128 and 256 bit variants of AES.

I'm not sure what the panic note is referring to - aes_ige doesn't have any asserts around the lengths of the input and output buffers.

[BrianOn99]

@sfackler I think it is refering to those lines

/// Performs AES IGE encryption or decryption
///
/// # Panics
///
/// Panics if `in_` is not the same length as `out`, if that length is not a multiple of 16, or if
/// `iv` is not at least 32 bytes.
pub fn aes_ige(in_: &[u8], out: &mut [u8], key: &AesKey, iv: &mut [u8], mode: Mode) {
    unsafe {
        assert!(in_.len() == out.len());
        assert!(in_.len() % ffi::AES_BLOCK_SIZE as usize == 0);
        assert!(iv.len() >= ffi::AES_BLOCK_SIZE as usize * 2);

Doesn't it panic if the buffer lengths is not multiple of ffi::AES_BLOCK_SIZE ?

[AndyGauge]

I can see the confusion. I'll try to incorporate both of those details at the top (the key is 128-bit, 192-bit, or 256-bit and that the input must be bounded to 16-bytes)

[sfackler]

Oh jeez, I totally misread in_ as iv, sorry!

…

On Wed, Sep 27, 2017 at 10:40 PM Chiu Yue Chun ***@***.***> wrote: *@BrianOn99* commented on this pull request. ------------------------------ In openssl/src/aes.rs <#734 (comment)>: > //! -//! The `symm` module should be used in preference to this module in most cases. +//! AES ECB, CBC, XTS, CTR, CFB, GCM and other conventional symmetric encryption +//! modes are found in [`symm`]. This is the implementation of AES IGE. +//! +//! Advanced Encryption Standard (AES) provides symmetric key cipher that +//! the same key is used to encrypt and decrypt data. This implementation +//! uses 128, 192, or 256 bit keys. This module provides functions to +//! create a new key with [`new_encrypt`] and perform an encryption/decryption +//! using that key with [`aes_ige`]. +//! +//! AES is a 128-bit (16 byte) block cipher. The rust implmentation will panic @sfackler <https://github.com/sfackler> I think it is refering to those lines /// Performs AES IGE encryption or decryption////// # Panics////// Panics if `in_` is not the same length as `out`, if that length is not a multiple of 16, or if/// `iv` is not at least 32 bytes.pub fn aes_ige(in_: &[u8], out: &mut [u8], key: &AesKey, iv: &mut [u8], mode: Mode) { unsafe { assert!(in_.len() == out.len()); assert!(in_.len() % ffi::AES_BLOCK_SIZE as usize == 0); assert!(iv.len() >= ffi::AES_BLOCK_SIZE as usize * 2); Doesn't it panic if the buffer lengths is not multiple of ffi::AES_BLOCK_SIZE ? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#734 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABY2UfNdRXPzuCRlL3cKmuS7ALmD25pmks5smzFVgaJpZM4PlCHL> .

[sfackler]

I would move those details to the function they describe though.

…

On Wed, Sep 27, 2017 at 10:51 PM Steven Fackler ***@***.***> wrote: Oh jeez, I totally misread in_ as iv, sorry! On Wed, Sep 27, 2017 at 10:40 PM Chiu Yue Chun ***@***.***> wrote: > *@BrianOn99* commented on this pull request. > ------------------------------ > > In openssl/src/aes.rs > <#734 (comment)> > : > > > //! > -//! The `symm` module should be used in preference to this module in most cases. > +//! AES ECB, CBC, XTS, CTR, CFB, GCM and other conventional symmetric encryption > +//! modes are found in [`symm`]. This is the implementation of AES IGE. > +//! > +//! Advanced Encryption Standard (AES) provides symmetric key cipher that > +//! the same key is used to encrypt and decrypt data. This implementation > +//! uses 128, 192, or 256 bit keys. This module provides functions to > +//! create a new key with [`new_encrypt`] and perform an encryption/decryption > +//! using that key with [`aes_ige`]. > +//! > +//! AES is a 128-bit (16 byte) block cipher. The rust implmentation will panic > > @sfackler <https://github.com/sfackler> I think it is refering to those > lines > > /// Performs AES IGE encryption or decryption////// # Panics////// Panics if `in_` is not the same length as `out`, if that length is not a multiple of 16, or if/// `iv` is not at least 32 bytes.pub fn aes_ige(in_: &[u8], out: &mut [u8], key: &AesKey, iv: &mut [u8], mode: Mode) { > unsafe { > assert!(in_.len() == out.len()); > assert!(in_.len() % ffi::AES_BLOCK_SIZE as usize == 0); > assert!(iv.len() >= ffi::AES_BLOCK_SIZE as usize * 2); > > Doesn't it panic if the buffer lengths is not multiple of > ffi::AES_BLOCK_SIZE ? > > — > You are receiving this because you were mentioned. > > > Reply to this email directly, view it on GitHub > <#734 (comment)>, > or mute the thread > <https://github.com/notifications/unsubscribe-auth/ABY2UfNdRXPzuCRlL3cKmuS7ALmD25pmks5smzFVgaJpZM4PlCHL> > . >

[BrianOn99]

Agree, and the line 128-bit (16 byte) block cipher need change.

[BrianOn99]

Sorry. that line is correct. Please ignore my prevoius comment.

[sfackler]

Looks good, thanks!