materials.h

Go to the documentation of this file.

/*
 * Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"). You may not use
 * this file except in compliance with the License. A copy of the License is
 * located at
 *
 *     http://aws.amazon.com/apache2.0/
 *
 * or in the "license" file accompanying this file. This file is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
 * implied. See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef AWS_CRYPTOSDK_MATERIALS_H
#define AWS_CRYPTOSDK_MATERIALS_H
 
#include <assert.h>
#include <limits.h>
#include <stdint.h>
 
#include <aws/common/array_list.h>
#include <aws/common/atomics.h>
#include <aws/common/byte_buf.h>
#include <aws/common/common.h>
#include <aws/common/hash_table.h>
 
#include <aws/cryptosdk/cipher.h>
#include <aws/cryptosdk/edk.h>
#include <aws/cryptosdk/error.h>
#include <aws/cryptosdk/exports.h>
#include <aws/cryptosdk/header.h>
#include <aws/cryptosdk/keyring_trace.h>
 
#ifdef __cplusplus
extern "C" {
#endif


 
// Note: Most of this file will be in the low-level section.
// To move something to the high-level section, use @ingroup cmm_kr_highlevel

struct aws_cryptosdk_cmm {
    struct aws_atomic_var refcount;
    const struct aws_cryptosdk_cmm_vt *vtable;
};

struct aws_cryptosdk_keyring {
    struct aws_atomic_var refcount;
    const struct aws_cryptosdk_keyring_vt *vtable;
};

enum aws_cryptosdk_commitment_policy {
    COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT = 0x598f396c,

    COMMITMENT_POLICY_REQUIRE_ENCRYPT_ALLOW_DECRYPT = 0x493769b7,

    COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT = 0x2735f98a,
};

struct aws_cryptosdk_enc_request {
    struct aws_allocator *alloc;
    struct aws_hash_table *enc_ctx;
    enum aws_cryptosdk_alg_id requested_alg;
    uint64_t plaintext_size;
    enum aws_cryptosdk_commitment_policy commitment_policy;
};
 
AWS_CRYPTOSDK_STATIC_INLINE bool aws_cryptosdk_enc_request_is_valid(const struct aws_cryptosdk_enc_request *request) {
    return request && aws_allocator_is_valid(request->alloc) && aws_hash_table_is_valid(request->enc_ctx);
}

struct aws_cryptosdk_enc_materials {
    struct aws_allocator *alloc;
    struct aws_byte_buf unencrypted_data_key;
    struct aws_array_list keyring_trace;
    struct aws_array_list encrypted_data_keys;
    struct aws_cryptosdk_sig_ctx *signctx;
    enum aws_cryptosdk_alg_id alg;
};

struct aws_cryptosdk_dec_request {
    struct aws_allocator *alloc;
    const struct aws_hash_table *enc_ctx;
    struct aws_array_list encrypted_data_keys;
    enum aws_cryptosdk_alg_id alg;
};
 
AWS_CRYPTOSDK_STATIC_INLINE bool aws_cryptosdk_dec_request_is_valid(const struct aws_cryptosdk_dec_request *request) {
    return request && aws_allocator_is_valid(request->alloc) &&
           aws_cryptosdk_edk_list_is_valid(&request->encrypted_data_keys) && aws_hash_table_is_valid(request->enc_ctx);
}

struct aws_cryptosdk_dec_materials {
    struct aws_allocator *alloc;
    struct aws_byte_buf unencrypted_data_key;
    struct aws_array_list keyring_trace;
    struct aws_cryptosdk_sig_ctx *signctx;
    enum aws_cryptosdk_alg_id alg;
};
 
AWS_CRYPTOSDK_STATIC_INLINE bool aws_cryptosdk_enc_materials_is_valid(
    const struct aws_cryptosdk_enc_materials *materials) {
    if (!AWS_OBJECT_PTR_IS_WRITABLE(materials)) {
        return false;
    }
    bool allocator_valid            = aws_allocator_is_valid(materials->alloc);
    bool unencrypted_data_key_valid = aws_byte_buf_is_valid(&materials->unencrypted_data_key);
    bool keyring_trace_valid        = aws_cryptosdk_keyring_trace_is_valid(&materials->keyring_trace);
    bool encrypted_data_keys_valid  = aws_cryptosdk_edk_list_is_valid(&materials->encrypted_data_keys);
    bool signctx_valid = (materials->signctx == NULL) || aws_cryptosdk_sig_ctx_is_valid(materials->signctx);
    return allocator_valid && unencrypted_data_key_valid && keyring_trace_valid && encrypted_data_keys_valid &&
           signctx_valid;
}
 
AWS_CRYPTOSDK_STATIC_INLINE bool aws_cryptosdk_dec_materials_is_valid(
    const struct aws_cryptosdk_dec_materials *materials) {
    if (!AWS_OBJECT_PTR_IS_WRITABLE(materials)) {
        return false;
    }
    bool allocator_valid            = aws_allocator_is_valid(materials->alloc);
    bool unencrypted_data_key_valid = aws_byte_buf_is_valid(&materials->unencrypted_data_key);
    bool keyring_trace_valid        = aws_cryptosdk_keyring_trace_is_valid(&materials->keyring_trace);
    bool signctx_valid = (materials->signctx == NULL) || aws_cryptosdk_sig_ctx_is_valid(materials->signctx);
    return allocator_valid && unencrypted_data_key_valid && keyring_trace_valid && signctx_valid;
}
 
#ifndef AWS_CRYPTOSDK_DOXYGEN /* do not document internal macros */
 
