#include #include #include #include #include enum class ProofMessageType { Revealed = 1, HiddenProofSpecificBlinding = 2, HiddenExternalBlinding = 3, }; /// ByteBuffer is a struct that represents an array of bytes to be sent over the FFI boundaries. /// There are several cases when you might want to use this, but the primary one for us /// is for returning protobuf-encoded data to Swift and Java. The type is currently rather /// limited (implementing almost no functionality), however in the future it may be /// more expanded. /// /// ## Caveats /// /// Note that the order of the fields is `len` (an i64) then `data` (a `*mut u8`), getting /// this wrong on the other side of the FFI will cause memory corruption and crashes. /// `i64` is used for the length instead of `u64` and `usize` because JNA has interop /// issues with both these types. /// /// ### `Drop` is not implemented /// /// ByteBuffer does not implement Drop. This is intentional. Memory passed into it will /// be leaked if it is not explicitly destroyed by calling [`ByteBuffer::destroy`], or /// [`ByteBuffer::destroy_into_vec`]. This is for two reasons: /// /// 1. In the future, we may allow it to be used for data that is not managed by /// the Rust allocator\*, and `ByteBuffer` assuming it's okay to automatically /// deallocate this data with the Rust allocator. /// /// 2. Automatically running destructors in unsafe code is a /// [frequent footgun](https://without.boats/blog/two-memory-bugs-from-ringbahn/) /// (among many similar issues across many crates). /// /// Note that calling `destroy` manually is often not needed, as usually you should /// be passing these to the function defined by [`define_bytebuffer_destructor!`] from /// the other side of the FFI. /// /// Because this type is essentially *only* useful in unsafe or FFI code (and because /// the most common usage pattern does not require manually managing the memory), it /// does not implement `Drop`. /// /// \* Note: in the case of multiple Rust shared libraries loaded at the same time, /// there may be multiple instances of "the Rust allocator" (one per shared library), /// in which case we're referring to whichever instance is active for the code using /// the `ByteBuffer`. Note that this doesn't occur on all platforms or build /// configurations, but treating allocators in different shared libraries as fully /// independent is always safe. /// /// ## Layout/fields /// /// This struct's field are not `pub` (mostly so that we can soundly implement `Send`, but also so /// that we can verify rust users are constructing them appropriately), the fields, their types, and /// their order are *very much* a part of the public API of this type. Consumers on the other side /// of the FFI will need to know its layout. /// /// If this were a C struct, it would look like /// /// ```c,no_run /// struct ByteBuffer { /// // Note: This should never be negative, but values above /// // INT64_MAX / i64::MAX are not allowed. /// int64_t len; /// // Note: nullable! /// uint8_t *data; /// }; /// ``` /// /// In rust, there are two fields, in this order: `len: i64`, and `data: *mut u8`. /// /// For clarity, the fact that the data pointer is nullable means that `Option` is not /// the same size as ByteBuffer, and additionally is not FFI-safe (the latter point is not /// currently guaranteed anyway as of the time of writing this comment). /// /// ### Description of fields /// /// `data` is a pointer to an array of `len` bytes. Note that data can be a null pointer and therefore /// should be checked. /// /// The bytes array is allocated on the heap and must be freed on it as well. Critically, if there /// are multiple rust shared libraries using being used in the same application, it *must be freed /// on the same heap that allocated it*, or you will corrupt both heaps. /// /// Typically, this object is managed on the other side of the FFI (on the "FFI consumer"), which /// means you must expose a function to release the resources of `data` which can be done easily /// using the [`define_bytebuffer_destructor!`] macro provided by this crate. struct ByteBuffer { int64_t len; uint8_t *data; }; /// A wrapper around error codes, which is represented identically to an i32 on the other side of /// the FFI. Essentially exists to check that we don't accidentally reuse success/panic codes for /// other things. using ErrorCode = int32_t; /// Represents an error that occured within rust, storing both an error code, and additional data /// that may be used by the caller. /// /// Misuse of this type can cause numerous issues, so please read the entire documentation before /// usage. /// /// ## Rationale /// /// This library encourages a pattern of taking a `&mut ExternError` as the final parameter for /// functions exposed over the FFI. This is an "out parameter" which we use to write error/success /// information that occurred during the function's execution. /// /// To be clear, this means instances of `ExternError` will be created on the other side of the FFI, /// and passed (by mutable reference) into Rust. /// /// While this pattern is not particularly ergonomic in Rust (although hopefully this library /// helps!), it offers two main benefits over something more ergonomic (which might be `Result` /// shaped). /// /// 1. It avoids defining a large number of `Result`-shaped types in the FFI consumer, as would /// be required with something like an `struct ExternResult { ok: *mut T, err:... }` /// /// 2. It offers additional type safety over `struct ExternResult { ok: *mut c_void, err:... }`, /// which helps avoid memory safety errors. It also can offer better performance for returning /// primitives and repr(C) structs (no boxing required). /// /// It also is less tricky to use properly than giving consumers a `get_last_error()` function, or /// similar. /// /// ## Caveats /// /// Note that the order of the fields is `code` (an i32) then `message` (a `*mut c_char`), getting /// this wrong on the other side of the FFI will cause memory corruption and crashes. /// /// The fields are public largely for documentation purposes, but you should use /// [`ExternError::new_error`] or [`ExternError::success`] to create these. /// /// ## Layout/fields /// /// This struct's field are not `pub` (mostly so that we can soundly implement `Send`, but also so /// that we can verify rust users are constructing them appropriately), the fields, their types, and /// their order are *very much* a part of the public API of this type. Consumers on the other side /// of the FFI will need to know its layout. /// /// If this were a C struct, it would look like /// /// ```c,no_run /// struct ExternError { /// int32_t code; /// char *message; // note: nullable /// }; /// ``` /// /// In rust, there are two fields, in this order: `code: ErrorCode`, and `message: *mut c_char`. /// Note that ErrorCode is a `#[repr(transparent)]` wrapper around an `i32`, so the first property /// is equivalent to an `i32`. /// /// #### The `code` field. /// /// This is the error code, 0 represents success, all other values represent failure. If the `code` /// field is nonzero, there should always be a message, and if it's zero, the message will always be /// null. /// /// #### The `message` field. /// /// This is a null-terminated C string containing some amount of additional information about the /// error. If the `code` property is nonzero, there should always be an error message. Otherwise, /// this should will be null. /// /// This string (when not null) is allocated on the rust heap (using this crate's /// [`rust_string_to_c`]), and must be freed on it as well. Critically, if there are multiple rust /// packages using being used in the same application, it *must be freed on the same heap that /// allocated it*, or you will corrupt both heaps. /// /// Typically, this object is managed on the other side of the FFI (on the "FFI consumer"), which /// means you must expose a function to release the resources of `message` which can be done easily /// using the [`define_string_destructor!`] macro provided by this crate. /// /// If, for some reason, you need to release the resources directly, you may call /// `ExternError::release()`. Note that you probably do not need to do this, and it's /// intentional that this is not called automatically by implementing `drop`. /// /// ## Example /// /// ```rust,no_run /// use ffi_support::{ExternError, ErrorCode}; /// /// #[derive(Debug)] /// pub enum MyError { /// IllegalFoo(String), /// InvalidBar(i64), /// // ... /// } /// /// // Putting these in a module is obviously optional, but it allows documentation, and helps /// // avoid accidental reuse. /// pub mod error_codes { /// // note: -1 and 0 are reserved by ffi_support /// pub const ILLEGAL_FOO: i32 = 1; /// pub const INVALID_BAR: i32 = 2; /// // ... /// } /// /// fn get_code(e: &MyError) -> ErrorCode { /// match e { /// MyError::IllegalFoo(_) => ErrorCode::new(error_codes::ILLEGAL_FOO), /// MyError::InvalidBar(_) => ErrorCode::new(error_codes::INVALID_BAR), /// // ... /// } /// } /// /// impl From for ExternError { /// fn from(e: MyError) -> ExternError { /// ExternError::new_error(get_code(&e), format!("{:?}", e)) /// } /// } /// ``` struct ExternError { ErrorCode code; char *message; }; /// `FfiStr<'a>` is a safe (`#[repr(transparent)]`) wrapper around a /// nul-terminated `*const c_char` (e.g. a C string). Conceptually, it is /// similar to [`std::ffi::CStr`], except that it may be used in the signatures /// of extern "C" functions. /// /// Functions accepting strings should use this instead of accepting a C string /// directly. This allows us to write those functions using safe code without /// allowing safe Rust to cause memory unsafety. /// /// A single function for constructing these from Rust ([`FfiStr::from_raw`]) /// has been provided. Most of the time, this should not be necessary, and users /// should accept `FfiStr` in the parameter list directly. /// /// ## Caveats /// /// An effort has been made to make this struct hard to misuse, however it is /// still possible, if the `'static` lifetime is manually specified in the /// struct. E.g. /// /// ```rust,no_run /// # use ffi_support::FfiStr; /// // NEVER DO THIS /// #[no_mangle] /// extern "C" fn never_do_this(s: FfiStr<'static>) { /// // save `s` somewhere, and access it after this /// // function returns. /// } /// ``` /// /// Instead, one of the following patterns should be used: /// /// ``` /// # use ffi_support::FfiStr; /// #[no_mangle] /// extern "C" fn valid_use_1(s: FfiStr<'_>) { /// // Use of `s` after this function returns is impossible /// } /// // Alternative: /// #[no_mangle] /// extern "C" fn valid_use_2(s: FfiStr) { /// // Use of `s` after this function returns is impossible /// } /// ``` using FfiStr = const char*; /// Used for receiving a ByteBuffer from C that was allocated by either C or Rust. /// If Rust allocated, then the outgoing struct is `ffi_support::ByteBuffer` /// Caller is responsible for calling free where applicable. /// /// C will not notice a difference and can use the same struct struct ByteArray { uintptr_t length; const uint8_t *data; }; extern "C" { /// Public destructor for strings managed by the other side of the FFI. /// /// # Safety /// /// This will free the string pointer it gets passed in as an argument, /// and thus can be wildly unsafe if misused. /// /// See the documentation of `ffi_support::destroy_c_string` and /// `ffi_support::define_string_destructor!` for further info. void bbs_string_free(char *s); void bbs_byte_buffer_free(ByteBuffer v); void free_bbs_blind_commitment(uint64_t v, ExternError *err); int32_t bbs_blind_signature_size(); uint64_t bbs_blind_commitment_context_init(ExternError *err); int32_t bbs_blind_commitment_context_add_message_string(uint64_t handle, uint32_t index, FfiStr message, ExternError *err); int32_t bbs_blind_commitment_context_add_message_bytes(uint64_t handle, uint32_t index, ByteArray message, ExternError *err); int32_t bbs_blind_commitment_context_add_message_prehashed(uint64_t handle, uint32_t index, ByteArray message, ExternError *err); int32_t bbs_blind_commitment_context_set_public_key(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_blind_commitment_context_set_nonce_string(uint64_t handle, FfiStr message, ExternError *err); int32_t bbs_blind_commitment_context_set_nonce_bytes(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_blind_commitment_context_set_nonce_prehashed(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_blind_commitment_context_finish(uint64_t handle, ByteBuffer *commitment, ByteBuffer *out_context, ByteBuffer *blinding_factor, ExternError *err); void free_bbs_blind_sign(uint64_t v, ExternError *err); int32_t bbs_blinding_factor_size(); uint64_t bbs_blind_sign_context_init(ExternError *err); int32_t bbs_blind_sign_context_add_message_string(uint64_t handle, uint32_t index, FfiStr message, ExternError *err); int32_t bbs_blind_sign_context_add_message_bytes(uint64_t handle, uint32_t index, ByteArray message, ExternError *err); int32_t bbs_blind_sign_context_add_message_prehashed(uint64_t handle, uint32_t index, ByteArray message, ExternError *err); int32_t bbs_blind_sign_context_set_public_key(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_blind_sign_context_set_secret_key(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_blind_sign_context_set_commitment(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_blind_sign_context_finish(uint64_t handle, ByteBuffer *blinded_signature, ExternError *err); int32_t bbs_unblind_signature(ByteArray blind_signature, ByteArray blinding_factor, ByteBuffer *unblind_signature, ExternError *err); void free_create_proof(uint64_t v, ExternError *err); int32_t bbs_create_proof_context_size(uint64_t handle); uint64_t bbs_create_proof_context_init(ExternError *err); int32_t bbs_create_proof_context_add_proof_message_string(uint64_t handle, FfiStr message, ProofMessageType xtype, ByteArray blinding_factor, ExternError *err); int32_t bbs_create_proof_context_add_proof_message_bytes(uint64_t handle, ByteArray message, ProofMessageType xtype, ByteArray blinding_factor, ExternError *err); int32_t bbs_create_proof_context_add_proof_message_prehashed(uint64_t handle, ByteArray message, ProofMessageType xtype, ByteArray blinding_factor, ExternError *err); int32_t bbs_create_proof_context_set_signature(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_create_proof_context_set_public_key(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_create_proof_context_set_nonce_string(uint64_t handle, FfiStr message, ExternError *err); int32_t bbs_create_proof_context_set_nonce_bytes(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_create_proof_context_set_nonce_prehashed(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_create_proof_context_finish(uint64_t handle, ByteBuffer *proof, ExternError *err); void free_bbs_sign(uint64_t v, ExternError *err); int32_t bbs_signature_size(); uint64_t bbs_sign_context_init(ExternError *err); int32_t bbs_sign_context_add_message_string(uint64_t handle, FfiStr message, ExternError *err); int32_t bbs_sign_context_add_message_bytes(uint64_t handle, ByteArray message, ExternError *err); int32_t bbs_sign_context_add_message_prehashed(uint64_t handle, ByteArray message, ExternError *err); int32_t bbs_sign_context_set_secret_key(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_sign_context_set_public_key(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_sign_context_finish(uint64_t handle, ByteBuffer *signature, ExternError *err); uint64_t bbs_verify_context_init(ExternError *err); int32_t bbs_verify_context_add_message_string(uint64_t handle, FfiStr message, ExternError *err); int32_t bbs_verify_context_add_message_bytes(uint64_t handle, ByteArray message, ExternError *err); int32_t bbs_verify_context_add_message_prehashed(uint64_t handle, ByteArray message, ExternError *err); int32_t bbs_verify_context_set_public_key(uint64_t handle, ByteArray public_key, ExternError *err); int32_t bbs_verify_context_set_signature(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_verify_context_finish(uint64_t handle, ExternError *err); void free_verify_proof(uint64_t v, ExternError *err); int32_t bbs_get_total_messages_count_for_proof(ByteArray proof); uint64_t bbs_verify_proof_context_init(ExternError *err); int32_t bbs_verify_proof_context_add_message_string(uint64_t handle, FfiStr message, ExternError *err); int32_t bbs_verify_proof_context_add_message_bytes(uint64_t handle, ByteArray message, ExternError *err); int32_t bbs_verify_proof_context_add_message_prehashed(uint64_t handle, ByteArray message, ExternError *err); int32_t bbs_verify_proof_context_set_proof(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_verify_proof_context_set_public_key(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_verify_proof_context_set_nonce_string(uint64_t handle, FfiStr message, ExternError *err); int32_t bbs_verify_proof_context_set_nonce_bytes(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_verify_proof_context_set_nonce_prehashed(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_verify_proof_context_finish(uint64_t handle, ExternError *err); void free_verify_sign_proof(uint64_t v, ExternError *err); uint64_t bbs_verify_blind_commitment_context_init(ExternError *err); int32_t bbs_verify_blind_commitment_context_add_blinded(uint64_t handle, uint32_t index, ExternError *err); int32_t bbs_verify_blind_commitment_context_set_public_key(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_verify_blind_commitment_context_set_nonce_string(uint64_t handle, FfiStr message, ExternError *err); int32_t bbs_verify_blind_commitment_context_set_nonce_bytes(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_verify_blind_commitment_context_set_nonce_prehashed(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_verify_blind_commitment_context_set_proof(uint64_t handle, ByteArray value, ExternError *err); int32_t bbs_verify_blind_commitment_context_finish(uint64_t handle, ExternError *err); int32_t bls_secret_key_size(); int32_t bls_public_key_g2_size(); int32_t blinding_factor_size(); int32_t bls_public_key_g1_size(); int32_t bls_generate_g2_key(ByteArray seed, ByteBuffer *public_key, ByteBuffer *secret_key, ExternError *err); int32_t bls_generate_g1_key(ByteArray seed, ByteBuffer *public_key, ByteBuffer *secret_key, ExternError *err); int32_t bls_generate_blinded_g2_key(ByteArray seed, ByteBuffer *public_key, ByteBuffer *secret_key, ByteBuffer *blinding_factor, ExternError *err); int32_t bls_generate_blinded_g1_key(ByteArray seed, ByteBuffer *public_key, ByteBuffer *secret_key, ByteBuffer *blinding_factor, ExternError *err); int32_t bls_get_public_key(ByteArray secret_key, ByteBuffer *public_key, ExternError *err); int32_t bls_secret_key_to_bbs_key(ByteArray secret_key, uint32_t message_count, ByteBuffer *public_key, ExternError *err); int32_t bls_public_key_to_bbs_key(ByteArray d_public_key, uint32_t message_count, ByteBuffer *public_key, ExternError *err); } // extern "C"