PFSS

For the x86 family of CPUs, there is one CPU instruction set that can be enabled: AES-NI.

You can generally enable AES-NI by adding -maes to both CFLAGS and CXXFLAGS. If you’re not cross-compiling, it’s usually sufficient to specify -march=native without any other -m options.

You can also specify --with-aes-ni to ./configure to instruct it to verify that AES-NI was detected, failing if not.

For the ARM family of CPUs, there is one CPU instruction set that can be enabled: ARM Crypto.

You can generally enable ARM Crypto by adding -march=armv8-a+crypto to both CFLAGS and CXXFLAGS. You can adjust this flag as needed, it is only the +crypto extension that is required. If you’re not cross-compiling, it’s usually sufficient to specify -march=native without any other -m options.

You can also specify --with-arm-crypto to ./configure to instruct it to verify that ARM Crypto was detected, failing if not.

The pfss_set_log_file function sets the logging destination to log_file and returns the previous logging destination.

A null pointer indicates logging is disabled.

If logging was not enabled at build time with ./configure --with-logging, getting and setting the logging destination still behaves normally, but logging is always disabled.

The pfss_get_log_file function returns the logging destination.

A null pointer indicates logging is disabled.

If logging was not enabled at build time with ./configure --with-logging, getting and setting the logging destination still behaves normally, but logging is always disabled.

The pfss_status type represents a status code of a function call. Most PFSS functions return a pfss_status code.

pfss_status is guaranteed to be an alias of uint32_t.

Each status code is defined as a macro that expands to an integer constant expression that can be used in both normal code and in preprocessor arithmetic. In normal code, the type of the expression is pfss_status.

The status codes and their meanings are listed below. Note that some meanings are more descriptive than others. Functions generally return the most descriptive status code they can.

The pfss_get_status_name function returns a pointer to a constant string with static storage duration that holds the name of the status code status. If status is not a valid status code, the string will be "PFSS_UNKNOWN_STATUS".

The pfss_endianness type describes the byte order of an integer value.

The endianness constants and their meanings are listed below.

The pfss_gen_sizes function determines how big each of the key blobs generated by the pfss_gen function will be for the given domain_bits and range_bits values, and how many random bytes will be needed to generate them.

The pfss_gen function generates two key blobs that form a secret sharing of the function \(f : \{0,1\}^\mathtt{domain\_bits} \rightarrow \{0,1\}^\mathtt{range\_bits}\) defined by \(f(\mathtt{alpha}) = \mathtt{beta}\) and \(f(x) = 0\) everywhere else.

domain_bits and range_bits should both be nonzero.

alpha should be an unsigned integer that consists of alpha_size bytes in alpha_endianness byte order. The bits are ordered from least to most significant, and any bits above the least significant domain_bits bits are ignored. alpha_size should be nonzero.

beta should be an unsigned integer that consists of beta_size bytes in beta_endianness byte order. The bits are ordered from least to most significant, and any bits above the least significant range_bits bits are ignored. beta_size should be nonzero.

The key blobs will be written to the key1_blob and key2_blob arrays. The size of both arrays should be the size obtained by a call to the pfss_gen_sizes function with the same domain_bits and range_bits values.

rand_buf should be an array of random bytes. The size of the array should be the size obtained by a call to the pfss_gen_sizes function with the same domain_bits and range_bits values.

The pfss_map_gen function creates FSS key pairs for each of the alphas_count elements of alphas and betas, storing the key pairs inside key1_blobs and key2_blobs. Each element of alphas should be an unsigned integer that consists of alpha_size bytes in alpha_endianness byte order. Each element of betas should be an unsigned integer that consists of beta_size bytes in beta_endianness byte order. Each element in alphas should be less than 2^domain_bits and each element of betas should be less than 2^range_bits. As long as the values of each element in alphas and betas are in range, alpha_size and beta_size can be arbitrarily large or small, but they must not be zero. key1_blobs and key2_blobs should be containers consisting of alphas_count * key_blob_size bytes. Similarly, rand_bufs should be a container consisting of alphas_count * rand_buf_size bytes. The function returns PFSS_OK upon success, or another status code upon failure.

The pfss_key type represents a key that has been parsed from a key blob.

The pfss_parse_key function parses a key blob.

The pfss_destroy_key function destroys a key.

The pfss_get_domain_bits function sets *domain_bits to the number of domain bits in *key.

