Crate secret_integers

Expand description

This crate defines simple wrappers around Rust’s integer type to guarantee they are used in a constant-time fashion. Hence, division and direct comparison of these “secret” integers is disallowed.

These integers are intended to be the go-to type to use when implementing cryptographic software, as they provide an extra automated check against use of variable-time operations.

To use the crate, just import everything (use secret_integers::*;) and replace your integer types with uppercase versions of their names (e.g. u8 -> U8).

§Examples

In order to print information or test code involving your secret integers, you need first to declassify them. Your crypto code should not contain any declassify occurence though to guarantee constant-timedness. Make sure to specify the type of your literals when classifying (e.g. 0x36u16) or else you’ll get a casting error.

let x = U32::classify(1u32);
let y : U32 = 2u32.into();
assert_eq!((x + y).declassify(), 3);

Using an illegal operation will get you a compile-time error:

let x = U32::classify(4u32);
let y : U32 = 2u32.into();
assert_eq!((x / y).declassify(), 2);

Since indexing arrays and vectors is only possible with usize, these secret integers also prevent you from using secret values to index memory (which is a breach to constant-timedness due to cache behaviour).

fn xor_block(block1: &mut [U64;16], block2: &[U64;16]) {
   for i in 0..16 {
     block1[i] ^= block2[i]
   }
}

See the Dalek and Chacha20 examples for more details on how to use this crate.

§Const-compatibility

Because stable Rust does not allow constant functions for now, it is impossible to use those wrappers in const declarations. Even classifying directly inside the declaration does not work:

const IV : [U32;2] = [U32::classify(0xbe6548u32),U32::classify(0xaec6d48u32)]

For now, the solution is to map your const items with classify once you’re inside a function, or call into.

const IV : [u32;2] = [0xbe6548, 0xaec6d48];

fn start_cipher(plain: &mut Vec<U32>) {
   for i in 0..plain.len() {
     plain[i] = plain[i] | (plain[i] ^ IV[i].into());
   }
}

Structs§

I8
I16
I32
I64
I128
U8
U16
U32
U64
U128

Functions§

I8_from_I16: Warning: wrapping semantics.
I8_from_I32: Warning: wrapping semantics.
I8_from_I64: Warning: wrapping semantics.
I8_from_I128: Warning: wrapping semantics.
I16_from_I8
I16_from_I32: Warning: wrapping semantics.
I16_from_I64: Warning: wrapping semantics.
I16_from_I128: Warning: wrapping semantics.
I32_from_I8
I32_from_I16
I32_from_I64: Warning: wrapping semantics.
I32_from_I128: Warning: wrapping semantics.
I64_from_I8
I64_from_I16
I64_from_I32
I64_from_I128: Warning: wrapping semantics.
I128_from_I8
I128_from_I16
I128_from_I32
I128_from_I64
U8_from_U16: Warning: wrapping semantics.
U8_from_U32: Warning: wrapping semantics.
U8_from_U64: Warning: wrapping semantics.
U8_from_U128: Warning: wrapping semantics.
U8_from_usize
U16_from_U8
U16_from_U32: Warning: wrapping semantics.
U16_from_U64: Warning: wrapping semantics.
U16_from_U128: Warning: wrapping semantics.
U32_from_U8
U32_from_U16
U32_from_U64: Warning: wrapping semantics.
U32_from_U128: Warning: wrapping semantics.
U64_from_U8
U64_from_U16
U64_from_U32
U64_from_U128: Warning: wrapping semantics.
U64_from_usize
U128_from_U8
U128_from_U16
U128_from_U32
U128_from_U64
U128_from_usize
declassify_u8_from_U8: Warning: conversion can be lossy!
declassify_u16_from_U8: Warning: conversion can be lossy!
declassify_u16_from_U16: Warning: conversion can be lossy!
declassify_u32_from_U8: Warning: conversion can be lossy!
declassify_u32_from_U16: Warning: conversion can be lossy!
declassify_u32_from_U32: Warning: conversion can be lossy!
declassify_u64_from_U8: Warning: conversion can be lossy!
declassify_u64_from_U16: Warning: conversion can be lossy!
declassify_u64_from_U32: Warning: conversion can be lossy!
declassify_u64_from_U64: Warning: conversion can be lossy!
declassify_u128_from_U8: Warning: conversion can be lossy!
declassify_u128_from_U32: Warning: conversion can be lossy!
declassify_u128_from_U64: Warning: conversion can be lossy!
declassify_u128_from_U128: Warning: conversion can be lossy!
declassify_usize_from_U8: Warning: conversion can be lossy!
u8_from_U16
u8_from_U32
u8_from_U64
u8_from_U128
u16_from_U32
u16_from_U64
u16_from_U128
u32_from_U64
u32_from_U128
u64_from_U128
u128_from_U16: Warning: conversion can be lossy!