/*
 * C99 standard dictates that "..." must have at least one argument behind it. Second arg of
 * _VF_CALL macros is always struct type, i.e., "cmm" or "keyring". These helper macros allow
 * us not to make struct_type a named argument, thus handling the case cleanly where there
 * are no more arguments.
 *
 * Note: We work around a VC++ preprocessor bug here. See https://stackoverflow.com/a/4750720
 */
#    define AWS_CRYPTOSDK_PRIVATE_STRUCT_NAME(...) AWS_CRYPTOSDK_PRIVATE_STRUCT_NAME_2((__VA_ARGS__, throwaway))
#    define AWS_CRYPTOSDK_PRIVATE_STRUCT_NAME_2(args) AWS_CRYPTOSDK_PRIVATE_STRUCT_NAME_3 args
#    define AWS_CRYPTOSDK_PRIVATE_STRUCT_NAME_3(struct_type, ...) struct_type
 
#    define AWS_CRYPTOSDK_PRIVATE_BASE_TYPE(...) AWS_CRYPTOSDK_PRIVATE_BASE_TYPE_2((__VA_ARGS__, throwaway))
#    define AWS_CRYPTOSDK_PRIVATE_BASE_TYPE_2(args) AWS_CRYPTOSDK_PRIVATE_BASE_TYPE_3 args
#    define AWS_CRYPTOSDK_PRIVATE_BASE_TYPE_3(struct_type, ...) const struct aws_cryptosdk_##struct_type

#    define AWS_CRYPTOSDK_PRIVATE_VF_CALL(fn_name, ...)                                                          \
        int ret;                                                                                                 \
        do {                                                                                                     \
            AWS_CRYPTOSDK_PRIVATE_BASE_TYPE(__VA_ARGS__) *pbase =                                                \
                (AWS_CRYPTOSDK_PRIVATE_BASE_TYPE(__VA_ARGS__) *)AWS_CRYPTOSDK_PRIVATE_STRUCT_NAME(__VA_ARGS__);  \
            ptrdiff_t memb_offset = (const uint8_t *)&(pbase->vtable)->fn_name - (const uint8_t *)pbase->vtable; \
            if (memb_offset + sizeof((pbase->vtable)->fn_name) > (pbase->vtable)->vt_size ||                     \
                !(pbase->vtable)->fn_name) {                                                                     \
                return aws_raise_error(AWS_ERROR_UNIMPLEMENTED);                                                 \
            }                                                                                                    \
            ret = (pbase->vtable)->fn_name(__VA_ARGS__);                                                         \
        } while (0)

