path: root/drivers/mxc/security/sahara2/include/fsl_shw.h

/*
 * Copyright (C) 2004-2010 Freescale Semiconductor, Inc. All Rights Reserved.
 */

/*
 * The code contained herein is licensed under the GNU General Public
 * License. You may obtain a copy of the GNU General Public License
 * Version 2 or later at the following locations:
 *
 * http://www.opensource.org/licenses/gpl-license.html
 * http://www.gnu.org/copyleft/gpl.html
 */

/*
 * NOTE TO MAINTAINERS: Although this header file is *the* header file to be
 * #include'd by FSL SHW programs, it does not itself make any definitions for
 * the API.  Instead, it uses the fsl_platform.h file and / or compiler
 * environment variables to determine which actual driver header file to
 * include.  This allows different implementations to contain different
 * implementations of the various objects, macros, etc., or even to change
 * which functions are macros and which are not.
 */

/*!
 * @file fsl_shw.h
 *
 * @brief Definition of the Freescale Security Hardware API.
 *
 * See @ref index for an overview of the API.
 */

/*!
 * @if USE_MAINPAGE
 * @mainpage Common API for Freescale Security Hardware (FSL SHW API)
 * @endif
 *
 * @section intro_sec Introduction
 *
 * This is the interface definition for the Freescale Security Hardware API
 * (FSL SHW API) for User Mode and Kernel Mode to access Freescale Security
 * Hardware components for cryptographic acceleration. The API is intended to
 * provide cross-platform access to security hardware components of Freescale.
 *
 * This documentation has not been approved, and should not be taken to
 * mean anything definite about future direction.
 *
 * Some example code is provided to give some idea of usage of this API.
 *
 * Note: This first version has been defined around the capabilities of the
 * Sahara2 cryptographic accelerator, and may be expanded in the future to
 * provide support for other platforms.  The Platform Capabilities Object is
 * intended as a way to allow programs to adapt to different platforms.
 *
 * The i.MX25 is an example of a platform without a SAHARA but yet has
 * capabilities supported by this API.  These include #fsl_shw_get_random() and
 * #fsl_shw_add_entropy(), and the use of Triple-DES (TDEA) cipher algorithm
 * (with no checking of key parity supported) in ECB and CBC modes with @ref
 * sym_sec.  See also the @ref di_sec for information on key handling, and @ref
 * td_sec for detection of Tamper Events.  Only the random functions are
 * available from user space on this platform.
 *
 * @section usr_ctx The User Context
 *
 * The User Context Object (#fsl_shw_uco_t) controls the interaction between
 * the user program and the API.  It is initialized as part of user
 * registration (#fsl_shw_register_user()), and is part of every interaction
 * thereafter.
 *
 * @section pf_sec Platform Capabilities
 *
 * Since this API is not tied to one specific type of hardware or even one
 * given version of a given type of hardware, the platform capabilities object
 * could be used by a portable program to make choices about using software
 * instead of hardware for certain operations.
 *
 * See the #fsl_shw_pco_t, returned by #fsl_shw_get_capabilities().
 *
 * @ref pcoops are provided to query its contents.
 *
 *
 * @section sym_sec Symmetric-Key Encryption and Decryption
 *
 * Symmetric-Key encryption support is provided for the block cipher algorithms
 * AES, DES, and Triple DES.  Modes supported are #FSL_SYM_MODE_ECB,
 * #FSL_SYM_MODE_CBC, and #FSL_SYM_MODE_CTR, though not necessarily all modes
 * for all algorithms.  There is also support for the stream cipher algorithm
 * commonly known as ARC4.
 *
 * Encryption and decryption are performed by using the functions
 * #fsl_shw_symmetric_encrypt() and #fsl_shw_symmetric_decrypt(), respectively.
 * There are two objects which provide information about the operation of these
 * functions.  They are the #fsl_shw_sko_t, to provide key and algorithm
 * information; and the #fsl_shw_scco_t, to provide (and store) initial context
 * or counter value information.
 *
 * CCM is not supported by these functions.  For information CCM support, see
 * @ref cmb_sec.
 *
 *
 * @section hash_sec Cryptographic Hashing
 *
 * Hashing is performed by fsl_shw_hash(). Control of the function is through
 * flags in the #fsl_shw_hco_t.  The algorithms which are
 * supported are listed in #fsl_shw_hash_alg_t.
 *
 * The hashing function works on octet streams.  If a user application needs to
 * hash a bitstream, it will need to do its own padding of the last block.
 *
 *
 * @section hmac_sec Hashed Message Authentication Codes
 *
 * An HMAC is a method of combining a hash and a key so that a message cannot
 * be faked by a third party.
 *
 * The #fsl_shw_hmac() can be used by itself for one-shot or multi-step
 * operations, or in combination with #fsl_shw_hmac_precompute() to provide the
 * ability to compute and save the beginning hashes from a key one time, and
 * then use #fsl_shw_hmac() to calculate an HMAC on each message as it is
 * processed.
 *
 * The maximum key length which is directly supported by this API is 64 octets.
 * If a longer key size is needed for HMAC, the user will have to hash the key
 * and present the digest value as the key to be used by the HMAC functions.
 *
 *
 * @section rnd_sec Random Numbers
 *
 * Support is available for acquiring random values from a
 * cryptographically-strong random number generator.  See
 * #fsl_shw_get_random().  The function #fsl_shw_add_entropy() may be used to
 * add entropy to the random number generator.
 *
 *
 * @section cmb_sec Combined Cipher and Authentication
 *
 * Some schemes require that messages be encrypted and that they also have an
 * authentication code associated with the message. The function
 * #fsl_shw_gen_encrypt() will generate the authentication code and encrypt the
 * message.
 *
 * Upon receipt of such a message, the message must be decrypted and the
 * authentication code validated.  The function
 * #fsl_shw_auth_decrypt() will perform these steps.
 *
 * Only AES-CCM is supported.
 *
 *
 * @section wrap_sec Wrapped Keys
 *
 * On platforms with a Secure Memory, the function #fsl_shw_establish_key() can
 * be used to place a key into the System Keystore.  This key then can be used
 * directly by the cryptographic hardware.  It later then be wrapped
 * (cryptographically obscured) by #fsl_shw_extract_key() and stored for later
 * use.  If a software key (#FSL_SKO_KEY_SW_KEY) was established, then its
 * value can be retrieved with a call to #fsl_shw_read_key().
 *
 * The wrapping and unwrapping functions provide security against unauthorized
 * use and detection of tampering.
 *
 * The functions can also be used with a User Keystore.
 *
 * @section smalloc_sec Secure Memory Allocation
 *
 * On platforms with multiple partitions of Secure Memory, the function
 * #fsl_shw_smalloc() can be used to acquire a partition for private use.  The
 * function #fsl_shw_diminish_perms() can then be used to revoke specific
 * permissions on the partition, and #fsl_shw_sfree() can be used to release the
 * partition.
 *
 * @section keystore_sec User Keystore
 *
 * User Keystore functionality is defined in fsl_shw_keystore.h.  See @ref
 * user_keystore for details.  This is not supported on platforms without SCC2.
 *
 * @section di_sec Hardware key-select extensions - DryIce
 *
 * Some platforms have a component called DryIce which allows the software to
 * control which key will be used by the secure memory encryption hardware.
 * The choices are the secret per-chip Fused (IIM) Key, an unknown, hardware-
 * generated Random Key, a software-written Programmed Key, or the IIM Key in
 * combination with one of the others.  #fsl_shw_pco_check_pk_supported() can
 * be used to determine whether this feature is available on the platform.
 * The rest of this section will explain the symmetric ciphering and key
 * operations which are available on such a platform.
 *
 * The function #fsl_shw_sko_init_pf_key() will set up a Secret Key Object to
 * refer to one of the system's platform keys.  All keys which reference a
 * platform key must use this initialization function, including a user-
 * provided key value.  Keys which are intended for software encryption must
 * use #fsl_shw_sko_init().
 *
 * To change the setting of the Programmed Key of the DryIce module,
 * #fsl_shw_establish_key() must be called with a platform key object of type
 * #FSL_SHW_PF_KEY_PRG or #FSL_SHW_PF_KEY_IIM_PRG.  The key will be go
 * into the PK register of DryIce and not to the keystore.  Any symmetric
 * operation which references either #FSL_SHW_PF_KEY_PRG or
 * #FSL_SHW_PF_KEY_IIM_PRG will use the current PK value (possibly modified by
 * the secret fused IIM key).  Before the Flatform Key can be changed, a call to
 * #fsl_shw_release_key() or #fsl_shw_extract_key() must be made.  Neither
 * function will change the value in the PK registers, and further ciphering
 * can take place.
 *
 * When #fsl_shw_establish_key() is called to change the PK value, a plaintext
 * key can be passed in with the #FSL_KEY_WRAP_ACCEPT argument or a previously
 * wrapped key can be passed in with the #FSL_KEY_WRAP_UNWRAP argument.  If
 * #FSL_KEY_WRAP_CREATE is passed in, then a random value will be loaded into
 * the PK register.  The PK value can be wrapped by a call to
 * #fsl_shw_extract_key() for later use with the #FSL_KEY_WRAP_UNWRAP argument.
 *
 * As an alternative to using only the fused key for @ref wrap_sec,
 * #fsl_shw_uco_set_wrap_key() can be used to select either the random key or
 * the random key with the fused key as the key which will be used to protect
 * the one-time value used to wrap the key.  This allows for these
 * wrapped keys to be dependent upon and therefore unrecoverable after a tamper
 * event causes the erasure of the DryIce Random Key register.
 *
 * The software can request that the hardware generate a (new) Random Key for
 * DryIce by calling #fsl_shw_gen_random_pf_key().
 *
 *
 * @section td_sec Device Tamper-Detection
 *
 * Some platforms have a component which can detect certain types of tampering
 * with the hardware.  #fsl_shw_read_tamper_event() API will allow the
 * retrieval of the type of event which caused a tamper-detection failure.
 *
 */

/*! @defgroup glossary Glossary
 *
 * @li @b AES - Advanced Encryption Standard - An NIST-created block cipher
 *          originally knowns as Rijndael.
 * @li @b ARC4 - ARCFOUR - An S-Box-based OFB mode stream cipher.
 * @li @b CBC - Cipher-Block Chaining - Each encrypted block is XORed with the
 *          result of the previous block's encryption.
 * @li @b CCM - A way of combining CBC and CTR to perform cipher and
 *        authentication.
 * @li @b ciphertext - @a plaintext which has been encrypted in some fashion.
 * @li @b context - Information on the state of a cryptographic operation,
 *        excluding any key.  This could include IV, Counter Value, or SBox.
 * @li @b CTR - A mode where a counter value is encrypted and then XORed with
 *        the data.  After each block, the counter value is incremented.
 * @li @b DES - Data Encryption Standard - An 8-octet-block cipher.
 * @li @b ECB - Electronic Codebook - A straight encryption/decryption of the
 *        data.
 * @li @b hash - A cryptographically strong one-way function performed on data.
 * @li @b HMAC - Hashed Message Authentication Code - A key-dependent one-way
 *        hash result, used to verify authenticity of a message.  The equation
 *        for an HMAC is hash((K + A) || hash((K + B) || msg)), where K is the
 *        key, A is the constant for the outer hash, B is the constant for the
 *        inner hash, and hash is the hashing function (MD5, SHA256, etc).
 * @li @b IPAD - In an HMAC operation, the context generated by XORing the key
 *        with a constant and then hashing that value as the first block of the
 *        inner hash.
 * @li @b IV - An "Initial Vector" or @a context for modes like CBC.
 * @li @b MAC - A Message Authentication Code.  HMAC, hashing, and CCM all
 *        produce a MAC.
 * @li @b mode  - A way of using a cryptographic algorithm.  See ECB, CBC, etc.
 * @li @b MD5 - Message Digest 5 - A one-way hash function.
 * @li @b plaintext - Data which has not been encrypted, or has been decrypted
 *        from @a ciphertext.
 * @li @b OPAD - In an HMAC operation, the context generated by XORing the key
 *        with a constant and then hashing that value as the first block of the
 *        outer hash.
 * @li @b SHA - Secure Hash Algorithm - A one-way hash function.
 * @li @b TDES - AKA @b 3DES - Triple Data Encryption Standard - A method of
 *        using two or three keys and DES to perform three operations (encrypt
 *        decrypt encrypt) to create a new algorithm.
 * @li @b XOR - Exclusive-OR.  A Boolean arithmetic function.
 * @li @b Wrapped value - A (key) which has been encrypted into an opaque datum
 *        which cannot be unwrapped (decrypted) for use except by an authorized
 *        user.  Once created, the key is never visible, but may be used for
 *        other cryptographic operations.
 */

