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 edit
SiD (talk | contribs)
23 edits
No edit summary
KindOne (talk | contribs)
84 edits
m Fix casing mistake in previous change.
Tag: Manual revert
 
(7 intermediate revisions by 2 users not shown)
Line 2: Line 2:
{{External Module}}
{{External Module}}


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 <code>CService</code> 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: [https://www.undernet.org/loc/ UnderNet 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 (<code>-x!</code>, <code>+x!</code>, or <code>-!+x</code>) 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.
# '''Clear Configuration''': Delete all stored credentials and settings with the <code>clearconfig</code> command.


== Usage ==
== Installation ==
{{Module arguments
1. Clone the repository:
| count = none
<pre>git clone https://github.com/your-repository/cservice-znc-module.git
| extra = No additional arguments are required to load the module. Use commands to configure settings.}}
cd cservice-znc-module</pre>


=== Commands ===
2. Generate your <code>MASTER_KEY</code> for encrypting sensitive data (password and 2FA secret):
==== setusername ====
<pre>openssl rand -hex 32</pre>
Sets the UnderNet username:
Replace the placeholder <code>MASTER_KEY</code> in the module code with the generated key:
/msg *cservice setusername your_username
<pre>const std::string MASTER_KEY = "REPLACE_WITH_YOUR_OWN_SECURE_KEY";</pre>


==== unsetusername ====
3. Build the module:
Removes the stored UnderNet username:
<pre>znc-buildmod cservice.cpp</pre>
/msg *cservice unsetusername


==== setpassword ====
4. Place the compiled module in your ZNC modules directory:
Sets the UnderNet password. The password is stored securely using AES-256 encryption:
<pre>mv cservice.so ~/.znc/modules/</pre>
/msg *cservice setpassword your_password


==== unsetpassword ====
5. Load the module in ZNC:
Removes the stored UnderNet password:
<pre>/znc loadmod cservice</pre>
/msg *cservice unsetpassword


==== setsecret ====
== Configuration ==
Sets the 2FA/TOTP secret key. The secret is stored securely using AES-256 encryption:
After loading the module, run the following command for help and configuration options:
/msg *cservice setsecret your_2fa_secret
<pre>/msg *cservice help</pre>


==== enable2fa ====
=== Commands ===
Enables 2FA/TOTP for secure logins:
* '''<code>setusername &lt;username&gt;</code>''' 
  /msg *cservice enable2fa
  Set your UnderNet username.  
 
  Example: <pre>/msg *cservice setusername myusername</pre>
==== disable2fa ====
Disables 2FA/TOTP:
/msg *cservice disable2fa


==== setusermode ====
* '''<code>setpassword &lt;password&gt;</code>''' 
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:
  Set your UnderNet password (stored encrypted). 
/msg *cservice setusermode +x!
  Example: <pre>/msg *cservice setpassword mypassword</pre>


==== showconfig ====
* '''<code>setsecret &lt;secret&gt;</code>''' 
Displays the current configuration settings:
  Set your 2FA/TOTP secret key (stored encrypted). Ensure the secret is formatted correctly (uppercase with no spaces). 
/msg *cservice showconfig
  Example: <pre>/msg *cservice setsecret A1B2C3D4E5F6G7H8</pre>


=== Example Usage ===
* '''<code>enable2fa</code>''' 
1. Set your username:  
  Enable 2FA/TOTP authentication.   
  /msg *cservice setusername MyUser
  Example: <pre>/msg *cservice enable2fa</pre>


2. Set your password:  
* '''<code>disable2fa</code>''' 
  /msg *cservice setpassword MyPassword
  Disable 2FA/TOTP authentication.   
  Example: <pre>/msg *cservice disable2fa</pre>


3. Set your TOTP secret:  
* '''<code>setusermode &lt;mode&gt;</code>''' 
  /msg *cservice setsecret ABCDEFGHIJKLMNOPQRSTUV
  Define the user mode prefix (<code>-x!</code>, <code>+x!</code>, or <code>-!+x</code>) used by LoC during server connection.   
  Example: <pre>/msg *cservice setusermode +x!</pre>


4. Enable 2FA:  
* '''<code>showconfig</code>''' 
  /msg *cservice enable2fa
  Show the current configuration settings (username, 2FA status, user mode, etc.).   
  Example: <pre>/msg *cservice showconfig</pre>


5. View your current configuration:  
* '''<code>clearconfig</code>''' 
  /msg *cservice showconfig
  Delete all stored configuration data (username, password, 2FA secret, etc.).   
  Example: <pre>/msg *cservice clearconfig</pre>


=== Formatting the 2FA Secret Key ===
=== Formatting the 2FA Secret Key ===
The CService website provides the 2FA secret key in eight groups separated by spaces, like this:
The CService website provides the 2FA secret key in eight groups separated by spaces, like this:
a1b2 c3d4 e5f6 g7h8 i9j0 k1l2 m3n4 o5p6
<pre>a1b2 c3d4 e5f6 g7h8 i9j0 k1l2 m3n4 o5p6</pre>
 
Before entering the key into the module, you must:
Before entering the key into the module, you must:
1. Remove all spaces.
# Remove all spaces.
2. Convert all lowercase letters to uppercase.
# 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


For example, if CService gives you <code>a1b2 c3d4 e5f6 g7h8 i9j0 k1l2 m3n4 o5p6</code>, you should enter it as:
<pre>A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6</pre>
This ensures compatibility with the module.
This ensures compatibility with the module.


You can use the following Linux command to reformat the key automatically:
You can use the following Linux command to reformat the key automatically:
bash
<pre>echo "a1b2 c3d4 e5f6 g7h8 i9j0 k1l2 m3n4 o5p6" | tr -d ' ' | tr '[:lower:]' '[:upper:]'</pre>
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 <code>MASTER_KEY</code>) and update the module code before building it.