This function returns PFSS_OK upon success, or another status code upon failure. You can use the pfss_get_status_name function to convert the status code into a human readable name.

Note that this function takes a pfss_key const *, not a pfss_key *. By convention, all functions that take a pfss_key const * are safe to call from multiple threads at the same time on the same key.

The pfss_get_range_bits function sets *range_bits to the number of range bits in *key.

This function returns PFSS_OK upon success, or another status code upon failure. You can use the pfss_get_status_name function to convert the status code into a human readable name.

Note that this function takes a pfss_key const *, not a pfss_key *. By convention, all functions that take a pfss_key const * are safe to call from multiple threads at the same time on the same key.

The pfss_eval function evaluates a key at a single domain element to produce a single range element.

This function returns PFSS_OK upon success, or another status code upon failure. You can use the pfss_get_status_name function to convert the status code into a human readable name.

Note that this function takes a pfss_key const *, not a pfss_key *. By convention, all functions that take a pfss_key const * are safe to call from multiple threads at the same time on the same key.

The PFSS_DEFINE_DIRECT_EVAL macro defines a self-contained function f that evaluates an unparsed key blob k at a domain value x. f can be any name of your choice. domain_bits should be an integer constant expression with type int whose value is between 1 and 128 inclusive. range_type should be either uint8_t, uint16_t, uint32_t, or uint64_t.

When calling f, k should be a key blob that was output by the pfss_gen function with the same number of domain bits and range bits as specified by domain_bits and range_type, and x should be an unsigned integer that consists of \(\lceil\mathtt{domain\_bits}/8\rceil\) bytes in little endian byte order. Any bits above the least significant domain_bits bits of x are ignored. The return value is the result of the evaluation.

The code of f is valid as both C and C++. However, f currently requires AES-NI support via the -maes compiler option. This option is normally handled by the PFSS build system, but since you’ll be compiling f yourself, you’ll need to provide this option yourself. In the future, it may be generalized to work on other systems.

The pfss_reduce_sum function sets x to the sum of the ys_count elements of ys. Each element of ys should be an unsigned integer that consists of y_size bytes in y_endianness byte order. The sum is taken modulo 2range_bits and output as an unsigned integer that consists of z_size bytes in z_endianness byte order. The function returns PFSS_OK upon success, or another status code upon failure.

The pfss_map_eval function evaluates a key over a list of domain elements to produce a list of range elements.

xs should point to the first byte of an array of xs_count unsigned integers, each of which consists of x_size bytes in x_endianness byte order.

ys should point to the first byte of an array of xs_count unsigned integers, each of which consists of y_size bytes in y_endianness byte order. It is also required that \(\mathtt{y\_size} \ge \lceil r / 8 \rceil\), where \(r\) is the number of range bits in the key.

The key is evaluated at each domain element in the xs array and each result is written to the corresponding range element in the ys array.

This function returns PFSS_OK upon success, or another status code upon failure. You can use the pfss_get_status_name function to convert the status code into a human readable name.

Note that this function takes a pfss_key const *, not a pfss_key *. By convention, all functions that take a pfss_key const * are safe to call from multiple threads at the same time on the same key.

The pfss_map_eval_reduce_sum function evaluates a key over a list of domain elements and sums the resulting range elements to produce a single range element.

xs should point to the first byte of an array of xs_count unsigned integers, each of which consists of x_size bytes in x_endianness byte order.

y should point to the first byte of a range element (i.e., an unsigned integer) that consists of y_size bytes in y_endianness byte order. It is also required that \(\mathtt{y\_size} \ge \lceil r / 8 \rceil\), where \(r\) is the number of range bits in the key.

The key is evaluated at each domain element in the xs array, the resulting range elements are summed modulo \(2^r\), and the sum is written to the range element pointed to by y.

This function returns PFSS_OK upon success, or another status code upon failure. You can use the pfss_get_status_name function to convert the status code into a human readable name.

Note that this function takes a pfss_key const *, not a pfss_key *. By convention, all functions that take a pfss_key const * are safe to call from multiple threads at the same time on the same key.

The pfss_eval_all function evaluates a key over a (partial) grid of domain elements to produce a (partial) grid of range elements.

First, the \(\lceil \mathtt{xp\_bits} / 8 \rceil\) bytes pointed to by xp are interpreted as an unsigned integer in xp_endianness byte order. All bits of this integer are ignored except for the least significant xp_bits bits, which form a value \(v\). This value is shifted left by \(k = d - \mathtt{xp\_bits}\) bits to form the first domain element \(x_1\) at which key will be evaluated, where \(d\) is the number of domain bits in key. In other words, \(x_1 = v \cdot 2^k\). It is required that \(k \ge 0\), i.e., that \(\mathtt{xp\_bits} \le d\).