#ifndef FSL_SHW_H
#define FSL_SHW_H

/* Set FSL_HAVE_* flags */

#include "fsl_platform.h"

#ifndef API_DOC

#if defined(FSL_HAVE_SAHARA2) || defined(FSL_HAVE_SAHARA4)

#include "sahara.h"

#else

#if defined(FSL_HAVE_RNGA) || defined(FSL_HAVE_RNGB) || defined(FSL_HAVE_RNGC)

#include "rng_driver.h"

#else

#error FSL_SHW_API_platform_not_recognized

#endif

#endif				/* HAVE SAHARA */

#else				/* API_DOC */

#include <inttypes.h>		/* for uint32_t, etc. */
#include <stdio.h>		/* Mainly for definition of NULL !! */

/* These groups will appear in the order in which they are defined. */

/*!
 * @defgroup strgrp Objects
 *
 * These objects are used to pass information into and out of the API.  Through
 * flags and other settings, they control the behavior of the @ref opfuns.
 *
 * They are manipulated and queried by use of the various access functions.
 * There are different sets defined for each object.  See @ref objman.
 */

/*!
 * @defgroup consgrp Enumerations and other Constants
 *
 * This collection of symbols comprise the values which can be passed into
 * various functions to control how the API will work.
 */

/*! @defgroup opfuns Operational Functions
 *
 * These functions request that the underlying hardware perform cryptographic
 * operations.  They are the heart of the API.
 */

/******  Organization the Object Operations under one group ! **********/
/*! @defgroup objman Object-Manipulation Operations
 *
 */
/*! @addtogroup objman
    @{ */
/*!
 * @defgroup pcoops Platform Context Object Operations
 *
 * The Platform Context object is "read-only", so only query operations are
 * provided for it.  It is returned by the #fsl_shw_get_capabilities()
 * function.
 */

/*! @defgroup ucoops User Context Operations
 *
 * These operations should be the only access to the #fsl_shw_uco_t
 * type/struct, as the internal members of the object are subject to change.
 * The #fsl_shw_uco_init() function must be called before any other use of the
 * object.
 */

/*!
 * @defgroup rops Result Object Operations
 *
 * As the Result Object contains the result of one of the @ref opfuns.  The
 * manipulations provided are query-only.  No initialization is needed for this
 * object.
 */

/*!
 * @defgroup skoops Secret Key Object Operations
 *
 * These operations should be the only access to the #fsl_shw_sko_t
 * type/struct, as the internal members of that object are subject to change.
 */

/*!
 * @defgroup ksoops Keystore Object Operations
 *
 * These operations should be the only access to the #fsl_shw_kso_t
 * type/struct, as the internal members of that object are subject to change.
 */

/*!
 * @defgroup hcops Hash Context Object Operations
 *
 * These operations should be the only access to the #fsl_shw_hco_t
 * type/struct, as the internal members of that object are subject to change.
 */

/*!
 * @defgroup hmcops HMAC Context Object Operations
 *
 * These operations should be the only access to the #fsl_shw_hmco_t
 * type/struct, as the internal members of that object are subject to change.
 */

/*!
 * @defgroup sccops Symmetric Cipher Context Operations
 *
 * These operations should be the only access to the #fsl_shw_scco_t
 * type/struct, as the internal members of that object are subject to change
 */

/*! @defgroup accoops Authentication-Cipher Context Object Operations
 *
 * These functions operate on a #fsl_shw_acco_t.  Their purpose is to set
 * flags, fields, etc., in order to control the operation of
 * #fsl_shw_gen_encrypt() and #fsl_shw_auth_decrypt().
 */

	 /* @} *//************ END GROUPING of Object Manipulations *****************/

/*! @defgroup miscfuns Miscellaneous Functions
 *
 * These functions are neither @ref opfuns nor @ref objman.  Their behavior
 * does not depend upon the flags in the #fsl_shw_uco_t, yet they may involve
 * more interaction with the library and the kernel than simply querying an
 * object.
 */

/******************************************************************************
 * Enumerations
 *****************************************************************************/
/*! @addtogroup consgrp
    @{ */

/*!
 * Flags for the state of the User Context Object (#fsl_shw_uco_t).
 *
 * These flags describe how the @ref opfuns will operate.
 */
typedef enum fsl_shw_user_ctx_flags_t {
	/*!
	 * API will block the caller until operation completes.  The result will be
	 * available in the return code.  If this is not set, user will have to get
	 * results using #fsl_shw_get_results().
	 */
	FSL_UCO_BLOCKING_MODE,
	/*!
	 * User wants callback (at the function specified with
	 * #fsl_shw_uco_set_callback()) when the operation completes.  This flag is
	 * valid only if #FSL_UCO_BLOCKING_MODE is not set.
	 */
	FSL_UCO_CALLBACK_MODE,
	/*! Do not free descriptor chain after driver (adaptor) finishes */
	FSL_UCO_SAVE_DESC_CHAIN,
	/*!
	 * User has made at least one request with callbacks requested, so API is
	 * ready to handle others.
	 */
	FSL_UCO_CALLBACK_SETUP_COMPLETE,
	/*!
	 * (virtual) pointer to descriptor chain is completely linked with physical
	 * (DMA) addresses, ready for the hardware.  This flag should not be used
	 * by FSL SHW API programs.
	 */
	FSL_UCO_CHAIN_PREPHYSICALIZED,
	/*!
	 * The user has changed the context but the changes have not been copied to
	 * the kernel driver.
	 */
	FSL_UCO_CONTEXT_CHANGED,
	/*! Internal Use.  This context belongs to a user-mode API user. */
	FSL_UCO_USERMODE_USER,
} fsl_shw_user_ctx_flags_t;

/*!
 * Return code for FSL_SHW library.
 *
 * These codes may be returned from a function call.  In non-blocking mode,
 * they will appear as the status in a Result Object.
 */
typedef enum fsl_shw_return_t {
	/*!
	 * No error.  As a function return code in Non-blocking mode, this may
	 * simply mean that the operation was accepted for eventual execution.
	 */
	FSL_RETURN_OK_S = 0,
	/*! Failure for non-specific reason. */
	FSL_RETURN_ERROR_S,
	/*!
	 * Operation failed because some resource was not able to be allocated.
	 */
	FSL_RETURN_NO_RESOURCE_S,
	/*! Crypto algorithm unrecognized or improper. */
	FSL_RETURN_BAD_ALGORITHM_S,
	/*! Crypto mode unrecognized or improper. */
	FSL_RETURN_BAD_MODE_S,
	/*! Flag setting unrecognized or inconsistent. */
	FSL_RETURN_BAD_FLAG_S,
	/*! Improper or unsupported key length for algorithm. */
	FSL_RETURN_BAD_KEY_LENGTH_S,
	/*! Improper parity in a (DES, TDES) key. */
	FSL_RETURN_BAD_KEY_PARITY_S,
	/*!
	 * Improper or unsupported data length for algorithm or internal buffer.
	 */
	FSL_RETURN_BAD_DATA_LENGTH_S,
	/*! Authentication / Integrity Check code check failed. */
	FSL_RETURN_AUTH_FAILED_S,
	/*! A memory error occurred. */
	FSL_RETURN_MEMORY_ERROR_S,
	/*! An error internal to the hardware occurred. */
	FSL_RETURN_INTERNAL_ERROR_S,
	/*! ECC detected Point at Infinity */
	FSL_RETURN_POINT_AT_INFINITY_S,
	/*! ECC detected No Point at Infinity */
	FSL_RETURN_POINT_NOT_AT_INFINITY_S,
	/*! GCD is One */
	FSL_RETURN_GCD_IS_ONE_S,
	/*! GCD is not One */
	FSL_RETURN_GCD_IS_NOT_ONE_S,
	/*! Candidate is Prime */
	FSL_RETURN_PRIME_S,
	/*! Candidate is not Prime */
	FSL_RETURN_NOT_PRIME_S,
	/*! N register loaded improperly with even value */
	FSL_RETURN_EVEN_MODULUS_ERROR_S,
	/*! Divisor is zero. */
	FSL_RETURN_DIVIDE_BY_ZERO_ERROR_S,
	/*! Bad Exponent or Scalar value for Point Multiply */
	FSL_RETURN_BAD_EXPONENT_ERROR_S,
	/*! RNG hardware problem. */
	FSL_RETURN_OSCILLATOR_ERROR_S,
	/*! RNG hardware problem. */
	FSL_RETURN_STATISTICS_ERROR_S,
} fsl_shw_return_t;

/*!
 * Algorithm Identifier.
 *
 * Selection of algorithm will determine how large the block size of the
 * algorithm is.   Context size is the same length unless otherwise specified.
 * Selection of algorithm also affects the allowable key length.
 */
typedef enum fsl_shw_key_alg_t {
	FSL_KEY_ALG_HMAC,	/*!< Key will be used to perform an HMAC.  Key
				   size is 1 to 64 octets.  Block size is 64
				   octets. */
	FSL_KEY_ALG_AES,	/*!< Advanced Encryption Standard (Rijndael).
				   Block size is 16 octets.  Key size is 16
				   octets.  (The single choice of key size is a
				   Sahara platform limitation.) */
	FSL_KEY_ALG_DES,	/*!< Data Encryption Standard.  Block size is
				   8 octets.  Key size is 8 octets. */
	FSL_KEY_ALG_TDES,	/*!< 2- or 3-key Triple DES.  Block size is 8
				   octets.  Key size is 16 octets for 2-key
				   Triple DES, and 24 octets for 3-key. */
	FSL_KEY_ALG_ARC4	/*!< ARC4.  No block size.  Context size is 259
				   octets.  Allowed key size is 1-16 octets.
				   (The choices for key size are a Sahara
				   platform limitation.) */
} fsl_shw_key_alg_t;

/*!
 * Mode selector for Symmetric Ciphers.
 *
 * The selection of mode determines how a cryptographic algorithm will be
 * used to process the plaintext or ciphertext.
 *
 * For all modes which are run block-by-block (that is, all but
 * #FSL_SYM_MODE_STREAM), any partial operations must be performed on a text
 * length which is multiple of the block size.  Except for #FSL_SYM_MODE_CTR,
 * these block-by-block algorithms must also be passed a total number of octets
 * which is a multiple of the block size.
 *
 * In modes which require that the total number of octets of data be a multiple
 * of the block size (#FSL_SYM_MODE_ECB and #FSL_SYM_MODE_CBC), and the user
 * has a total number of octets which are not a multiple of the block size, the
 * user must perform any necessary padding to get to the correct data length.
 */
typedef enum fsl_shw_sym_mode_t {
	/*!
	 * Stream.  There is no associated block size.  Any request to process data
	 * may be of any length.  This mode is only for ARC4 operations, and is
	 * also the only mode used for ARC4.
	 */
	FSL_SYM_MODE_STREAM,

	/*!
	 * Electronic Codebook.  Each block of data is encrypted/decrypted.  The
	 * length of the data stream must be a multiple of the block size.  This
	 * mode may be used for DES, 3DES, and AES.  The block size is determined
	 * by the algorithm.
	 */
	FSL_SYM_MODE_ECB,
	/*!
	 * Cipher-Block Chaining.  Each block of data is encrypted/decrypted and
	 * then "chained" with the previous block by an XOR function.  Requires
	 * context to start the XOR (previous block).  This mode may be used for
	 * DES, 3DES, and AES.  The block size is determined by the algorithm.
	 */
	FSL_SYM_MODE_CBC,
	/*!
	 * Counter.  The counter is encrypted, then XORed with a block of data.
	 * The counter is then incremented (using modulus arithmetic) for the next
	 * block. The final operation may be non-multiple of block size.  This mode
	 * may be used for AES.  The block size is determined by the algorithm.
	 */
	FSL_SYM_MODE_CTR,
} fsl_shw_sym_mode_t;

/*!
 * Algorithm selector for Cryptographic Hash functions.
 *
 * Selection of algorithm determines how large the context and digest will be.
 * Context is the same size as the digest (resulting hash), unless otherwise
 * specified.
 */