=== Notes ===
=== Generating a Secure Encryption Key ===
* Always generate a secure encryption key (MASTER_KEY) before compiling the module. Use the following OpenSSL command:
To generate a secure 256-bit (32-byte) hexadecimal key, use the following OpenSSL command:
  openssl rand -hex 32
<pre>openssl rand -hex 32</pre>
  Replace MASTER_KEY in the source code with the generated key.
Replace the placeholder <code>MASTER_KEY</code> in the module code with the generated key:
<pre>const std::string MASTER_KEY = "REPLACE_WITH_YOUR_OWN_SECURE_KEY";</pre>


* 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.
== Notes ==
 
* '''Security Warning''': Always keep your <code>MASTER_KEY</code> private. If the key is exposed, encrypted data can be compromised. If the <code>MASTER_KEY</code> 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:
* For changes to take effect, reload the module after updating configuration or code:
  /znc unloadmod cservice
<pre>/znc unloadmod cservice
  /znc loadmod cservice
/znc loadmod cservice</pre>


== See Also ==
== See Also ==
For more information on UnderNet's Login on Connect (LoC) feature, visit [https://www.undernet.org/loc/ UnderNet LoC].
For more information on UnderNet's Login on Connect (LoC) feature, visit [https://www.undernet.org/loc/ UnderNet LoC].


Enjoy secure and seamless logins with the CService ZNC module!
Enjoy secure and seamless logins with the <code>CService</code> ZNC module!
 
 
The section with rendering issue is:
 
=== 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:
bash
echo "a1b2 c3d4 e5f6 g7h8 i9j0 k1l2 m3n4 o5p6" | tr -d ' ' | tr '[:lower:]' '[:upper:]'

Latest revision as of 10:50, 17 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.
  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.
  6. Clear Configuration: Delete all stored credentials and settings with the clearconfig command.

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

Commands

  • setusername <username>
 Set your UnderNet username.

Example: 

/msg *cservice setusername myusername
  • setpassword <password>
 Set your UnderNet password (stored encrypted).

Example: 

/msg *cservice setpassword mypassword
  • setsecret <secret>
 Set your 2FA/TOTP secret key (stored encrypted). Ensure the secret is formatted correctly (uppercase with no spaces).

Example: 

/msg *cservice setsecret A1B2C3D4E5F6G7H8
  • enable2fa
 Enable 2FA/TOTP authentication.

Example: 

/msg *cservice enable2fa
  • disable2fa
 Disable 2FA/TOTP authentication.

Example: 

/msg *cservice disable2fa
  • setusermode <mode>
 Define the user mode prefix (-x!, +x!, or -!+x) used by LoC during server connection.

Example: 

/msg *cservice setusermode +x!
  • showconfig
 Show the current configuration settings (username, 2FA status, user mode, etc.).

Example: 

/msg *cservice showconfig
  • clearconfig
 Delete all stored configuration data (username, password, 2FA secret, etc.).

Example: 

/msg *cservice clearconfig

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=3218"