arrayref.rs (3928B)
1 // Copyright 2023 Cryspen Sarl 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 9 //! This module contains the trait and related errors for a KEM that takes array references as 10 //! arguments and writes to outputs to mutable array references. 11 12 /// A Key Encapsulation Mechanismd (KEM). This trait is the most low-level and mostly used in the 13 /// implementation of other, more usabe APIs on top. 14 pub trait Kem< 15 const EK_LEN: usize, 16 const DK_LEN: usize, 17 const CT_LEN: usize, 18 const SS_LEN: usize, 19 const RAND_KEYGEN_LEN: usize, 20 const RAND_ENCAPS_LEN: usize, 21 > 22 { 23 /// Generate a pair of encapsulation and decapsulation keys. 24 /// It is the responsibility of the caller to ensure that the `rand` argument is actually 25 /// random. 26 fn keygen( 27 ek: &mut [u8; EK_LEN], 28 dk: &mut [u8; DK_LEN], 29 rand: &[u8; RAND_KEYGEN_LEN], 30 ) -> Result<(), KeyGenError>; 31 32 /// Encapsulate a shared secret towards a given encapsulation key. 33 /// It is the responsibility of the caller to ensure that the `rand` argument is actually 34 /// random. 35 fn encaps( 36 ct: &mut [u8; CT_LEN], 37 ss: &mut [u8; SS_LEN], 38 ek: &[u8; EK_LEN], 39 rand: &[u8; RAND_ENCAPS_LEN], 40 ) -> Result<(), EncapsError>; 41 42 /// Decapsulate a shared secret. 43 fn decaps( 44 ss: &mut [u8; SS_LEN], 45 ct: &[u8; CT_LEN], 46 dk: &[u8; DK_LEN], 47 ) -> Result<(), DecapsError>; 48 } 49 50 /// Error generating key with provided randomness 51 #[derive(Debug)] 52 pub enum KeyGenError { 53 /// Error generating key with provided randomness 54 InvalidRandomness, 55 56 /// An unknown error occurred 57 Unknown, 58 } 59 60 /// Error indicating that encapsulating failed 61 #[derive(Debug)] 62 pub enum EncapsError { 63 /// Encapsulation key is invalid 64 InvalidEncapsKey, 65 66 /// Error encapsulating key with provided randomness 67 InvalidRandomness, 68 69 /// An unknown error occurred 70 Unknown, 71 } 72 73 /// Error indicating that decapsulating failed 74 #[derive(Debug)] 75 pub enum DecapsError { 76 /// Ciphertext key is invalid 77 InvalidCiphertext, 78 79 /// Decapsulation key is invalid 80 InvalidDecapsKey, 81 82 /// An unknown error occurred 83 Unknown, 84 } 85 86 impl core::fmt::Display for KeyGenError { 87 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { 88 let text = match self { 89 KeyGenError::InvalidRandomness => "error generating key with provided randomness", 90 KeyGenError::Unknown => "an unknown error occurred", 91 }; 92 93 f.write_str(text) 94 } 95 } 96 97 impl core::fmt::Display for EncapsError { 98 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { 99 let text = match self { 100 EncapsError::InvalidEncapsKey => "encapsulation key is invalid", 101 EncapsError::InvalidRandomness => "error generating key with provided randomness", 102 EncapsError::Unknown => "an unknown error occurred", 103 }; 104 105 f.write_str(text) 106 } 107 } 108 109 impl core::fmt::Display for DecapsError { 110 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { 111 let text = match self { 112 DecapsError::InvalidDecapsKey => "encapsulation key is invalid", 113 DecapsError::InvalidCiphertext => "ciphertext is invalid", 114 DecapsError::Unknown => "an unknown error occurred", 115 }; 116 117 f.write_str(text) 118 } 119 } 120 121 #[cfg(feature = "error-in-core")] 122 /// Here we implement the Error trait. This has only been added to core relatively recently, so we 123 /// are hiding that behind a feature. 124 mod error_in_core { 125 impl core::error::Error for super::EncapsError {} 126 impl core::error::Error for super::DecapsError {} 127 impl core::error::Error for super::KeyGenError {} 128 }