typedef enum fsl_shw_hash_alg_t {
	FSL_HASH_ALG_MD5,	/*!< MD5 algorithm.  Digest is 16 octets. */
	FSL_HASH_ALG_SHA1,	/*!< SHA-1 (aka SHA or SHA-160) algorithm.
				   Digest is 20 octets. */
	FSL_HASH_ALG_SHA224,	/*!< SHA-224 algorithm.  Digest is 28 octets,
				   though context is 32 octets. */
	FSL_HASH_ALG_SHA256	/*!< SHA-256 algorithm.  Digest is 32
				   octets. */
} fsl_shw_hash_alg_t;

/*!
 * The type of Authentication-Cipher function which will be performed.
 */
typedef enum fsl_shw_acc_mode_t {
	/*!
	 * CBC-MAC for Counter.  Requires context and modulus.  Final operation may
	 * be non-multiple of block size.  This mode may be used for AES.
	 */
	FSL_ACC_MODE_CCM,
	/*!
	 * SSL mode.  Not supported.  Combines HMAC and encrypt (or decrypt).
	 * Needs one key object for encryption, another for the HMAC.  The usual
	 * hashing and symmetric encryption algorithms are supported.
	 */
	FSL_ACC_MODE_SSL,
} fsl_shw_acc_mode_t;

/*!
 * The operation which controls the behavior of #fsl_shw_establish_key().
 *
 * These values are passed to #fsl_shw_establish_key().
 */
typedef enum fsl_shw_key_wrap_t {
	FSL_KEY_WRAP_CREATE,	/*!< Generate a key from random values. */
	FSL_KEY_WRAP_ACCEPT,	/*!< Use the provided clear key. */
	FSL_KEY_WRAP_UNWRAP	/*!< Unwrap a previously wrapped key. */
} fsl_shw_key_wrap_t;

/* REQ-S2LRD-PINTFC-COA-HCO-001 */
/*!
 * Flags which control a Hash operation.
 *
 *  These may be combined by ORing them together.  See #fsl_shw_hco_set_flags()
 * and #fsl_shw_hco_clear_flags().
 */
typedef enum fsl_shw_hash_ctx_flags_t {
	FSL_HASH_FLAGS_INIT = 1,	/*!< Context is empty.  Hash is started
					   from scratch, with a message-processed
					   count of zero. */
	FSL_HASH_FLAGS_SAVE = 2,	/*!< Retrieve context from hardware after
					   hashing.  If used with the
					   #FSL_HASH_FLAGS_FINALIZE flag, the final
					   digest value will be saved in the
					   object. */
	FSL_HASH_FLAGS_LOAD = 4,	/*!< Place context into hardware before
					   hashing. */
	FSL_HASH_FLAGS_FINALIZE = 8,	/*!< PAD message and perform final digest
					   operation.  If user message is
					   pre-padded, this flag should not be
					   used. */
} fsl_shw_hash_ctx_flags_t;

/*!
 * Flags which control an HMAC operation.
 *
 * These may be combined by ORing them together.  See #fsl_shw_hmco_set_flags()
 * and #fsl_shw_hmco_clear_flags().
 */
typedef enum fsl_shw_hmac_ctx_flags_t {
	FSL_HMAC_FLAGS_INIT = 1,	/*!< Message context is empty.  HMAC is
					   started from scratch (with key) or from
					   precompute of inner hash, depending on
					   whether
					   #FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT is
					   set. */
	FSL_HMAC_FLAGS_SAVE = 2,	/*!< Retrieve ongoing context from hardware
					   after hashing.  If used with the
					   #FSL_HMAC_FLAGS_FINALIZE flag, the final
					   digest value (HMAC) will be saved in the
					   object. */
	FSL_HMAC_FLAGS_LOAD = 4,	/*!< Place ongoing context into hardware
					   before hashing. */
	FSL_HMAC_FLAGS_FINALIZE = 8,	/*!< PAD message and perform final HMAC
					   operations of inner and outer hashes. */
	FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT = 16	/*!< This means that the context
						   contains precomputed inner and outer
						   hash values. */
} fsl_shw_hmac_ctx_flags_t;

/*!
 * Flags to control use of the #fsl_shw_scco_t.
 *
 * These may be ORed together to get the desired effect.
 * See #fsl_shw_scco_set_flags() and #fsl_shw_scco_clear_flags()
 */
typedef enum fsl_shw_sym_ctx_flags_t {
	/*!
	 * Context is empty.  In ARC4, this means that the S-Box needs to be
	 * generated from the key.  In #FSL_SYM_MODE_CBC mode, this allows an IV of
	 * zero to be specified.  In #FSL_SYM_MODE_CTR mode, it means that an
	 * initial CTR value of zero is desired.
	 */
	FSL_SYM_CTX_INIT = 1,
	/*!
	 * Load context from object into hardware before running cipher.  In
	 * #FSL_SYM_MODE_CTR mode, this would refer to the Counter Value.
	 */
	FSL_SYM_CTX_LOAD = 2,
	/*!
	 * Save context from hardware into object after running cipher.  In
	 * #FSL_SYM_MODE_CTR mode, this would refer to the Counter Value.
	 */
	FSL_SYM_CTX_SAVE = 4,
	/*!
	 * Context (SBox) is to be unwrapped and wrapped on each use.
	 * This flag is unsupported.
	 * */
	FSL_SYM_CTX_PROTECT = 8,
} fsl_shw_sym_ctx_flags_t;

/*!
 * Flags which describe the state of the #fsl_shw_sko_t.
 *
 * These may be ORed together to get the desired effect.
 * See #fsl_shw_sko_set_flags() and #fsl_shw_sko_clear_flags()
 */
typedef enum fsl_shw_key_flags_t {
	FSL_SKO_KEY_IGNORE_PARITY = 1,	/*!< If algorithm is DES or 3DES, do not
					   validate the key parity bits. */
	FSL_SKO_KEY_PRESENT = 2,	/*!< Clear key is present in the object. */
	FSL_SKO_KEY_ESTABLISHED = 4,	/*!< Key has been established for use.  This
					   feature is not available for all
					   platforms, nor for all algorithms and
					   modes. */
	FSL_SKO_KEY_SW_KEY = 8,	/*!< This key is for software use, and can
				   be copied out of a keystore by its owner.
				   The default is that they key is available
				   only for hardware (or security driver)
				   use. */
} fsl_shw_key_flags_t;

/*!
 * Type of value which is associated with an established key.
 */
typedef uint64_t key_userid_t;

/*!
 * Flags which describe the state of the #fsl_shw_acco_t.
 *
 * The @a FSL_ACCO_CTX_INIT and @a FSL_ACCO_CTX_FINALIZE flags, when used
 * together, provide for a one-shot operation.
 */
typedef enum fsl_shw_auth_ctx_flags_t {
	FSL_ACCO_CTX_INIT = 1,	/*!< Initialize Context(s) */
	FSL_ACCO_CTX_LOAD = 2,	/*!< Load intermediate context(s).
				   This flag is unsupported. */
	FSL_ACCO_CTX_SAVE = 4,	/*!< Save intermediate context(s).
				   This flag is unsupported. */
	FSL_ACCO_CTX_FINALIZE = 8,	/*!< Create MAC during this operation. */
	FSL_ACCO_NIST_CCM = 16,	/*!< Formatting of CCM input data is
				   performed by calls to
				   #fsl_shw_ccm_nist_format_ctr_and_iv() and
				   #fsl_shw_ccm_nist_update_ctr_and_iv().  */
} fsl_shw_auth_ctx_flags_t;

/*!
 *  Modulus Selector for CTR modes.
 *
 * The incrementing of the Counter value may be modified by a modulus.  If no
 * modulus is needed or desired for AES, use #FSL_CTR_MOD_128.
 */
typedef enum fsl_shw_ctr_mod_t {
	FSL_CTR_MOD_8,		/*!< Run counter with modulus of 2^8. */
	FSL_CTR_MOD_16,		/*!< Run counter with modulus of 2^16. */
	FSL_CTR_MOD_24,		/*!< Run counter with modulus of 2^24. */
	FSL_CTR_MOD_32,		/*!< Run counter with modulus of 2^32. */
	FSL_CTR_MOD_40,		/*!< Run counter with modulus of 2^40. */
	FSL_CTR_MOD_48,		/*!< Run counter with modulus of 2^48. */
	FSL_CTR_MOD_56,		/*!< Run counter with modulus of 2^56. */
	FSL_CTR_MOD_64,		/*!< Run counter with modulus of 2^64. */
	FSL_CTR_MOD_72,		/*!< Run counter with modulus of 2^72. */
	FSL_CTR_MOD_80,		/*!< Run counter with modulus of 2^80. */
	FSL_CTR_MOD_88,		/*!< Run counter with modulus of 2^88. */
	FSL_CTR_MOD_96,		/*!< Run counter with modulus of 2^96. */
	FSL_CTR_MOD_104,	/*!< Run counter with modulus of 2^104. */
	FSL_CTR_MOD_112,	/*!< Run counter with modulus of 2^112. */
	FSL_CTR_MOD_120,	/*!< Run counter with modulus of 2^120. */
	FSL_CTR_MOD_128		/*!< Run counter with modulus of 2^128. */
} fsl_shw_ctr_mod_t;

/*!
 * Permissions flags for Secure Partitions
 *
 * They currently map directly to the SCC2 hardware values, but this is not
 * guarinteed behavior.
 */
typedef enum fsl_shw_permission_t {
/*! SCM Access Permission: Do not zeroize/deallocate partition on SMN Fail state */
	FSL_PERM_NO_ZEROIZE,
/*! SCM Access Permission: Enforce trusted key read in  */
	FSL_PERM_TRUSTED_KEY_READ,
/*! SCM Access Permission: Ignore Supervisor/User mode in permission determination */
	FSL_PERM_HD_S,
/*! SCM Access Permission: Allow Read Access to  Host Domain */
	FSL_PERM_HD_R,
/*! SCM Access Permission: Allow Write Access to  Host Domain */
	FSL_PERM_HD_W,
/*! SCM Access Permission: Allow Execute Access to  Host Domain */
	FSL_PERM_HD_X,
/*! SCM Access Permission: Allow Read Access to Trusted Host Domain */
	FSL_PERM_TH_R,
/*! SCM Access Permission: Allow Write Access to Trusted Host Domain */
	FSL_PERM_TH_W,
/*! SCM Access Permission: Allow Read Access to Other/World Domain */
	FSL_PERM_OT_R,
/*! SCM Access Permission: Allow Write Access to Other/World Domain */
	FSL_PERM_OT_W,
/*! SCM Access Permission: Allow Execute Access to Other/World Domain */
	FSL_PERM_OT_X,
} fsl_shw_permission_t;

/*!
 * Select the cypher mode to use for partition cover/uncover operations.
 *
 * They currently map directly to the values used in the SCC2 driver, but this
 * is not guarinteed behavior.
 */
typedef enum fsl_shw_cypher_mode_t {
	FSL_SHW_CYPHER_MODE_ECB,	/*!< ECB mode */
	FSL_SHW_CYPHER_MODE_CBC,	/*!< CBC mode */
} fsl_shw_cypher_mode_t;

/*!
 * Which platform key should be presented for cryptographic use.
 */
typedef enum fsl_shw_pf_key_t {
	FSL_SHW_PF_KEY_IIM,	/*!< Present fused IIM key */
	FSL_SHW_PF_KEY_PRG,	/*!< Present Program key */
	FSL_SHW_PF_KEY_IIM_PRG,	/*!< Present IIM ^ Program key */
	FSL_SHW_PF_KEY_IIM_RND,	/*!< Present Random key */
	FSL_SHW_PF_KEY_RND,	/*!< Present IIM ^ Random key */
} fsl_shw_pf_key_t;

/*!
 * The various security tamper events
 */
typedef enum fsl_shw_tamper_t {
	FSL_SHW_TAMPER_NONE,	/*!< No error detected */
	FSL_SHW_TAMPER_WTD,	/*!< wire-mesh tampering det */
	FSL_SHW_TAMPER_ETBD,	/*!< ext tampering det: input B */
	FSL_SHW_TAMPER_ETAD,	/*!< ext tampering det: input A */
	FSL_SHW_TAMPER_EBD,	/*!< external boot detected */
	FSL_SHW_TAMPER_SAD,	/*!< security alarm detected */
	FSL_SHW_TAMPER_TTD,	/*!< temperature tampering det */
	FSL_SHW_TAMPER_CTD,	/*!< clock tampering det */
	FSL_SHW_TAMPER_VTD,	/*!< voltage tampering det */
	FSL_SHW_TAMPER_MCO,	/*!< monotonic counter overflow */
	FSL_SHW_TAMPER_TCO,	/*!< time counter overflow */
} fsl_shw_tamper_t;

