Neulock Crypto Whitepaper

This document describes the Neulock Crypto Password Manager, hosted at crypto.neulock.app and neulock.eth on IPNS.

Neulock Crypto is currently fully functional as a progressive web app and undergoing beta testing on the Sepolia testnet. Beta testers are welcome at our Discord community.

In this document, 'Neulock' and 'Neulock Crypto' are used interchangeably. References to the original Neulock Password Manager, currently hosted at neulock.app, are referred to as 'Neulock Legacy.'

The author can be contacted at the Neulock community on Discord.

A decentralized, Web3 native, on-chain password manager

The Neulock project has the stated goal of protecting people's privacy online by allowing them to have full custody of their passwords.

Operating under the premise that security should never depend on trust, users should never have to rely on someone else to secure their 'password vault'. Neulock is perhaps the first online password manager that never exports secrets from the user's devices, not even under encryption, which may have unknown vulnerabilities and implementation faults.

With Neulock, the user has full custody of their passwords. Even though Neulock syncs passwords seamlessly across all user devices, the only computers that ever touch any user secrets (passwords, private keys), in plaintext or ciphertext, are the user's own devices. Passwords couldn't possibly leak from any other source. It's within the user's reach to ensure the security of their devices, which is sufficient to guarantee the safety of their password vault.

The problem with cloud-based password managers

The original Neulock Legacy app is a cloud-based password manager. Neulock Legacy achieved an unprecedented degree of password confidentiality for an online password manager (its security model is described here). However, confidentiality is only one of the three pilars of information security. Admittedly, Neulock Legacy is only on-par with other cloud-based password managers in terms of:

• Integrity: data stored on cloud providers could be tampered.
• Availability: both the cloud provider and Studio V, the company that owns all Neulock password managers, could potentially take the service down. Moreover, the subscription-based business model has resulted in many users getting locked out of premium features due to payment declined by a third-party processor.

These issues stem from Neulock Legacy's reliance on centralized infrastructure.

The Neulock Project's mission is to grant users full custody of their secrets. Fulfilling this mission requires taking into account all three facets of information security, with the understanding that the owner of all data is the user alone.

Decentralized infrastructure empowers the user

Neulock Crypto is the result of adding the following requirements to the Neulock Project:

• All infrastructure must be decentralized.
• All infrastructure must be publicly accessible from the internet out-of-the-box, but must also be self-hostable if the user so wishes.
• The integrity of data stored online must be guaranteed in an auditable fashion.

The Ethereum ecosystem is a perfect match for such requirements. Wallets enable users to easily interact with applications that have backend logic residing in smart contracts on the blockchain (dapps).

By using Ethereum wallets as the sole source of user authentication, we eliminate the need for users to create an account or remember a master key. The manually-entered master key, a staple of password managers, is a liability to confidentiality (it can be vulnerable to brute-force attacks or leaked if backed up) and to availability (it can be forgotten).

To minimize gas fees, bulk data must also be stored in decentralized infrastructure, but off-chain. The Interplanetary File System (IPFS) provides this capability with additional benefits:

• IPFS files can be easily replicated by the user, both by pinning on an external service, or by self-hosting an IPFS node.
• Content is referenced by its hash (the CID), ensuring data integrity.

In order to provide out-of-the-box availability guarantees, Neulock Crypto stores user data on an IPFS provider and then backs it up with at least 3 FileCoin unexpirable contracts. Should a contract stop being fulfilled (ie. that contract no longer pins the user data), the backend will procure a replacement contract. Even if users take no additional measures to back up their data, persistence is guaranteed for the foreseeable future.

Neulock Crypto is the most secure online password manager because it addresses all aspects of information security:

• Confidentiality: building upon Neulock Legacy's principle of never exporting any user secrets, not even under encryption, Neulock Crypto is also bruteforce-resistant by not requiring a user-created master key.
• Integrity: all blockchain transactions are signed by the user's wallet. Ethereum consensus mechanism ensures the integrity of on-chain data. Off-chain data integrity is verified by IPFS CID.
• Availability: all infrastructure is decentralized, publicly and immediately available on the internet, and can be replicated locally (self-hosted). Users are able to continue using Neulock even if Studio V, its parent company, goes out of business.

Neulock Crypto vs. offline password managers

We would argue that, in most real-world applications, Neulock Crypto is also more secure than offline password managers. While, in theory, offline password managers could offer perfect confidentiality and integrity, they do so by offering poor availability guarantees. Attempts to increase their availability (eg. backups and replicas) can decrease confidentiality. Unless perfectly administered, offline password managers trade off availability for confidentiality and integrity.

Specifications

User authentication

Authentication in Neulock Crypto involves connecting an Ethereum wallet and signing a fixed message to generate two application keys:

• The password generation key, used in the password derivation step; and
• The encryption key, used in the data saving and fetching steps.

