https://github.com/brianschubert/purecipher
Demonstration of exposing non-primitive data structures over a foreign function interface in Rust.
https://github.com/brianschubert/purecipher
ffi ffi-wrapper
Last synced: 6 months ago
JSON representation
Demonstration of exposing non-primitive data structures over a foreign function interface in Rust.
- Host: GitHub
- URL: https://github.com/brianschubert/purecipher
- Owner: brianschubert
- License: mit
- Created: 2018-09-10T22:09:18.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-12-08T14:25:56.000Z (about 7 years ago)
- Last Synced: 2023-07-18T18:26:55.985Z (over 2 years ago)
- Topics: ffi, ffi-wrapper
- Language: C
- Homepage:
- Size: 98.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# purecipher
A rust library implementing pure (stateless) ciphers.
This repository is intended to serve as a terse demonstration of exposing
non-primitive data structures over a foreign function interface with the Rust
programming language.
purecipher provides a succinct interface for manipulating trivial substitution
ciphers. The "meat" of this repository lies in the interface between the Rust
code the comprises the purecipher library and the C code that allows this
library to used by applications written in C, C++, Python, and other languages.
The libraries defined in this repository are not intended for practical
applications and most definitely should not be used in place of conventional
cryptographic libraries.
## Usage
To incorporate the latest version of the purecipher library into a Rust crate,
add the following to the dependencies section of your `Cargo.toml` configuration:
```toml
[dependencies]
purecipher = { git = "https://github.com/blueschu/purecipher" }
```
Since the purecipher library is designed to demonstrate the implementation of
foreign function interfaces, it of course exposes a C API. This interface is
described by the C header file `./include/purecipher.h`. To use purecipher in a
C project, simply `#include` this header file and ensure that the purecipher
library file is discoverable at link time. To use the purecipher library in a
non-C, non-Rust environment, you may either employ a language specific FFI
library or make use of one the wrapper libraries provided in the `./wrappers`
of this repository. Usage instructions for each of these wrappers are
documented in the `README.md` files found in their respective source roots.
## Building
All components of this repository can be built using CMake for convenience. To
build all CMake targets, you may run the following.
```bash
$ mkdir -p cmake-build-debug
$ cd !$
$ cmake ..
$ make
```
Specific targets, (e.g. `purecipher` or `ctest`) may follow the `make` command
above to build only those targets. For a full listing of applicable targets, see
the `CMakeList.txt` files located throughout this repository.
System dependencies for targets are documented in the `README` files located in
their respective source root.
## Testing
Each component of this repository includes a set of unit tests. The procedure
for running these tests varies between components. Testing procedures for the
main rust library are documented below. For running unit tests against wrapper
implementations, see the `README` files in their source directory.
### Rust Tests
To build and run the Rust unit tests, simply use cargo's `test` command:
```bash
$ cargo test
```
### C Tests
Test cases for the C API exposed by the Rust crate may be found under the `ctest`
directory. If you have already built all CMake targets, these tests can run with
```bash
$ ./cmake-build-debug/ctest/ctest
```
where `cmake-build-debug` is the build directory used by CMake.
If using CMake is not an option on your system, you may also compile the test
sources by hand:
```bash
$ cd ctest
$ cargo build --manifest-path ../Cargo.toml
$ cc -o ctest test.c --std=c11 -Wall -I../include -L../target/debug -lpurecipher
$ LD_LIBRARY_PATH=../target/debug ./ctest
```
where `cc` is a compatible C compiler of your choosing (e.g. `gcc`, `clang`).
## Acknowledgments
The layout of this repository was inspired by the C API for the [Rust Regex Engine][rure].
## Copyright & License
Copyright © 2018 Brian Schubert - available under [MIT License][license].
[rure]: https://github.com/rust-lang/regex/tree/master/regex-capi
[license]: ./LICENSE