Authentication & Security
Relevant source files
The following files were used as context for generating this wiki page:
HX-Music implements a centralized authentication and security system designed for C/S architecture. The system secures sensitive resources through a combination of encrypted tokens, Role-Based Access Control (RBAC), and cryptographic hashing for credential storage. It ensures that only authorized users can perform actions like uploading music, managing playlists, or modifying user data.
The security architecture relies on a token-based authentication mechanism where the server issues an encrypted credential upon successful login. The client must include this credential in the HX-Token HTTP header for all subsequent protected requests. Server-side interceptors then validate the token and enforce permission levels before allowing endpoint execution.
User Authentication Flow
The authentication process begins with a login request containing the username and plaintext password. The server verifies these credentials against the UserDAO storage.
Login and Password Hashing
To protect user credentials, the system does not store plaintext passwords. Instead, it follows a specific hashing procedure:
- Registration: A unique salt is generated using
utils::Uuid::makeV4()for every new user. The plaintext password is concatenated with this salt and then hashed usingutils::md5. - Login Verification: The server retrieves the stored salt for the provided username, appends it to the incoming password, and compares the resulting MD5 hash with the stored hash.
Sources: HX-Music-Server/include/api/UserApi.hpp:95-104, HX-Music-Server/include/api/UserApi.hpp:124-142
Login Sequence Diagram
The following diagram illustrates the interaction between the Client, Server API, and Data Access Object (DAO) during the authentication phase.
Role-Based Access Control (RBAC)
The system enforces access control via the TokenInterceptor template class. Each API endpoint is decorated with an interceptor that specifies the minimum required PermissionEnum level.
Permission Levels
The project defines three primary permission tiers:
- ReadOnlyUser: Grants access to viewing music information and downloading files.
- RegularUser: Allows users to upload music, manage their own playlists, and update personal information (avatar, password).
- Administrator: Full system access, including user registration, user deletion, and scanning the server's physical directory for new music.
Sources: HX-Music-Server/include/api/UserApi.hpp:55-155, HX-Music-Server/include/api/MusicApi.hpp:115-119
Endpoint Permission Mapping
| Endpoint | Method | Required Permission | Action |
|---|---|---|---|
/user/add | POST | Administrator | Register new users |
/user/del/{id} | POST/DEL | Administrator | Delete existing users |
/user/selectAll | GET | Administrator | View all system users |
/music/runScan/ws | WS | Administrator | Scan filesystem for music |
/user/avatar/update | POST | RegularUser | Update profile picture |
/music/upload/init | POST | RegularUser | Start music upload task |
/music/info/{id} | GET | ReadOnlyUser | Fetch song metadata |
/cover/select/{id} | GET/HEAD | ReadOnlyUser | Download album art |
Sources: HX-Music-Server/include/api/UserApi.hpp, HX-Music-Server/include/api/MusicApi.hpp, HX-Music-Server/include/api/CoverApi.hpp:41-52
Token Management
The system uses a custom token implementation to maintain stateless authentication.
Configuration
The token behavior is controlled by global configurations:
- Header Key:
HX-Tokenis the required HTTP header field. - Validity: Tokens are valid for
EffectiveDuration, set to 24 hours (86,400,000 ms).
Sources: include/config/Token.hpp:31-37
Server-Side Validation Flow
When a request arrives at a protected endpoint, the TokenInterceptor performs the following checks:
- Extracts the token from the request header.
- Decrypts the token to retrieve the
TokenData(containinguserId,loginUuid, and expiration timestamps). - Validates that the current time is within the
nowTimeandEffectiveDurationrange. - Ensures the user's current permission level meets the endpoint's requirements.
Client-Side Security Handling
The UserController in the client application manages the lifecycle of the security token and handles server responses regarding credential validity.
Credential Persistence
The client stores the token in the musicConfig structure within the GlobalSingleton. Upon application startup or backend URL changes, the NetSingleton is updated with the active token to ensure all outgoing requests are authenticated.
Token Validation & Logout
The client performs a proactive token check using the /user/testToken endpoint:
- If the request fails (e.g., token expired or revoked), the client invokes
logoutReq(). logoutReq()clears the token frommusicConfigand transitions the UI to the login view.- Password updates trigger a
testToken()call to re-verify the session, as the server invalidates old credentials upon password changes by regenerating theloggedInUuid.
Sources: HX-Music-Client/include/controller/UserController.h:43-63, HX-Music-Server/include/api/UserApi.hpp:157-180
Cryptographic Implementation Summary
| Component | Logic / Algorithm | Purpose |
|---|---|---|
| Password Storage | md5(Password + UuidV4) | Prevents plaintext leaks and rainbow table attacks. |
| Token Encryption | Aes256Gcm | Ensures token contents cannot be tampered with or read by clients. |
| Session Identity | loggedInUuid | Allows the server to invalidate all sessions if the password is changed. |
| File Protection | useRangeTransferFile | Restricts file access to authorized sessions only. |
Sources: HX-Music-Server/include/api/UserApi.hpp:98-105, HX-Music-Server/include/api/CoverApi.hpp:46-50, HX-Music-Server/include/api/UserApi.hpp:178-180
Conclusion
The Authentication & Security module provides a robust barrier for the HX-Music ecosystem. By combining MD5-salted password hashing with AES-256-GCM encrypted tokens and strict RBAC interceptors, the system ensures data integrity and prevents unauthorized access to both user accounts and music assets. The 24-hour token rotation and session-specific UUIDs further enhance the security posture against credential theft and session hijacking.