floe-rs 0.1.0

Implementation of the FLOE cryptographic construction
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

// Copyright 2026 Damir Jelić.
// SPDX-License-Identifier: Apache-2.0
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Implementation of Floe using the AES-GCM variant.
//!
//! The crate offers a generic Floe implementation. This module specializes it
//! by providing type aliases for the GCM-based variant.

use aead::{Key, consts::U48};
use aes_gcm::Aes256Gcm;
use hmac::Hmac;
use sha2::Sha384;

use crate::{FloeAead, FloeKdf};

const FLOE_IV_LENGTH: usize = 32;

impl FloeKdf for Hmac<Sha384> {
    // As per the Floe spec defined in the derived parameters part:
    // https://github.com/Snowflake-Labs/floe-specification/blob/main/spec/README.md#derived-parameters
    type KeySize = U48;
    const KDF_ID: u8 = 0;
}

impl FloeAead for Aes256Gcm {
    // As per the Floe spec defined in the derived parameters part:
    // https://github.com/Snowflake-Labs/floe-specification/blob/main/spec/README.md#derived-parameters
    const AEAD_ID: u8 = 0;
    const AEAD_ROTATION_MASK: u64 = !((1u64 << 20) - 1);
    const AEAD_MAX_SEGMENTS: u64 = 1 << 40;
}

pub type FloeEncryptor<'a, const S: u32> =
    crate::random_access::FloeEncryptor<'a, Aes256Gcm, Hmac<Sha384>, FLOE_IV_LENGTH, S>;

pub type FloeDecryptor<'a, const S: u32> =
    crate::random_access::FloeDecryptor<'a, Aes256Gcm, Hmac<Sha384>, FLOE_IV_LENGTH, S>;

pub type FloeKey = Key<Aes256Gcm>;

/// The initialization vector of a Floe-Gcm session.
///
/// This variant of the initialization vector is 32 bytes long.
///
/// This initialization vector is randomly generated at the start of the
/// encryption operation.
pub type FloeIv = crate::types::FloeIv<FLOE_IV_LENGTH>;

/// The header of a Floe GCM ciphertext.
///
/// The Floe ciphertext consists of a header and a body. This struct represents
/// the header which contains:
/// * parameter information
/// * the 32-byte Floe initialization vector
/// * a tag
///
/// The header is created before the first segment is encrypted and is required
/// before any segment can be decrypted.
///
/// # Examples
///
/// ```no_run
/// use floe_rs::gcm::Header;
///
/// # let bytes: &[u8] = unimplemented!();
/// let header = Header::from_bytes(bytes)?;
///
/// // Now you can create a decryptor to attempt segment decryption.
/// # Ok::<(), anyhow::Error>(())
/// ```
pub type Header = crate::types::Header<FLOE_IV_LENGTH>;

/// Attempt to decode a slice of bytes as a Floe-Gcm [`Segment`]
///
/// *Note*: This only attempts to reinterpret the bytes as a valid
/// [`Segment`], as such it does not copy any data.
///
/// # Examples
///
/// ```no_run
/// use floe_rs::gcm::Segment;
///
/// # let bytes: &[u8] = unimplemented!();
/// let segment = Segment::from_bytes(bytes)?;
/// let buffer = vec![0u8; segment.plaintext_size()];
///
/// // Now you can attempt to decrypt the segment.
/// # Ok::<(), anyhow::Error>(())
/// ```
pub type Segment<'a> = crate::types::segment::Segment<'a, Aes256Gcm>;