wireapp / cryptobox-c Goto Github PK

C-FFI to cryptobox

License: GNU General Public License v3.0

Makefile 4.08% C 63.91% Rust 32.01%

cryptobox-c's Introduction

Wire

This repository is part of the source code of Wire. You can find more information at wire.com or by contacting [email protected].

You can find the published source code at github.com/wireapp.

For licensing information, see the attached LICENSE file and the list of third-party licenses at wire.com/legal/licenses/.

Cryptobox - C API

cryptobox-c provides a high-level C API for the cryptobox library.

Disclaimer: This project is an early work-in-progress.

Dependencies

Rust: 1.6 stable or later
Sodium: 1.0 or later

Building

Compile

make

Test

Valgrind must be installed, then

make test

Package

The current build can produce a basic Debian package. Makedeb must be installed, then

make dist

will place the package into target/release/. These debian packages are usually attached to every release and can be downloaded via github.

Language Bindings

Java / Android: A Java API through JNI with support for cross-compilation to Android is provided by cryptobox-jni.
Objective-C / iOS: Cross-compiled binaries for iOS as well as an Objective-C API is provided by cryptobox-ios.
Haskell: Haskell FFI bindings are available through cryptobox-haskell.

API Overview

The following is an API overview. For detailed function signatures, refer to the cbox.h header file.

CBox

A CBox is an opaque container for all the necessary key material of a single client (e.g. a single device of a user). A CBox is allocated with a call to cbox_file_open. It takes a path as an argument which must be a valid file path pointing to an existing directory. That directory becomes the root directory for all data stored by that CBox or any of the CBoxSessions obtained from it.

Note: Do not create multiple CBoxes that operate on the same or overlapping directories.

Opened CBoxes should typically be used for an extended period of time to obtain sessions and in turn encrypt and decrypt messages.

Note: Every call to cbox_file_open must be paired with a cbox_close to properly deallocate the CBox.

CBoxSession

A CBoxSession represents a cryptographic session between two endpoints (e.g. devices). Sessions are identified through a session ID, which is an opaque C string for the CryptoBox API. A session ID should uniquely identify a remote client or device.

Obtaining an existing session

Before deciding to initialise a new session, a client typically tries to obtain an existing session using cbox_session_get. If no session is found, the CBOX_NO_SESSION error code is returned.

Initialising a new session

If no session for a given session ID exists, a new session can be initialised either through cbox_session_init_from_prekey or cbox_session_init_from_message.

A client who wants to send a message to another client with whom no session exists obtains a prekey from its peer (directly or indirectly) and uses cbox_session_init_from_prekey.

A client who receives an encrypted message from another client with whom he has no existing session uses cbox_session_init_from_message.

Encrypting and decrypting messages

Once a session is obtained it can be used to encrypt and decrypt messages via cbox_encrypt and cbox_decrypt, respectively.

The encrypt and decrypt operations fill CBoxVec structures which provide access to the encrypted or decrypted data via cbox_vec_data as well as its length through cbox_vec_len. Once the data has been consumed and is no longer needed, a CBoxVec must be freed using cbox_vec_free.

Note: Every call to cbox_session_get, cbox_session_init_from_prekey or cbox_session_init_from_message must be paired with a cbox_session_close to properly deallocate the CBoxSession.

Saving a session

After successfully encrypting and/or decrypting one or more messages, a session can be saved through cbox_session_save. Once a session is saved, the changes to the key material are permanent, e.g. a decrypt operation cannot be repeated. It can therefore be advisable to save a session only once the decrypted plaintext has been safely stored.

Prekeys

In order to establish sessions, one client must be able to obtain a prekey from another. To generate a prekey, cbox_new_prekey is used, which fills a CBoxVec with the public key meterial of the newly generated prekey which can then be sent directly to another client or uploaded to a server for others to download.

Fingerprints

Public key fingerprints can be compared out-of-band to protect against MITM attacks. The functions cbox_fingerprint_local and cbox_fingerprint_remote are provided for that purpose.

Thread-safety

The API is not thread-safe. However, distinct CBoxes and CBoxSessions can be used independently (and concurrently). It is up to client code or higher-level language bindings to provide thread-safety as necessary for the desired usage pattern.

Note: When sessions are used concurrently, it is important to make sure not to have two or more sessions with the same session ID in use at the same time.

cryptobox-c's People

Contributors

Stargazers

Watchers

Forkers

romanb m-2k tommyteavee zhaohansprt just-d productinfo typfel ethanbrooks naamio ourlifekh jacky2050 victorwissink liam-i

cryptobox-c's Issues

warning: crate-type "cdylib" was not one of lib|rlib|dylib|staticlib

Hi, when I compile cryptobox-c with make command, I run into such problem:

warning: crate-type "cdylib" was not one of lib|rlib|dylib|staticlib
failed to parse lock file at: /mnt/Patriot/Others/cryptobox-c-develop/Cargo.lock

To learn more, run the command again with --verbose.

and my rustc and cargo version is:

[sl3@localhost cryptobox-c-develop]$ rustc --version
rustc 1.6.0 (c30b771ad 2016-01-19)
[sl3@localhost cryptobox-c-develop]$ cargo --version
cargo 0.7.0-nightly (1af03be 2015-12-08)

I search the google but find no results, do you know why?
I am compiling wire-server, which may need cryptobox-c I think... but stuck here, very sad...

I add --verbose after cargo build
the output is

[sl3@terry-fed038900 cryptobox-c-develop]# make
cargo build --verbose
warning: crate-type "cdylib" was not one of lib|rlib|dylib|staticlib
failed to parse lock file at: /mnt/Patriot/Others/cryptobox-c-develop/Cargo.lock

