Low-level cryptographic APIs

Data Structures
struct	aws_cryptosdk_alg_properties

Functions
const struct aws_cryptosdk_alg_properties *	aws_cryptosdk_alg_props (enum aws_cryptosdk_alg_id alg_id)
bool	aws_cryptosdk_alg_properties_is_valid (const struct aws_cryptosdk_alg_properties *const alg_props)
bool	aws_cryptosdk_sig_ctx_is_valid (const struct aws_cryptosdk_sig_ctx *sig_ctx)
int	aws_cryptosdk_sig_get_privkey (const struct aws_cryptosdk_sig_ctx *ctx, struct aws_allocator *alloc, struct aws_string **priv_key_buf)
int	aws_cryptosdk_sig_get_pubkey (const struct aws_cryptosdk_sig_ctx *ctx, struct aws_allocator *alloc, struct aws_string **pub_key_buf)
int	aws_cryptosdk_sig_sign_start_keygen (struct aws_cryptosdk_sig_ctx **ctx, struct aws_allocator *alloc, struct aws_string **pub_key_buf, const struct aws_cryptosdk_alg_properties *props)
int	aws_cryptosdk_sig_sign_start (struct aws_cryptosdk_sig_ctx **ctx, struct aws_allocator *alloc, struct aws_string **pub_key_buf, const struct aws_cryptosdk_alg_properties *props, const struct aws_string *priv_key)
int	aws_cryptosdk_sig_verify_start (struct aws_cryptosdk_sig_ctx **ctx, struct aws_allocator *alloc, const struct aws_string *pub_key, const struct aws_cryptosdk_alg_properties *props)
int	aws_cryptosdk_sig_update (struct aws_cryptosdk_sig_ctx *ctx, const struct aws_byte_cursor buf)
int	aws_cryptosdk_sig_verify_finish (struct aws_cryptosdk_sig_ctx *ctx, const struct aws_string *signature)
int	aws_cryptosdk_sig_sign_finish (struct aws_cryptosdk_sig_ctx *ctx, struct aws_allocator *alloc, struct aws_string **signature)
void	aws_cryptosdk_sig_abort (struct aws_cryptosdk_sig_ctx *ctx)

Detailed Description

These low-level cryptographic APIs should normally only be used by developers of keyrings or CMMs.

Function Documentation

aws_cryptosdk_alg_properties_is_valid()

bool aws_cryptosdk_alg_properties_is_valid

(

const struct aws_cryptosdk_alg_properties *const

alg_props

)

Checks whether an aws_cryptosdk_alg_properties is valid and supported by the SDK.

aws_cryptosdk_alg_props()

const struct aws_cryptosdk_alg_properties * aws_cryptosdk_alg_props

(

enum aws_cryptosdk_alg_id

alg_id

)

Looks up and returns the algorithm properties for a particular algorithm ID.

Returns

the algorithm properties, or NULL if alg_id is unknown

aws_cryptosdk_sig_abort()

void aws_cryptosdk_sig_abort

(

struct aws_cryptosdk_sig_ctx *

ctx

)

Aborts an ongoing sign or verify operation, and destroys the signature context. If ctx is null, this operation is a no-op.

aws_cryptosdk_sig_ctx_is_valid()

bool aws_cryptosdk_sig_ctx_is_valid

(

const struct aws_cryptosdk_sig_ctx *

sig_ctx

)

Performs basic validity checks for the signing context (e.g. that member pointers are not NULL).

aws_cryptosdk_sig_get_privkey()

int aws_cryptosdk_sig_get_privkey	(	const struct aws_cryptosdk_sig_ctx *	ctx,
		struct aws_allocator *	alloc,
		struct aws_string **	priv_key_buf )

Obtains the private key from a signing context, and serializes it to a byte buffer. The serialization format is not currently guaranteed to remain unchanged.

This method is intended to be used with caching mechanisms to clone the signing context.

aws_cryptosdk_sig_get_pubkey()