/*! @} *//* consgrp */

/******************************************************************************
 * Data Structures
 *****************************************************************************/
/*! @addtogroup strgrp
    @{ */

/* REQ-S2LRD-PINTFC-COA-IBO-001 */
/*!
 * Application Initialization Object
 *
 * This object, the operations on it, and its interaction with the driver are
 * TBD.
 */
typedef struct fsl_sho_ibo_t {
} fsl_sho_ibo_t;

/* REQ-S2LRD-PINTFC-COA-UCO-001 */
/*!
 * User Context Object
 *
 * This object must be initialized by a call to #fsl_shw_uco_init().  It must
 * then be passed to #fsl_shw_register_user() before it can be used in any
 * calls besides those in @ref ucoops.
 *
 * It contains the user's configuration for the API, for instance whether an
 * operation should block, or instead should call back the user upon completion
 * of the operation.
 *
 * See @ref ucoops for further information.
 */
typedef struct fsl_shw_uco_t {	/* fsl_shw_user_context_object */
} fsl_shw_uco_t;

/* REQ-S2LRD-PINTFC-API-GEN-006  ??  */
/*!
 * Result Object
 *
 * This object will contain success and failure information about a specific
 * cryptographic request which has been made.
 *
 * No direct access to its members should be made by programs.  Instead, the
 * object should be manipulated using the provided functions.  See @ref rops.
 */
typedef struct fsl_shw_result_t {	/* fsl_shw_result */
} fsl_shw_result_t;

/*!
 * Keystore Object
 *
 * This object holds the context of a user keystore, including the functions
 * that define the interface and pointers to where the key data is stored.  The
 * user must supply a set of functions to handle keystore management, including
 * slot allocation, deallocation, etc.  A default keystore manager is provided
 * as part of the API.
 *
 * No direct access to its members should be made by programs.  Instead, the
 * object should be manipulated using the provided functions.  See @ref ksoops.
 */
typedef struct fsl_shw_kso_t {	/* fsl_shw_keystore_object */
} fsl_shw_kso_t;

/* REQ-S2LRD-PINTFC-COA-SKO-001 */
/*!
 * Secret Key Object
 *
 * This object contains a key for a cryptographic operation, and information
 * about its current state, its intended usage, etc.  It may instead contain
 * information about a protected key, or an indication to use a platform-
 * specific secret key.
 *
 * No direct access to its members should be made by programs.  Instead, the
 * object should be manipulated using the provided functions.  See @ref skoops.
 */
typedef struct fsl_shw_sko_t {	/* fsl_shw_secret_key_object */
} fsl_shw_sko_t;

/* REQ-S2LRD-PINTFC-COA-CO-001 */
/*!
 * Platform Capabilities Object
 *
 * This object will contain information about the cryptographic features of the
 * platform which the program is running on.
 *
 * No direct access to its members should be made by programs.  Instead, the
 * object should be manipulated using the provided functions.
 *
 * See @ref pcoops.
 */
typedef struct fsl_shw_pco_t {	/* fsl_shw_platform_capabilities_object */
} fsl_shw_pco_t;

/* REQ-S2LRD-PINTFC-COA-HCO-001 */
/*!
 * Hash Context Object
 *
 * This object contains information to control hashing functions.

 * No direct access to its members should be made by programs.  Instead, the
 * object should be manipulated using the provided functions.  See @ref hcops.
 */
typedef struct fsl_shw_hco_t {	/* fsl_shw_hash_context_object */
} fsl_shw_hco_t;

/*!
 * HMAC Context Object
 *
 * This object contains information to control HMAC functions.

 * No direct access to its members should be made by programs.  Instead, the
 * object should be manipulated using the provided functions.  See @ref hmcops.
 */
typedef struct fsl_shw_hmco_t {	/* fsl_shw_hmac_context_object */
} fsl_shw_hmco_t;

/* REQ-S2LRD-PINTFC-COA-SCCO-001 */
/*!
 * Symmetric Cipher Context Object
 *
 * This object contains information to control Symmetric Ciphering encrypt and
 * decrypt functions in #FSL_SYM_MODE_STREAM (ARC4), #FSL_SYM_MODE_ECB,
 * #FSL_SYM_MODE_CBC, and #FSL_SYM_MODE_CTR modes and the
 * #fsl_shw_symmetric_encrypt() and #fsl_shw_symmetric_decrypt() functions.
 * CCM mode is controlled with the #fsl_shw_acco_t object.
 *
 * No direct access to its members should be made by programs.  Instead, the
 * object should be manipulated using the provided functions.  See @ref sccops.
 */
typedef struct fsl_shw_scco_t {	/* fsl_shw_symmetric_cipher_context_object */
} fsl_shw_scco_t;

/*!
 * Authenticate-Cipher Context Object

 * An object for controlling the function of, and holding information about,
 * data for the authenticate-cipher functions, #fsl_shw_gen_encrypt() and
 * #fsl_shw_auth_decrypt().
 *
 * No direct access to its members should be made by programs.  Instead, the
 * object should be manipulated using the provided functions.  See @ref
 * accoops.
 */
typedef struct fsl_shw_acco_t {	/* fsl_shw_authenticate_cipher_context_object */
} fsl_shw_acco_t;
	  /*! @} *//* strgrp */

/******************************************************************************
 * Access Macros for Objects
 *****************************************************************************/
/*! @addtogroup pcoops
    @{ */

/*!
 * Get FSL SHW API version
 *
 * @param      pc_info   The Platform Capabilities Object to query.
 * @param[out] major     A pointer to where the major version
 *                       of the API is to be stored.
 * @param[out] minor     A pointer to where the minor version
 *                       of the API is to be stored.
 */
void fsl_shw_pco_get_version(const fsl_shw_pco_t * pc_info,
			     uint32_t * major, uint32_t * minor);

/*!
 * Get underlying driver version.
 *
 * @param      pc_info   The Platform Capabilities Object to query.
 * @param[out] major     A pointer to where the major version
 *                       of the driver is to be stored.
 * @param[out] minor     A pointer to where the minor version
 *                       of the driver is to be stored.
 */
void fsl_shw_pco_get_driver_version(const fsl_shw_pco_t * pc_info,
				    uint32_t * major, uint32_t * minor);

/*!
 * Get list of symmetric algorithms supported.
 *
 * @param pc_info   The Platform Capabilities Object to query.
 * @param[out] algorithms A pointer to where to store the location of
 *                        the list of algorithms.
 * @param[out] algorithm_count A pointer to where to store the number of
 *                             algorithms in the list at @a algorithms.
 */
void fsl_shw_pco_get_sym_algorithms(const fsl_shw_pco_t * pc_info,
				    fsl_shw_key_alg_t * algorithms[],
				    uint8_t * algorithm_count);

/*!
 * Get list of symmetric modes supported.
 *
 * @param pc_info         The Platform Capabilities Object to query.
 * @param[out] modes      A pointer to where to store the location of
 *                        the list of modes.
 * @param[out] mode_count A pointer to where to store the number of
 *                        algorithms in the list at @a modes.
 */
void fsl_shw_pco_get_sym_modes(const fsl_shw_pco_t * pc_info,
			       fsl_shw_sym_mode_t * modes[],
			       uint8_t * mode_count);

/*!
 * Get list of hash algorithms supported.
 *
 * @param pc_info         The Platform Capabilities Object to query.
 * @param[out] algorithms A pointer which will be set to the list of
 *                        algorithms.
 * @param[out] algorithm_count The number of algorithms in the list at @a
 *                             algorithms.
 */
void fsl_shw_pco_get_hash_algorithms(const fsl_shw_pco_t * pc_info,
				     fsl_shw_hash_alg_t * algorithms[],
				     uint8_t * algorithm_count);

/*!
 * Determine whether the combination of a given symmetric algorithm and a given
 * mode is supported.
 *
 * @param pc_info    The Platform Capabilities Object to query.
 * @param algorithm  A Symmetric Cipher algorithm.
 * @param mode       A Symmetric Cipher mode.
 *
 * @return 0 if combination is not supported, non-zero if supported.
 */
int fsl_shw_pco_check_sym_supported(const fsl_shw_pco_t * pc_info,
				    fsl_shw_key_alg_t algorithm,
				    fsl_shw_sym_mode_t mode);

/*!
 * Determine whether a given Encryption-Authentication mode is supported.
 *
 * @param pc_info   The Platform Capabilities Object to query.
 * @param mode       The Authentication mode.
 *
 * @return 0 if mode is not supported, non-zero if supported.
 */
int fsl_shw_pco_check_auth_supported(const fsl_shw_pco_t * pc_info,
				     fsl_shw_acc_mode_t mode);

/*!
 * Determine whether Black Keys (key establishment / wrapping) is supported.
 *
 * @param pc_info  The Platform Capabilities Object to query.
 *
 * @return 0 if wrapping is not supported, non-zero if supported.
 */
int fsl_shw_pco_check_black_key_supported(const fsl_shw_pco_t * pc_info);

/*!
 * Get FSL SHW SCC driver version
 *
 * @param      pc_info   The Platform Capabilities Object to query.
 * @param[out] major     A pointer to where the major version
 *                       of the SCC driver is to be stored.
 * @param[out] minor     A pointer to where the minor version
 *                       of the SCC driver is to be stored.
 */
void fsl_shw_pco_get_scc_driver_version(const fsl_shw_pco_t * pc_info,
					uint32_t * major, uint32_t * minor);

/*!
 * Get SCM hardware version
 *
 * @param      pc_info   The Platform Capabilities Object to query.
 * @return               The SCM hardware version
 */
uint32_t fsl_shw_pco_get_scm_version(const fsl_shw_pco_t * pc_info);

/*!
 * Get SMN hardware version
 *
 * @param      pc_info   The Platform Capabilities Object to query.
 * @return               The SMN hardware version
 */
uint32_t fsl_shw_pco_get_smn_version(const fsl_shw_pco_t * pc_info);

/*!
 * Get the size of an SCM block, in bytes
 *
 * @param      pc_info   The Platform Capabilities Object to query.
 * @return               The size of an SCM block, in bytes.
 */
uint32_t fsl_shw_pco_get_scm_block_size(const fsl_shw_pco_t * pc_info);

/*!
 * Get size of Black and Red RAM memory
 *
 * @param      pc_info     The Platform Capabilities Object to query.
 * @param[out] black_size  A pointer to where the size of the Black RAM, in
 *                         blocks, is to be placed.
 * @param[out] red_size    A pointer to where the size of the Red RAM, in
 *                         blocks, is to be placed.
 */
void fsl_shw_pco_get_smn_size(const fsl_shw_pco_t * pc_info,
			      uint32_t * black_size, uint32_t * red_size);

/*!
 * Determine whether Secure Partitions are supported
 *
 * @param pc_info          The Platform Capabilities Object to query.
 *
 * @return 0 if secure partitions are not supported, non-zero if supported.
 */
int fsl_shw_pco_check_spo_supported(const fsl_shw_pco_t * pc_info);

/*!
 * Get the size of a Secure Partitions
 *
 * @param pc_info          The Platform Capabilities Object to query.
 *
 * @return Partition size, in bytes.  0 if Secure Partitions not supported.
 */
uint32_t fsl_shw_pco_get_spo_size_bytes(const fsl_shw_pco_t * pc_info);

/*!
 * Get the number of Secure Partitions on this platform
 *
 * @param pc_info          The Platform Capabilities Object to query.
 *
 * @return Number of partitions. 0 if Secure Partitions not supported.  Note
 *         that this returns the total number of partitions, though
 *         not all may be available to the user.
 */
uint32_t fsl_shw_pco_get_spo_count(const fsl_shw_pco_t * pc_info);

/*!
 * Determine whether Platform Key features are available
 *
 * @param pc_info          The Platform Capabilities Object to query.
 *
 * @return  1 if Programmed Key features are available, otherwise zero.
 */
int fsl_shw_pco_check_pk_supported(const fsl_shw_pco_t * pc_info);

/*!
  * Determine whether Software Key features are available
  *
  * @param pc_info 		 The Platform Capabilities Object to query.
  *
  * @return  1 if Software key features are available, otherwise zero.
  */
int fsl_shw_pco_check_sw_keys_supported(const fsl_shw_pco_t * pc_info);

/*! @} *//* pcoops */

/*! @addtogroup ucoops
    @{ */

