feature: v2 authentication request

common/client-libs/gateway-client/src/client/mod.rs

@@ -20,8 +20,8 @@ use nym_credentials_interface::TicketType;
 use nym_crypto::asymmetric::identity;
 use nym_gateway_requests::registration::handshake::client_handshake;
 use nym_gateway_requests::{
-    BinaryRequest, ClientControlRequest, ClientRequest, SensitiveServerResponse, ServerResponse,
-    SharedGatewayKey, SharedSymmetricKey, AES_GCM_SIV_PROTOCOL_VERSION,
+    BinaryRequest, ClientControlRequest, ClientRequest, GatewayProtocolVersionExt,
+    SensitiveServerResponse, ServerResponse, SharedGatewayKey, SharedSymmetricKey,
     CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION, CURRENT_PROTOCOL_VERSION,
 };
 use nym_sphinx::forwarding::packet::MixPacket;
@@ -563,28 +563,10 @@ impl<C, St> GatewayClient<C, St> {
         Ok(zeroizing_updated_key)
     }
 
-    async fn authenticate(&mut self) -> Result<(), GatewayClientError> {
-        let Some(shared_key) = self.shared_key.as_ref() else {
-            return Err(GatewayClientError::NoSharedKeyAvailable);
-        };
-
-        if !self.connection.is_established() {
-            return Err(GatewayClientError::ConnectionNotEstablished);
-        }
-        debug!("authenticating with gateway");
-
-        let self_address = self
-            .local_identity
-            .as_ref()
-            .public_key()
-            .derive_destination_address();
-
-        let msg = ClientControlRequest::new_authenticate(
-            self_address,
-            shared_key,
-            self.cfg.bandwidth.require_tickets,
-        )?;
-
+    async fn send_authenticate_request_and_handle_response(
+        &mut self,
+        msg: ClientControlRequest,
+    ) -> Result<(), GatewayClientError> {
         match self.send_websocket_message(msg).await? {
             ServerResponse::Authenticate {
                 protocol_version,
@@ -608,6 +590,51 @@ impl<C, St> GatewayClient<C, St> {
         }
     }
 
+    async fn authenticate_v1(&mut self) -> Result<(), GatewayClientError> {
+        debug!("using v1 authentication");
+
+        let Some(shared_key) = self.shared_key.as_ref() else {
+            return Err(GatewayClientError::NoSharedKeyAvailable);
+        };
+
+        let self_address = self
+            .local_identity
+            .public_key()
+            .derive_destination_address();
+
+        let msg = ClientControlRequest::new_authenticate(
+            self_address,
+            shared_key,
+            self.cfg.bandwidth.require_tickets,
+        )?;
+        self.send_authenticate_request_and_handle_response(msg)
+            .await
+    }
+
+    async fn authenticate_v2(&mut self) -> Result<(), GatewayClientError> {
+        debug!("using v2 authentication");
+        let Some(shared_key) = self.shared_key.as_ref() else {
+            return Err(GatewayClientError::NoSharedKeyAvailable);
+        };
+
+        let msg = ClientControlRequest::new_authenticate_v2(shared_key, &self.local_identity)?;
+        self.send_authenticate_request_and_handle_response(msg)
+            .await
+    }
+
+    async fn authenticate(&mut self, use_v2: bool) -> Result<(), GatewayClientError> {
+        if !self.connection.is_established() {
+            return Err(GatewayClientError::ConnectionNotEstablished);
+        }
+        debug!("authenticating with gateway");
+
+        if use_v2 {
+            self.authenticate_v2().await
+        } else {
+            self.authenticate_v1().await
+        }
+    }
+
     /// Helper method to either call register or authenticate based on self.shared_key value
     #[instrument(skip_all,
         fields(
@@ -623,19 +650,25 @@ impl<C, St> GatewayClient<C, St> {
         }
 
         // 1. check gateway's protocol version
-        let supports_aes_gcm_siv = match self.get_gateway_protocol().await {
-            Ok(protocol) => protocol >= AES_GCM_SIV_PROTOCOL_VERSION,
+        let gw_protocol = match self.get_gateway_protocol().await {
+            Ok(protocol) => Some(protocol),
             Err(_) => {
                 // if we failed to send the request, it means the gateway is running the old binary,
                 // so it has reset our connection - we have to reconnect
                 self.establish_connection().await?;
-                false
+                None
             }
         };
 
+        let supports_aes_gcm_siv = gw_protocol.supports_aes256_gcm_siv();
+        let supports_auth_v2 = gw_protocol.supports_authenticate_v2();
+
         if !supports_aes_gcm_siv {
             warn!("this gateway is on an old version that doesn't support AES256-GCM-SIV");
         }
+        if !supports_auth_v2 {
+            warn!("this gateway is on an old version that doesn't support authentication v2")
+        }
 
         if self.authenticated {
             debug!("Already authenticated");
@@ -650,7 +683,7 @@ impl<C, St> GatewayClient<C, St> {
         }
 
         if self.shared_key.is_some() {
-            self.authenticate().await?;
+            self.authenticate(supports_auth_v2).await?;
 
             if self.authenticated {
                 // if we are authenticated it means we MUST have an associated shared_key
@@ -983,7 +1016,8 @@ impl<C, St> GatewayClient<C, St> {
         }
 
         // if we're reconnecting, because we lost connection, we need to re-authenticate the connection
-        self.authenticate().await?;
+        self.authenticate(self.negotiated_protocol.supports_authenticate_v2())
+            .await?;
 
         // this call is NON-blocking
         self.start_listening_for_mixnet_messages()?;

common/gateway-requests/Cargo.toml

@@ -20,11 +20,14 @@ serde_json = { workspace = true }
 strum = { workspace = true }
 thiserror = { workspace = true }
 tracing = { workspace = true, features = ["log"] }
+time = { workspace = true }
+subtle = { workspace = true }
 zeroize = { workspace = true }
 
 nym-crypto = { path = "../crypto", features = ["aead", "hashing"] }
 nym-pemstore = { path = "../pemstore" }
 nym-sphinx = { path = "../nymsphinx" }
+nym-serde-helpers = { path = "../serde-helpers", features = ["base64"] }
 nym-task = { path = "../task" }
 
 nym-credentials = { path = "../credentials" }

common/gateway-requests/src/authentication/encrypted_address.rs

@@ -15,6 +15,12 @@ use thiserror::Error;
 // this is no longer constant size due to the differences in ciphertext between aes128ctr and aes256gcm-siv (inclusion of tag)
 pub struct EncryptedAddressBytes(Vec<u8>);
 
+impl From<Vec<u8>> for EncryptedAddressBytes {
+    fn from(encrypted_address: Vec<u8>) -> Self {
+        EncryptedAddressBytes(encrypted_address)
+    }
+}
+
 #[derive(Debug, Error)]
 pub enum EncryptedAddressConversionError {
     #[error("Failed to decode the encrypted address - {0}")]

common/gateway-requests/src/lib.rs

@@ -19,18 +19,37 @@ pub use shared_key::{
     SharedGatewayKey, SharedKeyConversionError, SharedKeyUsageError, SharedSymmetricKey,
 };
 
-pub const CURRENT_PROTOCOL_VERSION: u8 = AES_GCM_SIV_PROTOCOL_VERSION;
+pub const CURRENT_PROTOCOL_VERSION: u8 = AUTHENTICATE_V2_PROTOCOL_VERSION;
 
 /// Defines the current version of the communication protocol between gateway and clients.
 /// It has to be incremented for any breaking change.
 // history:
 // 1 - initial release
 // 2 - changes to client credentials structure
 // 3 - change to AES-GCM-SIV and non-zero IVs
+// 4 - introduction of v2 authentication protocol to prevent reply attacks
 pub const INITIAL_PROTOCOL_VERSION: u8 = 1;
 pub const CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION: u8 = 2;
 pub const AES_GCM_SIV_PROTOCOL_VERSION: u8 = 3;
+pub const AUTHENTICATE_V2_PROTOCOL_VERSION: u8 = 4;
 
 // TODO: could using `Mac` trait here for OutputSize backfire?
 // Should hmac itself be exposed, imported and used instead?
 pub type LegacyGatewayMacSize = <GatewayIntegrityHmacAlgorithm as OutputSizeUser>::OutputSize;
+
+pub trait GatewayProtocolVersionExt {
+    fn supports_aes256_gcm_siv(&self) -> bool;
+    fn supports_authenticate_v2(&self) -> bool;
+}
+
+impl GatewayProtocolVersionExt for Option<u8> {
+    fn supports_aes256_gcm_siv(&self) -> bool {
+        let Some(protocol) = *self else { return false };
+        protocol >= AES_GCM_SIV_PROTOCOL_VERSION
+    }
+
+    fn supports_authenticate_v2(&self) -> bool {
+        let Some(protocol) = *self else { return false };
+        protocol >= AUTHENTICATE_V2_PROTOCOL_VERSION
+    }
+}

common/gateway-requests/src/types/error.rs

@@ -3,6 +3,7 @@
 
 use crate::SharedKeyUsageError;
 use nym_credentials_interface::CompactEcashError;
+use nym_crypto::asymmetric::ed25519::SignatureError;
 use nym_sphinx::addressing::nodes::NymNodeRoutingAddressError;
 use nym_sphinx::forwarding::packet::MixPacketFormattingError;
 use nym_sphinx::params::packet_sizes::PacketSize;
@@ -92,7 +93,34 @@ pub enum GatewayRequestsError {
     #[error("the provided [v1] credential has invalid number of parameters - {0}")]
     InvalidNumberOfEmbededParameters(u32),
 
+    #[error("failed to authenticate the client: {0}")]
+    Authentication(#[from] AuthenticationFailure),
+
     // variant to catch legacy errors
     #[error("{0}")]
     Other(String),
 }
+
+#[derive(Debug, Error)]
+pub enum AuthenticationFailure {
+    #[error(transparent)]
+    KeyUsageFailure(#[from] SharedKeyUsageError),
+
+    #[error("failed to verify provided address ciphertext")]
+    MalformedCiphertext,
+
+    #[error("failed to verify request signature")]
+    InvalidSignature(#[from] SignatureError),
+
+    #[error("provided request timestamp is in the future")]
+    RequestTimestampInFuture,
+
+    #[error("the client is not registered")]
+    NotRegistered,
+
+    #[error("the provided request is too stale to process")]
+    StaleRequest,
+
+    #[error("the provided request timestamp is smaller or equal to a one previously used")]
+    RequestReuse,
+}