Received-SPF: pass (google.com: domain of linux-kernel+bounces-181502-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
From: Ariel Miculas <amiculas@cisco.com>
To: rust-for-linux@vger.kernel.org
Cc: linux-kernel@vger.kernel.org, linux-fsdevel@vger.kernel.org,
        tycho@tycho.pizza, brauner@kernel.org, viro@zeniv.linux.org.uk,
        ojeda@kernel.org, alex.gaynor@gmail.com, wedsonaf@gmail.com,
        shallyn@cisco.com, Ariel Miculas <amiculas@cisco.com>
Subject: [RFC PATCH v3 02/22] rust: hex: import crate
Date: Thu, 16 May 2024 22:03:25 +0300
Message-Id: <20240516190345.957477-3-amiculas@cisco.com>
In-Reply-To: <20240516190345.957477-1-amiculas@cisco.com>
References: <20240516190345.957477-1-amiculas@cisco.com>
Precedence: bulk
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

This is a subset of the Rust `hex` crate,
version v0.4.3, licensed under "Apache-2.0 OR MIT", from:

https://github.com/KokaKiwi/rust-hex/tree/v0.4.3/src

The files are copied as-is, with no modifications whatsoever
(not even adding the SPDX identifiers).

For copyright details, please see:

https://github.com/KokaKiwi/rust-hex/blob/v0.4.3/README.md#license
https://github.com/KokaKiwi/rust-hex/blob/v0.4.3/LICENSE-APACHE
https://github.com/KokaKiwi/rust-hex/blob/v0.4.3/LICENSE-MIT

The next three patches modify these files as needed for use within
the kernel. This patch split allows reviewers to double-check
the import and to clearly see the differences introduced.

The following script may be used to verify the contents:

for path in $(cd rust/hex/ && find . -type f -name '*.rs'); do
    curl --silent --show-error --location \
        https://github.com/KokaKiwi/rust-hex/raw/v0.4.3/src/$path \
        | diff --unified rust/hex/$path - && echo $path: OK
done

Signed-off-by: Ariel Miculas <amiculas@cisco.com>
---
 rust/hex/error.rs |  59 ++++++
 rust/hex/lib.rs   | 525 ++++++++++++++++++++++++++++++++++++++++++++++
 rust/hex/serde.rs | 102 +++++++++
 3 files changed, 686 insertions(+)
 create mode 100644 rust/hex/error.rs
 create mode 100644 rust/hex/lib.rs
 create mode 100644 rust/hex/serde.rs

diff --git a/rust/hex/error.rs b/rust/hex/error.rs
new file mode 100644
index 000000000000..ff7a3b5c16bd
--- /dev/null
+++ b/rust/hex/error.rs
@@ -0,0 +1,59 @@
+use core::fmt;
+
+/// The error type for decoding a hex string into `Vec<u8>` or `[u8; N]`.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum FromHexError {
+    /// An invalid character was found. Valid ones are: `0...9`, `a...f`
+    /// or `A...F`.
+    InvalidHexCharacter { c: char, index: usize },
+
+    /// A hex string's length needs to be even, as two digits correspond to
+    /// one byte.
+    OddLength,
+
+    /// If the hex string is decoded into a fixed sized container, such as an
+    /// array, the hex string's length * 2 has to match the container's
+    /// length.
+    InvalidStringLength,
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for FromHexError {}
+
+impl fmt::Display for FromHexError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match *self {
+            FromHexError::InvalidHexCharacter { c, index } => {
+                write!(f, "Invalid character {:?} at position {}", c, index)
+            }
+            FromHexError::OddLength => write!(f, "Odd number of digits"),
+            FromHexError::InvalidStringLength => write!(f, "Invalid string length"),
+        }
+    }
+}
+
+#[cfg(test)]
+// this feature flag is here to suppress unused
+// warnings of `super::*` and `pretty_assertions::assert_eq`
+#[cfg(feature = "alloc")]
+mod tests {
+    use super::*;
+    #[cfg(feature = "alloc")]
+    use alloc::string::ToString;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    fn test_display() {
+        assert_eq!(
+            FromHexError::InvalidHexCharacter { c: '\n', index: 5 }.to_string(),
+            "Invalid character '\\n' at position 5"
+        );
+
+        assert_eq!(FromHexError::OddLength.to_string(), "Odd number of digits");
+        assert_eq!(
+            FromHexError::InvalidStringLength.to_string(),
+            "Invalid string length"
+        );
+    }
+}
diff --git a/rust/hex/lib.rs b/rust/hex/lib.rs
new file mode 100644
index 000000000000..ec48961b9ffe
--- /dev/null
+++ b/rust/hex/lib.rs
@@ -0,0 +1,525 @@
+// Copyright (c) 2013-2014 The Rust Project Developers.
+// Copyright (c) 2015-2020 The rust-hex Developers.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+//! Encoding and decoding hex strings.
+//!
+//! For most cases, you can simply use the [`decode`], [`encode`] and
+//! [`encode_upper`] functions. If you need a bit more control, use the traits
+//! [`ToHex`] and [`FromHex`] instead.
+//!
+//! # Example
+//!
+//! ```
+//! # #[cfg(not(feature = "alloc"))]
+//! # let mut output = [0; 0x18];
+//! #
+//! # #[cfg(not(feature = "alloc"))]
+//! # hex::encode_to_slice(b"Hello world!", &mut output).unwrap();
+//! #
+//! # #[cfg(not(feature = "alloc"))]
+//! # let hex_string = ::core::str::from_utf8(&output).unwrap();
+//! #
+//! # #[cfg(feature = "alloc")]
+//! let hex_string = hex::encode("Hello world!");
+//!
+//! println!("{}", hex_string); // Prints "48656c6c6f20776f726c6421"
+//!
+//! # assert_eq!(hex_string, "48656c6c6f20776f726c6421");
+//! ```
+
+#![doc(html_root_url = "https://docs.rs/hex/0.4.3")]
+#![cfg_attr(not(feature = "std"), no_std)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![allow(clippy::unreadable_literal)]
+
+#[cfg(feature = "alloc")]
+extern crate alloc;
+#[cfg(feature = "alloc")]
+use alloc::{string::String, vec::Vec};
+
+use core::iter;
+
+mod error;
+pub use crate::error::FromHexError;
+
+#[cfg(feature = "serde")]
+#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
+pub mod serde;
+#[cfg(feature = "serde")]
+pub use crate::serde::deserialize;
+#[cfg(all(feature = "alloc", feature = "serde"))]
+pub use crate::serde::{serialize, serialize_upper};
+
+/// Encoding values as hex string.
+///
+/// This trait is implemented for all `T` which implement `AsRef<[u8]>`. This
+/// includes `String`, `str`, `Vec<u8>` and `[u8]`.
+///
+/// # Example
+///
+/// ```
+/// use hex::ToHex;
+///
+/// println!("{}", "Hello world!".encode_hex::<String>());
+/// # assert_eq!("Hello world!".encode_hex::<String>(), "48656c6c6f20776f726c6421".to_string());
+/// ```
+///
+/// *Note*: instead of using this trait, you might want to use [`encode()`].
+pub trait ToHex {
+    /// Encode the hex strict representing `self` into the result. Lower case
+    /// letters are used (e.g. `f9b4ca`)
+    fn encode_hex<T: iter::FromIterator<char>>(&self) -> T;
+
+    /// Encode the hex strict representing `self` into the result. Upper case
+    /// letters are used (e.g. `F9B4CA`)
+    fn encode_hex_upper<T: iter::FromIterator<char>>(&self) -> T;
+}
+
+const HEX_CHARS_LOWER: &[u8; 16] = b"0123456789abcdef";
+const HEX_CHARS_UPPER: &[u8; 16] = b"0123456789ABCDEF";
+
+struct BytesToHexChars<'a> {
+    inner: ::core::slice::Iter<'a, u8>,
+    table: &'static [u8; 16],
+    next: Option<char>,
+}
+
+impl<'a> BytesToHexChars<'a> {
+    fn new(inner: &'a [u8], table: &'static [u8; 16]) -> BytesToHexChars<'a> {
+        BytesToHexChars {
+            inner: inner.iter(),
+            table,
+            next: None,
+        }
+    }
+}
+
+impl<'a> Iterator for BytesToHexChars<'a> {
+    type Item = char;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        match self.next.take() {
+            Some(current) => Some(current),
+            None => self.inner.next().map(|byte| {
+                let current = self.table[(byte >> 4) as usize] as char;
+                self.next = Some(self.table[(byte & 0x0F) as usize] as char);
+                current
+            }),
+        }
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        let length = self.len();
+        (length, Some(length))
+    }
+}
+
+impl<'a> iter::ExactSizeIterator for BytesToHexChars<'a> {
+    fn len(&self) -> usize {
+        let mut length = self.inner.len() * 2;
+        if self.next.is_some() {
+            length += 1;
+        }
+        length
+    }
+}
+
+#[inline]
+fn encode_to_iter<T: iter::FromIterator<char>>(table: &'static [u8; 16], source: &[u8]) -> T {
+    BytesToHexChars::new(source, table).collect()
+}
+
+impl<T: AsRef<[u8]>> ToHex for T {
+    fn encode_hex<U: iter::FromIterator<char>>(&self) -> U {
+        encode_to_iter(HEX_CHARS_LOWER, self.as_ref())
+    }
+
+    fn encode_hex_upper<U: iter::FromIterator<char>>(&self) -> U {
+        encode_to_iter(HEX_CHARS_UPPER, self.as_ref())
+    }
+}
+
+/// Types that can be decoded from a hex string.
+///
+/// This trait is implemented for `Vec<u8>` and small `u8`-arrays.
+///
+/// # Example
+///
+/// ```
+/// use core::str;
+/// use hex::FromHex;
+///
+/// let buffer = <[u8; 12]>::from_hex("48656c6c6f20776f726c6421")?;
+/// let string = str::from_utf8(&buffer).expect("invalid buffer length");
+///
+/// println!("{}", string); // prints "Hello world!"
+/// # assert_eq!("Hello world!", string);
+/// # Ok::<(), hex::FromHexError>(())
+/// ```
+pub trait FromHex: Sized {
+    type Error;
+
+    /// Creates an instance of type `Self` from the given hex string, or fails
+    /// with a custom error type.
+    ///
+    /// Both, upper and lower case characters are valid and can even be
+    /// mixed (e.g. `f9b4ca`, `F9B4CA` and `f9B4Ca` are all valid strings).
+    fn from_hex<T: AsRef<[u8]>>(hex: T) -> Result<Self, Self::Error>;
+}
+
+fn val(c: u8, idx: usize) -> Result<u8, FromHexError> {
+    match c {
+        b'A'..=b'F' => Ok(c - b'A' + 10),
+        b'a'..=b'f' => Ok(c - b'a' + 10),
+        b'0'..=b'9' => Ok(c - b'0'),
+        _ => Err(FromHexError::InvalidHexCharacter {
+            c: c as char,
+            index: idx,
+        }),
+    }
+}
+
+#[cfg(feature = "alloc")]
+impl FromHex for Vec<u8> {
+    type Error = FromHexError;
+
+    fn from_hex<T: AsRef<[u8]>>(hex: T) -> Result<Self, Self::Error> {
+        let hex = hex.as_ref();
+        if hex.len() % 2 != 0 {
+            return Err(FromHexError::OddLength);
+        }
+
+        hex.chunks(2)
+            .enumerate()
+            .map(|(i, pair)| Ok(val(pair[0], 2 * i)? << 4 | val(pair[1], 2 * i + 1)?))
+            .collect()
+    }
+}
+
+// Helper macro to implement the trait for a few fixed sized arrays. Once Rust
+// has type level integers, this should be removed.
+macro_rules! from_hex_array_impl {
+    ($($len:expr)+) => {$(
+        impl FromHex for [u8; $len] {
+            type Error = FromHexError;
+
+            fn from_hex<T: AsRef<[u8]>>(hex: T) -> Result<Self, Self::Error> {
+                let mut out = [0_u8; $len];
+                decode_to_slice(hex, &mut out as &mut [u8])?;
+                Ok(out)
+            }
+        }
+    )+}
+}
+
+from_hex_array_impl! {
+    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 103 104 105 106 107 108 109 110 111 112
+    113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
+    160 192 200 224 256 384 512 768 1024 2048 4096 8192 16384 32768
+}
+
+#[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
+from_hex_array_impl! {
+    65536 131072 262144 524288 1048576 2097152 4194304 8388608
+    16777216 33554432 67108864 134217728 268435456 536870912
+    1073741824 2147483648
+}
+
+#[cfg(target_pointer_width = "64")]
+from_hex_array_impl! {
+    4294967296
+}
+
+/// Encodes `data` as hex string using lowercase characters.
+///
+/// Lowercase characters are used (e.g. `f9b4ca`). The resulting string's
+/// length is always even, each byte in `data` is always encoded using two hex
+/// digits. Thus, the resulting string contains exactly twice as many bytes as
+/// the input data.
+///
+/// # Example
+///
+/// ```
+/// assert_eq!(hex::encode("Hello world!"), "48656c6c6f20776f726c6421");
+/// assert_eq!(hex::encode(vec![1, 2, 3, 15, 16]), "0102030f10");
+/// ```
+#[must_use]
+#[cfg(feature = "alloc")]
+pub fn encode<T: AsRef<[u8]>>(data: T) -> String {
+    data.encode_hex()
+}
+
+/// Encodes `data` as hex string using uppercase characters.
+///
+/// Apart from the characters' casing, this works exactly like `encode()`.
+///
+/// # Example
+///
+/// ```
+/// assert_eq!(hex::encode_upper("Hello world!"), "48656C6C6F20776F726C6421");
+/// assert_eq!(hex::encode_upper(vec![1, 2, 3, 15, 16]), "0102030F10");
+/// ```
+#[must_use]
+#[cfg(feature = "alloc")]
+pub fn encode_upper<T: AsRef<[u8]>>(data: T) -> String {
+    data.encode_hex_upper()
+}
+
+/// Decodes a hex string into raw bytes.
+///
+/// Both, upper and lower case characters are valid in the input string and can
+/// even be mixed (e.g. `f9b4ca`, `F9B4CA` and `f9B4Ca` are all valid strings).
+///
+/// # Example
+///
+/// ```
+/// assert_eq!(
+///     hex::decode("48656c6c6f20776f726c6421"),
+///     Ok("Hello world!".to_owned().into_bytes())
+/// );
+///
+/// assert_eq!(hex::decode("123"), Err(hex::FromHexError::OddLength));
+/// assert!(hex::decode("foo").is_err());
+/// ```
+#[cfg(feature = "alloc")]
+pub fn decode<T: AsRef<[u8]>>(data: T) -> Result<Vec<u8>, FromHexError> {
+    FromHex::from_hex(data)
+}
+
+/// Decode a hex string into a mutable bytes slice.
+///
+/// Both, upper and lower case characters are valid in the input string and can
+/// even be mixed (e.g. `f9b4ca`, `F9B4CA` and `f9B4Ca` are all valid strings).
+///
+/// # Example
+///
+/// ```
+/// let mut bytes = [0u8; 4];
+/// assert_eq!(hex::decode_to_slice("6b697769", &mut bytes as &mut [u8]), Ok(()));
+/// assert_eq!(&bytes, b"kiwi");
+/// ```
+pub fn decode_to_slice<T: AsRef<[u8]>>(data: T, out: &mut [u8]) -> Result<(), FromHexError> {
+    let data = data.as_ref();
+
+    if data.len() % 2 != 0 {
+        return Err(FromHexError::OddLength);
+    }
+    if data.len() / 2 != out.len() {
+        return Err(FromHexError::InvalidStringLength);
+    }
+
+    for (i, byte) in out.iter_mut().enumerate() {
+        *byte = val(data[2 * i], 2 * i)? << 4 | val(data[2 * i + 1], 2 * i + 1)?;
+    }
+
+    Ok(())
+}
+
+// generates an iterator like this
+// (0, 1)
+// (2, 3)
+// (4, 5)
+// (6, 7)
+// ...
+#[inline]
+fn generate_iter(len: usize) -> impl Iterator<Item = (usize, usize)> {
+    (0..len).step_by(2).zip((0..len).skip(1).step_by(2))
+}
+
+// the inverse of `val`.
+#[inline]
+#[must_use]
+fn byte2hex(byte: u8, table: &[u8; 16]) -> (u8, u8) {
+    let high = table[((byte & 0xf0) >> 4) as usize];
+    let low = table[(byte & 0x0f) as usize];
+
+    (high, low)
+}
+
+/// Encodes some bytes into a mutable slice of bytes.
+///
+/// The output buffer, has to be able to hold at least `input.len() * 2` bytes,
+/// otherwise this function will return an error.
+///
+/// # Example
+///
+/// ```
+/// # use hex::FromHexError;
+/// # fn main() -> Result<(), FromHexError> {
+/// let mut bytes = [0u8; 4 * 2];
+///
+/// hex::encode_to_slice(b"kiwi", &mut bytes)?;
+/// assert_eq!(&bytes, b"6b697769");
+/// # Ok(())
+/// # }
+/// ```
+pub fn encode_to_slice<T: AsRef<[u8]>>(input: T, output: &mut [u8]) -> Result<(), FromHexError> {
+    if input.as_ref().len() * 2 != output.len() {
+        return Err(FromHexError::InvalidStringLength);
+    }
+
+    for (byte, (i, j)) in input
+        .as_ref()
+        .iter()
+        .zip(generate_iter(input.as_ref().len() * 2))
+    {
+        let (high, low) = byte2hex(*byte, HEX_CHARS_LOWER);
+        output[i] = high;
+        output[j] = low;
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+    #[cfg(feature = "alloc")]
+    use alloc::string::ToString;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    fn test_gen_iter() {
+        let result = vec![(0, 1), (2, 3)];
+
+        assert_eq!(generate_iter(5).collect::<Vec<_>>(), result);
+    }
+
+    #[test]
+    fn test_encode_to_slice() {
+        let mut output_1 = [0; 4 * 2];
+        encode_to_slice(b"kiwi", &mut output_1).unwrap();
+        assert_eq!(&output_1, b"6b697769");
+
+        let mut output_2 = [0; 5 * 2];
+        encode_to_slice(b"kiwis", &mut output_2).unwrap();
+        assert_eq!(&output_2, b"6b69776973");
+
+        let mut output_3 = [0; 100];
+
+        assert_eq!(
+            encode_to_slice(b"kiwis", &mut output_3),
+            Err(FromHexError::InvalidStringLength)
+        );
+    }
+
+    #[test]
+    fn test_decode_to_slice() {
+        let mut output_1 = [0; 4];
+        decode_to_slice(b"6b697769", &mut output_1).unwrap();
+        assert_eq!(&output_1, b"kiwi");
+
+        let mut output_2 = [0; 5];
+        decode_to_slice(b"6b69776973", &mut output_2).unwrap();
+        assert_eq!(&output_2, b"kiwis");
+
+        let mut output_3 = [0; 4];
+
+        assert_eq!(
+            decode_to_slice(b"6", &mut output_3),
+            Err(FromHexError::OddLength)
+        );
+    }
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    fn test_encode() {
+        assert_eq!(encode("foobar"), "666f6f626172");
+    }
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    fn test_decode() {
+        assert_eq!(
+            decode("666f6f626172"),
+            Ok(String::from("foobar").into_bytes())
+        );
+    }
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    pub fn test_from_hex_okay_str() {
+        assert_eq!(Vec::from_hex("666f6f626172").unwrap(), b"foobar");
+        assert_eq!(Vec::from_hex("666F6F626172").unwrap(), b"foobar");
+    }
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    pub fn test_from_hex_okay_bytes() {
+        assert_eq!(Vec::from_hex(b"666f6f626172").unwrap(), b"foobar");
+        assert_eq!(Vec::from_hex(b"666F6F626172").unwrap(), b"foobar");
+    }
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    pub fn test_invalid_length() {
+        assert_eq!(Vec::from_hex("1").unwrap_err(), FromHexError::OddLength);
+        assert_eq!(
+            Vec::from_hex("666f6f6261721").unwrap_err(),
+            FromHexError::OddLength
+        );
+    }
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    pub fn test_invalid_char() {
+        assert_eq!(
+            Vec::from_hex("66ag").unwrap_err(),
+            FromHexError::InvalidHexCharacter { c: 'g', index: 3 }
+        );
+    }
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    pub fn test_empty() {
+        assert_eq!(Vec::from_hex("").unwrap(), b"");
+    }
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    pub fn test_from_hex_whitespace() {
+        assert_eq!(
+            Vec::from_hex("666f 6f62617").unwrap_err(),
+            FromHexError::InvalidHexCharacter { c: ' ', index: 4 }
+        );
+    }
+
+    #[test]
+    pub fn test_from_hex_array() {
+        assert_eq!(
+            <[u8; 6] as FromHex>::from_hex("666f6f626172"),
+            Ok([0x66, 0x6f, 0x6f, 0x62, 0x61, 0x72])
+        );
+
+        assert_eq!(
+            <[u8; 5] as FromHex>::from_hex("666f6f626172"),
+            Err(FromHexError::InvalidStringLength)
+        );
+    }
+
+    #[test]
+    #[cfg(feature = "alloc")]
+    fn test_to_hex() {
+        assert_eq!(
+            [0x66, 0x6f, 0x6f, 0x62, 0x61, 0x72].encode_hex::<String>(),
+            "666f6f626172".to_string(),
+        );
+
+        assert_eq!(
+            [0x66, 0x6f, 0x6f, 0x62, 0x61, 0x72].encode_hex_upper::<String>(),
+            "666F6F626172".to_string(),
+        );
+    }
+}
diff --git a/rust/hex/serde.rs b/rust/hex/serde.rs
new file mode 100644
index 000000000000..335a15132a27
--- /dev/null
+++ b/rust/hex/serde.rs
@@ -0,0 +1,102 @@
+//! Hex encoding with `serde`.
+#[cfg_attr(
+    all(feature = "alloc", feature = "serde"),
+    doc = r##"
+# Example
+
+```
+use serde::{Serialize, Deserialize};
+
+#[derive(Serialize, Deserialize)]
+struct Foo {
+    #[serde(with = "hex")]
+    bar: Vec<u8>,
+}
+```
+"##
+)]
+use serde::de::{Error, Visitor};
+use serde::Deserializer;
+#[cfg(feature = "alloc")]
+use serde::Serializer;
+
+#[cfg(feature = "alloc")]
+use alloc::string::String;
+
+use core::fmt;
+use core::marker::PhantomData;
+
+use crate::FromHex;
+
+#[cfg(feature = "alloc")]
+use crate::ToHex;
+
+/// Serializes `data` as hex string using uppercase characters.
+///
+/// Apart from the characters' casing, this works exactly like `serialize()`.
+#[cfg(feature = "alloc")]
+pub fn serialize_upper<S, T>(data: T, serializer: S) -> Result<S::Ok, S::Error>
+where
+    S: Serializer,
+    T: ToHex,
+{
+    let s = data.encode_hex_upper::<String>();
+    serializer.serialize_str(&s)
+}
+
+/// Serializes `data` as hex string using lowercase characters.
+///
+/// Lowercase characters are used (e.g. `f9b4ca`). The resulting string's length
+/// is always even, each byte in data is always encoded using two hex digits.
+/// Thus, the resulting string contains exactly twice as many bytes as the input
+/// data.
+#[cfg(feature = "alloc")]
+pub fn serialize<S, T>(data: T, serializer: S) -> Result<S::Ok, S::Error>
+where
+    S: Serializer,
+    T: ToHex,
+{
+    let s = data.encode_hex::<String>();
+    serializer.serialize_str(&s)
+}
+
+/// Deserializes a hex string into raw bytes.
+///
+/// Both, upper and lower case characters are valid in the input string and can
+/// even be mixed (e.g. `f9b4ca`, `F9B4CA` and `f9B4Ca` are all valid strings).
+pub fn deserialize<'de, D, T>(deserializer: D) -> Result<T, D::Error>
+where
+    D: Deserializer<'de>,
+    T: FromHex,
+    <T as FromHex>::Error: fmt::Display,
+{
+    struct HexStrVisitor<T>(PhantomData<T>);
+
+    impl<'de, T> Visitor<'de> for HexStrVisitor<T>
+    where
+        T: FromHex,
+        <T as FromHex>::Error: fmt::Display,
+    {
+        type Value = T;
+
+        fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
+            write!(f, "a hex encoded string")
+        }
+
+        fn visit_str<E>(self, data: &str) -> Result<Self::Value, E>
+        where
+            E: Error,
+        {
+            FromHex::from_hex(data).map_err(Error::custom)
+        }
+
+        fn visit_borrowed_str<E>(self, data: &'de str) -> Result<Self::Value, E>
+        where
+            E: Error,
+        {
+            FromHex::from_hex(data).map_err(Error::custom)
+        }
+    }
+
+    deserializer.deserialize_str(HexStrVisitor(PhantomData))
+}
-- 
2.34.1