/*!
 * Initialize a User Context Object.
 *
 * This function must be called before performing any other operation with the
 * Object.  It sets the User Context Object to initial values, and set the size
 * of the results pool.  The mode will be set to a default of
 * #FSL_UCO_BLOCKING_MODE.
 *
 * When using non-blocking operations, this sets the maximum number of
 * operations which can be outstanding.  This number includes the counts of
 * operations waiting to start, operation(s) being performed, and results which
 * have not been retrieved.
 *
 * Changes to this value are ignored once user registration has completed.  It
 * should be set to 1 if only blocking operations will ever be performed.
 *
 * @param user_ctx     The User Context object to operate on.
 * @param pool_size    The maximum number of operations which can be
 *                     outstanding.
 */
void fsl_shw_uco_init(fsl_shw_uco_t * user_ctx, uint16_t pool_size);

/*!
 * Set the User Reference for the User Context.
 *
 * @param user_ctx     The User Context object to operate on.
 * @param reference    A value which will be passed back with a result.
 */
void fsl_shw_uco_set_reference(fsl_shw_uco_t * user_ctx, uint32_t reference);

/*!
 * Set the callback routine for the User Context.
 *
 * Note that the callback routine may be called when no results are available,
 * and possibly even when no requests are outstanding.
 *
 *
 * @param user_ctx     The User Context object to operate on.
 * @param callback_fn  The function the API will invoke when an operation
 *                     completes.
 */
void fsl_shw_uco_set_callback(fsl_shw_uco_t * user_ctx,
			      void (*callback_fn) (fsl_shw_uco_t * uco));

/*!
 * Set flags in the User Context.
 *
 * Turns on the flags specified in @a flags.  Other flags are untouched.
 *
 * @param user_ctx     The User Context object to operate on.
 * @param flags        ORed values from #fsl_shw_user_ctx_flags_t.
 */
void fsl_shw_uco_set_flags(fsl_shw_uco_t * user_ctx, uint32_t flags);

/*!
 * Clear flags in the User Context.
 *
 * Turns off the flags specified in @a flags.  Other flags are untouched.
 *
 * @param user_ctx     The User Context object to operate on.
 * @param flags        ORed values from #fsl_shw_user_ctx_flags_t.
 */
void fsl_shw_uco_clear_flags(fsl_shw_uco_t * user_ctx, uint32_t flags);

/*!
 * Select a key for the key-wrap key for key wrapping/unwrapping
 *
 * Without a call to this function, default is FSL_SHW_PF_KEY_IIM.  The wrap
 * key is used to encrypt and decrypt the per-key random secret which is used
 * to calculate the key which will encrypt/decrypt the user's key.
 *
 * @param user_ctx     The User Context object to operate on.
 * @param pf_key       Which key to use.  Valid choices are
 *                     #FSL_SHW_PF_KEY_IIM, #FSL_SHW_PF_KEY_RND, and
 *                     #FSL_SHW_PF_KEY_IIM_RND.
 */
void fsl_shw_uco_set_wrap_key(fsl_shw_uco_t * user_ctx,
			      fsl_shw_pf_key_t pf_key);

	  /*! @} *//* ucoops */

/*! @addtogroup rops
    @{ */

/*!
 * Retrieve the status code from a Result Object.
 *
 * @param result   The result object to query.
 *
 * @return The status of the request.
 */
fsl_shw_return_t fsl_shw_ro_get_status(fsl_shw_result_t * result);

/*!
 * Retrieve the reference value from a Result Object.
 *
 * @param result   The result object to query.
 *
 * @return The reference associated with the request.
 */
uint32_t fsl_shw_ro_get_reference(fsl_shw_result_t * result);

	 /* @} *//* rops */

/*! @addtogroup skoops
    @{ */

/*!
 * Initialize a Secret Key Object.
 *
 * This function or #fsl_shw_sko_init_pf_key() must be called before performing
 * any other operation with the Object.
 *
 * @param key_info  The Secret Key Object to be initialized.
 * @param algorithm DES, AES, etc.
 *
 */
void fsl_shw_sko_init(fsl_shw_sko_t * key_info, fsl_shw_key_alg_t algorithm);

/*!
 * Initialize a Secret Key Object to use a Platform Key register.
 *
 * This function or #fsl_shw_sko_init() must be called before performing any
 * other operation with the Object.  #fsl_shw_sko_set_key() does not work on
 * a key object initialized in this way.
 *
 * If this function is used to initialize the key object, but no key is
 * established with the key object, then the object will refer strictly to the
 * key value specified by the @c pf_key selection.
 *
 * If the pf key is #FSL_SHW_PF_KEY_PRG or #FSL_SHW_PF_KEY_IIM_PRG, then the
 * key object may be used with #fsl_shw_establish_key() to change the Program
 * Key value.  When the pf key is neither #FSL_SHW_PF_KEY_PRG nor
 * #FSL_SHW_PF_KEY_IIM_PRG, it is an error to call #fsl_shw_establish_key().
 *
 * @param key_info     The Secret Key Object to be initialized.
 * @param algorithm    DES, AES, etc.
 * @param pf_key       Which platform key is referenced.
 */
void fsl_shw_sko_init_pf_key(fsl_shw_sko_t * key_info,
			     fsl_shw_key_alg_t algorithm,
			     fsl_shw_pf_key_t pf_key);

/*!
 * Store a cleartext key in the key object.
 *
 * This has the side effect of setting the #FSL_SKO_KEY_PRESENT flag. It should
 * not be used if there is a key established with the key object.  If there is,
 * a call to #fsl_shw_release_key() should be made first.
 *
 * @param key_object   A variable of type #fsl_shw_sko_t.
 * @param key          A pointer to the beginning of the key.
 * @param key_length   The length, in octets, of the key.  The value should be
 *                     appropriate to the key size supported by the algorithm.
 *                     64 octets is the absolute maximum value allowed for this
 *                     call.
 */
void fsl_shw_sko_set_key(fsl_shw_sko_t * key_object,
			 const uint8_t * key, uint16_t key_length);

/*!
 * Set a size for the key.
 *
 * This function would normally be used when the user wants the key to be
 * generated from a random source.
 *
 * @param key_object   A variable of type #fsl_shw_sko_t.
 * @param key_length   The length, in octets, of the key.  The value should be
 *                     appropriate to the key size supported by the algorithm.
 *                     64 octets is the absolute maximum value allowed for this
 *                     call.
 */
void fsl_shw_sko_set_key_length(fsl_shw_sko_t * key_object,
				uint16_t key_length);

/*!
 * Set the User ID associated with the key.
 *
 * @param key_object   A variable of type #fsl_shw_sko_t.
 * @param userid       The User ID to identify authorized users of the key.
 */
void fsl_shw_sko_set_user_id(fsl_shw_sko_t * key_object, key_userid_t userid);

/*!
 * Set the keystore that the key will be stored in.
 *
 * @param key_object    A variable of type #fsl_shw_sko_t.
 * @param keystore      The keystore to place the key in.  This is a variable of
 *                      type #fsl_shw_kso_t.
 */
void fsl_shw_sko_set_keystore(fsl_shw_sko_t * key_object,
			      fsl_shw_kso_t * keystore);

/*!
 * Set the establish key handle into a key object.
 *
 * The @a userid field will be used to validate the access to the unwrapped
 * key.  This feature is not available for all platforms, nor for all
 * algorithms and modes.
 *
 * The #FSL_SKO_KEY_ESTABLISHED will be set (and the #FSL_SKO_KEY_PRESENT
 * flag will be cleared).
 *
 * @param key_object   A variable of type #fsl_shw_sko_t.
 * @param userid       The User ID to verify this user is an authorized user of
 *                     the key.
 * @param handle       A @a handle from #fsl_shw_sko_get_established_info.
 */
void fsl_shw_sko_set_established_info(fsl_shw_sko_t * key_object,
				      key_userid_t userid, uint32_t handle);

/*!
 * Extract the algorithm from a key object.
 *
 * @param      key_info  The Key Object to be queried.
 * @param[out] algorithm A pointer to the location to store the algorithm.
 */
void fsl_shw_sko_get_algorithm(const fsl_shw_sko_t * key_info,
			       fsl_shw_key_alg_t * algorithm);

/*!
 * Retrieve the cleartext key from a key object that is stored in a user
 * keystore.
 *
 * @param      skobject     The Key Object to be queried.
 * @param[out] skkey        A pointer to the location to store the key.  NULL
 *                          if the key is not stored in a user keystore.
 */
void fsl_shw_sko_get_key(const fsl_shw_sko_t * skobject, void *skkey);

/*!
 * Retrieve the established-key handle from a key object.
 *
 * @param key_object   A variable of type #fsl_shw_sko_t.
 * @param handle       The location to store the @a handle of the unwrapped
 *                     key.
 */
void fsl_shw_sko_get_established_info(fsl_shw_sko_t * key_object,
				      uint32_t * handle);

/*!
 * Determine the size of a wrapped key based upon the cleartext key's length.
 *
 * This function can be used to calculate the number of octets that
 * #fsl_shw_extract_key() will write into the location at @a covered_key.
 *
 * If zero is returned at @a length, this means that the key length in
 * @a key_info is not supported.
 *
 * @param      key_info         Information about a key to be wrapped.
 * @param      length           Location to store the length of a wrapped
 *                              version of the key in @a key_info.
 */
void fsl_shw_sko_calculate_wrapped_size(const fsl_shw_sko_t * key_info,
					uint32_t * length);

/*!
 * Set some flags in the key object.
 *
 * Turns on the flags specified in @a flags.  Other flags are untouched.
 *
 * @param key_object   A variable of type #fsl_shw_sko_t.
 * @param flags        (One or more) ORed members of #fsl_shw_key_flags_t which
 *                     are to be set.
 */
void fsl_shw_sko_set_flags(fsl_shw_sko_t * key_object, uint32_t flags);

/*!
 * Clear some flags in the key object.
 *
 * Turns off the flags specified in @a flags.  Other flags are untouched.
 *
 * @param key_object   A variable of type #fsl_shw_sko_t.
 * @param flags        (One or more) ORed members of #fsl_shw_key_flags_t which
 *                      are to be reset.
 */
void fsl_shw_sko_clear_flags(fsl_shw_sko_t * key_object, uint32_t flags);

	  /*! @} *//* end skoops */

/*****************************************************************************/

/*! @addtogroup hcops
    @{ */

/*****************************************************************************/
/* REQ-S2LRD-PINTFC-API-BASIC-HASH-004 - partially */
/*!
 * Initialize a Hash Context Object.
 *
 * This function must be called before performing any other operation with the
 * Object.  It sets the current message length and hash algorithm in the hash
 * context object.
 *
 * @param      hash_ctx  The hash context to operate upon.
 * @param      algorithm The hash algorithm to be used (#FSL_HASH_ALG_MD5,
 *                       #FSL_HASH_ALG_SHA256, etc).
 *
 */
void fsl_shw_hco_init(fsl_shw_hco_t * hash_ctx, fsl_shw_hash_alg_t algorithm);

/*****************************************************************************/
/* REQ-S2LRD-PINTFC-API-BASIC-HASH-001 */
/* REQ-S2LRD-PINTFC-API-BASIC-HASH-002 */
/*!
 * Get the current hash value and message length from the hash context object.
 *
 * The algorithm must have already been specified.  See #fsl_shw_hco_init().
 *
 * @param      hash_ctx  The hash context to query.
 * @param[out] digest    Pointer to the location of @a length octets where to
 *                       store a copy of the current value of the digest.
 * @param      length    Number of octets of hash value to copy.
 * @param[out] msg_length Pointer to the location to store the number of octets
 *                        already hashed.
 */
void fsl_shw_hco_get_digest(const fsl_shw_hco_t * hash_ctx, uint8_t * digest,
			    uint8_t length, uint32_t * msg_length);

/*****************************************************************************/
/* REQ-S2LRD-PINTFC-API-BASIC-HASH-002 - partially */
/*!
 * Get the hash algorithm from the hash context object.
 *
 * @param      hash_ctx  The hash context to query.
 * @param[out] algorithm Pointer to where the algorithm is to be stored.
 */
void fsl_shw_hco_get_info(const fsl_shw_hco_t * hash_ctx,
			  fsl_shw_hash_alg_t * algorithm);