#    define AWS_CRYPTOSDK_PRIVATE_VF_CALL_NO_RETURN(fn_name, ...)                                                \
        do {                                                                                                     \
            AWS_CRYPTOSDK_PRIVATE_BASE_TYPE(__VA_ARGS__) *pbase =                                                \
                (AWS_CRYPTOSDK_PRIVATE_BASE_TYPE(__VA_ARGS__) *)AWS_CRYPTOSDK_PRIVATE_STRUCT_NAME(__VA_ARGS__);  \
            ptrdiff_t memb_offset = (const uint8_t *)&(pbase->vtable)->fn_name - (const uint8_t *)pbase->vtable; \
            if (memb_offset + sizeof((pbase->vtable)->fn_name) > (pbase->vtable)->vt_size ||                     \
                !(pbase->vtable)->fn_name) {                                                                     \
                aws_raise_error(AWS_ERROR_UNIMPLEMENTED);                                                        \
            } else {                                                                                             \
                (pbase->vtable)->fn_name(__VA_ARGS__);                                                           \
            }                                                                                                    \
        } while (0)

AWS_CRYPTOSDK_STATIC_INLINE bool aws_cryptosdk_private_refcount_down(struct aws_atomic_var *refcount) {
    /*
     * Memory ordering note: We must use release_acquire memory order here. Otherwise, we have the following race:
     *
     * Program order:
     *
     * Thread A:
     *   Release(obj) [if down() { free(obj) } ]
     *
     * Thread B:
     *   obj->foo = 1;
     *   Release(obj)
     *
     * Execution order:
     *
     * Thread B: down() -> false
     * Thread A: down() -> true
     * Thread A: free(obj)
     * Thread B: obj->foo = 1
     *
     * To prevent this we use release_acquire order. The release forbids any memory accesses sequenced-before the
     * atomic decrement of down() from being reordered later. This prevents thread B from reordering the obj->foo
     * access to come after the down(). The acquire ensures that the atomic decrements of down() calls correctly
     * synchronize-with one-another.
     */
    size_t old_count = aws_atomic_fetch_sub_explicit(refcount, 1, aws_memory_order_acq_rel);
 
    assert(old_count != 0);
 
    return old_count == 1;
}

AWS_CRYPTOSDK_STATIC_INLINE void aws_cryptosdk_private_refcount_up(struct aws_atomic_var *refcount) {
    /*
     * Memory ordering note: It is safe to use relaxed here. As an invariant, we assume that,
     * on entry, the thread has some guarantee that the refcount will not reach zero until after
     * refcount_up completes. As long as this guarantee is maintained until the next release barrier,
     * there is no problem; if we down() on the current thread, we achieve this explicitly. Otherwise,
     * if we communicate to some other thread that it is safe to release the reference, that communication
     * needs to be in release order, as it's effectively a proxy down() call, for the same reasons outlined
     * above in refcount_down().
     *
     * Since we've established that our initial reference won't be released until a release barrier
     * occurs, we are happy to let the increment be deferred until that barrier occurs. We're also
     * perfectly happy with a refcount increment happening logically earlier than expected, since this
     * won't cause the object to be freed unexpectedly.
     *
     * We also note that acquire order is not required: We know that the object itself is already valid
     * when we enter refcount_up - that is, refcount_up does not change the internal state of the object.
     * Therefore, it's okay if some code accesses the logical state of the object "before" the refcount
     * increment, so long as the object is not actually freed.
     */
    size_t old_count = aws_atomic_fetch_add_explicit(refcount, 1, aws_memory_order_relaxed);
 
    assert(old_count != 0 && old_count != SIZE_MAX);
 
    // Suppress unused variable warning when NDEBUG is set
    (void)old_count;
}
#endif  // AWS_CRYPTOSDK_DOXYGEN

