To create new wiki account, please join us on #znc at Libera.Chat and ask admins to create a wiki account for you. You can say thanks to spambots for this inconvenience.

CService: Difference between revisions

From ZNC
Jump to navigation Jump to search
← Older editNewer edit →
SiD (talk | contribs)
23 edits
No edit summary
SiD (talk | contribs)
23 edits
No edit summary
Line 3: Line 3:


The `CService` ZNC module provides secure login functionality for X on UnderNet, including support for 2FA/TOTP authentication and LoC (Login on Connect). It allows users to configure login details, enable/disable 2FA, and specify user modes. Sensitive data, such as passwords and 2FA secrets, are encrypted using AES-256 encryption for enhanced security.
The `CService` ZNC module provides secure login functionality for X on UnderNet, including support for 2FA/TOTP authentication and LoC (Login on Connect). It allows users to configure login details, enable/disable 2FA, and specify user modes. Sensitive data, such as passwords and 2FA secrets, are encrypted using AES-256 encryption for enhanced security.
== Getting the Code ==
The code for this module can be found [https://github.com/CryptoSiD/cservice-znc-module here].
== Compatibility ==
This module was compiled and tested with '''ZNC 1.10'''.


== Features ==
== Features ==
* Secure Login: Authenticate with UnderNet using your username, password, and optional 2FA/TOTP.
# **Secure Login**: Authenticate securely with UnderNet using your username, password, and optional TOTP-based 2FA.
* 2FA/TOTP Support: Enhance security by adding time-based one-time passwords.
# **2FA/TOTP Support**: Enhance security by adding time-based one-time passwords to your login process.
* LoC (Login on Connect): Log in to UnderNet automatically using the LoC feature.
# **LoC (Login on Connect)**: Seamlessly log in to UnderNet using their LoC feature. Learn more: [UnderNet LoC](https://www.undernet.org/loc/).
* Custom User Modes: Set user mode prefixes (<nowiki>-x!</nowiki>, <nowiki>+x!</nowiki>, or <nowiki>-!+x</nowiki>) during server connection.
# **Custom User Modes**: Set your preferred user mode prefix (`-x!`, `+x!`, or `-!+x`) during server connection.
* Encrypted Credentials: Passwords and 2FA secrets are stored securely using AES-256 encryption.
# **Encrypted Credentials**: Protect your password and 2FA secret with AES-256 encryption, ensuring that sensitive data is stored securely.


== Usage ==
== Installation ==
{{Module arguments
1. Clone the repository:
| count = none
  <pre>
| extra = No additional arguments are required to load the module. Use commands to configure settings.}}
  git clone https://github.com/your-repository/cservice-znc-module.git
  cd cservice-znc-module
  </pre>
 
2. Generate your `MASTER_KEY` for encrypting sensitive data (password and 2FA secret):
  <pre>
  openssl rand -hex 32
  </pre>
  Replace the placeholder `MASTER_KEY` in the module code with the generated key:
  <pre>
  const std::string MASTER_KEY = "REPLACE_WITH_YOUR_OWN_SECURE_KEY";
  </pre>


=== Commands ===
3. Build the module:
==== setusername ====
  <pre>
Sets the UnderNet username:
  znc-buildmod cservice.cpp
/msg *cservice setusername your_username
  </pre>


==== unsetusername ====
4. Place the compiled module in your ZNC modules directory:
Removes the stored UnderNet username:
  <pre>
/msg *cservice unsetusername
  mv cservice.so ~/.znc/modules/
  </pre>


==== setpassword ====
5. Load the module in ZNC:
Sets the UnderNet password. The password is stored securely using AES-256 encryption:
  <pre>
/msg *cservice setpassword your_password
  /znc loadmod cservice
  </pre>


==== unsetpassword ====
== Configuration ==
Removes the stored UnderNet password:
After loading the module, run the following command for help and configuration options:
/msg *cservice unsetpassword
<pre>
 
/msg *cservice help
==== setsecret ====
</pre>
Sets the 2FA/TOTP secret key. The secret is stored securely using AES-256 encryption:
You can set:
/msg *cservice setsecret your_2fa_secret
- Your UnderNet username and password.
 
- Your 2FA secret for TOTP.
==== enable2fa ====
- Enable or disable 2FA.
Enables 2FA/TOTP for secure logins:
- Your preferred user mode (`-x!`, `+x!`, or `-!+x`).
/msg *cservice enable2fa
 
==== disable2fa ====
Disables 2FA/TOTP:
/msg *cservice disable2fa
 
==== setusermode ====
Sets the user mode prefix for the server connection. Valid options are <nowiki>-x!</nowiki>, <nowiki>+x!</nowiki>, <nowiki>-!+x</nowiki>, or an empty string:
/msg *cservice setusermode +x!
 
==== showconfig ====
Displays the current configuration settings:
/msg *cservice showconfig
 
=== Example Usage ===
1. Set your username: 
  /msg *cservice setusername MyUser
 
2. Set your password: 
  /msg *cservice setpassword MyPassword
 
3. Set your TOTP secret: 
  /msg *cservice setsecret ABCDEFGHIJKLMNOPQRSTUV
 
4. Enable 2FA: 
  /msg *cservice enable2fa
 
5. View your current configuration: 
  /msg *cservice showconfig


=== Formatting the 2FA Secret Key ===
=== Formatting the 2FA Secret Key ===
Line 80: Line 58:
a1b2 c3d4 e5f6 g7h8 i9j0 k1l2 m3n4 o5p6
a1b2 c3d4 e5f6 g7h8 i9j0 k1l2 m3n4 o5p6
</pre>
</pre>
Before entering the key into the module, you must:
Before entering the key into the module, you must:
1. Remove all spaces.
1. Remove all spaces.
Line 96: Line 73:
</pre>
</pre>


=== Notes ===
== Password and 2FA Encryption ==
* Always generate a secure encryption key (`MASTER_KEY`) before compiling the module. Use the following OpenSSL command:
This module encrypts sensitive data (password and 2FA secret) using AES-256 encryption. Each user must generate their own encryption key (referred to as `MASTER_KEY`) and update the module code before building it.
  openssl rand -hex 32 
  Replace `MASTER_KEY` in the source code with the generated key.


* ***Security Warning***: The `MASTER_KEY` must be kept safe. If lost, the encrypted password and 2FA secret key will no longer work and you'll have to reconfigure it.
=== Generating a Secure Encryption Key ===
To generate a secure 256-bit (32-byte) hexadecimal key, use the following OpenSSL command:
<pre>
openssl rand -hex 32
</pre>
Replace the placeholder `MASTER_KEY` in the module code with the generated key:
<pre>
const std::string MASTER_KEY = "REPLACE_WITH_YOUR_OWN_SECURE_KEY";
</pre>


* For changes to take effect, reload the module:
== Notes ==
   /znc unloadmod cservice
* **Security Warning**: Always keep your `MASTER_KEY` private. If the key is exposed, encrypted data can be compromised. If the `MASTER_KEY` is lost, the encrypted password and 2FA secret will no longer work, and you will have to reconfigure the module.
* For changes to take effect, reload the module after updating configuration or code:
  <pre>
   /znc unloadmod cservice
   /znc loadmod cservice
   /znc loadmod cservice
  </pre>


== See Also ==
== See Also ==

Revision as of 19:20, 8 February 2025

 This is an external module.
Please note that it may or may not work with the current release (1.9.1).
This module is not included in the default ZNC installation, and you will need to manually compile it before you can load this module.
Contact the author if you have any questions, but feel free to ask in #znc on Libera.Chat. Someone might be able to help you there.

The `CService` ZNC module provides secure login functionality for X on UnderNet, including support for 2FA/TOTP authentication and LoC (Login on Connect). It allows users to configure login details, enable/disable 2FA, and specify user modes. Sensitive data, such as passwords and 2FA secrets, are encrypted using AES-256 encryption for enhanced security.

Features

  1. **Secure Login**: Authenticate securely with UnderNet using your username, password, and optional TOTP-based 2FA.
  2. **2FA/TOTP Support**: Enhance security by adding time-based one-time passwords to your login process.
  3. **LoC (Login on Connect)**: Seamlessly log in to UnderNet using their LoC feature. Learn more: [UnderNet LoC](https://www.undernet.org/loc/).
  4. **Custom User Modes**: Set your preferred user mode prefix (`-x!`, `+x!`, or `-!+x`) during server connection.
  5. **Encrypted Credentials**: Protect your password and 2FA secret with AES-256 encryption, ensuring that sensitive data is stored securely.

Installation

1. Clone the repository: 

   git clone https://github.com/your-repository/cservice-znc-module.git
   cd cservice-znc-module

2. Generate your `MASTER_KEY` for encrypting sensitive data (password and 2FA secret): 

   openssl rand -hex 32
   
  Replace the placeholder `MASTER_KEY` in the module code with the generated key:

   const std::string MASTER_KEY = "REPLACE_WITH_YOUR_OWN_SECURE_KEY";

3. Build the module: 

   znc-buildmod cservice.cpp

4. Place the compiled module in your ZNC modules directory: 

   mv cservice.so ~/.znc/modules/

5. Load the module in ZNC: 

   /znc loadmod cservice

Configuration

After loading the module, run the following command for help and configuration options: 

/msg *cservice help

You can set: - Your UnderNet username and password. - Your 2FA secret for TOTP. - Enable or disable 2FA. - Your preferred user mode (`-x!`, `+x!`, or `-!+x`).

Formatting the 2FA Secret Key

The CService website provides the 2FA secret key in eight groups separated by spaces, like this: 

a1b2 c3d4 e5f6 g7h8 i9j0 k1l2 m3n4 o5p6

Before entering the key into the module, you must: 1. Remove all spaces. 2. Convert all lowercase letters to uppercase.

For example, if CService gives you `a1b2 c3d4 e5f6 g7h8 i9j0 k1l2 m3n4 o5p6`, you should enter it as: 

A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6

This ensures compatibility with the module.

You can use the following Linux command to reformat the key automatically: 

echo "a1b2 c3d4 e5f6 g7h8 i9j0 k1l2 m3n4 o5p6" | tr -d ' ' | tr '[:lower:]' '[:upper:]'

Password and 2FA Encryption

This module encrypts sensitive data (password and 2FA secret) using AES-256 encryption. Each user must generate their own encryption key (referred to as `MASTER_KEY`) and update the module code before building it.

Generating a Secure Encryption Key

To generate a secure 256-bit (32-byte) hexadecimal key, use the following OpenSSL command: 

openssl rand -hex 32

Replace the placeholder `MASTER_KEY` in the module code with the generated key: 

const std::string MASTER_KEY = "REPLACE_WITH_YOUR_OWN_SECURE_KEY";

Notes

  • **Security Warning**: Always keep your `MASTER_KEY` private. If the key is exposed, encrypted data can be compromised. If the `MASTER_KEY` is lost, the encrypted password and 2FA secret will no longer work, and you will have to reconfigure the module.
  • For changes to take effect, reload the module after updating configuration or code:
   /znc unloadmod cservice
   /znc loadmod cservice

See Also

For more information on UnderNet's Login on Connect (LoC) feature, visit UnderNet LoC.

Enjoy secure and seamless logins with the `CService` ZNC module!

Retrieved from "https://wiki.znc.in/index.php?title=CService&oldid=3194"