/*****************************************************************************/
/* REQ-S2LRD-PINTFC-API-BASIC-HASH-003 */
/* REQ-S2LRD-PINTFC-API-BASIC-HASH-004 */
/*!
 * Set the current hash value and message length in the hash context object.
 *
 * The algorithm must have already been specified.  See #fsl_shw_hco_init().
 *
 * @param      hash_ctx  The hash context to operate upon.
 * @param      context   Pointer to buffer of appropriate length to copy into
 *                       the hash context object.
 * @param      msg_length The number of octets of the message which have
 *                        already been hashed.
 *
 */
void fsl_shw_hco_set_digest(fsl_shw_hco_t * hash_ctx, const uint8_t * context,
			    uint32_t msg_length);

/*!
 * Set flags in a Hash Context Object.
 *
 * Turns on the flags specified in @a flags.  Other flags are untouched.
 *
 * @param hash_ctx   The hash context to be operated on.
 * @param flags      The flags to be set in the context.  These can be ORed
 *                   members of #fsl_shw_hash_ctx_flags_t.
 */
void fsl_shw_hco_set_flags(fsl_shw_hco_t * hash_ctx, uint32_t flags);

/*!
 * Clear flags in a Hash Context Object.
 *
 * Turns off the flags specified in @a flags.  Other flags are untouched.
 *
 * @param hash_ctx   The hash context to be operated on.
 * @param flags      The flags to be reset in the context.  These can be ORed
 *                   members of #fsl_shw_hash_ctx_flags_t.
 */
void fsl_shw_hco_clear_flags(fsl_shw_hco_t * hash_ctx, uint32_t flags);

	  /*! @} *//* end hcops */

/*****************************************************************************/

/*! @addtogroup hmcops
    @{ */

/*!
 * Initialize an HMAC Context Object.
 *
 * This function must be called before performing any other operation with the
 * Object.  It sets the current message length and hash algorithm in the HMAC
 * context object.
 *
 * @param      hmac_ctx  The HMAC context to operate upon.
 * @param      algorithm The hash algorithm to be used (#FSL_HASH_ALG_MD5,
 *                       #FSL_HASH_ALG_SHA256, etc).
 *
 */
void fsl_shw_hmco_init(fsl_shw_hmco_t * hmac_ctx, fsl_shw_hash_alg_t algorithm);

/*!
 * Set flags in an HMAC Context Object.
 *
 * Turns on the flags specified in @a flags.  Other flags are untouched.
 *
 * @param hmac_ctx   The HMAC context to be operated on.
 * @param flags      The flags to be set in the context.  These can be ORed
 *                   members of #fsl_shw_hmac_ctx_flags_t.
 */
void fsl_shw_hmco_set_flags(fsl_shw_hmco_t * hmac_ctx, uint32_t flags);

/*!
 * Clear flags in an HMAC Context Object.
 *
 * Turns off the flags specified in @a flags.  Other flags are untouched.
 *
 * @param hmac_ctx   The HMAC context to be operated on.
 * @param flags      The flags to be reset in the context.  These can be ORed
 *                   members of #fsl_shw_hmac_ctx_flags_t.
 */
void fsl_shw_hmco_clear_flags(fsl_shw_hmco_t * hmac_ctx, uint32_t flags);

/*! @} */

/*****************************************************************************/

/*! @addtogroup sccops
    @{ */

/*!
 * Initialize a Symmetric Cipher Context Object.
 *
 * This function must be called before performing any other operation with the
 * Object.  This will set the @a mode and @a algorithm and initialize the
 * Object.
 *
 * @param sym_ctx   The context object to operate on.
 * @param algorithm The cipher algorithm this context will be used with.
 * @param mode      #FSL_SYM_MODE_CBC, #FSL_SYM_MODE_ECB, etc.
 *
 */
void fsl_shw_scco_init(fsl_shw_scco_t * sym_ctx,
		       fsl_shw_key_alg_t algorithm, fsl_shw_sym_mode_t mode);

/*!
 * Set the flags for a Symmetric Cipher Context.
 *
 * Turns on the flags specified in @a flags.  Other flags are untouched.
 *
 * @param sym_ctx  The context object to operate on.
 * @param flags    The flags to reset (one or more values from
 *                 #fsl_shw_sym_ctx_flags_t ORed together).
 *
 */
void fsl_shw_scco_set_flags(fsl_shw_scco_t * sym_ctx, uint32_t flags);

/*!
 * Clear some flags in a Symmetric Cipher Context Object.
 *
 * Turns off the flags specified in @a flags.  Other flags are untouched.
 *
 * @param sym_ctx  The context object to operate on.
 * @param flags    The flags to reset (one or more values from
 *                 #fsl_shw_sym_ctx_flags_t ORed together).
 *
 */
void fsl_shw_scco_clear_flags(fsl_shw_scco_t * sym_ctx, uint32_t flags);

/*!
 * Set the Context (IV) for a Symmetric Cipher Context.
 *
 * This is to set the context/IV for #FSL_SYM_MODE_CBC mode, or to set the
 * context (the S-Box and pointers) for ARC4.  The full context size will
 * be copied.
 *
 * @param sym_ctx  The context object to operate on.
 * @param context  A pointer to the buffer which contains the context.
 *
 */
void fsl_shw_scco_set_context(fsl_shw_scco_t * sym_ctx, uint8_t * context);

/*!
 * Get the Context for a Symmetric Cipher Context.
 *
 * This is to retrieve the context/IV for #FSL_SYM_MODE_CBC mode, or to
 * retrieve context (the S-Box and pointers) for ARC4.  The full context
 * will be copied.
 *
 * @param      sym_ctx  The context object to operate on.
 * @param[out] context  Pointer to location where context will be stored.
 */
void fsl_shw_scco_get_context(const fsl_shw_scco_t * sym_ctx,
			      uint8_t * context);

/*!
 * Set the Counter Value for a Symmetric Cipher Context.
 *
 * This will set the Counter Value for CTR mode.
 *
 * @param sym_ctx  The context object to operate on.
 * @param counter  The starting counter value.  The number of octets.
 *                 copied will be the block size for the algorithm.
 * @param modulus  The modulus for controlling the incrementing of the counter.
 *
 */
void fsl_shw_scco_set_counter_info(fsl_shw_scco_t * sym_ctx,
				   const uint8_t * counter,
				   fsl_shw_ctr_mod_t modulus);

/*!
 * Get the Counter Value for a Symmetric Cipher Context.
 *
 * This will retrieve the Counter Value is for CTR mode.
 *
 * @param sym_ctx         The context object to query.
 * @param[out] counter    Pointer to location to store the current counter
 *                        value.  The number of octets copied will be the
 *                        block size for the algorithm.
 * @param[out] modulus    Pointer to location to store the modulus.
 *
 */
void fsl_shw_scco_get_counter_info(const fsl_shw_scco_t * sym_ctx,
				   uint8_t * counter,
				   fsl_shw_ctr_mod_t * modulus);

	  /*! @} *//* end sccops */

/*****************************************************************************/

/*! @addtogroup accoops
    @{ */

/*!
 * Initialize a Authentication-Cipher Context.
 *
 * @param auth_object  Pointer to object to operate on.
 * @param mode         The mode for this object (only #FSL_ACC_MODE_CCM
 *                     supported).
 */
void fsl_shw_acco_init(fsl_shw_acco_t * auth_object, fsl_shw_acc_mode_t mode);

/*!
 * Set the flags for a Authentication-Cipher Context.
 *
 * Turns on the flags specified in @a flags.  Other flags are untouched.
 *
 * @param auth_object  Pointer to object to operate on.
 * @param flags        The flags to set (one or more from
 *                     #fsl_shw_auth_ctx_flags_t ORed together).
 *
 */
void fsl_shw_acco_set_flags(fsl_shw_acco_t * auth_object, uint32_t flags);

/*!
 * Clear some flags in a Authentication-Cipher Context Object.
 *
 * Turns off the flags specified in @a flags.  Other flags are untouched.
 *
 * @param auth_object  Pointer to object to operate on.
 * @param flags        The flags to reset (one or more from
 *                     #fsl_shw_auth_ctx_flags_t ORed together).
 *
 */
void fsl_shw_acco_clear_flags(fsl_shw_acco_t * auth_object, uint32_t flags);

/*!
 * Set up the Authentication-Cipher Object for CCM mode.
 *
 * This will set the @a auth_object for CCM mode and save the @a ctr,
 * and @a mac_length.  This function can be called instead of
 * #fsl_shw_acco_init().
 *
 * The parameter @a ctr is Counter Block 0, (counter value 0), which is for the
 * MAC.
 *
 * @param auth_object  Pointer to object to operate on.
 * @param algorithm    Cipher algorithm.  Only AES is supported.
 * @param ctr          The initial counter value.
 * @param mac_length   The number of octets used for the MAC.  Valid values are
 *                     4, 6, 8, 10, 12, 14, and 16.
 */
void fsl_shw_acco_set_ccm(fsl_shw_acco_t * auth_object,
			  fsl_shw_key_alg_t algorithm,
			  const uint8_t * ctr, uint8_t mac_length);

/*!
 * Format the First Block (IV) & Initial Counter Value per NIST CCM.
 *
 * This function will also set the IV and CTR values per Appendix A of NIST
 * Special Publication 800-38C (May 2004).  It will also perform the
 * #fsl_shw_acco_set_ccm() operation with information derived from this set of
 * parameters.
 *
 * Note this function assumes the algorithm is AES.  It initializes the
 * @a auth_object by setting the mode to #FSL_ACC_MODE_CCM and setting the
 * flags to be #FSL_ACCO_NIST_CCM.
 *
 * @param auth_object  Pointer to object to operate on.
 * @param t_length     The number of octets used for the MAC.  Valid values are
 *                     4, 6, 8, 10, 12, 14, and 16.
 * @param ad_length    Number of octets of Associated Data (may be zero).
 * @param q_length     A value for the size of the length of @a q field.  Valid
 *                     values are 1-8.
 * @param n            The Nonce (packet number or other changing value). Must
 *                     be (15 - @a q_length) octets long.
 * @param q            The value of Q (size of the payload in octets).
 *
 */
void fsl_shw_ccm_nist_format_ctr_and_iv(fsl_shw_acco_t * auth_object,
					uint8_t t_length,
					uint32_t ad_length,
					uint8_t q_length,
					const uint8_t * n, uint32_t q);

/*!
 * Update the First Block (IV) & Initial Counter Value per NIST CCM.
 *
 * This function will set the IV and CTR values per Appendix A of NIST Special
 * Publication 800-38C (May 2004).
 *
 * Note this function assumes that #fsl_shw_ccm_nist_format_ctr_and_iv() has
 * previously been called on the @a auth_object.
 *
 * @param auth_object  Pointer to object to operate on.
 * @param n             The Nonce (packet number or other changing value). Must
 *                      be (15 - @a q_length) octets long.
 * @param q             The value of Q (size of the payload in octets).
 *
 */
void fsl_shw_ccm_nist_update_ctr_and_iv(fsl_shw_acco_t * auth_object,
					const uint8_t * n, uint32_t q);

	 /* @} *//* accoops */

/******************************************************************************
 * Library functions
 *****************************************************************************/

/*! @addtogroup miscfuns
    @{ */

/* REQ-S2LRD-PINTFC-API-GEN-003 */
/*!
 * Determine the hardware security capabilities of this platform.
 *
 * Though a user context object is passed into this function, it will always
 * act in a non-blocking manner.
 *
 * @param  user_ctx   The user context which will be used for the query.
 *
 * @return  A pointer to the capabilities object.
 */
extern fsl_shw_pco_t *fsl_shw_get_capabilities(fsl_shw_uco_t * user_ctx);

/* REQ-S2LRD-PINTFC-API-GEN-004 */
/*!
 * Create an association between the user and the provider of the API.
 *
 * @param  user_ctx   The user context which will be used for this association.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_register_user(fsl_shw_uco_t * user_ctx);

/* REQ-S2LRD-PINTFC-API-GEN-005 */
/*!
 * Destroy the association between the user and the provider of the API.
 *
 * @param  user_ctx   The user context which is no longer needed.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_deregister_user(fsl_shw_uco_t * user_ctx);

/* REQ-S2LRD-PINTFC-API-GEN-006 */
/*!
 * Retrieve results from earlier operations.
 *
 * @param         user_ctx     The user's context.
 * @param         result_size  The number of array elements of @a results.
 * @param[in,out] results      Pointer to first of the (array of) locations to
 *                             store results.
 * @param[out]    result_count Pointer to store the number of results which
 *                             were returned.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_get_results(fsl_shw_uco_t * user_ctx,
					    uint16_t result_size,
					    fsl_shw_result_t results[],
					    uint16_t * result_count);

/*!
 * Allocate a block of secure memory
 *
 * @param       user_ctx        User context
 * @param       size            Memory size (octets).  Note: currently only
 *                              supports only single-partition sized blocks.
 * @param       UMID            User Mode ID to use when registering the
 *                              partition.
 * @param       permissions     Permissions to initialize the partition with.
 *                              Can be made by ORing flags from the
 *                              #fsl_shw_permission_t.
 *
 * @return                      Address of the allocated memory.  NULL if the
 *                              call was not successful.
 */