Since both keys are deterministically generated from the wallet signature of a fixed message (using HMAC-BLAKE2b), these keys never leave the user device, and can be replicated on other user devices by authenticating with the same wallet.

Neulock's authentication flow provides the following advantages over most password managers:

• Users do not create an account. Connecting the Ethereum wallet is sufficient for authentication, as with most dapps.
• Users do not create a master key manually. All 256-bit keys are automatically derived from the wallet signature. There's no need to backup these keys, and they are bruteforce-resistant.

The password derivation algorithm

In Neulock Crypto, user data does not contain any secrets.

The two keys generated in the "User authentication" step are the only secret information, and these keys never leave the user devices, not even under encryption. This clear separation between secret keys (derived directly from the user wallet) and non-secret user data (uploaded to decentralized storage under encryption) enables the secrecy of your passwords, even in the unlikely event that encryption gets broken.

Neulock derives passwords by processing the password generation key and a random, password-specific 256-bit sequence through an HMAC-based Extract-and-Expand Key Derivation Function (HKDF) to generate a long sequence of statistically random bits. This sequence is used to generate the actual password, conforming to desired password length and charset definitions. Neulock uses HMAC-BLAKE2b as its HKDF. The chart below illustrates this process.

Note: User data is guaranteed to not include any secrets as long as all your passwords have been generated with Neulock. Imported or manually-entered passwords will be present in user data, and will be uploaded to decentralized storage under end-to-end encryption. While this should be safe for short-term adoption purposes, we recommend changing all your passwords to Neulock-generated ones at your earliest convenience.

Data synchronization

Neulock Crypto seamlessly synchronizes user passwords across all devices using only decentralized infrastructure.

Data saving

When the user decides to save local data online, the following steps are executed:

1. The Neulock app encrypts all user data (this data is illustrated in the Password Derivation chart and does not include generated passwords or keys).
2. The Neulock app uploads the encrypted user data to IPFS and receives the corresponding content ID (CID).
3. If using the default IPFS provider, the backend will automatically procure at least 3 FileCoin contracts to guarantee the persistency of the uploaded user data.
4. The Neulock app encrypts the CID.
5. The Neulock app requests the user wallet to save the encrypted CID to the blockchain, calling the Neulock smart contract on-chain.
6. The wallet app asks the user to authorize the write transaction to the Neulock smart contract (incurs gas fees).
7. The wallet app sends the transaction to the blockchain using its own RPC node.
8. The wallet app sends the transaction hash back to the Neulock app.
9. The Neulock app requests its Ethereum RPC node to independently verify the success of the transaction.

The chart below illustrates the above steps.

Data fetching

The Neulock app retrieves data previously saved by the user (ie. by the same wallet address as currently connected) by following these steps:

1. The Neulock app requests its Ethereum RPC node to read the Neulock smart contract and retrieve the latest encrypted IPFS content ID (CID) for the saved user data.
2. The Neulock app verifies and decrypts the response, obtaining the CID for the latest saved user data.
3. The Neulock app requests the encrypted user data from the IPFS node by passing the CID.
4. Upon receiving the encrypted user data, the Neulock app verifies and decrypts this data.

The chart below illustrates the above steps.

Self-custody of data

Neulock Crypto grants the user out-of-box self-custody of data, similar to how an Ethereum wallet grants self-custody of currency, NFT, and other tokens. All data is stored on decentralized infrastructure, accessible only to the wallet owner.

User data self-hosting

Note: The overrides described in this section are not implemented yet for Neulock Crypto Beta, but they will be implemented before the first production release.

Neulock Crypto functions without additional customization. Users are free, however, to replace some or all of the underlying infrastructure with the ones provided by third parties or with their own. The following connections can be overriden:

Ethereum RPC node

Neulock Crypto currently uses the publicnode.com HTTPS RPC endpoints for Ethereum and, on testing, for Sepolia. The user can provide another HTTPS RPC URL that's reachable from the Neulock app. It's possible to use a self-hosted node running on the local network.

Note: This setting does not affect the RPC node used by the wallet to send transactions! You must configure this separately on your wallet app.

IPFS node

Neulock Crypto currently uses the IPFS service provided by Fleek. You can change this by setting a base URL that implements the /add and /get endpoints of the Kubo RPC API v0.

Note: If you change the IPFS node, Neulock Crypto cannot procure FileCoin contracts to guarantee the availability of your data! You are responsible for making sure your data is available should you decide to use your own IPFS node.

IPFS data pinning

Even if you don't change the IPFS node settings, you can still pin (duplicate) your data in your own node or using third-party services. Neulock Crypto can show your current IPFS Content ID (CID). You can use the CID to retrieve your encrypted user data on any IPFS node and pin it. Neulock Crypto will be able to retrieve your pinned data, as long as your IPFS node is online.