struct aws_cryptosdk_cmm_vt {
    size_t vt_size;
    const char *name;
    void (*destroy)(struct aws_cryptosdk_cmm *cmm);

    int (*generate_enc_materials)(
        struct aws_cryptosdk_cmm *cmm,
        struct aws_cryptosdk_enc_materials **output,
        struct aws_cryptosdk_enc_request *request);
    int (*decrypt_materials)(
        struct aws_cryptosdk_cmm *cmm,
        struct aws_cryptosdk_dec_materials **output,
        struct aws_cryptosdk_dec_request *request);
};

AWS_CRYPTOSDK_STATIC_INLINE bool aws_atomic_var_is_valid_int(const struct aws_atomic_var *var) {
    return AWS_MEM_IS_WRITABLE(var, sizeof(size_t));
}

AWS_CRYPTOSDK_STATIC_INLINE bool aws_atomic_var_is_valid_ptr(const struct aws_atomic_var *var) {
    return AWS_OBJECT_PTR_IS_WRITABLE(var) && AWS_OBJECT_PTR_IS_WRITABLE((size_t *)aws_atomic_load_ptr(var));
}

AWS_CRYPTOSDK_STATIC_INLINE bool aws_cryptosdk_cmm_vtable_is_valid(const struct aws_cryptosdk_cmm_vt *vtable) {
    return AWS_OBJECT_PTR_IS_READABLE(vtable) && vtable->vt_size == sizeof(struct aws_cryptosdk_cmm_vt) &&
           aws_c_string_is_valid(vtable->name);
}

AWS_CRYPTOSDK_STATIC_INLINE bool aws_cryptosdk_cmm_base_is_valid(const struct aws_cryptosdk_cmm *cmm) {
    return AWS_OBJECT_PTR_IS_WRITABLE(cmm) && aws_atomic_var_is_valid_int(&cmm->refcount) &&
           aws_atomic_load_int(&cmm->refcount) > 0 && aws_atomic_load_int(&cmm->refcount) <= SIZE_MAX &&
           aws_cryptosdk_cmm_vtable_is_valid(cmm->vtable);
}

AWS_CRYPTOSDK_STATIC_INLINE void aws_cryptosdk_cmm_base_init(
    struct aws_cryptosdk_cmm *cmm, const struct aws_cryptosdk_cmm_vt *vtable) {
    AWS_PRECONDITION(AWS_OBJECT_PTR_IS_WRITABLE(cmm));
    AWS_PRECONDITION(aws_cryptosdk_cmm_vtable_is_valid(vtable));
    cmm->vtable = vtable;
    aws_atomic_init_int(&cmm->refcount, 1);
    AWS_POSTCONDITION(aws_cryptosdk_cmm_base_is_valid(cmm));
}

AWS_CRYPTOSDK_STATIC_INLINE void aws_cryptosdk_cmm_release(struct aws_cryptosdk_cmm *cmm) {
    AWS_PRECONDITION(!cmm || aws_cryptosdk_cmm_base_is_valid(cmm));
    if (cmm && aws_cryptosdk_private_refcount_down(&cmm->refcount)) {
        AWS_CRYPTOSDK_PRIVATE_VF_CALL_NO_RETURN(destroy, cmm);
    }
}

AWS_CRYPTOSDK_STATIC_INLINE struct aws_cryptosdk_cmm *aws_cryptosdk_cmm_retain(struct aws_cryptosdk_cmm *cmm) {
    AWS_PRECONDITION(aws_cryptosdk_cmm_base_is_valid(cmm));
    AWS_PRECONDITION(aws_atomic_load_int(&cmm->refcount) < SIZE_MAX);
    aws_cryptosdk_private_refcount_up(&cmm->refcount);
    AWS_POSTCONDITION(aws_cryptosdk_cmm_base_is_valid(cmm));
    return cmm;
}

