Expand description
Rust wrapper for the aws-c-cal library. For testing purposes only.
For interacting with AWS services, use the aws-sdk-rust crate instead.
Structs
struct aws_atomic_var represents an atomic variable - a value which can hold an integer or pointer
that can be manipulated atomically. struct aws_atomic_vars should normally only be manipulated
with atomics methods defined in this header.
Represents a length-delimited binary string or buffer. If byte buffer points
to constant memory or memory that should otherwise not be freed by this
struct, set allocator to NULL and free function will be a no-op.
Represents a movable pointer within a larger binary string or buffer.
Options for aws_logger_init_standard().
Set
filename to open a file for logging and close it when the logger cleans up.
Set file to use a file that is already open, such as stderr or stdout.We separate the log level function from the log call itself so that we can do the filter check in the macros (see
below)
Constants
Specifies acquire-release order; if this operation acts as a load, it acts as an
acquire operation; if it acts as a store, it acts as a release operation; if it’s
a load-store, it does both.
Specifies acquire ordering. No reads or writes on the current thread can be
reordered to happen before this operation. This is typically paired with a release
ordering; any writes that happened on the releasing operation will be visible
after the paired acquire operation.
No particular ordering constraints are guaranteed relative to other
operations at all; we merely ensure that the operation itself is atomic.
Specifies release order. No reads or writes can be reordered to come after this
operation. Typically paired with an acquire operation.
Specifies acquire-release order; if this operation acts as a load, it acts as an
acquire operation; if it acts as a store, it acts as a release operation; if it’s
a load-store, it does both.
Functions
Adds [num] arguments (expected to be of size_t), and returns the result in *r.
If the result overflows, returns AWS_OP_ERR; otherwise returns AWS_OP_SUCCESS.
Inexpensive (constant time) check of data-structure invariants.
Compare two arrays.
Return whether their contents are equivalent.
NULL may be passed as the array pointer if its length is declared to be 0.
Compare an array and a null-terminated string.
Returns true if their contents are equivalent.
The array should NOT contain a null-terminator, or the comparison will always return false.
NULL may be passed as the array pointer if its length is declared to be 0.
Perform a case-insensitive string comparison of an array and a null-terminated string.
Return whether their contents are equivalent.
The array should NOT contain a null-terminator, or the comparison will always return false.
NULL may be passed as the array pointer if its length is declared to be 0.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Perform a case-insensitive string comparison of two arrays.
Return whether their contents are equivalent.
NULL may be passed as the array pointer if its length is declared to be 0.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Copies the elements from from to to. If to is in static mode, it must at least be the same length as from. Any data
in to will be overwritten in this copy.
Ensures that the array list has enough capacity to store a value at the specified index. If there is not already
enough capacity, and the list is in dynamic mode, this function will attempt to allocate more memory, expanding the
list. In static mode, if ‘index’ is beyond the maximum index, AWS_ERROR_INVALID_INDEX will be raised.
If in dynamic mode, shrinks the allocated array size to the minimum amount necessary to store its elements.
Swap elements at the specified indices, which must be within the bounds of the array.
Appends a sub-buffer to the specified buffer.
Copies from to to. If to is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be
returned. dest->len will contain the amount of data actually copied to dest.
Copy contents of cursor to buffer, then update cursor to reference the memory stored in the buffer.
If buffer is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be returned.
Copies a single byte into
to. If to is too small, the buffer will be grown appropriately and
the old contents copied over, before the byte is appended.Copies a single byte into
to. If to is too small, the buffer will be grown appropriately and
the old contents copied over, before the byte is appended.Copies from to to. If to is too small, the buffer will be grown appropriately and
the old contents copied to, before the new contents are appended.
Copies
from to to. If to is too small, the buffer will be grown appropriately and
the old contents copied over, before the new contents are appended.Appends ‘\0’ at the end of the buffer.
Copies from to to while converting bytes via the passed in lookup table.
If to is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be
returned. to->len will contain its original size plus the amount of data actually copied to to.
Concatenates a variable number of struct aws_byte_buf * into destination.
Number of args must be greater than 1. If dest is too small,
AWS_ERROR_DEST_COPY_TOO_SMALL will be returned. dest->len will contain the
amount of data actually copied to dest.
Equivalent to calling aws_byte_buf_secure_zero and then aws_byte_buf_clean_up
on the buffer.
Compare two aws_byte_buf structures.
Return whether their contents are equivalent.
Compare an aws_byte_buf and a null-terminated string.
Returns true if their contents are equivalent.
The buffer should NOT contain a null-terminator, or the comparison will always return false.
Perform a case-insensitive string comparison of an aws_byte_buf and a null-terminated string.
Return whether their contents are equivalent.
The buffer should NOT contain a null-terminator, or the comparison will always return false.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Perform a case-insensitive string comparison of two aws_byte_buf structures.
Return whether their contents are equivalent.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
For creating a byte buffer from a null-terminated string literal.
Init buffer with contents of multiple cursors, and update cursors to reference the memory stored in the buffer.
Each cursor arg must be an
struct aws_byte_cursor *. NULL must be passed as the final arg.
NOTE: Do not append/grow/resize buffers initialized this way, or the cursors will end up referencing invalid memory.
Returns AWS_OP_SUCCESS in case of success.
AWS_OP_ERR is returned if memory can’t be allocated or the total cursor length exceeds SIZE_MAX.Initializes an aws_byte_buf structure base on another valid one.
Requires: *src and *allocator are valid objects.
Ensures: *dest is a valid aws_byte_buf with a new backing array dest->buffer
which is a copy of the elements from src->buffer.
Copies src buffer into dest and sets the correct len and capacity.
A new memory zone is allocated for dest->buffer. When dest is no longer needed it will have to be cleaned-up using
aws_byte_buf_clean_up(dest).
Dest capacity and len will be equal to the src len. Allocator of the dest will be identical with parameter allocator.
If src buffer is null the dest will have a null buffer with a len and a capacity of 0
Returns AWS_OP_SUCCESS in case of success or AWS_OP_ERR when memory can’t be allocated.
Reads ‘filename’ into ‘out_buf’. If successful, ‘out_buf’ is allocated and filled with the data;
It is your responsibility to call ‘aws_byte_buf_clean_up()’ on it. Otherwise, ‘out_buf’ remains
unused. In the very unfortunate case where some API needs to treat out_buf as a c_string, a null terminator
is appended, but is not included as part of the length field.
Evaluates the set of properties that define the shape of all valid aws_byte_buf structures.
It is also a cheap check, in the sense it run in constant time (i.e., no loops or recursion).
Attempts to increase the capacity of a buffer to the requested capacity
Convenience function that attempts to increase the capacity of a buffer relative to the current
length.
Resets the len of the buffer to 0, but does not free the memory. The buffer can then be reused.
Optionally zeroes the contents, if the “zero_contents” flag is true.
Sets all bytes of buffer to zero and resets len to zero.
Write specified number of bytes from array to byte buffer.
Writes a 16-bit integer in network byte order (big endian) to buffer.
Writes low 24-bits (3 bytes) of an unsigned integer in network byte order (big endian) to buffer.
Ex: If x is 0x00AABBCC then {0xAA, 0xBB, 0xCC} is written to buffer.
Writes a 32-bit integer in network byte order (big endian) to buffer.
Writes a 64-bit integer in network byte order (big endian) to buffer.
Writes a 32-bit float in network byte order (big endian) to buffer.
Writes a 64-bit float in network byte order (big endian) to buffer.
Copies all bytes from buffer to buffer.
Copies all bytes from buffer to buffer.
Without increasing buf’s capacity, write as much as possible from advancing_cursor into buf.
Copies one byte to buffer.
Writes one byte repeatedly to buffer (like memset)
Tests if the given aws_byte_cursor has at least len bytes remaining. If so,
*buf is advanced by len bytes (incrementing ->ptr and decrementing ->len),
and an aws_byte_cursor referring to the first len bytes of the original *buf
is returned. Otherwise, an aws_byte_cursor with ->ptr = NULL, ->len = 0 is
returned.
Behaves identically to aws_byte_cursor_advance, but avoids speculative
execution potentially reading out-of-bounds pointers (by returning an
empty ptr in such speculated paths).
Lexical (byte value) comparison of two byte cursors
Lexical (byte value) comparison of two byte cursors where the raw values are sent through a lookup table first
Compare two aws_byte_cursor structures.
Return whether their contents are equivalent.
Compare an aws_byte_cursor and an aws_byte_buf.
Return whether their contents are equivalent.
Perform a case-insensitive string comparison of an aws_byte_cursor and an aws_byte_buf.
Return whether their contents are equivalent.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Compare an aws_byte_cursor and a null-terminated string.
Returns true if their contents are equivalent.
The cursor should NOT contain a null-terminator, or the comparison will always return false.
Perform a case-insensitive string comparison of an aws_byte_cursor and a null-terminated string.
Return whether their contents are equivalent.
The cursor should NOT contain a null-terminator, or the comparison will always return false.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Perform a case-insensitive string comparison of two aws_byte_cursor structures.
Return whether their contents are equivalent.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Search for an exact byte match inside a cursor. The first match will be returned. Returns AWS_OP_SUCCESS
on successful match and first_find will be set to the offset in input_str, and length will be the remaining length
from input_str past the returned offset. If the match was not found, AWS_OP_ERR will be returned and
AWS_ERROR_STRING_MATCH_NOT_FOUND will be raised.
Evaluates the set of properties that define the shape of all valid aws_byte_cursor structures.
It is also a cheap check, in the sense it runs in constant time (i.e., no loops or recursion).
Shrinks a byte cursor from the left for as long as the supplied predicate is true
No copies, no buffer allocations. Iterates over input_str, and returns the
next substring between split_on instances relative to previous substr.
Behaves similar to strtok with substr being used as state for next split.
Reads specified length of data from byte cursor and copies it to the
destination array.
Reads as many bytes from cursor as size of buffer, and copies them to buffer.
Reads a 16-bit value in network byte order from cur, and places it in host
byte order into var.
Reads an unsigned 24-bit value (3 bytes) in network byte order from cur,
and places it in host byte order into 32-bit var.
Ex: if cur’s next 3 bytes are {0xAA, 0xBB, 0xCC}, then var becomes 0x00AABBCC.
Reads a 32-bit value in network byte order from cur, and places it in host
byte order into var.
Reads a 64-bit value in network byte order from cur, and places it in host
byte order into var.
Reads a 32-bit value in network byte order from cur, and places it in host
byte order into var.
Reads a 64-bit value in network byte order from cur, and places it in host
byte order into var.
Reads 2 hex characters from ASCII/UTF-8 text to produce an 8-bit number.
Accepts both lowercase ‘a’-‘f’ and uppercase ‘A’-‘F’.
For example: “0F” produces 15.
Reads a single byte from cursor, placing it in *var.
Shrinks a byte cursor from the right for as long as the supplied predicate is true
Returns true if the byte cursor’s range of bytes all satisfy the predicate
No copies, no buffer allocations. Fills in output with a list of
aws_byte_cursor instances where buffer is an offset into the input_str and
len is the length of that string in the original buffer.
No copies, no buffer allocations. Fills in output with a list of aws_byte_cursor instances where buffer is
an offset into the input_str and len is the length of that string in the original buffer. N is the max number of
splits, if this value is zero, it will add all splits to the output.
Return true if the input starts with the prefix (exact byte comparison).
Return true if the input starts with the prefix (case-insensitive).
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Shrinks a byte cursor from both sides for as long as the supplied predicate is true
Read entire cursor as ASCII/UTF-8 unsigned base-10 number.
Stricter than strtoull(), which allows whitespace and inputs that start with “0x”
Read entire cursor as ASCII/UTF-8 unsigned base-16 number with NO “0x” prefix.
Shuts down the internal datastructures used by aws-c-common.
Initializes internal datastructures used by aws-c-common.
Must be called before using any functionality in aws-c-common.
Returns an instance of system default thread options.
Get the curve name from the oid. OID here is the payload of the DER encoded ASN.1 part (doesn’t include
type specifier or length. On success, the value of curve_name will be set.
Creates an Elliptic curve public key from x and y coordinates encoded as hex strings
Returns a new instance of aws_ecc_key_pair if the key was successfully built.
Otherwise returns NULL.
Adds one to an ecc key pair’s ref count.
Derives a public key from the private key if supported by this operating system (not supported on OSX).
key_pair::pub_x and key_pair::pub_y will be set with the raw key buffers.
Creates a Eliptic Curve public/private key pair from a DER encoded key pair.
Returns a new instance of aws_ecc_key_pair if the key was successfully built.
Otherwise returns NULL. Whether or not signing or verification can be perform depends
on if encoded_keys is a public/private pair or a public key.
Creates a Eliptic Curve private key that can be used for signing.
Returns a new instance of aws_ecc_key_pair if the key was successfully built.
Otherwise returns NULL. Note: priv_key::len must match the appropriate length
for the selected curve_name.
Creates a Eliptic Curve public key that can be used for verifying.
Returns a new instance of aws_ecc_key_pair if the key was successfully built.
Otherwise returns NULL. Note: public_key_x::len and public_key_y::len must
match the appropriate length for the selected curve_name.
Creates a Eliptic Curve public/private key pair that can be used for signing and verifying.
Returns a new instance of aws_ecc_key_pair if the key was successfully built.
Otherwise returns NULL.
Subtracts one from an ecc key pair’s ref count. If ref count reaches zero, the key pair is destroyed.
Uses the key_pair’s private key to sign message. The output will be in signature. Signature must be large enough
to hold the signature. Check aws_ecc_key_pair_signature_length() for the appropriate size. Signature will be DER
encoded.
Uses the key_pair’s public key to verify signature of message. Signature should be DER
encoded.
Get the DER encoded OID from the curve_name. The OID in this case will not contain the type or the length specifier.
Case-insensitive hash function for array containing ASCII or UTF-8 text.
Case-insensitive hash function for aws_byte_cursors stored in an aws_hash_table.
For case-sensitive hashing, use aws_hash_byte_cursor_ptr().
Cleans up and deallocates hash.
Completes the hash computation and writes the final digest to output.
Allocation of output is the caller’s responsibility. If you specify
truncate_to to something other than 0, the output will be truncated to that
number of bytes. For example, if you want a SHA256 digest as the first 16
bytes, set truncate_to to 16. If you want the full digest size, just set this
to 0.
Updates the running hash with to_hash. this can be called multiple times.
Cleans up and deallocates hmac.
Completes the hmac computation and writes the final digest to output.
Allocation of output is the caller’s responsibility. If you specify
truncate_to to something other than 0, the output will be truncated to that
number of bytes. For example if you want a SHA256 digest as the first 16
bytes, set truncate_to to 16. If you want the full digest size, just set this
to 0.
Updates the running hmac with to_hash. this can be called multiple times.
Like isalnum(), but ignores C locale.
Returns true if ch has the value of ASCII/UTF-8: ‘a’-‘z’, ‘A’-‘Z’, or ‘0’-‘9’.
Like isalpha(), but ignores C locale.
Returns true if ch has the value of ASCII/UTF-8: ‘a’-‘z’ or ‘A’-‘Z’.
Like isdigit().
Returns true if ch has the value of ASCII/UTF-8: ‘0’-‘9’.
Like isspace(), but ignores C locale.
Return true if ch has the value of ASCII/UTF-8: space (0x20), form feed (0x0C),
line feed (0x0A), carriage return (0x0D), horizontal tab (0x09), or vertical tab (0x0B).
Like isxdigit().
Returns true if ch has the value of ASCII/UTF-8: ‘0’-‘9’, ‘a’-‘f’, or ‘A’-‘F’.
Converts a log level to a c-string constant. Intended primarily to support building log lines that
include the level in them, i.e.
Get subject name from log subject.
Cleans up all resources used by the logger; simply invokes the clean_up v-function
Gets the aws logger used globally across the process.
Gets the aws logger used globally across the process if the logging level is at least the inputted level.
Sets the aws logger used globally across the process. Not thread-safe. Must only be called once.
Sets the current logging level for the logger. Loggers are not require to support this.
@param logger logger to set the log level for
@param level new log level for the logger
@return AWS_OP_SUCCESS if the level was successfully set, AWS_OP_ERR otherwise
Returns lookup table to go from ASCII/UTF-8 hex character to a number (0-15).
Non-hex characters map to 255.
Valid examples:
‘0’ -> 0
‘F’ -> 15
‘f’ -> 15
Invalid examples:
’ ’ -> 255
‘Z’ -> 255
‘\0’ -> 255
Returns a lookup table for bytes that is the identity transformation with the exception
of uppercase ascii characters getting replaced with lowercase characters. Used in
caseless comparisons.
Computes the md5 hash over input and writes the digest output to ‘output’.
Use this if you don’t need to stream the data you’re hashing and you can load
the entire input to hash into memory.
Allocates and initializes an md5 hash instance.
Returns at least
size of memory ready for usage. In versions v0.6.8 and prior, this function was allowed to return
NULL. In later versions, if allocator->mem_acquire() returns NULL, this function will assert and exit. To handle
conditions where OOM is not a fatal error, allocator->mem_acquire() is responsible for finding/reclaiming/running a
GC etc…before returning.Allocates many chunks of bytes into a single block. Expects to be called with alternating void ** (dest), size_t
(size). The first void ** will be set to the root of the allocation. Alignment is assumed to be sizeof(intmax_t).
Allocates a block of memory for an array of num elements, each of them size bytes long, and initializes all its bits
to zero. In versions v0.6.8 and prior, this function was allowed to return NULL.
In later versions, if allocator->mem_calloc() returns NULL, this function will assert and exit. To handle
conditions where OOM is not a fatal error, allocator->mem_calloc() is responsible for finding/reclaiming/running a
GC etc…before returning.
Attempts to adjust the size of the pointed-to memory buffer from oldsize to
newsize. The pointer (*ptr) may be changed if the memory needs to be
reallocated.
Releases ptr back to whatever allocated it.
Nothing happens if ptr is NULL.
TODO: this needs to be a private function (wait till we have the cmake story
better before moving it though). It should be external for the purpose of
other libs we own, but customers should not be able to hit it without going
out of their way to do so.
Connects log subject strings with log subject integer values
Securely zeroes a memory buffer. This function will attempt to ensure that
the compiler will not optimize away this zeroing operation.
Set the implementation of md5 to use. If you compiled without BYO_CRYPTO,
you do not need to call this. However, if use this, we will honor it,
regardless of compile options. This may be useful for testing purposes. If
you did set BYO_CRYPTO, and you do not call this function you will
segfault.
Set the implementation of sha1 to use. If you compiled without
BYO_CRYPTO, you do not need to call this. However, if use this, we will
honor it, regardless of compile options. This may be useful for testing
purposes. If you did set BYO_CRYPTO, and you do not call this function
you will segfault.
Set the implementation of sha256 hmac to use. If you compiled without
BYO_CRYPTO, you do not need to call this. However, if use this, we will
honor it, regardless of compile options. This may be useful for testing
purposes. If you did set BYO_CRYPTO, and you do not call this function
you will segfault.
Set the implementation of sha256 to use. If you compiled without
BYO_CRYPTO, you do not need to call this. However, if use this, we will
honor it, regardless of compile options. This may be useful for testing
purposes. If you did set BYO_CRYPTO, and you do not call this function
you will segfault.
Computes the sha1 hash over input and writes the digest output to ‘output’.
Use this if you don’t need to stream the data you’re hashing and you can load
the entire input to hash into memory. If you specify truncate_to to something
other than 0, the output will be truncated to that number of bytes. For
example, if you want a SHA1 digest as the first 16 bytes, set truncate_to
to 16. If you want the full digest size, just set this to 0.
Allocates and initializes a sha1 hash instance.
Computes the sha256 hash over input and writes the digest output to ‘output’.
Use this if you don’t need to stream the data you’re hashing and you can load
the entire input to hash into memory. If you specify truncate_to to something
other than 0, the output will be truncated to that number of bytes. For
example, if you want a SHA256 digest as the first 16 bytes, set truncate_to
to 16. If you want the full digest size, just set this to 0.
Computes the sha256 hmac over input and writes the digest output to ‘output’.
Use this if you don’t need to stream the data you’re hashing and you can load
the entire input to hash into memory. If you specify truncate_to to something
other than 0, the output will be truncated to that number of bytes. For
example if you want a SHA256 HMAC digest as the first 16 bytes, set
truncate_to to 16. If you want the full digest size, just set this to 0.
Allocates and initializes a sha256 hmac instance. Secret is the key to be
used for the hmac process.
Allocates and initializes a sha256 hash instance.
Converts a c-string constant to a log level value. Uses case-insensitive comparison
and simply iterates all possibilities until a match or nothing remains. If no match
is found, AWS_OP_ERR is returned.
Cleans up the thread handle. Don’t call this on a managed thread. If you wish to join the thread, you must join
before calling this function.
Adds a callback to the chain to be called when the current thread joins.
Callbacks are called from the current thread, in the reverse order they
were added, after the thread function returns.
If not called from within an aws_thread, has no effect.
Sleeps the current thread by nanos.
Returns the thread id of the calling thread.
Decrements the count of unjoined threads in the managed thread system. Used by managed threads and
event loop threads. Additional usage requires the user to join corresponding threads themselves and
correctly increment/decrement even in the face of launch/join errors.
Gets the detach state of the thread. For example, is it safe to call join on
this thread? Has it been detached()?
Gets the id of thread
Converts an aws_thread_id_t to a c-string. For portability, aws_thread_id_t
must not be printed directly. Intended primarily to support building log
lines that include the thread id in them. The parameter
buffer must
point-to a char buffer of length bufsz == AWS_THREAD_ID_T_REPR_BUFSZ. The
thread id representation is returned in buffer.Increments the count of unjoined threads in the managed thread system. Used by managed threads and
event loop threads. Additional usage requires the user to join corresponding threads themselves and
correctly increment/decrement even in the face of launch/join errors.
Initializes a new platform specific thread object struct (not the os-level
thread itself).
Joins the calling thread to a thread instance. Returns when thread is
finished. Calling this from the associated OS thread will cause a deadlock.
Blocking call that waits for all managed threads to complete their join call. This can only be called
from the main thread or a non-managed thread.
Creates an OS level thread and associates it with func. context will be passed to func when it is executed.
options will be applied to the thread if they are applicable for the platform.
Overrides how long, in nanoseconds, that aws_thread_join_all_managed will wait for threads to complete.
A value of zero will result in an unbounded wait.
Compare thread ids.
Convert a c library io error into an aws error.
Disconnects log subject strings with log subject integer values
Type Definitions
Prototype for a comparator function for sorting elements.
Signature for function argument to trim APIs
Controls what log calls pass through the logger and what log calls get filtered out.
If a log level has a value of X, then all log calls using a level <= X will appear, while
those using a value > X will not occur.
Log subject is a way of designating the topic of logging.
@deprecated Use int64_t instead for offsets in public APIs.
Specifies the join strategy used on an aws_thread, which in turn controls whether or not a thread participates
in the managed thread system. The managed thread system provides logic to guarantee a join on all participating
threads at the cost of laziness (the user cannot control when joins happen).