extern void *fsl_shw_smalloc(fsl_shw_uco_t * user_ctx,
			     uint32_t size,
			     const uint8_t * UMID, uint32_t permissions);

/*!
 * Free a block of secure memory that was allocated with #fsl_shw_smalloc
 *
 * @param       user_ctx        User context
 * @param       address         Address of the block of secure memory to be
 *                              released.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_sfree(fsl_shw_uco_t * user_ctx, void *address);

/*!
 * Diminish the permissions of a block of secure memory.  Note that permissions
 * can only be revoked.
 *
 * @param       user_ctx        User context
 * @param       address         Base address of the secure memory to work with
 * @param       permissions     Permissions to initialize the partition with.
 *                              Can be made by ORing flags from the
 *                              #fsl_shw_permission_t.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_diminish_perms(fsl_shw_uco_t * user_ctx,
					       void *address,
					       uint32_t permissions);

/*!
 * @brief   Encrypt a region of secure memory using the hardware secret key
 *
 * @param       user_ctx        User context
 * @param       partition_base  Base address of the partition
 * @param       offset_bytes    Offset of data from the partition base
 * @param       byte_count      Length of the data to encrypt
 * @param       black_data      Location to store the encrypted data
 * @param       IV              IV to use for the encryption routine
 * @param       cypher_mode     Cyphering mode to use, specified by type
 *                              #fsl_shw_cypher_mode_t
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t
do_scc_encrypt_region(fsl_shw_uco_t * user_ctx,
		      void *partition_base, uint32_t offset_bytes,
		      uint32_t byte_count, uint8_t * black_data,
		      uint32_t * IV, fsl_shw_cypher_mode_t cypher_mode);

/*!
 * @brief   Decrypt a region of secure memory using the hardware secret key
 *
 * @param       user_ctx        User context
 * @param       partition_base  Base address of the partition
 * @param       offset_bytes    Offset of data from the partition base
 * @param       byte_count      Length of the data to encrypt
 * @param       black_data      Location to store the encrypted data
 * @param       IV              IV to use for the encryption routine
 * @param       cypher_mode     Cyphering mode to use, specified by type
 *                              #fsl_shw_cypher_mode_t
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t
do_scc_decrypt_region(fsl_shw_uco_t * user_ctx,
		      void *partition_base, uint32_t offset_bytes,
		      uint32_t byte_count, const uint8_t * black_data,
		      uint32_t * IV, fsl_shw_cypher_mode_t cypher_mode);

	  /*! @} *//* miscfuns */

/*! @addtogroup opfuns
    @{ */

/* REQ-S2LRD-PINTFC-API-BASIC-SYM-002 */
/* PINTFC-API-BASIC-SYM-ARC4-001 */
/* PINTFC-API-BASIC-SYM-ARC4-002 */
/*!
 * Encrypt a stream of data with a symmetric-key algorithm.
 *
 * In ARC4, and also in #FSL_SYM_MODE_CBC and #FSL_SYM_MODE_CTR modes, the
 * flags of the @a sym_ctx object will control part of the operation of this
 * function.  The #FSL_SYM_CTX_INIT flag means that there is no context info in
 * the object.  The #FSL_SYM_CTX_LOAD means to use information in the
 * @a sym_ctx at the start of the operation, and the #FSL_SYM_CTX_SAVE flag
 * means to update the object's context information after the operation has
 * been performed.
 *
 * All of the data for an operation can be run through at once using the
 * #FSL_SYM_CTX_INIT or #FSL_SYM_CTX_LOAD flags, as appropriate, and then using
 * a @a length for the whole of the data.
 *
 * If a #FSL_SYM_CTX_SAVE flag were added, an additional call to the function
 * would "pick up" where the previous call left off, allowing the user to
 * perform the larger function in smaller steps.
 *
 * In #FSL_SYM_MODE_CBC and #FSL_SYM_MODE_ECB modes, the @a length must always
 * be a multiple of the block size for the algorithm being used.  For proper
 * operation in #FSL_SYM_MODE_CTR mode, the @a length must be a multiple of the
 * block size until the last operation on the total octet stream.
 *
 * Some users of ARC4 may want to compute the context (S-Box and pointers) from
 * the key before any data is available.  This may be done by running this
 * function with a @a length of zero, with the init & save flags flags on in
 * the @a sym_ctx.  Subsequent operations would then run as normal with the
 * load and save flags.  Note that they key object is still required.
 *
 * @param         user_ctx  A user context from #fsl_shw_register_user().
 * @param         key_info  Key and algorithm  being used for this operation.
 * @param[in,out] sym_ctx   Info on cipher mode, state of the cipher.
 * @param         length   Length, in octets, of the pt (and ct).
 * @param         pt       pointer to plaintext to be encrypted.
 * @param[out]    ct       pointer to where to store the resulting ciphertext.
 *
 * @return    A return code of type #fsl_shw_return_t.
 *
 */
extern fsl_shw_return_t fsl_shw_symmetric_encrypt(fsl_shw_uco_t * user_ctx,
						  fsl_shw_sko_t * key_info,
						  fsl_shw_scco_t * sym_ctx,
						  uint32_t length,
						  const uint8_t * pt,
						  uint8_t * ct);

/* PINTFC-API-BASIC-SYM-002 */
/* PINTFC-API-BASIC-SYM-ARC4-001 */
/* PINTFC-API-BASIC-SYM-ARC4-002 */
/*!
 * Decrypt a stream of data with a symmetric-key algorithm.
 *
 * In ARC4, and also in #FSL_SYM_MODE_CBC and #FSL_SYM_MODE_CTR modes, the
 * flags of the @a sym_ctx object will control part of the operation of this
 * function.  The #FSL_SYM_CTX_INIT flag means that there is no context info in
 * the object.  The #FSL_SYM_CTX_LOAD means to use information in the
 * @a sym_ctx at the start of the operation, and the #FSL_SYM_CTX_SAVE flag
 * means to update the object's context information after the operation has
 * been performed.
 *
 * All of the data for an operation can be run through at once using the
 * #FSL_SYM_CTX_INIT or #FSL_SYM_CTX_LOAD flags, as appropriate, and then using
 * a @a length for the whole of the data.
 *
 * If a #FSL_SYM_CTX_SAVE flag were added, an additional call to the function
 * would "pick up" where the previous call left off, allowing the user to
 * perform the larger function in smaller steps.
 *
 * In #FSL_SYM_MODE_CBC and #FSL_SYM_MODE_ECB modes, the @a length must always
 * be a multiple of the block size for the algorithm being used.  For proper
 * operation in #FSL_SYM_MODE_CTR mode, the @a length must be a multiple of the
 * block size until the last operation on the total octet stream.
 *
 * Some users of ARC4 may want to compute the context (S-Box and pointers) from
 * the key before any data is available.  This may be done by running this
 * function with a @a length of zero, with the #FSL_SYM_CTX_INIT &
 * #FSL_SYM_CTX_SAVE flags on in the @a sym_ctx.  Subsequent operations would
 * then run as normal with the load & save flags.  Note that they key object is
 * still required.
 *
 * @param      user_ctx  A user context from #fsl_shw_register_user().
 * @param      key_info The key and algorithm being used in this operation.
 * @param[in,out] sym_ctx Info on cipher mode, state of the cipher.
 * @param      length   Length, in octets, of the ct (and pt).
 * @param      ct       pointer to ciphertext to be decrypted.
 * @param[out] pt       pointer to where to store the resulting plaintext.
 *
 * @return    A return code of type #fsl_shw_return_t
 *
 */
extern fsl_shw_return_t fsl_shw_symmetric_decrypt(fsl_shw_uco_t * user_ctx,
						  fsl_shw_sko_t * key_info,
						  fsl_shw_scco_t * sym_ctx,
						  uint32_t length,
						  const uint8_t * ct,
						  uint8_t * pt);

