Introduction

libsodium is a cross-platform fork of the NaCl cryptographic library. It provides secret-key and public-key encryption (XSalsa20), message authentication (Poly1305), digital signatures (Ed25519), key exchange (X25519), generic hashing (BLAKE2b, SHA256, SHA512), password hashing and key derivation (scrypt or Argon2i), in addition to facilities for guarded memory allocations and constant-time string comparisons.

RB-libsodium is a libsodium binding for Realbasic and Xojo ("classic" framework) projects. Library binaries for a number of platforms are available, or can built from source.

Example

This example generates and validates a password hash that is suitable to be stored in a database (more examples):

  Dim pw As libsodium.Password = "seekrit"
  Dim hash As String = pw.GenerateHash()
  If Not pw.VerifyHash(hash) Then MsgBox("Bad password!")

Hilights

• Password hashing and Password-based key derivation (PBKDF2) using either Argon2 or scrypt
• Secret-key and public-key cryptography
• Diffie-Hellman key exchange (X25519)
• Secret-key message authentication
• Public-key message signatures
• Fast generic or keyed hashing using BLAKE2b, SHA512, or SHA256
• Secured memory allocations
• Import and export keys, messages, hashes, etc. with optional password protection.

Synopsis

RB-libsodium is designed to make it as hard as possible to write bad crypto code. For example signing keys can't be used to perform encryption, so methods that need a signing key will require an instance of the SigningKey class as a parameter; attempting to pass an EncryptionKey will generate a compiler error.

All key types are represented by a different class:

Object Class	Comment
EncryptionKey	A private key for use with Diffie–Hellman based encryption.
PublicKey	A public key for use with encryption or signatures.
SecretKey	A secret key for use with symmetric encryption and message authentication.
SharedSecret	A shared secret encryption key derived using a Diffie–Hellman key exchange.
SigningKey	A private key for use with EdDSA-based signatures.

libsodium uses state-of-the-art cryptographic primitives and algorithms based on elliptic curves ("ECC"). ECC provides comparable security to older systems based on prime factorization, such as RSA, but with much smaller key sizes. For example, a 224-bit (28 byte) ECC key provides a level of security that is comparable to a 2,048-bit (256 byte) RSA key. For comparison, NIST recommends a RSA key size of at least 3,072 bits to ensure security through the year 2030.

How to incorporate libsodium into your Realbasic/Xojo project

Import the libsodium module

1. Download the RB-libsodium project either in ZIP archive format or by cloning the repository with your Git client.
2. Open the RB-libsodium project in REALstudio or Xojo. Open your project in a separate window.
3. Copy the libsodium module into your project and save.

Ensure the libsodium shared library is installed

libsodium is not ordinarily installed by default on most operating systems, you will need to ship necessary DLL/SO/DyLibs with your application. You can use pre-built binaries available here, or you can build them yourself from source.

RB-libsodium will raise a PlatformNotSupportedException when used if all required DLLs/SOs/DyLibs are not available at runtime.

Examples

• Secure memory
• Password hashing
• Generic hashing
• Encrypting streams or files
  • ...with gzip compression
  • Password protected file example
• PKI
  • Encryption
    • Generate a key pair
    • Derive a key pair from a password
    • Encrypt data
    • Decrypt data
  • Digital signatures
    • Generate a key pair
    • Derive a key pair from a password
    • Sign data
    • Verify data
• SKI
  • Encryption
    • Generate a key
    • Derive a key from a password
    • Encrypt data
    • Decrypt data
  • Message authentication
    • Generate a MAC
    • Verify a MAC