Next, key is evaluated at each successive domain element up to and including \(x_{2^k} = x_1 + 2^k - 1\), and each result is written to a specific location in the array of bytes pointed to by ys. The array of bytes is treated as an array of unsigned integers, each consisting of y_size bytes in y_endianness byte order. It is required that \(\mathtt{y\_size} \ge \lceil r / 8 \rceil\), where \(r\) is the number of range bits in key. The evaluation result of each \(x_i\) is written to the \(x_i\)'th element of the array.

This function returns PFSS_OK upon success, or another status code upon failure. You can use the pfss_get_status_name function to convert the status code into a human readable name.

Note that this function takes a pfss_key const *, not a pfss_key *. By convention, all functions that take a pfss_key const * are safe to call from multiple threads at the same time on the same key.

The pfss_eval_all_sum function evaluates multiple keys over the complete grid of domain elements and sums the resulting grids into an existing grid.

keys should point to an array of keys_count keys. All keys should have the same number of domain bits. All keys should have the same number of range bits. If keys_count is zero, keys will not be accessed but should still be a valid pointer.

ys should point to a complete grid of range elements, i.e., an array of \(2^d\) unsigned integers where \(d\) is the number of domain bits in each key. Each unsigned integer should consist of y_size bytes in y_endianness byte order. y_size should always be positive. If keys_count is zero, ys will not be accessed but it should still be a valid pointer.

Each key is evaluated at all domain elements to produce an intermediate grid, which is then summed into ys.

thread_count specifies the number of threads to use to perform the computation. This number should always be positive.

This function returns PFSS_OK upon success, or another status code upon failure. You can use the pfss_get_status_name function to convert the status code into a human readable name.

Note that this function takes a pfss_key const *, not a pfss_key *. By convention, all functions that take a pfss_key const * are safe to call from multiple threads at the same time on the same key.

The pfss_eval_all_dot function evaluates multiple keys over the complete grid of domain elements and computes the dot product of each resulting grid with an existing grid.

keys should point to an array of keys_count keys. All keys should have the same number of domain bits. All keys should have the same number of range bits. If keys_count is zero, keys will not be accessed but should still be a valid pointer.

ys should point to a complete grid of range elements, i.e., an array of \(2^d\) unsigned integers where \(d\) is the number of domain bits in each key. Each unsigned integer should consist of y_size bytes in y_endianness byte order. y_size should always be positive. If keys_count is zero, ys will not be accessed but it should still be a valid pointer.

zs should point to an array of keys_count unsigned integers. Each unsigned integer should consist of z_size bytes in z_endianness byte order.

Each key is evaluated at all domain elements to produce an intermediate grid. The dot product of the intermediate grid is taken with ys, and the result is written to the corresponding element of zs. The result is taken modulo \(2^r\) where \(r\) is the number of range bits in each key.

thread_count specifies the number of threads to use to perform the computation. This number should always be positive.

This function returns PFSS_OK upon success, or another status code upon failure. You can use the pfss_get_status_name function to convert the status code into a human readable name.

Note that this function takes a pfss_key const *, not a pfss_key *. By convention, all functions that take a pfss_key const * are safe to call from multiple threads at the same time on the same key.

The PFSS_SWITCH_DB_RB macro expands to a do { /* ... */ } while (0) block of code that calls either template_code((domain_bits), (range_bits)) or standard_code() depending on whether PFSS was compiled with template optimizations enabled for the given domain_bits and range_bits combination via switch_db_rb.cfg. template_code should be the name of a function-like macro that takes two parameters. The arguments passed to template_code will not actually be domain_bits and range_bits, but rather decimal constants whose values match domain_bits and range_bits, which allows them to be used as template arguments in C++. standard_code should be the name of a function-like macro that takes no arguments. template_code and standard_code should each expand to a do { /* ... */ } while (0) block of code. domain_bits and range_bits will each be evaluated exactly once.

Here is an example function that determines whether PFSS was compiled with template optimizations enabled for a given domain_bits and range_bits combination:

The Node.js bindings are provided in the src/node directory, which is actually an example project. The intent is that you can take pfss-node.cpp verbatim and adapt binding.gyp and package.json into your own project.