/* REQ-S2LRD-PINTFC-API-BASIC-HASH-005 */
/*!
 * Hash a stream of data with a cryptographic hash algorithm.
 *
 * The flags in the @a hash_ctx control the operation of this function.
 *
 * Hashing functions work on 64 octets of message at a time.  Therefore, when
 * any partial hashing of a long message is performed, the message @a length of
 * each segment must be a multiple of 64.  When ready to
 * #FSL_HASH_FLAGS_FINALIZE the hash, the @a length may be any value.
 *
 * With the #FSL_HASH_FLAGS_INIT and #FSL_HASH_FLAGS_FINALIZE flags on, a
 * one-shot complete hash, including padding, will be performed.  The @a length
 * may be any value.
 *
 * The first octets of a data stream can be hashed by setting the
 * #FSL_HASH_FLAGS_INIT and #FSL_HASH_FLAGS_SAVE flags.  The @a length must be
 * a multiple of 64.
 *
 * The flag #FSL_HASH_FLAGS_LOAD is used to load a context previously saved by
 * #FSL_HASH_FLAGS_SAVE.  The two in combination will allow a (multiple-of-64
 * octets) 'middle sequence' of the data stream to be hashed with the
 * beginning.  The @a length must again be a multiple of 64.
 *
 * Since the flag #FSL_HASH_FLAGS_LOAD is used to load a context previously
 * saved by #FSL_HASH_FLAGS_SAVE, the #FSL_HASH_FLAGS_LOAD and
 * #FSL_HASH_FLAGS_FINALIZE flags, used together, can be used to finish the
 * stream.  The @a length may be any value.
 *
 * If the user program wants to do the padding for the hash, it can leave off
 * the #FSL_HASH_FLAGS_FINALIZE flag.  The @a length must then be a multiple of
 * 64 octets.
 *
 * @param      user_ctx  A user context from #fsl_shw_register_user().
 * @param[in,out] hash_ctx Hashing algorithm and state of the cipher.
 * @param      msg       Pointer to the data to be hashed.
 * @param      length    Length, in octets, of the @a msg.
 * @param[out] result    If not null, pointer to where to store the hash
 *                       digest.
 * @param      result_len Number of octets to store in @a result.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_hash(fsl_shw_uco_t * user_ctx,
				     fsl_shw_hco_t * hash_ctx,
				     const uint8_t * msg,
				     uint32_t length,
				     uint8_t * result, uint32_t result_len);

/* REQ-S2LRD-PINTFC-API-BASIC-HMAC-001 */
/*!
 * Precompute the Key hashes for an HMAC operation.
 *
 * This function may be used to calculate the inner and outer precomputes,
 * which are the hash contexts resulting from hashing the XORed key for the
 * 'inner hash' and the 'outer hash', respectively, of the HMAC function.
 *
 * After execution of this function, the @a hmac_ctx will contain the
 * precomputed inner and outer contexts, so that they may be used by
 * #fsl_shw_hmac().  The flags of @a hmac_ctx will be updated with
 * #FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT to mark their presence.  In addition, the
 * #FSL_HMAC_FLAGS_INIT flag will be set.
 *
 * @param      user_ctx  A user context from #fsl_shw_register_user().
 * @param      key_info  The key being used in this operation.  Key must be
 *                       1 to 64 octets long.
 * @param[in,out] hmac_ctx The context which controls, by its flags and
 *                         algorithm, the operation of this function.
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_hmac_precompute(fsl_shw_uco_t * user_ctx,
						fsl_shw_sko_t * key_info,
						fsl_shw_hmco_t * hmac_ctx);

/* REQ-S2LRD-PINTFC-API-BASIC-HMAC-002 */
/*!
 * Continue, finalize, or one-shot an HMAC operation.
 *
 * There are a number of ways to use this function.  The flags in the
 * @a hmac_ctx object will determine what operations occur.
 *
 * If #FSL_HMAC_FLAGS_INIT is set, then the hash will be started either from
 * the @a key_info, or from the precomputed inner hash value in the
 * @a hmac_ctx, depending on the value of #FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT.
 *
 * If, instead, #FSL_HMAC_FLAGS_LOAD is set, then the hash will be continued
 * from the ongoing inner hash computation in the @a hmac_ctx.
 *
 * If #FSL_HMAC_FLAGS_FINALIZE are set, then the @a msg will be padded, hashed,
 * the outer hash will be performed, and the @a result will be generated.
 *
 * If the #FSL_HMAC_FLAGS_SAVE flag is set, then the (ongoing or final) digest
 * value will be stored in the ongoing inner hash computation field of the @a
 * hmac_ctx.
 *
 * @param      user_ctx  A user context from #fsl_shw_register_user().
 * @param key_info       If #FSL_HMAC_FLAGS_INIT is set in the @a hmac_ctx,
 *                       this is the key being used in this operation, and the
 *                       IPAD.  If #FSL_HMAC_FLAGS_INIT is set in the @a
 *                       hmac_ctx and @a key_info is NULL, then
 *                       #fsl_shw_hmac_precompute() has been used to populate
 *                       the @a inner_precompute and @a outer_precompute
 *                       contexts.  If #FSL_HMAC_FLAGS_INIT is not set, this
 *                       parameter is ignored.

 * @param[in,out] hmac_ctx The context which controls, by its flags and
 *                       algorithm, the operation of this function.
 * @param      msg               Pointer to the message to be hashed.
 * @param      length            Length, in octets, of the @a msg.
 * @param[out] result            Pointer, of @a result_len octets, to where to
 *                               store the HMAC.
 * @param      result_len        Length of @a result buffer.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_hmac(fsl_shw_uco_t * user_ctx,
				     fsl_shw_sko_t * key_info,
				     fsl_shw_hmco_t * hmac_ctx,
				     const uint8_t * msg,
				     uint32_t length,
				     uint8_t * result, uint32_t result_len);

/* REQ-S2LRD-PINTFC-API-BASIC-RNG-002 */
/*!
 * Get random data.
 *
 * @param      user_ctx  A user context from #fsl_shw_register_user().
 * @param      length    The number of octets of @a data being requested.
 * @param[out] data      A pointer to a location of @a length octets to where
 *                       random data will be returned.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_get_random(fsl_shw_uco_t * user_ctx,
					   uint32_t length, uint8_t * data);

/* REQ-S2LRD-PINTFC-API-BASIC-RNG-002 */
/*!
 * Add entropy to random number generator.
 *
 * @param      user_ctx  A user context from #fsl_shw_register_user().
 * @param      length    Number of bytes at @a data.
 * @param      data      Entropy to add to random number generator.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_add_entropy(fsl_shw_uco_t * user_ctx,
					    uint32_t length, uint8_t * data);

/*!
 * Perform Generation-Encryption by doing a Cipher and a Hash.
 *
 * Generate the authentication value @a auth_value as well as encrypt the @a
 * payload into @a ct (the ciphertext).  This is a one-shot function, so all of
 * the @a auth_data and the total message @a payload must passed in one call.
 * This also means that the flags in the @a auth_ctx must be #FSL_ACCO_CTX_INIT
 * and #FSL_ACCO_CTX_FINALIZE.
 *
 * @param      user_ctx         A user context from #fsl_shw_register_user().
 * @param      auth_ctx         Controlling object for Authenticate-decrypt.
 * @param      cipher_key_info  The key being used for the cipher part of this
 *                              operation.  In CCM mode, this key is used for
 *                              both parts.
 * @param      auth_key_info    The key being used for the authentication part
 *                              of this operation.  In CCM mode, this key is
 *                              ignored and may be NULL.
 * @param      auth_data_length Length, in octets, of @a auth_data.
 * @param      auth_data        Data to be authenticated but not encrypted.
 * @param      payload_length   Length, in octets, of @a payload.
 * @param      payload          Pointer to the plaintext to be encrypted.
 * @param[out] ct               Pointer to the where the encrypted @a payload
 *                              will be stored.  Must be @a payload_length
 *                              octets long.
 * @param[out] auth_value       Pointer to where the generated authentication
 *                              field will be stored. Must be as many octets as
 *                              indicated by MAC length in the @a function_ctx.
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_gen_encrypt(fsl_shw_uco_t * user_ctx,
					    fsl_shw_acco_t * auth_ctx,
					    fsl_shw_sko_t * cipher_key_info,
					    fsl_shw_sko_t * auth_key_info,
					    uint32_t auth_data_length,
					    const uint8_t * auth_data,
					    uint32_t payload_length,
					    const uint8_t * payload,
					    uint8_t * ct, uint8_t * auth_value);

/*!
 * Perform Authentication-Decryption in Cipher + Hash.
 *
 * This function will perform a one-shot decryption of a data stream as well as
 * authenticate the authentication value.  This is a one-shot function, so all
 * of the @a auth_data and the total message @a payload must passed in one
 * call.  This also means that the flags in the @a auth_ctx must be
 * #FSL_ACCO_CTX_INIT and #FSL_ACCO_CTX_FINALIZE.
 *
 * @param      user_ctx         A user context from #fsl_shw_register_user().
 * @param      auth_ctx         Controlling object for Authenticate-decrypt.
 * @param      cipher_key_info  The key being used for the cipher part of this
 *                              operation.  In CCM mode, this key is used for
 *                              both parts.
 * @param      auth_key_info    The key being used for the authentication part
 *                              of this operation.  In CCM mode, this key is
 *                              ignored and may be NULL.
 * @param      auth_data_length Length, in octets, of @a auth_data.
 * @param      auth_data        Data to be authenticated but not decrypted.
 * @param      payload_length   Length, in octets, of @a ct and @a pt.
 * @param      ct               Pointer to the encrypted input stream.
 * @param      auth_value       The (encrypted) authentication value which will
 *                              be authenticated.  This is the same data as the
 *                              (output) @a auth_value argument to
 *                              #fsl_shw_gen_encrypt().
 * @param[out] payload          Pointer to where the plaintext resulting from
 *                              the decryption will be stored.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_auth_decrypt(fsl_shw_uco_t * user_ctx,
					     fsl_shw_acco_t * auth_ctx,
					     fsl_shw_sko_t * cipher_key_info,
					     fsl_shw_sko_t * auth_key_info,
					     uint32_t auth_data_length,
					     const uint8_t * auth_data,
					     uint32_t payload_length,
					     const uint8_t * ct,
					     const uint8_t * auth_value,
					     uint8_t * payload);

/*!
 * Establish the key in a protected location, which can be the system keystore,
 * user keystore, or (on platforms that support it) as a Platform Key.
 *
 * By default, keys initialized with #fsl_shw_sko_init() will be placed into
 * the system keystore.  The user can cause the key to be established in a
 * user keystore by first calling #fsl_shw_sko_set_keystore() on the key.
 * Normally, keys in the system keystore can only be used for hardware
 * encrypt or decrypt operations, however if the #FSL_SKO_KEY_SW_KEY flag is
 * applied using #fsl_shw_sko_set_flags(), the key will be established as a
 * software key, which can then be read out using #fsl_shw_read_key().
 *
 * Keys initialized with #fsl_shw_sko_init_pf_key() are established as a
 * Platform Key.  Their use is covered in @ref di_sec.
 *
 * This function only needs to be used when unwrapping a key, setting up a key
 * which could be wrapped with a later call to #fsl_shw_extract_key(), or
 * setting up a key as a Platform Key.  Normal cleartext keys can simply be
 * placed into #fsl_shw_sko_t key objects with #fsl_shw_sko_set_key() and used
 * directly.
 *
 * The maximum key size supported for wrapped/unwrapped keys is 32 octets.
 * (This is the maximum reasonable key length on Sahara - 32 octets for an HMAC
 * key based on SHA-256.)  The key size is determined by the @a key_info.  The
 * expected length of @a key can be determined by
 * #fsl_shw_sko_calculate_wrapped_size()
 *
 * The protected key will not be available for use until this operation
 * successfully completes.
 *
 * This feature is not available for all platforms, nor for all algorithms and
 * modes.
 *
 * @param      user_ctx         A user context from #fsl_shw_register_user().
 * @param[in,out] key_info      The information about the key to be which will
 *                              be established.  In the create case, the key
 *                              length must be set.
 * @param      establish_type   How @a key will be interpreted to establish a
 *                              key for use.
 * @param key                   If @a establish_type is #FSL_KEY_WRAP_UNWRAP,
 *                              this is the location of a wrapped key.  If
 *                              @a establish_type is #FSL_KEY_WRAP_CREATE, this
 *                              parameter can be @a NULL.  If @a establish_type
 *                              is #FSL_KEY_WRAP_ACCEPT, this is the location
 *                              of a plaintext key.
 */
extern fsl_shw_return_t fsl_shw_establish_key(fsl_shw_uco_t * user_ctx,
					      fsl_shw_sko_t * key_info,
					      fsl_shw_key_wrap_t establish_type,
					      const uint8_t * key);

/*!
 * Read the key value from a key object.
 *
 * Only a key marked as a software key (#FSL_SKO_KEY_SW_KEY) can be read with
 * this call.  It has no effect on the status of the key store.
 *
 * @param      user_ctx         A user context from #fsl_shw_register_user().
 * @param      key_info         The referenced key.
 * @param[out] key              The location to store the key value.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_read_key(fsl_shw_uco_t * user_ctx,
					 fsl_shw_sko_t * key_info,
					 uint8_t * key);

/*!
 * Wrap a key and retrieve the wrapped value.
 *
 * A wrapped key is a key that has been cryptographically obscured.  It is
 * only able to be used with keys that have been established by
 * #fsl_shw_establish_key().
 *
 * For keys established in the system or user keystore, this function will
 * also release the key (see #fsl_shw_release_key()) so that it must be re-
 * established before reuse.  This function will not release keys that are
 * established as a Platform Key, so a call to #fsl_shw_release_key() is
 * necessary to release those keys.
 *
 * This feature is not available for all platforms, nor for all algorithms and
 * modes.
 *
 * @param      user_ctx         A user context from #fsl_shw_register_user().
 * @param      key_info         The information about the key to be deleted.
 * @param[out] covered_key      The location to store the wrapped key.
 *                              (This size is based upon the maximum key size
 *                              of 32 octets).
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_extract_key(fsl_shw_uco_t * user_ctx,
					    fsl_shw_sko_t * key_info,
					    uint8_t * covered_key);

/*!
 * De-establish a key so that it can no longer be accessed.
 *
 * The key will need to be re-established before it can again be used.
 *
 * This feature is not available for all platforms, nor for all algorithms and
 * modes.
 *
 * @param      user_ctx         A user context from #fsl_shw_register_user().
 * @param      key_info         The information about the key to be deleted.
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_release_key(fsl_shw_uco_t * user_ctx,
					    fsl_shw_sko_t * key_info);

/*!
 * Cause the hardware to create a new random key for use by the secure memory
 * encryption hardware.
 *
 * Have the hardware use the secure hardware random number generator to load a
 * new secret key into the system's Random Key register.
 *
 * @param      user_ctx         A user context from #fsl_shw_register_user().
 *
 * @return    A return code of type #fsl_shw_return_t.
 */
extern fsl_shw_return_t fsl_shw_gen_random_pf_key(fsl_shw_uco_t * user_ctx);

/*!
 * Retrieve the detected tamper event.
 *
 * Note that if more than one event was detected, this routine will only ever
 * return one of them.
 *
 * @param[in]  user_ctx         A user context from #fsl_shw_register_user().
 * @param[out] tamperp          Location to store the tamper information.
 * @param[out] timestampp       Locate to store timestamp from hardwhare when
 *                              an event was detected.
 *
 *
 * @return    A return code of type #fsl_shw_return_t (for instance, if the platform
 *            is not in a fail state.
 */
extern fsl_shw_return_t fsl_shw_read_tamper_event(fsl_shw_uco_t * user_ctx,
						  fsl_shw_tamper_t * tamperp,
						  uint64_t * timestampp);

/*! @} *//* opfuns */

/* Insert example code into the API documentation. */

/*!
 * @example apitest.c
 */

/*!
 * @example sym.c
 */

/*!
 * @example rand.c
 */

/*!
 * @example hash.c
 */

/*!
 * @example hmac1.c
 */

/*!
 * @example hmac2.c
 */

/*!
 * @example gen_encrypt.c
 */

/*!
 * @example auth_decrypt.c
 */

/*!
 * @example wrapped_key.c
 */

/*!
 * @example smalloc.c
 */

/*!
 * @example user_keystore.c
 */

/*!
 * @example dryice.c
 */

#endif				/* API_DOC */

#endif				/* FSL_SHW_H */