Caused by:
  expected a section for the key `root`
make: *** [compile] Error 101

make install: DESTDIR not respected

Please disable make install since it seems to be a dead end.

Is this a viable install script for non-Debian distributions?

install -d ${pkgdir}/usr/include
install -m 644 ./src/cbox.h ${pkgdir}/usr/include/

install -d ${pkgdir}/usr/lib
install -m 644 ./target/release/libcryptobox.so ${pkgdir}/usr/lib/

“Makedeb must be installed”, but it’s missing

This pkg does not exist:

https://github.com/wireapp/wire-server/tree/develop/tools/makedeb

Apparently the Makefile needs to be edited to do dpkg-deb --build instead, no? Or is there a new location for makedeb?

Add full msg sending example

I'm looking for a simple example:

app.exe --email xx --password yy --conv_id 111 --msg "this is a message to converasion"

The description of cryptography primitives in cbox is only useful for core developers of Wire.

reserved identifier violation

I would like to point out that an identifier like "__CRYPTOBOX_H__" does eventually not fit to the expected naming convention of the C++ language standard.
Would you like to adjust your selection for unique names?

deb file missing from release tarball

The readme says:

“These debian packages are usually attached to every release and can be downloaded via github.”

The tarball for 1.1.3 is missing the deb file:

cryptobox-c-1.1.3/.gitignore
cryptobox-c-1.1.3/.travis.yml
cryptobox-c-1.1.3/CHANGELOG.txt
cryptobox-c-1.1.3/Cargo.lock
cryptobox-c-1.1.3/Cargo.toml
cryptobox-c-1.1.3/LICENSE
cryptobox-c-1.1.3/Makefile
cryptobox-c-1.1.3/README.md
cryptobox-c-1.1.3/deb/
cryptobox-c-1.1.3/deb/DEBIAN/
cryptobox-c-1.1.3/deb/DEBIAN/control
cryptobox-c-1.1.3/src/
cryptobox-c-1.1.3/src/cbox.h
cryptobox-c-1.1.3/src/lib.rs
cryptobox-c-1.1.3/src/log.rs
cryptobox-c-1.1.3/test/
cryptobox-c-1.1.3/test/bench.c
cryptobox-c-1.1.3/test/main.c

Valgrind tests fail on Bookworm

$ make test
  cargo build
  warning: attribute should be applied to a free function, impl method or static
    --> src/lib.rs:46:1
     |
  46 |   #[no_mangle]
     |   ^^^^^^^^^^^^
  47 |   #[derive(Clone, Copy, Debug, Eq, PartialEq)]
  48 | / pub enum CBoxIdentityMode {
  49 | |     Complete = 0,
  50 | |     Public   = 1
  51 | | }
     | |_- not a free function, impl method or static
     |
     = note: `#[warn(unused_attributes)]` on by default
     = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!

     warning: attribute should be applied to a free function, impl method or static
     --> src/lib.rs:351:1
      |
  351 |   #[no_mangle]
      |   ^^^^^^^^^^^^
  352 |   #[derive(Clone, Copy, Debug)]
  353 | / pub enum CBoxResult {
  354 | |     Success               = 0,
  355 | |     StorageError          = 1,
  356 | |     SessionNotFound       = 2,
  ...   |
  371 | |     DegeneratedKey        = 17
  372 | | }
      | |_- not a free function, impl method or static
      |
      = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!

  warning: `cryptobox-c` (lib) generated 2 warnings
      Finished dev [unoptimized + debuginfo] target(s) in 0.46s
  mkdir -p test/target
  cp target/debug/libcryptobox.so test/target/libcryptobox.so
  rm -f test/target/main
  cc -std=c99 -Wall -Wextra -Werror -g test/main.c -o test/target/main -Isrc -Ltest/target -lcryptobox
  LD_LIBRARY_PATH=test/target valgrind --leak-check=full --error-exitcode=1 --track-origins=yes test/target/main
  ==68253== Memcheck, a memory error detector
  ==68253== Copyright (C) 2002-2022, and GNU GPL'd, by Julian Seward et al.
  ==68253== Using Valgrind-3.19.0 and LibVEX; rerun with -h for copyright info
  ==68253== Command: test/target/main
  ==68253==
  alice="/tmp/cbox_test_aliceNgw9Dt", bob="/tmp/cbox_test_bobubbcd1"
  test_basics ... OK
  ERROR: CBoxError: proteus error: PreKeyNotFound: 1
  test_prekey_removal ... OK
  test_random_bytes ... OK
  ERROR: CBOR decoder error: DecodeError: unexpected type Text (info=14)
  test_is_prekey ... OK
  test_last_prekey ... OK
  ERROR: CBoxError: proteus error: DuplicateMessage
  test_duplicate_msg ... OK
  test_delete_session ... OK
  test_box_reopen ... OK
  ERROR: CBoxError: identity error   
  test_external_identity ... OK
  ERROR: CBoxError: identity error   
  ERROR: CBoxError: identity error   
  test_wrong_identity ... OK
  test_fingerprint_prekey ... OK

  ==68253==
  ==68253== HEAP SUMMARY:
  ==68253==     in use at exit: 0 bytes in 0 blocks
  ==68253==   total heap usage: 1,124 allocs, 1,124 frees, 269,456 bytes allocated
  ==68253==
  ==68253== All heap blocks were freed -- no leaks are possible
  ==68253==
  ==68253== For lists of detected and suppressed errors, rerun with: -s
  ==68253== ERROR SUMMARY: 0 errors from 0 contexts (suppressed: 0 from 0)