AWS_CRYPTOSDK_STATIC_INLINE int aws_cryptosdk_cmm_generate_enc_materials(
    struct aws_cryptosdk_cmm *cmm,
    struct aws_cryptosdk_enc_materials **output,
    struct aws_cryptosdk_enc_request *request) {
    if (output) {
        *output = NULL;
    }
    AWS_ERROR_PRECONDITION(aws_cryptosdk_cmm_base_is_valid(cmm), AWS_ERROR_UNIMPLEMENTED);
    AWS_ERROR_PRECONDITION(output == NULL || AWS_OBJECT_PTR_IS_WRITABLE(output));
    AWS_ERROR_PRECONDITION(request == NULL || aws_cryptosdk_enc_request_is_valid(request));
    AWS_CRYPTOSDK_PRIVATE_VF_CALL(generate_enc_materials, cmm, output, request);
    return ret;
}

AWS_CRYPTOSDK_STATIC_INLINE int aws_cryptosdk_cmm_decrypt_materials(
    struct aws_cryptosdk_cmm *cmm,
    struct aws_cryptosdk_dec_materials **output,
    struct aws_cryptosdk_dec_request *request) {
    if (output) {
        *output = NULL;
    }
    AWS_ERROR_PRECONDITION(aws_cryptosdk_cmm_base_is_valid(cmm), AWS_ERROR_UNIMPLEMENTED);
    AWS_ERROR_PRECONDITION(output == NULL || AWS_OBJECT_PTR_IS_WRITABLE(output));
    AWS_ERROR_PRECONDITION(request == NULL || aws_cryptosdk_dec_request_is_valid(request));
 
    AWS_CRYPTOSDK_PRIVATE_VF_CALL(decrypt_materials, cmm, output, request);
    return ret;
}
 
struct aws_cryptosdk_keyring_vt {
    size_t vt_size;
    const char *name;
    void (*destroy)(struct aws_cryptosdk_keyring *keyring);

    int (*on_encrypt)(
        struct aws_cryptosdk_keyring *keyring,
        struct aws_allocator *request_alloc,
        struct aws_byte_buf *unencrypted_data_key,
        struct aws_array_list *keyring_trace,
        struct aws_array_list *edks,
        const struct aws_hash_table *enc_ctx,
        enum aws_cryptosdk_alg_id alg);

    int (*on_decrypt)(
        struct aws_cryptosdk_keyring *keyring,
        struct aws_allocator *request_alloc,
        struct aws_byte_buf *unencrypted_data_key,
        struct aws_array_list *keyring_trace,
        const struct aws_array_list *edks,
        const struct aws_hash_table *enc_ctx,
        enum aws_cryptosdk_alg_id alg);
};

AWS_CRYPTOSDK_STATIC_INLINE bool aws_cryptosdk_keyring_vt_is_valid(const struct aws_cryptosdk_keyring_vt *vtable) {
    return AWS_OBJECT_PTR_IS_READABLE(vtable) && aws_c_string_is_valid(vtable->name) &&
           /* Always set to sizeof(struct aws_cryptosdk_keyring_vt). */
           (vtable->vt_size == sizeof(struct aws_cryptosdk_keyring_vt));
}

AWS_CRYPTOSDK_STATIC_INLINE bool aws_cryptosdk_keyring_is_valid(const struct aws_cryptosdk_keyring *keyring) {
    return AWS_OBJECT_PTR_IS_READABLE(keyring) && aws_atomic_var_is_valid_int(&keyring->refcount) &&
           (aws_atomic_load_int(&keyring->refcount) > 0) && (aws_atomic_load_int(&keyring->refcount) <= SIZE_MAX) &&
           (keyring->vtable == NULL || aws_cryptosdk_keyring_vt_is_valid(keyring->vtable));
}

AWS_CRYPTOSDK_STATIC_INLINE void aws_cryptosdk_keyring_base_init(
    struct aws_cryptosdk_keyring *keyring, const struct aws_cryptosdk_keyring_vt *vtable) {
    AWS_PRECONDITION(keyring != NULL);
    AWS_PRECONDITION(vtable == NULL || aws_cryptosdk_keyring_vt_is_valid(vtable));
    AWS_PRECONDITION(vtable == NULL || aws_c_string_is_valid(vtable->name));
    keyring->vtable = vtable;
    aws_atomic_init_int(&keyring->refcount, 1);
}

