Create Example Documentation

[WingZer0o]

@rakurame96 I am making this ticket as we discussed through email. I will provide some examples of demonstration code in this thread. I think it will be good to have examples for the specific usage case of each cryptographic algorithm from a file.

So for instance I would read a file from disk and get the bytes and perform the necessary operation.

Hashers would compare two hashes of different files and show a true / false example. I can some code examples in this thread for a hash and aes_gcm.

• Asymmetric
• Compression
• Digital Signature
• ecdsa
• hashers
• hybrid
• key_exchange
• message
• password_hashers
• signatures
• sponges
• symmetric

[WingZer0o]

@rakurame96 I made an example for AES 256 encrypting and decrypting a docx and writing it disk after each round. This way the user can see its encrypted but when the bytes decrypted its the same file that is written to disk as the original.

You can test this by doing a cargo init then doing cargo add cas-lib.

use std::{fs::{File}, io::Write, path::Path};

use cas_lib::symmetric::{aes::CASAES256, cas_symmetric_encryption::CASAESEncryption};

fn main() {
    let path = Path::new("MikeMulchrone_Resume2024.docx");
    let file_bytes: Vec<u8> = std::fs::read(path).unwrap();
    let aes_nonce = <CASAES256 as CASAESEncryption>::generate_nonce();
    let aes_key = <CASAES256 as CASAESEncryption>::generate_key();
    let encrypted_bytes = <CASAES256 as CASAESEncryption>::encrypt_plaintext(aes_key.clone(), aes_nonce.clone(), file_bytes);
    let mut file =  File::create("encrypted.docx").unwrap();
    file.write_all(&encrypted_bytes);

    let path = Path::new("encrypted.docx");
    let file_bytes: Vec<u8> = std::fs::read(path).unwrap();
    let decrypted_bytes = <CASAES256 as CASAESEncryption>::decrypt_ciphertext(aes_key, aes_nonce, file_bytes);
    let mut file =  File::create("decrypted.docx").unwrap();
    file.write_all(&decrypted_bytes);
}

[WingZer0o]

I created a .md file at this location, https://github.com/Cryptographic-API-Services/cas-lib/blob/main/docs/EXAMPLES.md

[rakurame96]

Hello Michael,

Thank you for providing the markdown file. I will begin working on these examples next week and assign this ticket to myself.

[rakurame96]

Hi @WingZer0o,

I just created a PR (#15) with the above example, placed inside tests/ folder. Created binary crate with name symmetric and added the code. Do you have any other ideas, or continue the current approach?

[WingZer0o]

Hello, I took a quick glance at the code this would be great to incorporate a test suite. I made a separate issue for that but we can combine them. If you could get this to run with a cargo test that would be fantastic and I think it would be a good way to continue approaching examples. I will be out of town for a few days before I merged anything into main.

…

On Tue, Nov 26, 2024 at 1:10 PM Rakuram ***@***.***> wrote: Hi @WingZer0o <https://github.com/WingZer0o>, I just created a PR (#15 <#15>) with the above example, placed inside tests/ folder. Created binary crate with name symmetric and added the code. Do you have any other ideas, or continue the current approach? — Reply to this email directly, view it on GitHub <#7 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BEG2SNGFDO2F3OF62ODUENL2CS2RXAVCNFSM6AAAAABSIAOSKWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKMBRGYZDCNRWGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[rakurame96]

Hi,
I managed to update the symmetric test to invoke upon cargo test command. I pushed the changes to the same PR. If it is good, then I will slowly start for other algorithms as well.

[WingZer0o]

I will have a look in a few days and run on my computer I’m currently out of town with no laptop.

…

On Fri, Nov 29, 2024 at 7:09 AM Rakuram ***@***.***> wrote: Hi, I managed to update the symmetric test to invoke upon cargo test command. I pushed the changes to the same PR. If it is good, then I will slowly start for other algorithms as well. — Reply to this email directly, view it on GitHub <#7 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BEG2SNGDA73MUGNHX7QJ56T2DBKPVAVCNFSM6AAAAABSIAOSKWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKMBXGY4DMOJTHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[WingZer0o]

@rakurame96 I started working on the hasher test cases here. I still have to create example but this fail and success comparison will be a good addition to the test suite.

https://github.com/Cryptographic-API-Services/cas-lib/blob/main/tests/hashers.rs

[rakurame96]

Thanks for the info. For next tests, which one should I consider?

So far, hashers & symmetric has been in good shape with more scenarios can be added in future.

[WingZer0o]

I thinking wrapping up the threadpool methods for the SHA3 hashes would be best and moving onto the blake2 hash. If you wanna take those up lemme know.

आपकी सहायता के लिए धन्यवाद

[rakurame96]

Sure, but would require some assistance from you in this regard.

[WingZer0o]

Honestly the best way to go about this would be to mimic the existing test cases for the SHA256 and SHA512 test cases that I already created, the threadpool methods just have the characters _threadpool appended on it. Here is an example for SHA256 threadpool.

fn test_sha_256_threadpool_compare_fail() {
        let path = Path::new("tests/test.docx");
        let file_bytes: Vec<u8> = std::fs::read(path).unwrap();
        let hash = <CASSHA as CASHasher>::hash_256_threadpool(file_bytes);

        let path_2 = Path::new("tests/test2.docx");
        let file_bytes_2: Vec<u8> = std::fs::read(path_2).unwrap();
        let hash_2 = <CASSHA as CASHasher>::hash_256_threadpool(file_bytes_2);

        assert_ne!(hash, hash_2);
    }

[rakurame96]

Got it. I have created PR for this.

During build, I have noticed many Clippy warnings. Should we add an appropriate command to suppress them or look for permanent fix? Most of them were related to unused variables warnings.

[WingZer0o]

Probably a fix would be more appropriate but I wouldn’t worry about it in this PR. I’ll have a closer look after the holidays.

…

On Thu, Dec 26, 2024 at 4:25 AM Rakuram ***@***.***> wrote: Got it. I have created PR for this. During build, I have noticed many Clippy warnings. Should we add an appropriate command to suppress them or look for permanent fix? Most of them were related to unused variables warnings. — Reply to this email directly, view it on GitHub <#7 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BEG2SNB6MHIA2P2WP7CS55D2HPDPHAVCNFSM6AAAAABSIAOSKWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKNRSGM2TSMZQGQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>