int aws_cryptosdk_sig_get_pubkey	(	const struct aws_cryptosdk_sig_ctx *	ctx,
		struct aws_allocator *	alloc,
		struct aws_string **	pub_key_buf )

Obtains the public key from a signing context, which may be in either sign or verify mode, and serializes it to a byte buffer.

This method is intended to be used with caching mechanisms to clone a verification context.

aws_cryptosdk_sig_sign_finish()

int aws_cryptosdk_sig_sign_finish	(	struct aws_cryptosdk_sig_ctx *	ctx,
		struct aws_allocator *	alloc,
		struct aws_string **	signature )

Generates the final signature based on data previously passed to aws_cryptosdk_sig_update. The signature buffer will be allocated using 'alloc'.

The context must have been created in verify mode, using aws_cryptosdk_sig_sign_start[_keygen]; failing to do so results in undefined behavior.

The context is always freed, regardless of success or failure.

aws_cryptosdk_sig_sign_start()

int aws_cryptosdk_sig_sign_start	(	struct aws_cryptosdk_sig_ctx **	ctx,
		struct aws_allocator *	alloc,
		struct aws_string **	pub_key_buf,
		const struct aws_cryptosdk_alg_properties *	props,
		const struct aws_string *	priv_key )

Initializes a new signature context based on a private key serialized using aws_cryptosdk_sig_get_privkey.

Parameters

ctx	a pointer to a variable to receive the signing context
alloc	the allocator to use
pub_key_buf	a pointer to a buffer that will receive the base-64 public key, or NULL if not required
props	algorithm properties for the algorithm suite in use
priv_key	the previously serialized private key

aws_cryptosdk_sig_sign_start_keygen()

int aws_cryptosdk_sig_sign_start_keygen	(	struct aws_cryptosdk_sig_ctx **	ctx,
		struct aws_allocator *	alloc,
		struct aws_string **	pub_key_buf,
		const struct aws_cryptosdk_alg_properties *	props )

Generates a new signature keypair, initializes a signing context, and serializes the public key. If a non-signing algorithm is used, this function returns successfully, sets *ctx to NULL, and zeroes pub_key_buf.

Parameters

ctx	- a pointer to a variable to receive the context pointer
alloc	- the allocator to use
pub_key_buf	- A buffer that will receive the public key (in base64 format). This buffer will be allocated as part of this call, and does not need to be pre-initialized.
props	- The algorithm properties for the algorithm to use

aws_cryptosdk_sig_update()

int aws_cryptosdk_sig_update	(	struct aws_cryptosdk_sig_ctx *	ctx,
		const struct aws_byte_cursor	buf )

Supplies some data to an ongoing sign or verify operation.

aws_cryptosdk_sig_verify_finish()

int aws_cryptosdk_sig_verify_finish	(	struct aws_cryptosdk_sig_ctx *	ctx,
		const struct aws_string *	signature )

Verifies a signature against the data previously passed to aws_cryptosdk_sig_update. If successful, this function returns AWS_OP_SUCCESS; if the signature was invalid, raises AWS_CRYPTOSDK_ERR_BAD_CIPHERTEXT and returns AWS_OP_ERR.

The context must have been created in verify mode, using aws_cryptosdk_sig_verify_start; failing to do so results in undefined behavior.

The context is always freed, regardless of success or failure.

aws_cryptosdk_sig_verify_start()

int aws_cryptosdk_sig_verify_start	(	struct aws_cryptosdk_sig_ctx **	ctx,
		struct aws_allocator *	alloc,
		const struct aws_string *	pub_key,
		const struct aws_cryptosdk_alg_properties *	props )

Prepares to validate a signature. If a non-signing algorithm is used, this function returns successfully, and sets *ctx to NULL.

Parameters

ctx	a pointer to a variable to receive the context pointer
alloc	the allocator to use
pub_key	A buffer containing the (base64) public key
props	The algorithm properties for the algorithm to use