AWS_CRYPTOSDK_STATIC_INLINE void aws_cryptosdk_keyring_release(struct aws_cryptosdk_keyring *keyring) {
    AWS_PRECONDITION(!keyring || (aws_cryptosdk_keyring_is_valid(keyring) && keyring->vtable != NULL));
    if (keyring && aws_cryptosdk_private_refcount_down(&keyring->refcount)) {
        AWS_CRYPTOSDK_PRIVATE_VF_CALL_NO_RETURN(destroy, keyring);
    }
}

AWS_CRYPTOSDK_STATIC_INLINE struct aws_cryptosdk_keyring *aws_cryptosdk_keyring_retain(
    struct aws_cryptosdk_keyring *keyring) {
    AWS_PRECONDITION(aws_cryptosdk_keyring_is_valid(keyring));
    AWS_PRECONDITION(aws_atomic_var_is_valid_int(&keyring->refcount));
    AWS_PRECONDITION(aws_atomic_load_int(&keyring->refcount) < SIZE_MAX);
    aws_cryptosdk_private_refcount_up(&keyring->refcount);
    return keyring;
}

AWS_CRYPTOSDK_API
int aws_cryptosdk_keyring_on_encrypt(
    struct aws_cryptosdk_keyring *keyring,
    struct aws_allocator *request_alloc,
    struct aws_byte_buf *unencrypted_data_key,
    struct aws_array_list *keyring_trace,
    struct aws_array_list *edks,
    const struct aws_hash_table *enc_ctx,
    enum aws_cryptosdk_alg_id alg);

AWS_CRYPTOSDK_API
int aws_cryptosdk_keyring_on_decrypt(
    struct aws_cryptosdk_keyring *keyring,
    struct aws_allocator *request_alloc,
    struct aws_byte_buf *unencrypted_data_key,
    struct aws_array_list *keyring_trace,
    const struct aws_array_list *edks,
    const struct aws_hash_table *enc_ctx,
    enum aws_cryptosdk_alg_id alg);

AWS_CRYPTOSDK_API
struct aws_cryptosdk_enc_materials *aws_cryptosdk_enc_materials_new(
    struct aws_allocator *alloc, enum aws_cryptosdk_alg_id alg);

AWS_CRYPTOSDK_API
void aws_cryptosdk_enc_materials_destroy(struct aws_cryptosdk_enc_materials *enc_mat);

AWS_CRYPTOSDK_API
struct aws_cryptosdk_dec_materials *aws_cryptosdk_dec_materials_new(
    struct aws_allocator *alloc, enum aws_cryptosdk_alg_id alg);

AWS_CRYPTOSDK_API
void aws_cryptosdk_dec_materials_destroy(struct aws_cryptosdk_dec_materials *dec_mat);

AWS_CRYPTOSDK_STATIC_INLINE bool aws_cryptosdk_commitment_policy_is_valid(uint32_t commitment_policy) {
    switch (commitment_policy) {
        case COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT:
        case COMMITMENT_POLICY_REQUIRE_ENCRYPT_ALLOW_DECRYPT:
        case COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT: return true;
        default: return false;
    }
}

AWS_CRYPTOSDK_STATIC_INLINE bool aws_cryptosdk_commitment_policy_encrypt_must_include_commitment(
    enum aws_cryptosdk_commitment_policy commitment_policy) {
    switch (commitment_policy) {
        case COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT:
        case COMMITMENT_POLICY_REQUIRE_ENCRYPT_ALLOW_DECRYPT: return true;
        case COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT: return false;
        default: return false;
    }
}
 
#ifdef __cplusplus
}
#endif
  // doxygen group cmm_kr_lowlevel
 
#endif  // AWS_CRYPTOSDK_MATERIALS_H