emCrypt User Guide & Reference Manual
Cryptographic algorithm library.
emCrypt 2.36, January 30, 2023
Introduction
This manual describes the interfaces made available by emCrypt
to the application programmer.
What is emCrypt?
emCrypt is practical cryptographic algorithm library that is designed
to run on embedded systems. It is designed to be small, efficient, secure,
and broad enough to function as the basis of security protocols such as SSL,
SSH, and IPsec. emCrypt is the foundation of all SEGGER security
products — emSSL, emSSH, emSecure-RSA, emSecure-ECDSA — and is shared
between them.
emCrypt is not a library of algorithms for research into cryptography,
it does not target absolute performance with complex algorithms requiring
large working stores, nor does it offer every hashing and ciphering scheme
ever devised and found through Google. It does not offer the general ability
to mix algorithms and modes to construct encryption schemes that are of little
practical use. Should you require this, then emCrypt is not for you.
emCrypt targets what is needed for industry-standard protocols, and
to do this with robust, cleanly-engineered code. If you absolutely require
some scheme that we do not support, you can always ask us to devote some
engineering time to the problem.
emCrypt has the capability to use hardware accelerators, if they
are available, to accelerate ciphering, hashing, and public key
cryptography. SEGGER have written support for several popular embedded
cryptographic accelerators so customers can immediately put these to use
in end applications.
Target audience
This manual is a reference for the emCrypt cryptographic library.
It is not intended as a tutorial on security, nor will it help you
design secure protocols. Therefore, we assume that you are familiar
with cryptographic principles and simply need to know how to put
emCrypt to use and, optionally, gain an insight into the
underlying implementation techniques.
Package content
emCrypt is provided in source code and the exact content
depends upon the versions and add-ons that you purchase.
The following table shows the content of the package:
Files | Description |
Config | Configuration header files. |
CRYPTO | emCrypt cryptographic library source code. |
Doc | emCrypt documentation. |
Sample/Config | Example emCrypt user configuration. |
SEGGER | SEGGER software component source code. |
Application | emCrypt sample applications. |
Sample applications
The emCrypt library ships with a number of sample applications that demonstrate how
to integrate IoT capability into your application. Each sample application
demonstrates a specific capability of the emCrypt library or is a small incremental
step over previous examples.
Benchmark samples
The sample applications are:
Application | Description |
CRYPTO_Bench_AES.c | Benchmark AES performance. |
CRYPTO_Bench_DES.c | Benchmark DES and TDES performance. |
CRYPTO_Bench_Camellia.c | Benchmark Camellia performance. |
CRYPTO_Bench_ECDH.c | Benchmark ECDH key agreement performance. |
CRYPTO_Bench_ECDSA.c | Benchmark ECDSA sign and verify performance. |
CRYPTO_Bench_Hashes.c | Benchmark performance of all hash algorithms. |
CRYPTO_Bench_MD5.c | Benchmark MD5 performance. |
CRYPTO_Bench_ModExp.c | Benchmark performance of all modular exponentiation alogorithms by implementation. |
CRYPTO_Bench_RIPEMD160.c | Benchmark RIPEMD-160 performance. |
CRYPTO_Bench_RNG.c | Benchmark performance of all DRBG algorithms. |
CRYPTO_Bench_SHA1.c | Benchmark SHA-1 performance. |
CRYPTO_Bench_SHA256.c | Benchmark SHA-256 performance. |
CRYPTO_Bench_SHA512.c | Benchmark SHA-512 performance. |
CRYPTO_Bench_SHA3.c | Benchmark SHA-3 performance. |
Self-test samples
The sample applications are:
Application | Description |
CRYPTO_Test_All.c | Run all algorithm self-tests. |
CRYPTO_Test_AES.c | Run AES self-tests. |
CRYPTO_Test_DES.c | Run DES self-tests. |
CRYPTO_Test_SEED.c | Run SEED self-tests. |
CRYPTO_Test_ARIA.c | Run ARIA self-tests. |
CRYPTO_Test_Camellia.c | Run Camellia self-tests. |
CRYPTO_Test_MD5.c | Run MD5 self-tests. |
CRYPTO_Test_RIPEMD160c | Run RIPEMD-160 self-tests. |
CRYPTO_Test_SHA1.c | Run SHA-1 self-tests. |
CRYPTO_Test_SHA256.c | Run SHA-256 self-tests. |
CRYPTO_Test_SHA512.c | Run SHA-512 self-tests. |
CRYPTO_Test_EdDSA.c | Run Ed25519 self-tests. |
Other samples
The sample applications are:
Application | Description |
CRYPTO_DumpContextSize.c | Display all algorithm context sizes. |
Naming conventions
emCrypt uses a number of naming conventions for functions, types,
variables, and preprocessor symbols. These conventions are described
in this section.
Product namespace
All emCrypt functions, types, variables, and preprocessor symbols
are prefixed by CRYPTO to indicate they are part of the emCrypt
product and to prevent name clashes with other libraries.
Abstract interfaces (APIs)
An emCrypt API is a generic interface to a set of data and functions
that implement that interface. The API is defined as a C structure
grouping data members and function pointers and can can be viewed as a
C++ abstract class or as a Java interface.
The name of the interface, as a C type, is of the following form:
CRYPTO_name_API
The CRYPTO prefix defines the namespace as above. The suffix API
indicates that the type is an emCrypt API.
emCrypt has the following abstract APIs:
API name | Description |
CRYPTO_RNG_API | Interface for random numbers. |
CRYPTO_CIPHER_API | Interface for ciphers. |
CRYPTO_HASH_API | Interface for message digest algorithms. |
CRYPTO_MAC_API | Interface for message authentication code algorithms. |
CRYPTO_MODEXP_API | Interface for modular exponentiation algorithms. |
emCrypt offers concrete implementations conforming to these APIs.
A function that conforms to a function prototype in an API places
the name of the API immediately following the CRYPTO prefix:
CRYPTO_api-name_...
As an example, the function that initializes an AES cipher in
encryption mode and that conforms to the CIPHER API is:
void CRYPTO_CIPHER_AES_InitEncrypt(void *pSelf, const U8 *pKey, unsigned KeyLen);
Functions accepting fixed-size data
In some cases there are two implementations of a function where both do
essentially the same work. One implementation takes a length
parameter and the other does not. When the length can be implied
from the context, it is not necessary to pass the length as a parameter.
For instance, initializing an AES cipher in encryption mode is a matter
of calling the following function:
void CRYPTO_CIPHER_AES_InitEncrypt(void *pSelf, const U8 *pKey, unsigned KeyLen);
In many cases the key length is known in advance, for instance when
initializing AES encryption with a 128-bit key (AES-128). In this case,
emCrypt offers an additional function that provides this capability:
void CRYPTO_CIPHER_AES_128_InitEncrypt(void *pSelf, const U8 *pKey);
This drops the key length and places it where it is commonly expected,
in this case after the “AES”.
This convention is applied consistently throughout emCrypt. For instance,
even though the name for 128-bit KMAC is standardized as KMAC128 by NIST,
emCrypt uses KMAC_128 separating the key length and algorithm.
Functions delivering fixed-size data
Following on from the previous section, there are functions that typically
deliver fixed-size data but are also required to deliver truncated data
by some algorithms. A MAC or hash is an example of this and, in the same
way as the key size above, two (or more) functions are provided.
The first delivers a MAC with the possibility of truncation:
void CRYPTO_MAC_HMAC_SHA1_Final(void *pSelf, U8 *pMAC, unsigned MACLen);
And the remainder deliver MACs of different (fixed) sizes:
void CRYPTO_MAC_HMAC_SHA1_Final_160(void *pSelf, U8 *pMAC);
void CRYPTO_MAC_HMAC_SHA1_Final_96 (void *pSelf, U8 *pMAC);
In this case the size of the data delivered is placed at the end of
the function name. The MAC functions above deliver 160 bits of data
(a full HMAC-SHA-1 MAC) and a 96-bit truncated MAC (HMAC-SHA-1-96).
The emCrypt convention is that all output size information is
placed at the end of the function name even though the algorithm
name (HMAC-SHA-1-96) would suggest that it should come after SHA1
and before Final.
Self-test names
The general naming convention is:
CRYPTO_algorithm[_mode]_source_SelfTest()
The algorithm refers to the algorithm under test (e.g. AES)
or a particular group of functions (e.g. MPI, multi-precision
integer arithmetic).
The mode is something such as signature (Sign), signature
verification (Verify), a cipher mode (e.g. GCM or CCM), or is
omitted if the self-test combines everything required
to test the module as a unit (e.g. a symmetric cipher).
The source describes the source of the test vectors, for
instance a standards document, a web page, or something else recognizable.
For test vectors that originate from NIST as part of the
CAVS suite, they would be named with “CAVS” as the source.
EMC are a source of some vectors, RFCs are sources of other
vectors, and others are taken from specifications with associated
test vectors available on the Internet.
API conventions
Parameter order
All functions that operate on an algorithm context always pass the
algorithm context as the first parameter.
All function that require a memory allocator context always pass
the context as the final parameter.
Output parameters always preceed input parameters.
Unless otherwise documented, all parameters that take a pointer to an
object require that the pointer be nonnull. If a null pointer is
acceptable to a function, it is documented as being acceptable in
the Parameter section or in the Additional Information section
if there are special or complex conditions for acceptability.
A special case is made for compound parameters where an address
and a size that define an object are passed to a function:
if the size is zero, the address may be the null pointer.
Design considerations
Multithreading and reentrancy
All algorithmic functions are designed to be reentrant. For those
that take a context, such as an encryption context, hash context,
memory allocation context and so on, reentrancy is guaranteed only
if each context in the two (or more) threads of execution is
different.
Sharing contexts between different functions requires a mutual
exclusion mechanism to protect the context. This mechanism is left
to the user to implement. Although possible, it is recommended that
memory allocators do not implement mutual exclusion themselves
as this leads to suboptimal performance in multithreaded systems—it
is much more efficient to ensure mutual exclusion above the emCrypt
API at the application level.
Dynamic memory usage
Some of the functions of emCrypt use data objects that may grow during operation,
for example the multi precision integers needed for asymmetric cryptography.
The caller has to provide a memory context (of type CRYPTO_MEM_CONTEXT) to all of these functions.
The memory context has to be initialized before it can be used.
This requires a memory allocator and a memory buffer of fixed size, that will be used to
store the dynamic objects. Segger provides several memory allocators for this purpose that are
shipped with emCrypt.
The memory context may be initialized globally for the whole application or
locally to perform only a few cryptographic operations.
It may be discarded if the objects stored in it are not used any more.
Example
//
// Example using SEGGER_MEM_SIMPLE_HEAP.
//
int Sign(const U8 *pData, U32 DataLen, U8 *pResult) {
int r;
SEGGER_MEM_SIMPLE_HEAP SimpleHeap;
SEGGER_MEM_CONTEXT MemContext;
U32 BigBuff[1024];
//
// Initialize memory context.
//
SEGGER_MEM_SIMPLE_HEAP_Init(&MemContext, &SimpleHeap,
&BigBuff[0], sizeof(BigBuff), 8);
//
// Perform cryptographic operation.
//
r = CRYPTO_RSA_PKCS1_SHA1_Sign(&PrivateKey, pData, DataLen,
NULL, 0, pResult, MAX_SIZE, &MemContext);
//
// Memory context is discarded upon return of the function.
//
return r;
}
Building emCrypt
This section describes how to build emCrypt on Windows and Linux.
Quick start
emCrypt is distributed with a CMake file that enables you to build
the demonstration emCrypt files on Windows and Linux to get up and
running quickly. This section describes how to use CMake to build
these examples using Visual Studio on Windows and using the standard
make utility on Linux.
Installing CMake
Before you can build emCrypt, you must install CMake 2.8 or later.
You can find CMake distributions for Windows on the CMake.org
download page, https://cmake.org/download/.
The distributed software, and this section, are accuracte using CMake 3.5.2.
For Linux, you can usually find and install precompiled versions of
CMake using whatever software installation tool comes with your particular
distribution.
Unpacking and configuring
Building on Windows
Once you can unzipped your application into a clean directory,
you will see a number of subdirectories and a top-level file called
CMakeLists.txt.
C:> dir
Directory of C:\Work
23/03/2017 21:53 <DIR> .
23/03/2017 21:53 <DIR> ..
23/03/2017 21:53 <DIR> Application
23/03/2017 21:38 1,931 CMakeLists.txt
23/03/2017 21:53 <DIR> Config
23/03/2017 21:53 <DIR> CRYPTO
23/03/2017 21:53 <DIR> Doc
23/03/2017 21:53 <DIR> Sample
23/03/2017 21:53 <DIR> SEGGER
23/03/2017 21:53 <DIR> Windows
C:> _
Typically, to keep directories from becoming polluted with build outputs
and temporary files, CMake users create an out-of-source build directory
that keeps their image clean:
C:> mkdir Build
C:> cd Build
C:> _
Once in the build directory, it’s time to configure the application using
CMake:
C:> cmake . ..
-- Building for: Visual Studio 14 2015
-- The C compiler identification is MSVC 19.0.24215.1
-- The CXX compiler identification is MSVC 19.0.24215.1
-- Check for working C compiler using: Visual Studio 14 2015
-- Check for working C compiler using: Visual Studio 14 2015 -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working CXX compiler using: Visual Studio 14 2015
-- Check for working CXX compiler using: Visual Studio 14 2015 -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: C:/Work/Build
C:> _
In the build directory you will find a Visual Studio solution file that
you can open:
C:> dir *.sln
23/03/2017 21:59 33,984 emCrypt.sln
C:> _
You should now be able to build all the sample applications, and
the emCrypt library, from within the Visual Studio IDE.
Building on Linux
Using Linux to build emCrypt and the sample applications is not
very different from Windows. Create a Build directory for the
out-of-source build and configure using CMake:
paul@ubuntu:~/Work/emCrypt mkdir Build
paul@ubuntu:~/Work/emCrypt/Build cd Build
paul@ubuntu:~/Work/emCrypt/Build cmake . ..
-- The C compiler identification is GNU 5.4.0
-- The CXX compiler identification is GNU 5.4.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Build files have been written to: /home/paul/Work/emCrypt/Build
paul@ubuntu:~/Work/emCrypt/Build _
All you have to do now is use the standard make utility
to build:
paul@ubuntu:~/Work/emCrypt/Build make
-- Build files have been written to: /home/paul/Work/emCrypt/Build
Scanning dependencies of target SEGGER
[ 0%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_SYS_IO_Linux.c.o
[ 1%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_SYS_Linux.c.o
[ 1%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_SYS_OS_Linux.c.o
[ 1%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_MEM.c.o
[ 1%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_memxor.c.o
[ 2%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_MEM_CHUNK_HEAP.c.o
[ 2%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_MEM_SBUFFER.c.o
[ 2%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_MEM_SIMPLE_HEAP.c.o
[ 2%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_MEM_SYSTEM_HEAP.c.o
[ 2%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_SYS.c.o
[ 3%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_SYS_IO.c.o
[ 3%] Building C object CMakeFiles/SEGGER.dir/SEGGER/SEGGER_VERSION.c.o
[ 3%] Linking C static library libSEGGER.a
[ 3%] Built target SEGGER
Scanning dependencies of target CRYPTO
[ 3%] Building C object CMakeFiles/CRYPTO.dir/CRYPTO/CRYPTO_AES.c.o
[ 4%] Building C object CMakeFiles/CRYPTO.dir/CRYPTO/CRYPTO_AES_128_CAVS_SelfTest.c.
...
[ 99%] Building C object CMakeFiles/CRYPTO_TestAES.dir/Application/CRYPTO_TestAES.c.o
[100%] Linking C executable CRYPTO_TestAES
[100%] Built target CRYPTO_TestAES
Scanning dependencies of target CRYPTO_TestCamellia
[100%] Building C object CMakeFiles/CRYPTO_TestCamellia.dir/Application/CRYPTO_TestCamellia.c.o
[100%] Linking C executable CRYPTO_TestCamellia
[100%] Built target CRYPTO_TestCamellia
paul@ubuntu:~/Work/emCrypt/Build _
The applications are built into the Build directory for you to run:
paul@ubuntu:~/Work/emCrypt/Build ./CRYPTO_Test_AES
Copyright (c) 2014-2018 SEGGER Microcontroller GmbH www.segger.com
AES Self-Test compiled Mar 18 2018 16:31:03
Algorithm Source Status #Test
---------------------------------------------
AES-128-ECB RFC 3602 PASS 2
AES-128-ECB CAVS PASS 568
AES-128-CCM CAVS PASS 720
AES-128-GCM CAVS PASS 7875
AES-192-ECB CAVS PASS 700
AES-192-CCM CAVS PASS 720
AES-192-GCM CAVS PASS 7875
AES-256-ECB CAVS PASS 810
AES-256-CCM CAVS PASS 720
AES-256-GCM CAVS PASS 7875
AES-CCM SP800-38C PASS 12
All tests passed.
paul@ubuntu:~/Work/emCrypt/Build _
Configuring emCrypt
Initializing emCrypt
Before using any emCrypt service you must initialize the CRYPTO module. You
do this by including the emCrypt header CRYPTO.h and by calling CRYPTO_Init().
//
// Initialize emCrypt.
//
CRYPTO_Init();
You configure the capabilities of emCrypt in the function CRYPTO_X_Config()
that is called as part of the emCrypt initialization carried out by CRYPTO_Init.
CRYPTO_X_Config() must be provided in your application as a function with
external linkage and an example is shipped with emCrypt.
Sample implementations of CRYPTO_X_Config() can be found in CRYPTO-OS binding for embOS
and CRYPTO-OS binding for bare metal.
Additionally the functions CRYPTO_OS_Init(), CRYPTO_OS_Claim(),
CRYPTO_OS_Request() and CRYPTO_OS_Unclaim() must be provided
by the application. If hardware acceleration is used in a threaded execution
environment, these functions are required to lock hardware resources against
simultaneously access by different threads, see CRYPTO-OS integration.
Otherwise the functions may be empty as provided in file CRYPTO_OS_None.c from the emCrypt shipping.
CRYPTO-OS integration
In a threaded execution environment individual hardware resources must
be protected from simultaneous use by more than one thread. emCrypt
does this by surrounding use of hardware resources by calls to an OS
binding layer.
To use a shared resource, emCrypt will either:
The parameter Unit is a zero-based index to the hardware being
requested and is defined by the specific hardware platform or target
device that is in use. No hardware acceleration interface in emCrypt
requires more than three units (e.g. a ciphering unit, a hashing unit,
and a random number generation unit). The specific requirements for
each device are described in the relevant sections.
As an OS layer may well need to create mutexes or semaphores corresponding
to each unit, CRYPTO_OS_Init() is called as part of emCrypt
initialization.
CRYPTO-OS API
CRYPTO_OS_Init()
Description
Initialize CRYPTO binding to OS.
Prototype
void CRYPTO_OS_Init(void);
Additional information
This function should initialize any semaphores or mutexes used
for protecting each hardware unit.
CRYPTO_OS_Claim()
Description
Claim a hardware resource.
Prototype
void CRYPTO_OS_Claim(unsigned Unit);
Parameters
Parameter | Description |
Unit | Zero-based index to hardware resource. |
Additional information
Claim the hardware resource that corresponds to the unit index.
In a threaded environment, this function should block a task
requesting a resource that is already in use by using a semaphore
or mutex, for example. For a super-loop or non-threaded application
where there is no possibility of concurrent use of the hardware
resource, this function can be empty.
CRYPTO_OS_Request()
Description
Test-and-claim a hardware resource.
Prototype
int CRYPTO_OS_Request(unsigned Unit);
Parameters
Parameter | Description |
Unit | Zero-based index to hardware resource. |
Return value
= 0 | Resource is already in use and was not claimed. |
≠ 0 | Resource claimed. |
Additional information
Attempt to claim the hardware resource that corresponds to the
unit index. In a threaded environment, this function is a
nonblocking test-and-lock of a semaphore or mutex. For a
super-loop or non-threaded application where there is no
possibility of concurrent use of the hardware resource, this
function should always return nonzero, i.e. resource claimed.
CRYPTO_OS_Unclaim()
Description
Release claim on a hardware resource.
Prototype
void CRYPTO_OS_Unclaim(unsigned Unit);
Parameters
Parameter | Description |
Unit | Zero-based index to hardware resource. |
Additional information
Release the claim the hardware resource that corresponds to
the unit index. This will only be called to unclaim a claimed
resource.
CRYPTO-OS binding for embOS
The following is a sample binding for SEGGER embOS, CRYPTO_OS_embOS.c:
/*********************************************************************
* (c) SEGGER Microcontroller GmbH & Co. KG *
* The Embedded Experts *
* www.segger.com *
**********************************************************************
-------------------------- END-OF-HEADER -----------------------------
File : CRYPTO_OS_embOS.c
Purpose : SEGGER embOS CRYPTO-OS binding.
*/
/*********************************************************************
*
* #include section
*
**********************************************************************
*/
#include "CRYPTO.h"
#include "RTOS.h"
/*********************************************************************
*
* Preprocessor definitions, configurable
*
**********************************************************************
*/
#ifndef CRYPTO_CONFIG_OS_MAX_UNIT
#define CRYPTO_CONFIG_OS_MAX_UNIT (CRYPTO_OS_MAX_INTERNAL_UNIT + 3)
#endif
/*********************************************************************
*
* Static data
*
**********************************************************************
*/
static OS_SEMAPHORE _aSema[CRYPTO_CONFIG_OS_MAX_UNIT];
/*********************************************************************
*
* Public functions
*
**********************************************************************
*/
/*********************************************************************
*
* CRYPTO_OS_Claim()
*
* Function description
* Claim a hardware resource.
*
* Parameters
* Unit - Zero-based index to hardware resource.
*/
void CRYPTO_OS_Claim(unsigned Unit) {
if (Unit >= CRYPTO_CONFIG_OS_MAX_UNIT) {
OS_Error(OS_ERR_HW_NOT_AVAILABLE);
}
//
OS_WaitCSema(&_aSema[Unit]);
}
/*********************************************************************
*
* CRYPTO_OS_Request()
*
* Function description
* Request a hardware resource.
*
* Parameters
* Unit - Zero-based index to hardware resource.
*
* Return value
* == 0 - Resource is already in use and was not claimed.
* != 0 - Resource claimed.
*/
int CRYPTO_OS_Request(unsigned Unit) {
if (Unit >= CRYPTO_CONFIG_OS_MAX_UNIT) {
OS_Error(OS_ERR_HW_NOT_AVAILABLE);
}
//
return OS_CSemaRequest(&_aSema[Unit]);
}
/*********************************************************************
*
* CRYPTO_OS_Unclaim()
*
* Function description
* Release claim on a hardware resource.
*
* Parameters
* Unit - Zero-based index to hardware resource.
*/
void CRYPTO_OS_Unclaim(unsigned Unit) {
if (Unit >= CRYPTO_CONFIG_OS_MAX_UNIT) {
OS_Error(OS_ERR_HW_NOT_AVAILABLE);
}
//
OS_SignalCSema(&_aSema[Unit]);
}
/*********************************************************************
*
* CRYPTO_OS_Init()
*
* Function description
* Initialize CRYPTO binding to OS.
*/
void CRYPTO_OS_Init(void) {
unsigned Unit;
//
for (Unit = 0; Unit < CRYPTO_CONFIG_OS_MAX_UNIT; ++Unit) {
OS_CreateCSema(&_aSema[Unit], 1);
}
}
/*********************************************************************
*
* CRYPTO_OS_Exit()
*
* Function description
* Deinitialize CRYPTO binding to OS.
*/
void CRYPTO_OS_Exit(void) {
unsigned Unit;
//
for (Unit = 0; Unit < CRYPTO_CONFIG_OS_MAX_UNIT; ++Unit) {
OS_DeleteCSema(&_aSema[Unit]);
}
}
/*************************** End of file ****************************/
The following is a sample binding for a bare metal system that has no tasking, CRYPTO_OS_None.c:
/*********************************************************************
* (c) SEGGER Microcontroller GmbH *
* The Embedded Experts *
* www.segger.com *
**********************************************************************
-------------------------- END-OF-HEADER -----------------------------
File : CRYPTO_OS_None.c
Purpose : Bare metal CRYPTO-OS binding.
*/
#include "CRYPTO.h"
/*********************************************************************
*
* Public code
*
**********************************************************************
*/
/*********************************************************************
*
* CRYPTO_OS_Claim()
*
* Function description
* Claim a hardware resource.
*
* Parameters
* Unit - Zero-based index to hardware resource.
*/
void CRYPTO_OS_Claim(unsigned Unit) {
CRYPTO_USE_PARA(Unit);
}
/*********************************************************************
*
* CRYPTO_OS_Request()
*
* Function description
* Test-and-claim a hardware resource.
*
* Parameters
* Unit - Zero-based index to hardware resource.
*
* Return value
* == 0 - Resource is already in use and was not claimed.
* != 0 - Resource claimed.
*/
int CRYPTO_OS_Request(unsigned Unit) {
CRYPTO_USE_PARA(Unit);
return 1;
}
/*********************************************************************
*
* CRYPTO_OS_Unclaim()
*
* Function description
* Release claim on a hardware resource.
*
* Parameters
* Unit - Zero-based index to hardware resource.
*/
void CRYPTO_OS_Unclaim(unsigned Unit) {
CRYPTO_USE_PARA(Unit);
}
/*********************************************************************
*
* CRYPTO_OS_Init()
*
* Function description
* Initialize CRYPTO binding to OS.
*/
void CRYPTO_OS_Init(void) {
/* Nothing to do. */
}
/*********************************************************************
*
* CRYPTO_OS_Init()
*
* Function description
* Deinitialize CRYPTO binding to OS.
*/
void CRYPTO_OS_Exit(void) {
/* Nothing to do. */
}
/*************************** End of file ****************************/
Component API
This chapter describes the API functions that related to the emCrypt
component as a whole.
Preprocessor symbols
Version number
Description
Symbol expands to a number that identifies the specific emCrypt release.
Definition
#define CRYPTO_VERSION 23800
Symbols
Definition | Description |
CRYPTO_VERSION | Format is “Mmmrr” so, for example, 12304 corresponds to version 1.23d. |
API functions
The following table lists the component API functions.
CRYPTO_GetCopyrightText()
Description
Get copyright as printable string.
Prototype
char *CRYPTO_GetCopyrightText(void);
Return value
Zero-terminated copyright string.
CRYPTO_GetVersionText()
Description
Get version as printable string.
Prototype
char *CRYPTO_GetVersionText(void);
Return value
Zero-terminated version string.
CRYPTO_Init()
Description
Initialize CRYPTO component.
Prototype
void CRYPTO_Init(void);
Hash algorithms
emCrypt implements the following message digest algorithms:
Introduction
In general a hash calculation is performed in three steps:
- Initialising the calculation.
- Processing input data. This step can be repeated multiple times.
- Calculating the final hash value.
The intermediate results are stored in a data structure called a ’hash context’.
The hash context is maintained by the hash functions, only the memory must be provided by the caller.
It can be discarded after the final hash calculation is done.
The API functions are named in the same way for all hash algorithms:
- CRYPTO_<hash_name>_Init() for initializing.
- CRYPTO_<hash_name>_Add() to process data.
- CRYPTO_<hash_name>_Final() to calculate the final hash value.
Example
//
// Example for a SHA-1 hash calculation.
//
CRYPTO_SHA1_CONTEXT SHAContext;
U8 aDigest[CRYPTO_SHA1_DIGEST_BYTE_COUNT];
//
// Initialize the hash context.
//
CRYPTO_SHA1_Init(&SHAContext);
//
// Process input data.
//
CRYPTO_SHA1_Add(&SHAContext, Data1, Data1Len);
//
// More data.
//
CRYPTO_SHA1_Add(&SHAContext, Data2, Data2Len);
//
// Calculate hash.
//
CRYPTO_SHA1_Final(&SHAContext, aDigest, sizeof(aDigest));
//
// aDigest now contains the hash value.
// From now, SHAContext is not used any more.
//
For every hash algorithm there is also a function to perform the whole hash calculation in one step.
These functions are called CRYPTO_<hash_name>_Calc() and provide an easy way to calculate a hash from a single piece of data.
Besides the type-safe API functions described above, there are also generic API functions, that use a void pointer to take the hash context.
These are useful, if the API functions shall be called via functions pointers to dynamically choose different hash algorithms.
When using the generic functions the caller is responsible to provide the correct context (or memory areas) via the void pointer argument.
BLAKE2b
Standards reference
BLAKE2b is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_BLAKE2B_BLOCK_BYTE_COUNT 128
The number of bytes in a single BLAKE2B block.
Digest size
#define CRYPTO_BLAKE2B_DIGEST_BIT_COUNT 512
#define CRYPTO_BLAKE2B_DIGEST_BYTE_COUNT 64
The number of bits and bytes required to hold a complete BLAKE2b digest.
Type-safe API
The following table lists the BLAKE2b type-safe API functions.
CRYPTO_BLAKE2B_Add()
Description
Add data to digest.
Prototype
void CRYPTO_BLAKE2B_Add( CRYPTO_BLAKE2B_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_BLAKE2B_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_BLAKE2B_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_BLAKE2B_Calc_512()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_BLAKE2B_Calc_512( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 64 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_BLAKE2B_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_BLAKE2B_Final(CRYPTO_BLAKE2B_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_BLAKE2B_Final_512()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_BLAKE2B_Final_512(CRYPTO_BLAKE2B_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 64 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_BLAKE2B_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_BLAKE2B_Get(CRYPTO_BLAKE2B_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_BLAKE2B_Init()
Description
Initialize context.
Prototype
void CRYPTO_BLAKE2B_Init(CRYPTO_BLAKE2B_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_BLAKE2B_Install()
Description
Install BLAKE2b hash implementation.
Prototype
void CRYPTO_BLAKE2B_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_BLAKE2B_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_BLAKE2B_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_BLAKE2B_Kill()
Description
Destroy context.
Prototype
void CRYPTO_BLAKE2B_Kill(CRYPTO_BLAKE2B_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_BLAKE2B_QueryInstall()
Description
Query BLAKE2b hardware accelerator.
Prototype
void CRYPTO_BLAKE2B_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the BLAKE2b functions that conform to the generic hash API.
CRYPTO_HASH_BLAKE2B_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_BLAKE2B_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_BLAKE2B_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_BLAKE2B_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_BLAKE2B_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_BLAKE2B_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_BLAKE2B_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_BLAKE2B_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_BLAKE2B_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_BLAKE2B_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the BLAKE2b self-test API functions.
CRYPTO_BLAKE2B_RFC7693_SelfTest()
Description
Run BLAKE2 KATs from RFC 7693.
Prototype
void CRYPTO_BLAKE2B_RFC7693_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
CRYPTO_BLAKE2B_Ref_SelfTest()
Description
Run BLAKE2b reference self-tests.
Prototype
void CRYPTO_BLAKE2B_Ref_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
BLAKE2s
Standards reference
BLAKE2s is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_BLAKE2S_BLOCK_BYTE_COUNT 64
The number of bytes in a single BLAKE2S block.
Digest size
#define CRYPTO_BLAKE2S_DIGEST_BIT_COUNT 256
#define CRYPTO_BLAKE2S_DIGEST_BYTE_COUNT 32
The number of bits and bytes required to hold a complete BLAKE2s digest.
Type-safe API
The following table lists the BLAKE2s type-safe API functions.
CRYPTO_BLAKE2S_Add()
Description
Add data to digest.
Prototype
void CRYPTO_BLAKE2S_Add( CRYPTO_BLAKE2S_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_BLAKE2S_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_BLAKE2S_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_BLAKE2S_Calc_256()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_BLAKE2S_Calc_256( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 32 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_BLAKE2S_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_BLAKE2S_Final(CRYPTO_BLAKE2S_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_BLAKE2S_Final_256()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_BLAKE2S_Final_256(CRYPTO_BLAKE2S_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 32 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_BLAKE2S_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_BLAKE2S_Get(CRYPTO_BLAKE2S_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_BLAKE2S_Init()
Description
Initialize context.
Prototype
void CRYPTO_BLAKE2S_Init(CRYPTO_BLAKE2S_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_BLAKE2S_Install()
Description
Install BLAKE2s hash implementation.
Prototype
void CRYPTO_BLAKE2S_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_BLAKE2S_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_BLAKE2S_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_BLAKE2S_Kill()
Description
Destroy context.
Prototype
void CRYPTO_BLAKE2S_Kill(CRYPTO_BLAKE2S_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_BLAKE2S_QueryInstall()
Description
Query BLAKE2s hardware accelerator.
Prototype
void CRYPTO_BLAKE2S_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the BLAKE2s functions that conform to the generic hash API.
CRYPTO_HASH_BLAKE2S_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_BLAKE2S_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_BLAKE2S_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_BLAKE2S_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_BLAKE2S_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_BLAKE2S_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_BLAKE2S_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_BLAKE2S_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_BLAKE2S_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_BLAKE2S_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the BLAKE2s self-test API functions.
CRYPTO_BLAKE2S_RFC7693_SelfTest()
Description
Run BLAKE2 KATs from RFC 7693.
Prototype
void CRYPTO_BLAKE2S_RFC7693_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
MD5
Standards reference
MD5 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_MD5_BLOCK_BYTE_COUNT 64
The number of bytes in a single MD5 block.
Digest size
#define CRYPTO_MD5_DIGEST_BIT_COUNT 128
#define CRYPTO_MD5_DIGEST_BYTE_COUNT 16
The number of bits and bytes required to hold a complete MD5 digest.
#define CRYPTO_MD5_96_DIGEST_BYTE_COUNT (96/8)
The number of bytes required to hold a truncated MD5 digest of 96 bits.
Configuration and resource use
Default
#define CRYPTO_CONFIG_MD5_OPTIMIZE 0
Override
To define a non-default value, define this symbol in CRYPTO_Conf.h.
Description
Set this preprocessor symbol to zero to optimize the MD5 hash functions
for size rather than for speed. When optimized for speed, the MD5
function is open coded and faster, but is significantly larger.
Profile
The following table shows required context size, lookup table (LUT) size,
and code size in kilobytes for each configuration value. All values are
approximate and for a Cortex-M3 processor.
Setting | Context size | LUT | LUT size | Code size | | Total size |
0 | 0.16 KB | Flash | 0.3 KB | 0.4 KB | | 0.7 KB |
1 | 0.16 KB | - | - | 2.0 KB | | 2.0 KB |
Type-safe API
The following table lists the MD5 type-safe API functions.
CRYPTO_MD5_Add()
Description
Add data to digest.
Prototype
void CRYPTO_MD5_Add( CRYPTO_MD5_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_MD5_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_MD5_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_MD5_Calc_160()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_MD5_Calc_160( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 20 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_MD5_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_MD5_Final(CRYPTO_MD5_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_MD5_Final_160()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_MD5_Final_160(CRYPTO_MD5_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 20 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_MD5_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_MD5_Get(CRYPTO_MD5_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_MD5_Init()
Description
Initialize context.
Prototype
void CRYPTO_MD5_Init(CRYPTO_MD5_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_MD5_Install()
Description
Install MD5 hash implementation.
Prototype
void CRYPTO_MD5_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_MD5_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_MD5_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_MD5_Kill()
Description
Destroy context.
Prototype
void CRYPTO_MD5_Kill(CRYPTO_MD5_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_MD5_QueryInstall()
Description
Query MD5 hardware accelerator.
Prototype
void CRYPTO_MD5_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the MD5 functions that conform to the generic hash API.
CRYPTO_HASH_MD5_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_MD5_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_MD5_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_MD5_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_MD5_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_MD5_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_MD5_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_MD5_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_MD5_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_MD5_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the MD5 self-test API functions.
CRYPTO_MD5_RFC1321_SelfTest()
Description
Run MD5 test vectors from RFC 1321.
Prototype
void CRYPTO_MD5_RFC1321_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
Example applications
CRYPTO_Bench_MD5.c
This application benchmarks the configured performance of MD5.
It will benchmark both the software and hardware implementations,
if a hardware accelerator is installed.
Example output
Copyright (c) 2014-2018 SEGGER Microcontroller GmbH www.segger.com
MD5 Benchmark compiled Mar 19 2018 16:34:02
Compiler: clang 5.0.0 (tags/RELEASE_500/final)
System: Processor speed = 200.000 MHz
Config: CRYPTO_VERSION = 22400 [2.24]
Config: CRYPTO_CONFIG_MD5_OPTIMIZE = 1
Config: CRYPTO_CONFIG_MD5_HW_OPTIMIZE = 1
+--------------+-----------+
| Algorithm | Hash MB/s |
+--------------+-----------+
| MD5 | 25.10 |
+--------------+-----------+
Benchmark complete
Complete listing
/*********************************************************************
* (c) SEGGER Microcontroller GmbH *
* The Embedded Experts *
* www.segger.com *
**********************************************************************
-------------------------- END-OF-HEADER -----------------------------
File : CRYPTO_Bench_MD5.c
Purpose : Benchmark MD5 implementation.
*/
/*********************************************************************
*
* #include section
*
**********************************************************************
*/
#include "CRYPTO.h"
#include "SEGGER_SYS.h"
/*********************************************************************
*
* Static data
*
**********************************************************************
*/
static U8 _aTestMessage[65536] = { 0 };
/*********************************************************************
*
* Static code
*
**********************************************************************
*/
/*********************************************************************
*
* _ConvertTicksToSeconds()
*
* Function description
* Convert ticks to seconds.
*
* Parameters
* Ticks - Number of ticks reported by SEGGER_SYS_OS_GetTimer().
*
* Return value
* Number of seconds corresponding to tick.
*/
static double _ConvertTicksToSeconds(U64 Ticks) {
return SEGGER_SYS_OS_ConvertTicksToMicros(Ticks) / 1000000.0;
}
/*********************************************************************
*
* _HashBenchmark()
*
* Function description
* Benchmarks a hash implementation.
*
* Parameters
* sAlgorithm - Hash algorithm name.
* pAPI - Pointer to hash API.
*/
static void _HashBenchmark(const char *sAlgorithm, const CRYPTO_HASH_API *pAPI) {
CRYPTO_MD5_CONTEXT C;
U64 T0;
U64 OneSecond;
unsigned n;
//
SEGGER_SYS_IO_Printf("| %-12s | ", sAlgorithm);
OneSecond = SEGGER_SYS_OS_ConvertMicrosToTicks(1000000);
//
T0 = SEGGER_SYS_OS_GetTimer();
n = 0;
if (pAPI->pfClaim) {
pAPI->pfClaim();
}
pAPI->pfInit(&C);
while (SEGGER_SYS_OS_GetTimer() - T0 < OneSecond) {
pAPI->pfAdd(&C, &_aTestMessage[0], sizeof(_aTestMessage));
n += sizeof(_aTestMessage);
}
pAPI->pfKill(&C);
T0 = SEGGER_SYS_OS_GetTimer() - T0;
SEGGER_SYS_IO_Printf("%9.2f |\n", (double)n / (1024.0*1024.0) / _ConvertTicksToSeconds(T0));
}
/*********************************************************************
*
* Public code
*
**********************************************************************
*/
/*********************************************************************
*
* MainTask()
*
* Function description
* Main entry point for application to run all the tests.
*/
void MainTask(void);
void MainTask(void) {
const CRYPTO_HASH_API *pHWAPI;
const CRYPTO_HASH_API *pSWAPI;
//
CRYPTO_Init();
SEGGER_SYS_Init();
//
SEGGER_SYS_IO_Printf("%s www.segger.com\n", CRYPTO_GetCopyrightText());
SEGGER_SYS_IO_Printf("MD5 Benchmark compiled " __DATE__ " " __TIME__ "\n\n");
//
SEGGER_SYS_IO_Printf("Compiler: %s\n", SEGGER_SYS_GetCompiler());
if (SEGGER_SYS_GetProcessorSpeed() > 0) {
SEGGER_SYS_IO_Printf("System: Processor speed = %.3f MHz\n", (double)SEGGER_SYS_GetProcessorSpeed() / 1000000.0f);
}
SEGGER_SYS_IO_Printf("Config: CRYPTO_VERSION = %u [%s]\n", CRYPTO_VERSION, CRYPTO_GetVersionText());
SEGGER_SYS_IO_Printf("Config: CRYPTO_CONFIG_MD5_OPTIMIZE = %d\n", CRYPTO_CONFIG_MD5_OPTIMIZE);
SEGGER_SYS_IO_Printf("Config: CRYPTO_CONFIG_MD5_HW_OPTIMIZE = %d\n\n", CRYPTO_CONFIG_MD5_HW_OPTIMIZE);
//
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
SEGGER_SYS_IO_Printf("| Algorithm | Hash MB/s |\n");
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
//
_HashBenchmark("MD5", &CRYPTO_HASH_MD5_SW);
CRYPTO_MD5_QueryInstall(&pHWAPI, &pSWAPI);
if (pHWAPI && pHWAPI != &CRYPTO_HASH_MD5_SW) {
_HashBenchmark("MD5 (HW)", pHWAPI);
}
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
//
SEGGER_SYS_IO_Printf("\nBenchmark complete\n");
SEGGER_SYS_OS_PauseBeforeHalt();
SEGGER_SYS_OS_Halt(0);
}
/*************************** End of file ****************************/
RIPEMD-160
Standards reference
RIPEMD-160 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_RIPEMD160_BLOCK_BYTE_COUNT 64
The number of bytes in a single RIPEMD-160 block.
Digest size
#define CRYPTO_RIPEMD160_DIGEST_BIT_COUNT 160
#define CRYPTO_RIPEMD160_DIGEST_BYTE_COUNT 20
The number of bits and bytes required to hold a complete RIPEMD-160 digest.
Configuration and resource use
Default
#define CRYPTO_CONFIG_RIPEMD160_OPTIMIZE 0
Override
To define a non-default value, define this symbol in CRYPTO_Conf.h.
Description
Set this preprocessor symbol to zero to optimize the RIPEMD-160 hash functions
for size rather than for speed. When optimized for speed, the RIPEMD-160
function is open coded and faster, but is significantly larger.
Profile
The following table shows required context size, lookup table (LUT) size,
and code size in kilobytes for each configuration value. All values are
approximate and for a Cortex-M3 processor.
Setting | Context size | LUT | LUT size | Code size | | Total size |
0 | 0.16 KB | Flash | 0.3 KB | 0.7 KB | | 1.0 KB |
1 | 0.16 KB | - | - | 4.6 KB | | 4.6 KB |
Type-safe API
The following table lists the RIPEMD-160 type-safe API functions.
CRYPTO_RIPEMD160_Add()
Description
Add data to digest.
Prototype
void CRYPTO_RIPEMD160_Add( CRYPTO_RIPEMD160_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_RIPEMD160_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_RIPEMD160_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_RIPEMD160_Calc_160()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_RIPEMD160_Calc_160( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 20 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_RIPEMD160_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_RIPEMD160_Final(CRYPTO_RIPEMD160_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_RIPEMD160_Final_160()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_RIPEMD160_Final_160(CRYPTO_RIPEMD160_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 20 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_RIPEMD160_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_RIPEMD160_Get(CRYPTO_RIPEMD160_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_RIPEMD160_Init()
Description
Initialize context.
Prototype
void CRYPTO_RIPEMD160_Init(CRYPTO_RIPEMD160_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_RIPEMD160_Install()
Description
Install RIPEMD-160 hash implementation.
Prototype
void CRYPTO_RIPEMD160_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_RIPEMD160_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_RIPEMD160_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_RIPEMD160_Kill()
Description
Destroy context.
Prototype
void CRYPTO_RIPEMD160_Kill(CRYPTO_RIPEMD160_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_RIPEMD160_QueryInstall()
Description
Query RIPEMD-160 hardware accelerator.
Prototype
void CRYPTO_RIPEMD160_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the RIPEMD-160 functions that conform to the generic hash API.
CRYPTO_HASH_RIPEMD160_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_RIPEMD160_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_RIPEMD160_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_RIPEMD160_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_RIPEMD160_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_RIPEMD160_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_RIPEMD160_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_RIPEMD160_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_RIPEMD160_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_RIPEMD160_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the RIPEMD-160 self-test API functions.
CRYPTO_RIPEMD160_Bosselaers_SelfTest()
Description
Run all RIPEMD160 test vectors defined by Bosselaers.
Prototype
void CRYPTO_RIPEMD160_Bosselaers_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
Example applications
CRYPTO_Bench_RIPEMD160.c
This application benchmarks the configured performance of RIPEMD-160.
It will benchmark both the software and hardware implementations,
if a hardware accelerator is installed.
Example output
Copyright (c) 2014-2018 SEGGER Microcontroller GmbH www.segger.com
RIPEMD160 Benchmark compiled Mar 19 2018 16:42:14
Compiler: clang 5.0.0 (tags/RELEASE_500/final)
System: Processor speed = 200.000 MHz
Config: CRYPTO_VERSION = 22400 [2.24]
Config: CRYPTO_CONFIG_RIPEMD160_OPTIMIZE = 1
+----------------+-----------+
| Algorithm | Hash MB/s |
+----------------+-----------+
| RIPEMD160 (SW) | 8.47 |
+----------------+-----------+
Benchmark complete
Complete listing
/*********************************************************************
* (c) SEGGER Microcontroller GmbH *
* The Embedded Experts *
* www.segger.com *
**********************************************************************
-------------------------- END-OF-HEADER -----------------------------
File : CRYPTO_Bench_RIPEMD160.c
Purpose : Benchmark RIPEMD-160 implementation.
*/
/*********************************************************************
*
* #include section
*
**********************************************************************
*/
#include "CRYPTO.h"
#include "SEGGER_SYS.h"
/*********************************************************************
*
* Static const data
*
**********************************************************************
*/
static const U8 _aTestMessage[65536] = { 0 };
/*********************************************************************
*
* Static code
*
**********************************************************************
*/
/*********************************************************************
*
* _ConvertTicksToSeconds()
*
* Function description
* Convert ticks to seconds.
*
* Parameters
* Ticks - Number of ticks reported by SEGGER_SYS_OS_GetTimer().
*
* Return value
* Number of seconds corresponding to tick.
*/
static double _ConvertTicksToSeconds(U64 Ticks) {
return SEGGER_SYS_OS_ConvertTicksToMicros(Ticks) / 1000000.0;
}
/*********************************************************************
*
* _HashBenchmark()
*
* Function description
* Benchmarks a hash implementation.
*
* Parameters
* sAlgorithm - Hash algorithm name.
* pAPI - Pointer to hash API.
*/
static void _HashBenchmark(const char *sAlgorithm, const CRYPTO_HASH_API *pAPI) {
CRYPTO_SHA512_CONTEXT C; // big enough for most things...
U64 T0;
U64 OneSecond;
unsigned n;
//
SEGGER_SYS_IO_Printf("| %-14s | ", sAlgorithm);
OneSecond = SEGGER_SYS_OS_ConvertMicrosToTicks(1000000);
//
T0 = SEGGER_SYS_OS_GetTimer();
n = 0;
pAPI->pfInit(&C);
while (SEGGER_SYS_OS_GetTimer() - T0 < OneSecond) {
pAPI->pfAdd(&C, &_aTestMessage[0], sizeof(_aTestMessage));
n += sizeof(_aTestMessage);
}
pAPI->pfKill(&C);
T0 = SEGGER_SYS_OS_GetTimer() - T0;
SEGGER_SYS_IO_Printf("%9.2f |\n", (double)n / (1024.0*1024.0) / _ConvertTicksToSeconds(T0));
}
/*********************************************************************
*
* Public code
*
**********************************************************************
*/
/*********************************************************************
*
* MainTask()
*
* Function description
* Main entry point for application to run all the tests.
*/
void MainTask(void);
void MainTask(void) {
const CRYPTO_HASH_API *pHWAPI;
const CRYPTO_HASH_API *pSWAPI;
//
CRYPTO_Init();
SEGGER_SYS_Init();
//
SEGGER_SYS_IO_Printf("%s www.segger.com\n", CRYPTO_GetCopyrightText());
SEGGER_SYS_IO_Printf("RIPEMD160 Benchmark compiled " __DATE__ " " __TIME__ "\n\n");
//
SEGGER_SYS_IO_Printf("Compiler: %s\n", SEGGER_SYS_GetCompiler());
if (SEGGER_SYS_GetProcessorSpeed() > 0) {
SEGGER_SYS_IO_Printf("System: Processor speed = %.3f MHz\n", (double)SEGGER_SYS_GetProcessorSpeed() / 1000000.0f);
}
SEGGER_SYS_IO_Printf("Config: CRYPTO_VERSION = %u [%s]\n", CRYPTO_VERSION, CRYPTO_GetVersionText());
SEGGER_SYS_IO_Printf("Config: CRYPTO_CONFIG_RIPEMD160_OPTIMIZE = %d\n\n", CRYPTO_CONFIG_RIPEMD160_OPTIMIZE);
//
SEGGER_SYS_IO_Printf("+----------------+-----------+\n");
SEGGER_SYS_IO_Printf("| Algorithm | Hash MB/s |\n");
SEGGER_SYS_IO_Printf("+----------------+-----------+\n");
//
_HashBenchmark("RIPEMD160 (SW)", &CRYPTO_HASH_RIPEMD160_SW);
CRYPTO_RIPEMD160_QueryInstall(&pHWAPI, &pSWAPI);
if (pHWAPI != &CRYPTO_HASH_RIPEMD160_SW) {
_HashBenchmark("RIPEMD160 (HW)", pHWAPI);
}
SEGGER_SYS_IO_Printf("+----------------+-----------+\n");
//
SEGGER_SYS_IO_Printf("\nBenchmark complete\n");
SEGGER_SYS_OS_Halt(0);
}
/*************************** End of file ****************************/
SHA-1
Standards reference
SHA-1 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SHA1_BLOCK_BYTE_COUNT 64
The number of bytes in a single SHA-1 block.
Digest size
#define CRYPTO_SHA1_DIGEST_BIT_COUNT 160
#define CRYPTO_SHA1_DIGEST_BYTE_COUNT 20
The number of bits and bytes required to hold a complete SHA-1 digest.
#define CRYPTO_SHA1_96_DIGEST_BYTE_COUNT (96/8)
The number of bytes required to hold a truncated SHA-1 digest of 96 bits.
Configuration and resource use
Default
#define CRYPTO_CONFIG_SHA1_OPTIMIZE 0
Override
To define a non-default value, define this symbol in CRYPTO_Conf.h.
Description
Set this preprocessor symbol to zero to optimize the SHA-1 hash
functions for size rather than for speed. When optimized for speed,
the SHA-1 function is open coded and faster, but is significantly
larger.
Profile
The following table shows required context size, lookup table (LUT) size,
and code size in kilobytes for each configuration value. All values are
approximate and for a Cortex-M4 processor.
Setting | Context size | LUT | LUT size | Code size | | Total size |
0 | 0.16 KB | - | - | 0.6 KB | | 0.6 KB |
1 | 0.16 KB | - | - | 3.6 KB | | 3.6 KB |
Type-safe API
The following table lists the SHA-1 type-safe API functions.
CRYPTO_SHA1_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SHA1_Add( CRYPTO_SHA1_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SHA1_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_SHA1_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA1_Calc_160()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_SHA1_Calc_160( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 20 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA1_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SHA1_Final(CRYPTO_SHA1_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA1_Final_160()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_SHA1_Final_160(CRYPTO_SHA1_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 20 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA1_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SHA1_Get(CRYPTO_SHA1_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_SHA1_Init()
Description
Initialize context.
Prototype
void CRYPTO_SHA1_Init(CRYPTO_SHA1_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SHA1_Install()
Description
Install SHA-1 hash implementation.
Prototype
void CRYPTO_SHA1_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_SHA1_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_SHA1_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_SHA1_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SHA1_Kill(CRYPTO_SHA1_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA1_QueryInstall()
Description
Query SHA-1 hardware accelerator.
Prototype
void CRYPTO_SHA1_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the SHA-1 functions that conform to the generic hash API.
CRYPTO_HASH_SHA1_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SHA1_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SHA1_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SHA1_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SHA1_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SHA1_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SHA1_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SHA1_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SHA1_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SHA1_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the SHA-1 self-test API functions.
CRYPTO_SHA1_CAVS_SelfTest()
Description
Run SHA-1 KATs from CAVS.
Prototype
void CRYPTO_SHA1_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
CRYPTO_SHA1_FIPS180_SelfTest()
Description
Run SHA-1 KATs from FIPS 180-2.
Prototype
void CRYPTO_SHA1_FIPS180_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
Example applications
CRYPTO_Bench_SHA1.c
This application benchmarks the configured performance of SHA-1.
It will benchmark both the software and hardware implementations,
if a hardware accelerator is installed.
Example output
Copyright (c) 2014-2018 SEGGER Microcontroller GmbH www.segger.com
SHA-1 Benchmark compiled Mar 19 2018 16:42:46
Compiler: clang 5.0.0 (tags/RELEASE_500/final)
System: Processor speed = 200.000 MHz
Config: CRYPTO_VERSION = 22400 [2.24]
Config: CRYPTO_CONFIG_SHA1_OPTIMIZE = 1
Config: CRYPTO_CONFIG_SHA1_HW_OPTIMIZE = 1
+--------------+-----------+
| Algorithm | Hash MB/s |
+--------------+-----------+
| SHA-1 | 11.68 |
| SHA-1 (HW) | 65.51 |
+--------------+-----------+
Benchmark complete
Complete listing
/*********************************************************************
* (c) SEGGER Microcontroller GmbH *
* The Embedded Experts *
* www.segger.com *
**********************************************************************
-------------------------- END-OF-HEADER -----------------------------
File : CRYPTO_Bench_SHA1.c
Purpose : Benchmark SHA-1 implementation.
*/
/*********************************************************************
*
* #include section
*
**********************************************************************
*/
#include "CRYPTO.h"
#include "SEGGER_SYS.h"
/*********************************************************************
*
* Static const data
*
**********************************************************************
*/
static const U8 _aTestMessage[65536] = { 0 };
/*********************************************************************
*
* Static code
*
**********************************************************************
*/
/*********************************************************************
*
* _ConvertTicksToSeconds()
*
* Function description
* Convert ticks to seconds.
*
* Parameters
* Ticks - Number of ticks reported by SEGGER_SYS_OS_GetTimer().
*
* Return value
* Number of seconds corresponding to tick.
*/
static double _ConvertTicksToSeconds(U64 Ticks) {
return SEGGER_SYS_OS_ConvertTicksToMicros(Ticks) / 1000000.0;
}
/*********************************************************************
*
* _HashBenchmark()
*
* Function description
* Benchmarks a hash implementation.
*
* Parameters
* sAlgorithm - Hash algorithm name.
* pAPI - Pointer to hash API.
*/
static void _HashBenchmark(const char *sAlgorithm, const CRYPTO_HASH_API *pAPI) {
CRYPTO_SHA512_CONTEXT C; // big enough for most things...
U64 T0;
U64 OneSecond;
unsigned n;
//
SEGGER_SYS_IO_Printf("| %-12s | ", sAlgorithm);
OneSecond = SEGGER_SYS_OS_ConvertMicrosToTicks(1000000);
//
T0 = SEGGER_SYS_OS_GetTimer();
n = 0;
if (pAPI->pfClaim) {
pAPI->pfClaim();
}
pAPI->pfInit(&C);
while (SEGGER_SYS_OS_GetTimer() - T0 < OneSecond) {
pAPI->pfAdd(&C, &_aTestMessage[0], sizeof(_aTestMessage));
n += sizeof(_aTestMessage);
}
pAPI->pfKill(&C);
T0 = SEGGER_SYS_OS_GetTimer() - T0;
SEGGER_SYS_IO_Printf("%9.2f |\n", (double)n / (1024.0*1024.0) / _ConvertTicksToSeconds(T0));
}
/*********************************************************************
*
* Public code
*
**********************************************************************
*/
/*********************************************************************
*
* MainTask()
*
* Function description
* Main entry point for application to run all the tests.
*/
void MainTask(void);
void MainTask(void) {
const CRYPTO_HASH_API * pHWAPI;
const CRYPTO_HASH_API * pSWAPI;
//
CRYPTO_Init();
SEGGER_SYS_Init();
//
SEGGER_SYS_IO_Printf("%s www.segger.com\n", CRYPTO_GetCopyrightText());
SEGGER_SYS_IO_Printf("SHA-1 Benchmark compiled " __DATE__ " " __TIME__ "\n\n");
//
SEGGER_SYS_IO_Printf("Compiler: %s\n", SEGGER_SYS_GetCompiler());
if (SEGGER_SYS_GetProcessorSpeed() > 0) {
SEGGER_SYS_IO_Printf("System: Processor speed = %.3f MHz\n", (double)SEGGER_SYS_GetProcessorSpeed() / 1000000.0f);
}
SEGGER_SYS_IO_Printf("Config: CRYPTO_VERSION = %u [%s]\n", CRYPTO_VERSION, CRYPTO_GetVersionText());
SEGGER_SYS_IO_Printf("Config: CRYPTO_CONFIG_SHA1_OPTIMIZE = %d\n", CRYPTO_CONFIG_SHA1_OPTIMIZE);
SEGGER_SYS_IO_Printf("Config: CRYPTO_CONFIG_SHA1_HW_OPTIMIZE = %d\n\n", CRYPTO_CONFIG_SHA1_HW_OPTIMIZE);
//
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
SEGGER_SYS_IO_Printf("| Algorithm | Hash MB/s |\n");
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
//
_HashBenchmark("SHA-1", &CRYPTO_HASH_SHA1_SW);
CRYPTO_SHA1_QueryInstall(&pHWAPI, &pSWAPI);
if (pHWAPI && pHWAPI != &CRYPTO_HASH_SHA1_SW) {
_HashBenchmark("SHA-1 (HW)", pHWAPI);
}
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
//
SEGGER_SYS_IO_Printf("\nBenchmark complete\n");
SEGGER_SYS_OS_PauseBeforeHalt();
SEGGER_SYS_OS_Halt(0);
}
/*************************** End of file ****************************/
SHA-224
Standards reference
SHA-224 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SHA224_BLOCK_BYTE_COUNT 64
The number of bytes in a single SHA-224 block.
Digest size
#define CRYPTO_SHA224_DIGEST_BIT_COUNT 224
#define CRYPTO_SHA224_DIGEST_BYTE_COUNT 28
The number of bit and bytes required to hold a complete SHA-1 digest.
Type-safe API
The following table lists the SHA-224 type-safe API functions.
CRYPTO_SHA224_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SHA224_Add( CRYPTO_SHA224_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SHA224_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_SHA224_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA224_Calc_224()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_SHA224_Calc_224( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 28 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA224_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SHA224_Final(CRYPTO_SHA224_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA224_Final_224()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_SHA224_Final_224(CRYPTO_SHA224_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 28 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA224_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SHA224_Get(CRYPTO_SHA224_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_SHA224_Init()
Description
Initialize context.
Prototype
void CRYPTO_SHA224_Init(CRYPTO_SHA224_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SHA224_Install()
Description
Install SHA-224 hash implementation.
Prototype
void CRYPTO_SHA224_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_SHA224_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_SHA224_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_SHA224_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SHA224_Kill(CRYPTO_SHA224_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA224_QueryInstall()
Description
Query SHA-224 hardware accelerator.
Prototype
void CRYPTO_SHA224_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the SHA-224 functions that conform to the generic hash API.
CRYPTO_HASH_SHA224_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SHA224_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SHA224_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SHA224_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SHA224_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SHA224_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SHA224_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SHA224_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SHA224_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SHA224_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the SHA-224 self-test API functions.
CRYPTO_SHA224_CAVS_SelfTest()
Description
Run SHA-224 KATs from CAVS.
Prototype
void CRYPTO_SHA224_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
SHA-256
Standards reference
SHA-256 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SHA256_BLOCK_BYTE_COUNT 64
The number of bytes in a single SHA-256 block.
Digest size
#define CRYPTO_SHA256_DIGEST_BIT_COUNT 256
#define CRYPTO_SHA256_DIGEST_BYTE_COUNT 32
The number of bits and bytes required to hold a complete SHA-256 digest.
Configuration and resource use
Default
#define CRYPTO_CONFIG_SHA256_OPTIMIZE 0
Override
To define a non-default value, define this symbol in CRYPTO_Conf.h.
Description
Set this preprocessor symbol to zero to optimize the SHA-256 hash
functions for size rather than for speed. When optimized for speed,
the SHA-256 function is open coded and faster, but is significantly
larger.
Profile
The following table shows required context size, lookup table (LUT) size,
and code size in kilobytes for each configuration value. All values are
approximate and for a Cortex-M3 processor.
Setting | Context size | LUT | LUT size | Code size | | Total size |
0 | 0.17 KB | Flash | 0.3 KB | 0.5 KB | | 0.8 KB |
1 | 0.17 KB | - | - | 7.7 KB | | 7.7 KB |
Type-safe API
The following table lists the SHA-256 type-safe API functions.
CRYPTO_SHA256_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SHA256_Add( CRYPTO_SHA256_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SHA256_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_SHA256_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA256_Calc_256()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_SHA256_Calc_256( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 32 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA256_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SHA256_Final(CRYPTO_SHA256_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA256_Final_256()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_SHA256_Final_256(CRYPTO_SHA256_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 32 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA256_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SHA256_Get(CRYPTO_SHA256_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_SHA256_Init()
Description
Initialize context.
Prototype
void CRYPTO_SHA256_Init(CRYPTO_SHA256_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SHA256_Install()
Description
Install SHA-256 hash implementation.
Prototype
void CRYPTO_SHA256_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_SHA256_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_SHA256_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_SHA256_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SHA256_Kill(CRYPTO_SHA256_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA256_QueryInstall()
Description
Query SHA-256 hardware accelerator.
Prototype
void CRYPTO_SHA256_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the SHA-256 functions that conform to the generic hash API.
CRYPTO_HASH_SHA256_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SHA256_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SHA256_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SHA256_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SHA256_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SHA256_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SHA256_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SHA256_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SHA256_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SHA256_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the SHA-256 self-test API functions.
CRYPTO_SHA256_CAVS_SelfTest()
Description
Run SHA-256 KATs from CAVS.
Prototype
void CRYPTO_SHA256_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
CRYPTO_SHA256_FIPS180_SelfTest()
Description
Run SHA-256 KATs from FIPS 180-2.
Prototype
void CRYPTO_SHA256_FIPS180_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
Example applications
CRYPTO_Bench_SHA256.c
This application benchmarks the configured performance of SHA-256.
It will benchmark both the software and hardware implementations,
if a hardware accelerator is installed.
Example output
Copyright (c) 2014-2018 SEGGER Microcontroller GmbH www.segger.com
SHA-256 Benchmark compiled Mar 19 2018 16:23:21
Compiler: clang 5.0.0 (tags/RELEASE_500/final)
System: Processor speed = 200.000 MHz
Config: CRYPTO_VERSION = 22400 [2.24]
Config: CRYPTO_CONFIG_SHA256_OPTIMIZE = 1
Config: CRYPTO_CONFIG_SHA256_HW_OPTIMIZE = 1
+--------------+-----------+
| Algorithm | Hash MB/s |
+--------------+-----------+
| SHA-256 (SW) | 3.61 |
| SHA-256 (HW) | 112.94 |
+--------------+-----------+
Benchmark complete
Complete listing
/*********************************************************************
* (c) SEGGER Microcontroller GmbH *
* The Embedded Experts *
* www.segger.com *
**********************************************************************
-------------------------- END-OF-HEADER -----------------------------
File : CRYPTO_Bench_SHA256.c
Purpose : Benchmark SHA-256 implementation.
*/
/*********************************************************************
*
* #include section
*
**********************************************************************
*/
#include "CRYPTO.h"
#include "SEGGER_SYS.h"
/*********************************************************************
*
* Static data
*
**********************************************************************
*/
static const U8 _aTestMessage[8192] = { 0 };
/*********************************************************************
*
* Static code
*
**********************************************************************
*/
/*********************************************************************
*
* _ConvertTicksToSeconds()
*
* Function description
* Convert ticks to seconds.
*
* Parameters
* Ticks - Number of ticks reported by SEGGER_SYS_OS_GetTimer().
*
* Return value
* Number of seconds corresponding to tick.
*/
static double _ConvertTicksToSeconds(U64 Ticks) {
return SEGGER_SYS_OS_ConvertTicksToMicros(Ticks) / 1000000.0;
}
/*********************************************************************
*
* _HashBenchmark()
*
* Function description
* Benchmarks a hash implementation.
*
* Parameters
* sAlgorithm - Hash algorithm name.
* pAPI - Pointer to hash API.
*/
static void _HashBenchmark(const char *sAlgorithm, const CRYPTO_HASH_API *pAPI) {
CRYPTO_SHA256_CONTEXT C;
U64 T0;
U64 OneSecond;
unsigned n;
//
SEGGER_SYS_IO_Printf("| %-12s | ", sAlgorithm);
OneSecond = SEGGER_SYS_OS_ConvertMicrosToTicks(1000000);
//
T0 = SEGGER_SYS_OS_GetTimer();
n = 0;
if (pAPI->pfClaim) {
pAPI->pfClaim();
}
pAPI->pfInit(&C);
while (SEGGER_SYS_OS_GetTimer() - T0 < OneSecond) {
pAPI->pfAdd(&C, &_aTestMessage[0], sizeof(_aTestMessage));
n += sizeof(_aTestMessage);
}
pAPI->pfKill(&C);
T0 = SEGGER_SYS_OS_GetTimer() - T0;
SEGGER_SYS_IO_Printf("%9.2f |\n", (double)n / (1024.0*1024.0) / _ConvertTicksToSeconds(T0));
}
/*********************************************************************
*
* Public code
*
**********************************************************************
*/
/*********************************************************************
*
* MainTask()
*
* Function description
* Main entry point for application to run all the tests.
*/
void MainTask(void);
void MainTask(void) {
const CRYPTO_HASH_API * pHWAPI;
const CRYPTO_HASH_API * pSWAPI;
//
CRYPTO_Init();
SEGGER_SYS_Init();
//
SEGGER_SYS_IO_Printf("%s www.segger.com\n", CRYPTO_GetCopyrightText());
SEGGER_SYS_IO_Printf("SHA-256 Benchmark compiled " __DATE__ " " __TIME__ "\n\n");
//
SEGGER_SYS_IO_Printf("Compiler: %s\n", SEGGER_SYS_GetCompiler());
if (SEGGER_SYS_GetProcessorSpeed() > 0) {
SEGGER_SYS_IO_Printf("System: Processor speed = %.3f MHz\n", (double)SEGGER_SYS_GetProcessorSpeed() / 1000000.0f);
}
SEGGER_SYS_IO_Printf("Config: CRYPTO_VERSION = %u [%s]\n", CRYPTO_VERSION, CRYPTO_GetVersionText());
SEGGER_SYS_IO_Printf("Config: CRYPTO_CONFIG_SHA256_OPTIMIZE = %d\n", CRYPTO_CONFIG_SHA256_OPTIMIZE);
SEGGER_SYS_IO_Printf("Config: CRYPTO_CONFIG_SHA256_HW_OPTIMIZE = %d\n\n", CRYPTO_CONFIG_SHA256_HW_OPTIMIZE);
//
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
SEGGER_SYS_IO_Printf("| Algorithm | Hash MB/s |\n");
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
//
_HashBenchmark("SHA-224 (SW)", &CRYPTO_HASH_SHA224_SW);
CRYPTO_SHA224_QueryInstall(&pHWAPI, &pSWAPI);
if (pHWAPI && pHWAPI != &CRYPTO_HASH_SHA224_SW) {
_HashBenchmark("SHA-224 (HW)", pHWAPI);
}
_HashBenchmark("SHA-256 (SW)", &CRYPTO_HASH_SHA256_SW);
CRYPTO_SHA256_QueryInstall(&pHWAPI, &pSWAPI);
if (pHWAPI && pHWAPI != &CRYPTO_HASH_SHA256_SW) {
_HashBenchmark("SHA-256 (HW)", pHWAPI);
}
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
//
SEGGER_SYS_IO_Printf("\nBenchmark complete\n");
SEGGER_SYS_OS_PauseBeforeHalt();
SEGGER_SYS_OS_Halt(0);
}
/*************************** End of file ****************************/
SHA-384
Standards reference
SHA-384 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SHA384_BLOCK_BYTE_COUNT 64
The number of bytes in a single SHA-384 block.
Digest size
#define CRYPTO_SHA384_DIGEST_BIT_COUNT 384
#define CRYPTO_SHA384_DIGEST_BYTE_COUNT 48
The number of bits and bytes required to hold a complete SHA-384 digest.
Type-safe API
The following table lists the SHA-384 type-safe API functions.
CRYPTO_SHA384_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SHA384_Add( CRYPTO_SHA384_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SHA384_Calc()
Description
All-in-one computation of SHA-384 digest over data.
Prototype
void CRYPTO_SHA384_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA384_Calc_384()
Description
Calculate digest over message.
Prototype
void CRYPTO_SHA384_Calc_384( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 48 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA384_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SHA384_Final(CRYPTO_SHA384_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA384_Final_384()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_SHA384_Final_384(CRYPTO_SHA384_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 32 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA384_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SHA384_Get(CRYPTO_SHA384_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_SHA384_Init()
Description
Initialize context.
Prototype
void CRYPTO_SHA384_Init(CRYPTO_SHA384_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SHA384_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SHA384_Kill(CRYPTO_SHA384_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Generic API
The following table lists the SHA-384 functions that conform to the generic hash API.
CRYPTO_HASH_SHA384_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SHA384_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SHA384_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SHA384_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SHA384_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SHA384_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SHA384_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SHA384_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SHA384_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SHA384_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the SHA-384 self-test API functions.
CRYPTO_SHA384_CAVS_SelfTest()
Description
Run SHA-384 KATs from CAVS.
Prototype
void CRYPTO_SHA384_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
SHA-512
Standards reference
SHA-512 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SHA512_BLOCK_BYTE_COUNT 128
The number of bytes in a single SHA-512 block.
Digest size
#define CRYPTO_SHA512_DIGEST_BIT_COUNT 512
#define CRYPTO_SHA512_DIGEST_BYTE_COUNT 64
The number of bits and bytes required to hold a complete SHA-512 digest.
Configuration and resource use
Default
#define CRYPTO_CONFIG_SHA512_OPTIMIZE 0
Override
To define a non-default value, define this symbol in CRYPTO_Conf.h.
Description
Set this preprocessor symbol to zero to optimize the SHA-512 hash
functions for size rather than for speed. When optimized for speed,
the SHA-512 function is open coded and faster, but is significantly
larger.
Profile
The following table shows required context size, lookup table (LUT) size,
and code size in kilobytes for each configuration value. All values are
approximate and for a Cortex-M3 processor.
Setting | Context size | LUT | LUT size | Code size | | Total size |
0 | 0.20 KB | Flash | 0.7 KB | 1.1 KB | | 1.8 KB |
1 | 0.20 KB | Flash | 0.7 KB | 10.3 KB | | 11.0 KB |
2 | 0.20 KB | Flash | 0.1 KB | 41.5 KB | | 41.6 KB |
Type-safe API
The following table lists the SHA-512 type-safe API functions.
CRYPTO_SHA512_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SHA512_Add( CRYPTO_SHA512_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SHA512_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_SHA512_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA512_Calc_512()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_SHA512_Calc_512( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 64 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA512_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SHA512_Final(CRYPTO_SHA512_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA512_Final_512()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_SHA512_Final_512(CRYPTO_SHA512_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 64 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA512_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SHA512_Get(CRYPTO_SHA512_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_SHA512_Init()
Description
Initialize context.
Prototype
void CRYPTO_SHA512_Init(CRYPTO_SHA512_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SHA512_Install()
Description
Install SHA-512 hash implementation.
Prototype
void CRYPTO_SHA512_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_SHA512_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_SHA512_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_SHA512_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SHA512_Kill(CRYPTO_SHA512_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA512_QueryInstall()
Description
Query SHA-512 hardware accelerator.
Prototype
void CRYPTO_SHA512_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the SHA-512 functions that conform to the generic hash API.
CRYPTO_HASH_SHA512_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SHA512_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SHA512_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SHA512_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SHA512_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SHA512_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SHA512_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SHA512_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SHA512_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SHA512_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the SHA-512 self-test API functions.
CRYPTO_SHA512_CAVS_SelfTest()
Description
Run SHA-512 KATs from CAVS.
Prototype
void CRYPTO_SHA512_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
CRYPTO_SHA512_FIPS180_SelfTest()
Description
Run SHA-512 KATs from FIPS 180-2.
Prototype
void CRYPTO_SHA512_FIPS180_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
Example applications
CRYPTO_Bench_SHA512.c
This application benchmarks the configured performance of SHA-512.
It will benchmark both the software and hardware implementations,
if a hardware accelerator is installed.
Example output
Copyright (c) 2014-2018 SEGGER Microcontroller GmbH www.segger.com
SHA-512 Benchmark compiled Mar 19 2018 16:43:06
Compiler: clang 5.0.0 (tags/RELEASE_500/final)
System: Processor speed = 200.000 MHz
Config: CRYPTO_VERSION = 22400 [2.24]
Config: CRYPTO_CONFIG_SHA512_OPTIMIZE = 2
Config: CRYPTO_CONFIG_SHA512_HW_OPTIMIZE = 1
+--------------+-----------+
| Algorithm | Hash MB/s |
+--------------+-----------+
| SHA-512 (SW) | 1.57 |
+--------------+-----------+
Benchmark complete
Complete listing
/*********************************************************************
* (c) SEGGER Microcontroller GmbH *
* The Embedded Experts *
* www.segger.com *
**********************************************************************
-------------------------- END-OF-HEADER -----------------------------
File : CRYPTO_Bench_SHA512.c
Purpose : Benchmark SHA-512 implementation.
*/
/*********************************************************************
*
* #include section
*
**********************************************************************
*/
#include "CRYPTO.h"
#include "SEGGER_SYS.h"
/*********************************************************************
*
* Static const data
*
**********************************************************************
*/
static const U8 _aTestMessage[65536] = { 0 };
/*********************************************************************
*
* Static code
*
**********************************************************************
*/
/*********************************************************************
*
* _ConvertTicksToSeconds()
*
* Function description
* Convert ticks to seconds.
*
* Parameters
* Ticks - Number of ticks reported by SEGGER_SYS_OS_GetTimer().
*
* Return value
* Number of seconds corresponding to tick.
*/
static double _ConvertTicksToSeconds(U64 Ticks) {
return SEGGER_SYS_OS_ConvertTicksToMicros(Ticks) / 1000000.0;
}
/*********************************************************************
*
* _HashBenchmark()
*
* Function description
* Benchmarks a hash implementation.
*
* Parameters
* sAlgorithm - Hash algorithm name.
* pAPI - Pointer to hash API.
*/
static void _HashBenchmark(const char *sAlgorithm, const CRYPTO_HASH_API *pAPI) {
CRYPTO_SHA512_CONTEXT C; // big enough for most things...
U64 T0;
U64 OneSecond;
unsigned n;
//
SEGGER_SYS_IO_Printf("| %-12s | ", sAlgorithm);
OneSecond = SEGGER_SYS_OS_ConvertMicrosToTicks(1000000);
//
T0 = SEGGER_SYS_OS_GetTimer();
n = 0;
pAPI->pfInit(&C);
while (SEGGER_SYS_OS_GetTimer() - T0 < OneSecond) {
pAPI->pfAdd(&C, &_aTestMessage[0], sizeof(_aTestMessage));
n += sizeof(_aTestMessage);
}
pAPI->pfKill(&C);
T0 = SEGGER_SYS_OS_GetTimer() - T0;
SEGGER_SYS_IO_Printf("%9.2f |\n", (double)n / (1024.0*1024.0) / _ConvertTicksToSeconds(T0));
}
/*********************************************************************
*
* Public code
*
**********************************************************************
*/
/*********************************************************************
*
* MainTask()
*
* Function description
* Main entry point for application to run all the tests.
*/
void MainTask(void);
void MainTask(void) {
const CRYPTO_HASH_API * pHWAPI;
const CRYPTO_HASH_API * pSWAPI;
//
CRYPTO_Init();
SEGGER_SYS_Init();
//
SEGGER_SYS_IO_Printf("%s www.segger.com\n", CRYPTO_GetCopyrightText());
SEGGER_SYS_IO_Printf("SHA-512 Benchmark compiled " __DATE__ " " __TIME__ "\n\n");
//
SEGGER_SYS_IO_Printf("Compiler: %s\n", SEGGER_SYS_GetCompiler());
if (SEGGER_SYS_GetProcessorSpeed() > 0) {
SEGGER_SYS_IO_Printf("System: Processor speed = %.3f MHz\n", (double)SEGGER_SYS_GetProcessorSpeed() / 1000000.0f);
}
SEGGER_SYS_IO_Printf("Config: CRYPTO_VERSION = %u [%s]\n", CRYPTO_VERSION, CRYPTO_GetVersionText());
SEGGER_SYS_IO_Printf("Config: CRYPTO_CONFIG_SHA512_OPTIMIZE = %d\n", CRYPTO_CONFIG_SHA512_OPTIMIZE);
SEGGER_SYS_IO_Printf("Config: CRYPTO_CONFIG_SHA512_HW_OPTIMIZE = %d\n\n", CRYPTO_CONFIG_SHA256_HW_OPTIMIZE);
//
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
SEGGER_SYS_IO_Printf("| Algorithm | Hash MB/s |\n");
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
//
_HashBenchmark("SHA-512 (SW)", &CRYPTO_HASH_SHA512_SW);
CRYPTO_SHA512_QueryInstall(&pHWAPI, &pSWAPI);
if (pHWAPI != &CRYPTO_HASH_SHA512_SW) {
_HashBenchmark("SHA-512 (HW)", pHWAPI);
}
SEGGER_SYS_IO_Printf("+--------------+-----------+\n");
//
SEGGER_SYS_IO_Printf("\nBenchmark complete\n");
SEGGER_SYS_OS_PauseBeforeHalt();
SEGGER_SYS_OS_Halt(0);
}
/*************************** End of file ****************************/
SHA-512/224
Standards reference
SHA-512/224 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SHA512_224_BLOCK_BYTE_COUNT 128
The number of bytes in a single SHA-512/224 block.
Digest size
#define CRYPTO_SHA512_224_DIGEST_BIT_COUNT 224
#define CRYPTO_SHA512_224_DIGEST_BYTE_COUNT 28
The number of bits and bytes required to hold a complete SHA-512/224 digest.
Type-safe API
The following table lists the SHA-512/224 type-safe API functions.
CRYPTO_SHA512_224_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SHA512_224_Add( CRYPTO_SHA512_224_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SHA512_224_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_SHA512_224_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
CRYPTO_SHA512_224_Calc_224()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_SHA512_224_Calc_224( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 28 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
CRYPTO_SHA512_224_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SHA512_224_Final(CRYPTO_SHA512_224_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA512_224_Final_224()
Description
Finish digest calculation, fixed size.
Prototype
void CRYPTO_SHA512_224_Final_224(CRYPTO_SHA512_224_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 28 bytes. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA512_224_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SHA512_224_Get(CRYPTO_SHA512_224_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function calculates the intermediate SHA-512/256 digest
from the data that has been added. After calling
this function, the context is not destroyed and
additional data can be added to continue digest calculation.
CRYPTO_SHA512_224_Init()
Description
Initialize context.
Prototype
void CRYPTO_SHA512_224_Init(CRYPTO_SHA512_224_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SHA512_224_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SHA512_224_Kill(CRYPTO_SHA512_224_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Generic API
The following table lists the SHA-512/224 functions that conform to the generic hash API.
CRYPTO_HASH_SHA512_224_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SHA512_224_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SHA512_224_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SHA512_224_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SHA512_224_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SHA512_224_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SHA512_224_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SHA512_224_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SHA512_224_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SHA512_224_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
SHA-512/256
Standards reference
SHA-512/256 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SHA512_256_BLOCK_BYTE_COUNT 128
The number of bytes in a single SHA-512/256 block.
Digest size
#define CRYPTO_SHA512_256_DIGEST_BIT_COUNT 256
#define CRYPTO_SHA512_256_DIGEST_BYTE_COUNT 32
The number of bits and bytes required to hold a complete SHA-512/256 digest.
Type-safe API
The following table lists the SHA-512/256 type-safe API functions.
CRYPTO_SHA512_256_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SHA512_256_Add( CRYPTO_SHA512_256_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SHA512_256_Calc()
Description
Calculate digest over message.
Prototype
void CRYPTO_SHA512_256_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
pInput | Pointer to input octet string to hash. |
InputLen | Octet length of the input octet string. |
CRYPTO_SHA512_256_Calc_256()
Description
Calculate digest over message.
Prototype
void CRYPTO_SHA512_256_Calc_256( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
pInput | Pointer to input octet string to hash. |
InputLen | Octet length of the input octet string. |
CRYPTO_SHA512_256_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SHA512_256_Final(CRYPTO_SHA512_256_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA512_256_Final_256()
Description
Finish digest calculation, fixed size.
Prototype
void CRYPTO_SHA512_256_Final_256(CRYPTO_SHA512_256_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 32 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA512_256_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SHA512_256_Get(CRYPTO_SHA512_256_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
CRYPTO_SHA512_256_Init()
Description
Initialize context.
Prototype
void CRYPTO_SHA512_256_Init(CRYPTO_SHA512_256_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SHA512_256_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SHA512_256_Kill(CRYPTO_SHA512_256_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Generic API
The following table lists the SHA-512/256 functions that conform to the generic hash API.
CRYPTO_HASH_SHA512_256_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SHA512_256_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SHA512_256_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SHA512_256_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SHA512_256_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SHA512_256_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SHA512_256_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SHA512_256_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SHA512_256_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SHA512_256_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
SHA3-224
Standards reference
SHA3-224 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SHA3_224_BLOCK_BYTE_COUNT 144
The number of bytes in a single SHA3-224 block.
Digest size
#define CRYPTO_SHA3_224_DIGEST_BIT_COUNT 224
#define CRYPTO_SHA3_224_DIGEST_BYTE_COUNT 28
The number of bit and bytes required to hold a complete SHA3-1 digest.
Type-safe API
The following table lists the SHA3-224 type-safe API functions.
CRYPTO_SHA3_224_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SHA3_224_Add( CRYPTO_SHA3_224_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SHA3_224_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_SHA3_224_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA3_224_Calc_224()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_SHA3_224_Calc_224( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 28 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA3_224_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SHA3_224_Final(CRYPTO_SHA3_224_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_224_Final_224()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_SHA3_224_Final_224(CRYPTO_SHA3_224_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 28 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_224_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SHA3_224_Get(CRYPTO_SHA3_224_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_SHA3_224_Init()
Description
Initialize context.
Prototype
void CRYPTO_SHA3_224_Init(CRYPTO_SHA3_224_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SHA3_224_Install()
Description
Install SHA3-224 hash implementation.
Prototype
void CRYPTO_SHA3_224_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_SHA3_224_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_SHA3_224_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_SHA3_224_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SHA3_224_Kill(CRYPTO_SHA3_224_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_224_QueryInstall()
Description
Query SHA3-224 hardware accelerator.
Prototype
void CRYPTO_SHA3_224_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the SHA3-224 functions that conform to the generic hash API.
CRYPTO_HASH_SHA3_224_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SHA3_224_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SHA3_224_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SHA3_224_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SHA3_224_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SHA3_224_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SHA3_224_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SHA3_224_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SHA3_224_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SHA3_224_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the SHA3-224 self-test API functions.
CRYPTO_SHA3_224_CAVS_SelfTest()
Description
Run SHA3-224 KATs from CAVS.
Prototype
void CRYPTO_SHA3_224_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
CRYPTO_SHA3_224_FIPS202_SelfTest()
Description
Run SHA3-224 KATs from FIPS 202.
Prototype
void CRYPTO_SHA3_224_FIPS202_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
SHA3-256
Standards reference
SHA3-256 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SHA3_256_BLOCK_BYTE_COUNT 136
The number of bytes in a single SHA3-256 block.
Digest size
#define CRYPTO_SHA3_256_DIGEST_BIT_COUNT 256
#define CRYPTO_SHA3_256_DIGEST_BYTE_COUNT 32
The number of bits and bytes required to hold a complete SHA3-256 digest.
Type-safe API
The following table lists the SHA3-256 type-safe API functions.
CRYPTO_SHA3_256_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SHA3_256_Add( CRYPTO_SHA3_256_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SHA3_256_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_SHA3_256_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA3_256_Calc_256()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_SHA3_256_Calc_256( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 32 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA3_256_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SHA3_256_Final(CRYPTO_SHA3_256_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_256_Final_256()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_SHA3_256_Final_256(CRYPTO_SHA3_256_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 32 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_256_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SHA3_256_Get(CRYPTO_SHA3_256_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_SHA3_256_Init()
Description
Initialize context.
Prototype
void CRYPTO_SHA3_256_Init(CRYPTO_SHA3_256_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SHA3_256_Install()
Description
Install SHA3-256 hash implementation.
Prototype
void CRYPTO_SHA3_256_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_SHA3_256_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_SHA3_256_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_SHA3_256_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SHA3_256_Kill(CRYPTO_SHA3_256_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_256_QueryInstall()
Description
Query SHA3-256 hardware accelerator.
Prototype
void CRYPTO_SHA3_256_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the SHA3-256 functions that conform to the generic hash API.
CRYPTO_HASH_SHA3_256_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SHA3_256_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SHA3_256_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SHA3_256_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SHA3_256_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SHA3_256_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SHA3_256_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SHA3_256_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SHA3_256_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SHA3_256_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the SHA3-256 self-test API functions.
CRYPTO_SHA3_256_CAVS_SelfTest()
Description
Run SHA3-256 KATs from CAVS.
Prototype
void CRYPTO_SHA3_256_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
CRYPTO_SHA3_256_FIPS202_SelfTest()
Description
Run SHA3-256 KATs from FIPS 202.
Prototype
void CRYPTO_SHA3_256_FIPS202_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
SHA3-384
Standards reference
SHA3-384 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SHA3_384_BLOCK_BYTE_COUNT 104
The number of bytes in a single SHA3-384 block.
Digest size
#define CRYPTO_SHA3_384_DIGEST_BIT_COUNT 384
#define CRYPTO_SHA3_384_DIGEST_BYTE_COUNT 48
The number of bits and bytes required to hold a complete SHA3-384 digest.
Type-safe API
The following table lists the SHA3-384 type-safe API functions.
CRYPTO_SHA3_384_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SHA3_384_Add( CRYPTO_SHA3_384_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SHA3_384_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_SHA3_384_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA3_384_Calc_384()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_SHA3_384_Calc_384( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 48 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA3_384_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SHA3_384_Final(CRYPTO_SHA3_384_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_384_Final_384()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_SHA3_384_Final_384(CRYPTO_SHA3_384_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 48 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_384_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SHA3_384_Get(CRYPTO_SHA3_384_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_SHA3_384_Init()
Description
Initialize context.
Prototype
void CRYPTO_SHA3_384_Init(CRYPTO_SHA3_384_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SHA3_384_Install()
Description
Install SHA3-384 hash implementation.
Prototype
void CRYPTO_SHA3_384_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_SHA3_384_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_SHA3_384_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_SHA3_384_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SHA3_384_Kill(CRYPTO_SHA3_384_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_384_QueryInstall()
Description
Query SHA3-384 hardware accelerator.
Prototype
void CRYPTO_SHA3_384_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the SHA3-384 functions that conform to the generic hash API.
CRYPTO_HASH_SHA3_384_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SHA3_384_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SHA3_384_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SHA3_384_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SHA3_384_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SHA3_384_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SHA3_384_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SHA3_384_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SHA3_384_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SHA3_384_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the SHA3-384 self-test API functions.
CRYPTO_SHA3_384_CAVS_SelfTest()
Description
Run SHA3-384 KATs from CAVS.
Prototype
void CRYPTO_SHA3_384_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
CRYPTO_SHA3_384_FIPS202_SelfTest()
Description
Run SHA3-384 KATs from FIPS 202.
Prototype
void CRYPTO_SHA3_384_FIPS202_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
SHA3-512
Standards reference
SHA3-512 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SHA3_512_BLOCK_BYTE_COUNT 72
The number of bytes in a single SHA3-512 block.
Digest size
#define CRYPTO_SHA3_512_DIGEST_BIT_COUNT 512
#define CRYPTO_SHA3_512_DIGEST_BYTE_COUNT 64
The number of bits and bytes required to hold a complete SHA3-512 digest.
Type-safe API
The following table lists the SHA3-512 type-safe API functions.
CRYPTO_SHA3_512_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SHA3_512_Add( CRYPTO_SHA3_512_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SHA3_512_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_SHA3_512_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA3_512_Calc_512()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_SHA3_512_Calc_512( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 64 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SHA3_512_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SHA3_512_Final(CRYPTO_SHA3_512_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_512_Final_512()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_SHA3_512_Final_512(CRYPTO_SHA3_512_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 64 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_512_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SHA3_512_Get(CRYPTO_SHA3_512_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_SHA3_512_Init()
Description
Initialize context.
Prototype
void CRYPTO_SHA3_512_Init(CRYPTO_SHA3_512_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SHA3_512_Install()
Description
Install SHA3-512 hash implementation.
Prototype
void CRYPTO_SHA3_512_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_SHA3_512_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_SHA3_512_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_SHA3_512_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SHA3_512_Kill(CRYPTO_SHA3_512_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SHA3_512_QueryInstall()
Description
Query SHA3-512 hardware accelerator.
Prototype
void CRYPTO_SHA3_512_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the SHA3-512 functions that conform to the generic hash API.
CRYPTO_HASH_SHA3_512_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SHA3_512_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SHA3_512_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SHA3_512_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SHA3_512_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SHA3_512_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SHA3_512_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SHA3_512_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SHA3_512_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SHA3_512_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the SHA3-512 self-test API functions.
CRYPTO_SHA3_512_CAVS_SelfTest()
Description
Run SHA3-512 KATs from CAVS.
Prototype
void CRYPTO_SHA3_512_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
CRYPTO_SHA3_512_FIPS202_SelfTest()
Description
Run SHA3-512 KATs from FIPS 202.
Prototype
void CRYPTO_SHA3_512_FIPS202_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
SM3
Standards reference
SM3 is specified by the following document:
Algorithm parameters
Block size
#define CRYPTO_SM3_BLOCK_BYTE_COUNT 64
The number of bytes in a single SM3 block.
Digest size
#define CRYPTO_SM3_DIGEST_BIT_COUNT 256
#define CRYPTO_SM3_DIGEST_BYTE_COUNT 32
The number of bits and bytes required to hold a complete SM3 digest.
Configuration and resource use
Default
#define CRYPTO_CONFIG_SM3_OPTIMIZE 0
Override
To define a non-default value, define this symbol in CRYPTO_Conf.h.
Description
Set this preprocessor symbol to zero to optimize the SM3 hash
functions for size rather than for speed. When optimized for speed,
the SM3 function is open coded and faster, but is significantly
larger.
Profile
The following table shows required context size, lookup table (LUT) size,
and code size in kilobytes for each configuration value. All values are
approximate and for a Cortex-M3 processor.
Setting | Context size | LUT | LUT size | Code size | | Total size |
0 | 0.17 KB | Flash | 0.3 KB | 0.7 KB | | 1.0 KB |
1 | 0.17 KB | - | - | 8.2 KB | | 8.2 KB |
Type-safe API
The following table lists the SM3 type-safe API functions.
CRYPTO_SM3_Add()
Description
Add data to digest.
Prototype
void CRYPTO_SM3_Add( CRYPTO_SM3_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_SM3_Calc()
Description
Calculate digest.
Prototype
void CRYPTO_SM3_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SM3_Calc_256()
Description
Calculate digest, fixed size.
Prototype
void CRYPTO_SM3_Calc_256( U8 * pOutput,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 32 octets. |
pInput | Pointer to input octet string. |
InputLen | Octet length of the input octet string. |
Additional information
It is possible to truncate the digest by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the digest are written to the message digest
buffer.
CRYPTO_SM3_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_SM3_Final(CRYPTO_SM3_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SM3_Final_256()
Description
Finalize digest calculation, fixed size.
Prototype
void CRYPTO_SM3_Final_256(CRYPTO_SM3_CONTEXT * pSelf,
U8 * pOutput);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest, 32 octets. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SM3_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_SM3_Get(CRYPTO_SM3_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_SM3_Init()
Description
Initialize context.
Prototype
void CRYPTO_SM3_Init(CRYPTO_SM3_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
CRYPTO_SM3_Install()
Description
Install SM3 hash implementation.
Prototype
void CRYPTO_SM3_Install(const CRYPTO_HASH_API * pHWAPI,
const CRYPTO_HASH_API * pSWAPI);
Parameters
Parameter | Description |
pHWAPI | Pointer to API to use as the preferred implementation. |
pSWAPI | Pointer to API to use as the fallback implementation. |
CRYPTO_SM3_IsInstalled()
Description
Query whether hash algorithm is installed.
Prototype
int CRYPTO_SM3_IsInstalled(void);
Return value
= 0 | Hash algorithm is not installed. |
≠ 0 | Hash algorithm is installed. |
CRYPTO_SM3_Kill()
Description
Destroy context.
Prototype
void CRYPTO_SM3_Kill(CRYPTO_SM3_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_SM3_QueryInstall()
Description
Query SM3 hardware accelerator.
Prototype
void CRYPTO_SM3_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
const CRYPTO_HASH_API ** ppSWAPI);
Parameters
Parameter | Description |
ppHWAPI | Pointer to object that receives the preferred API pointer. |
ppSWAPI | Pointer to object that receives the fallback API pointer. |
Generic API
The following table lists the SM3 functions that conform to the generic hash API.
CRYPTO_HASH_SM3_Add()
Description
Add data to digest.
Prototype
void CRYPTO_HASH_SM3_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pInput | Pointer to octet string to add to digest. |
InputLen | Octet length of the octet string. |
CRYPTO_HASH_SM3_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_HASH_SM3_Final(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
CRYPTO_HASH_SM3_Get()
Description
Get incremental digest.
Prototype
void CRYPTO_HASH_SM3_Get(void * pContext,
U8 * pDigest,
unsigned DigestLen);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
pDigest | Pointer to object that receives the message digest. |
DigestLen | Octet length of the digest. |
Additional information
This function computes the current message digest and writes
it to the receiving object. The hash context is not invalidated
and additional data can be added to the hash context in order
to continue hashing.
CRYPTO_HASH_SM3_Init()
Description
Initialize context.
Prototype
void CRYPTO_HASH_SM3_Init(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
CRYPTO_HASH_SM3_Kill()
Description
Destroy digest.
Prototype
void CRYPTO_HASH_SM3_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to hash context. |
Additional information
After calling this function, the context is destroyed
and must be reinitialized to be used again. The entire hash
context is set to zero to ensure no cryptographic material
remains in memory.
Self-test API
The following table lists the SM3 self-test API functions.
CRYPTO_SM3_GBT_SelfTest()
Description
Run SM3 KATs from GBT.
Prototype
void CRYPTO_SM3_GBT_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
GHASH
Type-safe API
The following table lists the GHASH type-safe API functions.
CRYPTO_GHASH_Add()
Description
Add data to digest.
Prototype
void CRYPTO_GHASH_Add( CRYPTO_GHASH_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pInput | Pointer to input string to add. |
InputLen | Octet length of the input string. |
CRYPTO_GHASH_Calc()
Description
Calculate digest over message.
Prototype
void CRYPTO_GHASH_Calc( U8 * pOutput,
const U8 * pSubkey,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the message digest, 16 octets. |
pSubkey | Pointer to hash subkey, 16 octets. |
pInput | Pointer to message to hash. |
InputLen | Octet length of message. |
CRYPTO_GHASH_Final()
Description
Finalize digest calculation.
Prototype
void CRYPTO_GHASH_Final(CRYPTO_GHASH_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pOutput | Pointer to object that receives the message digest. |
OutputLen | Octet length of the message digest. |
CRYPTO_GHASH_InitEx()
Description
Initialize context.
Prototype
void CRYPTO_GHASH_InitEx( CRYPTO_GHASH_CONTEXT * pSelf,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
pIV | Pointer to initialization vector. |
IVLen | Octet length of the initialization vector. |
CRYPTO_GHASH_Kill()
Description
Destroy context.
Prototype
void CRYPTO_GHASH_Kill(CRYPTO_GHASH_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to hash context. |
MAC algorithms
emCrypt implements the following message authentication
code algorithms:
Introduction
In general a MAC calculation is performed in three steps:
- Initialising the calculation using the key.
- Processing input data. This step can be repeated multiple times.
- Calculating the final MAC value.
The key and the intermediate results are stored in a data structure called a ’MAC context’.
The MAC context is maintained by the MAC functions, only the memory must be provided by the caller.
It can be discarded after the final MAC calculation is done.
The API functions are named in the same way for all MAC algorithms:
- CRYPTO_<mac_algo_name>_Init() for initializing and setting the key.
- CRYPTO_<mac_algo_name>_Add() to process data.
- CRYPTO_<mac_algo_name>_Final() to calculate the final MAC value.
Example
//
// Example for a SHA-1 HMAC calculation.
//
static const U8 Key[] = { 0x08, 0x15, 0x85, 0xa1, ..., 0x5b, 0xa3 };
CRYPTO_HMAC_SHA1_CONTEXT HMACContext;
U8 aMAC[CRYPTO_SHA1_DIGEST_BYTE_COUNT];
//
// Initialize the hash context.
//
CRYPTO_HMAC_SHA1_Init(&HMACContext, Key, sizeof(Key));
//
// Process input data.
//
CRYPTO_HMAC_SHA1_Add(&HMACContext, Data1, Data1Len);
//
// More data.
//
CRYPTO_HMAC_SHA1_Add(&HMACContext, Data2, Data2Len);
//
// Calculate MAC.
//
CRYPTO_HMAC_SHA1_Final(&HMACContext, aMAC, sizeof(aMAC));
//
// aMAC now contains the MAC value.
// From now, HMACContext is not used any more.
//
For every MAC algorithm there is also a function to perform the whole MAC calculation in one step.
These functions are called CRYPTO_<mac_algo_name>_Calc() and provide an easy way to calculate a MAC from a single piece of data.
Besides the type-safe API functions described above, there are also generic API functions, that use a void pointer to take the MAC context.
These are useful, if the API functions shall be called via functions pointers to dynamically choose different MAC algorithms.
When using the generic functions the caller is responsible to provide the correct context (or memory areas) via the void pointer argument.
CMAC-AES
Standards reference
CMAC is specified by the following document:
AES is specified by the following document:
Type-safe API
The following table lists the CMAC-AES type-safe API functions.
CRYPTO_CMAC_AES_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_CMAC_AES_Add( CRYPTO_CMAC_AES_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pInput | Pointer to octet string to add to MAC. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_CMAC_AES_Calc()
Description
Calculate MAC.
Prototype
void CRYPTO_CMAC_AES_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 16 octets. |
OutputLen | Octet length of the MAC. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_AES_Calc_128()
Description
Calculate MAC, fixed size.
Prototype
void CRYPTO_CMAC_AES_Calc_128( U8 * pOutput,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 16 octets. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_AES_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_CMAC_AES_Final(CRYPTO_CMAC_AES_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pOutput | Pointer to object that receives the MAC. |
OutputLen | Octet length of the MAC. |
Additional information
It is possible to truncate the MAC by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the MAC are written to the receiving object.
CRYPTO_CMAC_AES_Final_128()
Description
Finish MAC calculation, fixed size.
Prototype
void CRYPTO_CMAC_AES_Final_128(CRYPTO_CMAC_AES_CONTEXT * pSelf,
U8 * pMAC);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC, 16 octets. |
CRYPTO_CMAC_AES_Init()
Description
Initialize context.
Prototype
void CRYPTO_CMAC_AES_Init( CRYPTO_CMAC_AES_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
CRYPTO_CMAC_AES_InitEx()
Description
Initialize context, include subkey.
Prototype
void CRYPTO_CMAC_AES_InitEx( CRYPTO_CMAC_AES_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pIV | Pointer to initialization vector (ignored). |
IVLen | Octet length of the initialization vector (must be zero). |
CRYPTO_CMAC_AES_Kill()
Description
Destroy context.
Prototype
void CRYPTO_CMAC_AES_Kill(CRYPTO_CMAC_AES_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
Generic API
The following table lists the CMAC-AES functions that conform to the generic MAC API.
CRYPTO_MAC_CMAC_AES_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_MAC_CMAC_AES_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pInput | Pointer to input to add to MAC. |
InputLen | Octet length of the input string. |
CRYPTO_MAC_CMAC_AES_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_MAC_CMAC_AES_Final(void * pContext,
U8 * pMAC,
unsigned MACLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC. |
MACLen | Octet length of the MAC. |
CRYPTO_MAC_CMAC_AES_Final_128()
Description
Finish MAC calculation, fixed size.
Prototype
void CRYPTO_MAC_CMAC_AES_Final_128(void * pContext,
U8 * pMAC);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC. |
CRYPTO_MAC_CMAC_AES_Init()
Description
Initialize context.
Prototype
void CRYPTO_MAC_CMAC_AES_Init( void * pContext,
const U8 * pKey,
unsigned KeyLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pKey | Pointer to octet string that is the key. |
KeyLen | Length of key octet string. |
CRYPTO_MAC_CMAC_AES_InitEx()
Description
Initialize context, include subkey.
Prototype
void CRYPTO_MAC_CMAC_AES_InitEx( void * pContext,
unsigned DigestLen,
const U8 * pKey,
unsigned KeyLen,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
DigestLen | Octet length of the digest octet string. |
pKey | Pointer to key octet string. |
KeyLen | Octet length of the key octet string. |
pIV | Pointer to IV octet string. |
IVLen | Octet length of the IV octet string. |
CRYPTO_MAC_CMAC_AES_Kill()
Description
Destroy MAC context.
Prototype
void CRYPTO_MAC_CMAC_AES_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
Self-test API
The following table lists the CMAC-AES self-test API functions.
CRYPTO_CMAC_AES_CAVS_SelfTest()
Description
Run AES-CMAC self-test.
Prototype
void CRYPTO_CMAC_AES_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
CMAC-TDES
Standards reference
CMAC is specified by the following document:
DES and TDES are specified by the following document:
Type-safe API
The following table lists the CMAC-TDES type-safe API functions.
CRYPTO_CMAC_TDES_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_CMAC_TDES_Add( CRYPTO_CMAC_TDES_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pInput | Pointer to octet string to add to MAC. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_CMAC_TDES_Calc()
Description
Calculate MAC.
Prototype
void CRYPTO_CMAC_TDES_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 8 octets. |
OutputLen | Octet length of the MAC. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_TDES_Calc_64()
Description
Calculate MAC, fixed size.
Prototype
void CRYPTO_CMAC_TDES_Calc_64( U8 * pOutput,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 8 octets. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_TDES_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_CMAC_TDES_Final(CRYPTO_CMAC_TDES_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pOutput | Pointer to object that receives the MAC. |
OutputLen | Octet length of the MAC. |
Additional information
It is possible to truncate the MAC by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the MAC are written to the receiving object.
CRYPTO_CMAC_TDES_Final_64()
Description
Finish MAC calculation, fixed size.
Prototype
void CRYPTO_CMAC_TDES_Final_64(CRYPTO_CMAC_TDES_CONTEXT * pSelf,
U8 * pMAC);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC, 8 octets. |
CRYPTO_CMAC_TDES_Init()
Description
Initialize context.
Prototype
void CRYPTO_CMAC_TDES_Init( CRYPTO_CMAC_TDES_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
CRYPTO_CMAC_TDES_InitEx()
Description
Initialize context, include subkey.
Prototype
void CRYPTO_CMAC_TDES_InitEx( CRYPTO_CMAC_TDES_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pIV | Pointer to initialization vector (ignored). |
IVLen | Octet length of the initialization vector (must be zero). |
CRYPTO_CMAC_TDES_Kill()
Description
Destroy context.
Prototype
void CRYPTO_CMAC_TDES_Kill(CRYPTO_CMAC_TDES_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
Generic API
The following table lists the CMAC-TDES functions that conform to the generic MAC API.
CRYPTO_MAC_CMAC_TDES_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_MAC_CMAC_TDES_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pInput | Pointer to input to add to MAC. |
InputLen | Octet length of the input string. |
CRYPTO_MAC_CMAC_TDES_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_MAC_CMAC_TDES_Final(void * pContext,
U8 * pMAC,
unsigned MACLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC. |
MACLen | Octet length of the MAC. |
CRYPTO_MAC_CMAC_TDES_Final_64()
Description
Finish MAC calculation, fixed size.
Prototype
void CRYPTO_MAC_CMAC_TDES_Final_64(void * pContext,
U8 * pMAC);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC. |
CRYPTO_MAC_CMAC_TDES_Init()
Description
Initialize context.
Prototype
void CRYPTO_MAC_CMAC_TDES_Init( void * pContext,
const U8 * pKey,
unsigned KeyLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pKey | Pointer to octet string that is the key. |
KeyLen | Length of key octet string. |
CRYPTO_MAC_CMAC_TDES_InitEx()
Description
Initialize context, include subkey.
Prototype
void CRYPTO_MAC_CMAC_TDES_InitEx( void * pContext,
unsigned DigestLen,
const U8 * pKey,
unsigned KeyLen,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
DigestLen | Octet length of the digest octet string. |
pKey | Pointer to key octet string. |
KeyLen | Octet length of the key octet string. |
pIV | Pointer to IV octet string. |
IVLen | Octet length of the IV octet string. |
CRYPTO_MAC_CMAC_TDES_Kill()
Description
Destroy MAC context.
Prototype
void CRYPTO_MAC_CMAC_TDES_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
Self-test API
The following table lists the CMAC-TDES self-test API functions.
CRYPTO_CMAC_TDES_CAVS_SelfTest()
Description
Run AES-CMAC self-test.
Prototype
void CRYPTO_CMAC_TDES_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);
Parameters
Parameter | Description |
pAPI | Pointer to self-test API. |
CMAC-IDEA
Standards reference
CMAC is specified by the following document:
Type-safe API
The following table lists the CMAC-IDEA type-safe API functions.
CRYPTO_CMAC_IDEA_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_CMAC_IDEA_Add( CRYPTO_CMAC_IDEA_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pInput | Pointer to octet string to add to MAC. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_CMAC_IDEA_Calc()
Description
Calculate MAC.
Prototype
void CRYPTO_CMAC_IDEA_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 8 octets. |
OutputLen | Octet length of the MAC. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_IDEA_Calc_64()
Description
Calculate MAC, fixed size.
Prototype
void CRYPTO_CMAC_IDEA_Calc_64( U8 * pOutput,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 8 octets. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_IDEA_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_CMAC_IDEA_Final(CRYPTO_CMAC_IDEA_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pOutput | Pointer to object that receives the MAC. |
OutputLen | Octet length of the MAC. |
Additional information
It is possible to truncate the MAC by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the MAC are written to the receiving object.
CRYPTO_CMAC_IDEA_Final_64()
Description
Finish MAC calculation, fixed size.
Prototype
void CRYPTO_CMAC_IDEA_Final_64(CRYPTO_CMAC_IDEA_CONTEXT * pSelf,
U8 * pMAC);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC, 8 octets. |
CRYPTO_CMAC_IDEA_Init()
Description
Initialize context.
Prototype
void CRYPTO_CMAC_IDEA_Init( CRYPTO_CMAC_IDEA_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
CRYPTO_CMAC_IDEA_InitEx()
Description
Initialize context, include subkey.
Prototype
void CRYPTO_CMAC_IDEA_InitEx( CRYPTO_CMAC_IDEA_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pIV | Pointer to initialization vector (ignored). |
IVLen | Octet length of the initialization vector (must be zero). |
CRYPTO_CMAC_IDEA_Kill()
Description
Destroy context.
Prototype
void CRYPTO_CMAC_IDEA_Kill(CRYPTO_CMAC_IDEA_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
Generic API
The following table lists the CMAC-IDEA functions that conform to the generic MAC API.
CRYPTO_MAC_CMAC_IDEA_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_MAC_CMAC_IDEA_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pInput | Pointer to input to add to MAC. |
InputLen | Octet length of the input string. |
CRYPTO_MAC_CMAC_IDEA_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_MAC_CMAC_IDEA_Final(void * pContext,
U8 * pMAC,
unsigned MACLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC. |
MACLen | Octet length of the MAC. |
CRYPTO_MAC_CMAC_IDEA_Final_64()
Description
Finish MAC calculation, fixed size.
Prototype
void CRYPTO_MAC_CMAC_IDEA_Final_64(void * pContext,
U8 * pMAC);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC. |
CRYPTO_MAC_CMAC_IDEA_Init()
Description
Initialize context.
Prototype
void CRYPTO_MAC_CMAC_IDEA_Init( void * pContext,
const U8 * pKey,
unsigned KeyLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pKey | Pointer to octet string that is the key. |
KeyLen | Length of key octet string. |
CRYPTO_MAC_CMAC_IDEA_InitEx()
Description
Initialize context, include subkey.
Prototype
void CRYPTO_MAC_CMAC_IDEA_InitEx( void * pContext,
unsigned DigestLen,
const U8 * pKey,
unsigned KeyLen,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
DigestLen | Octet length of the digest octet string. |
pKey | Pointer to key octet string. |
KeyLen | Octet length of the key octet string. |
pIV | Pointer to IV octet string. |
IVLen | Octet length of the IV octet string. |
CRYPTO_MAC_CMAC_IDEA_Kill()
Description
Destroy MAC context.
Prototype
void CRYPTO_MAC_CMAC_IDEA_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
CMAC-CAST
Type-safe API
The following table lists the CMAC-CAST type-safe API functions.
CRYPTO_CMAC_CAST_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_CMAC_CAST_Add( CRYPTO_CMAC_CAST_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pInput | Pointer to octet string to add to MAC. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_CMAC_CAST_Calc()
Description
Calculate MAC.
Prototype
void CRYPTO_CMAC_CAST_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 8 octets. |
OutputLen | Octet length of the MAC. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_CAST_Calc_64()
Description
Calculate MAC, fixed size.
Prototype
void CRYPTO_CMAC_CAST_Calc_64( U8 * pOutput,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 8 octets. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_CAST_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_CMAC_CAST_Final(CRYPTO_CMAC_CAST_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pOutput | Pointer to object that receives the MAC. |
OutputLen | Octet length of the MAC. |
Additional information
It is possible to truncate the MAC by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the MAC are written to the receiving object.
CRYPTO_CMAC_CAST_Final_64()
Description
Finish MAC calculation, fixed size.
Prototype
void CRYPTO_CMAC_CAST_Final_64(CRYPTO_CMAC_CAST_CONTEXT * pSelf,
U8 * pMAC);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC, 8 octets. |
CRYPTO_CMAC_CAST_Init()
Description
Initialize context.
Prototype
void CRYPTO_CMAC_CAST_Init( CRYPTO_CMAC_CAST_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
CRYPTO_CMAC_CAST_InitEx()
Description
Initialize context, include subkey.
Prototype
void CRYPTO_CMAC_CAST_InitEx( CRYPTO_CMAC_CAST_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pIV | Pointer to initialization vector (ignored). |
IVLen | Octet length of the initialization vector (must be zero). |
CRYPTO_CMAC_CAST_Kill()
Description
Destroy context.
Prototype
void CRYPTO_CMAC_CAST_Kill(CRYPTO_CMAC_CAST_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
Generic API
The following table lists the CMAC-CAST functions that conform to the generic MAC API.
CRYPTO_MAC_CMAC_CAST_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_MAC_CMAC_CAST_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pInput | Pointer to input to add to MAC. |
InputLen | Octet length of the input string. |
CRYPTO_MAC_CMAC_CAST_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_MAC_CMAC_CAST_Final(void * pContext,
U8 * pMAC,
unsigned MACLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC. |
MACLen | Octet length of the MAC. |
CRYPTO_MAC_CMAC_CAST_Final_64()
Description
Finish MAC calculation, fixed size.
Prototype
void CRYPTO_MAC_CMAC_CAST_Final_64(void * pContext,
U8 * pMAC);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC. |
CRYPTO_MAC_CMAC_CAST_Init()
Description
Initialize context.
Prototype
void CRYPTO_MAC_CMAC_CAST_Init( void * pContext,
const U8 * pKey,
unsigned KeyLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pKey | Pointer to octet string that is the key. |
KeyLen | Length of key octet string. |
CRYPTO_MAC_CMAC_CAST_InitEx()
Description
Initialize context, include subkey.
Prototype
void CRYPTO_MAC_CMAC_CAST_InitEx( void * pContext,
unsigned DigestLen,
const U8 * pKey,
unsigned KeyLen,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
DigestLen | Octet length of the digest octet string. |
pKey | Pointer to key octet string. |
KeyLen | Octet length of the key octet string. |
pIV | Pointer to IV octet string. |
IVLen | Octet length of the IV octet string. |
CRYPTO_MAC_CMAC_CAST_Kill()
Description
Destroy MAC context.
Prototype
void CRYPTO_MAC_CMAC_CAST_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
CMAC-SEED
Standards reference
CMAC is specified by the following document:
SEED is specified by the following document:
Type-safe API
The following table lists the CMAC-SEED type-safe API functions.
CRYPTO_CMAC_SEED_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_CMAC_SEED_Add( CRYPTO_CMAC_SEED_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pInput | Pointer to octet string to add to MAC. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_CMAC_SEED_Calc()
Description
Calculate MAC.
Prototype
void CRYPTO_CMAC_SEED_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 16 octets. |
OutputLen | Octet length of the MAC. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_SEED_Calc_128()
Description
Calculate MAC, fixed size.
Prototype
void CRYPTO_CMAC_SEED_Calc_128( U8 * pOutput,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 16 octets. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_SEED_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_CMAC_SEED_Final(CRYPTO_CMAC_SEED_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pOutput | Pointer to object that receives the MAC. |
OutputLen | Octet length of the MAC. |
Additional information
It is possible to truncate the MAC by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the MAC are written to the receiving object.
CRYPTO_CMAC_SEED_Final_128()
Description
Finish MAC calculation, fixed size.
Prototype
void CRYPTO_CMAC_SEED_Final_128(CRYPTO_CMAC_SEED_CONTEXT * pSelf,
U8 * pMAC);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC, 16 octets. |
CRYPTO_CMAC_SEED_Init()
Description
Initialize context.
Prototype
void CRYPTO_CMAC_SEED_Init( CRYPTO_CMAC_SEED_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
CRYPTO_CMAC_SEED_InitEx()
Description
Initialize context, include subkey.
Prototype
void CRYPTO_CMAC_SEED_InitEx( CRYPTO_CMAC_SEED_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pIV | Pointer to initialization vector (ignored). |
IVLen | Octet length of the initialization vector (must be zero). |
CRYPTO_CMAC_SEED_Kill()
Description
Destroy context.
Prototype
void CRYPTO_CMAC_SEED_Kill(CRYPTO_CMAC_SEED_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
Generic API
The following table lists the CMAC-SEED functions that conform to the generic MAC API.
CRYPTO_MAC_CMAC_SEED_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_MAC_CMAC_SEED_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pInput | Pointer to input to add to MAC. |
InputLen | Octet length of the input string. |
CRYPTO_MAC_CMAC_SEED_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_MAC_CMAC_SEED_Final(void * pContext,
U8 * pMAC,
unsigned MACLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC. |
MACLen | Octet length of the MAC. |
CRYPTO_MAC_CMAC_SEED_Final_128()
Description
Finish MAC calculation, fixed size.
Prototype
void CRYPTO_MAC_CMAC_SEED_Final_128(void * pContext,
U8 * pMAC);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC. |
CRYPTO_MAC_CMAC_SEED_Init()
Description
Initialize context.
Prototype
void CRYPTO_MAC_CMAC_SEED_Init( void * pContext,
const U8 * pKey,
unsigned KeyLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pKey | Pointer to octet string that is the key. |
KeyLen | Length of key octet string. |
CRYPTO_MAC_CMAC_SEED_InitEx()
Description
Initialize context, include subkey.
Prototype
void CRYPTO_MAC_CMAC_SEED_InitEx( void * pContext,
unsigned DigestLen,
const U8 * pKey,
unsigned KeyLen,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
DigestLen | Octet length of the digest octet string. |
pKey | Pointer to key octet string. |
KeyLen | Octet length of the key octet string. |
pIV | Pointer to IV octet string. |
IVLen | Octet length of the IV octet string. |
CRYPTO_MAC_CMAC_SEED_Kill()
Description
Destroy MAC context.
Prototype
void CRYPTO_MAC_CMAC_SEED_Kill(void * pContext);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
CMAC-ARIA
Standards reference
CMAC is specified by the following document:
ARIA is specified by the following document:
Type-safe API
The following table lists the CMAC-ARIA type-safe API functions.
CRYPTO_CMAC_ARIA_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_CMAC_ARIA_Add( CRYPTO_CMAC_ARIA_CONTEXT * pSelf,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pInput | Pointer to octet string to add to MAC. |
InputLen | Octet length of the octet string. |
Additional information
The input data can be any length and is not limited to the
underlying block size: the algorithm internally manages
correct blocking of data.
CRYPTO_CMAC_ARIA_Calc()
Description
Calculate MAC.
Prototype
void CRYPTO_CMAC_ARIA_Calc( U8 * pOutput,
unsigned OutputLen,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 16 octets. |
OutputLen | Octet length of the MAC. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_ARIA_Calc_128()
Description
Calculate MAC, fixed size.
Prototype
void CRYPTO_CMAC_ARIA_Calc_128( U8 * pOutput,
const U8 * pKey,
unsigned KeyLen,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pOutput | Pointer to object that receives the MAC, 16 octets. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pInput | Pointer to message. |
InputLen | Octet length of the message. |
CRYPTO_CMAC_ARIA_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_CMAC_ARIA_Final(CRYPTO_CMAC_ARIA_CONTEXT * pSelf,
U8 * pOutput,
unsigned OutputLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pOutput | Pointer to object that receives the MAC. |
OutputLen | Octet length of the MAC. |
Additional information
It is possible to truncate the MAC by specifying OutputLen
less than the full digest length: in this case, the leftmost (most
significant) octets of the MAC are written to the receiving object.
CRYPTO_CMAC_ARIA_Final_128()
Description
Finish MAC calculation, fixed size.
Prototype
void CRYPTO_CMAC_ARIA_Final_128(CRYPTO_CMAC_ARIA_CONTEXT * pSelf,
U8 * pMAC);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pMAC | Pointer to object that receives the MAC, 16 octets. |
CRYPTO_CMAC_ARIA_Init()
Description
Initialize context.
Prototype
void CRYPTO_CMAC_ARIA_Init( CRYPTO_CMAC_ARIA_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
CRYPTO_CMAC_ARIA_InitEx()
Description
Initialize context, include subkey.
Prototype
void CRYPTO_CMAC_ARIA_InitEx( CRYPTO_CMAC_ARIA_CONTEXT * pSelf,
const U8 * pKey,
unsigned KeyLen,
const U8 * pIV,
unsigned IVLen);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
pKey | Pointer to cipher key. |
KeyLen | Octet length of the cipher key. |
pIV | Pointer to initialization vector (ignored). |
IVLen | Octet length of the initialization vector (must be zero). |
CRYPTO_CMAC_ARIA_Kill()
Description
Destroy context.
Prototype
void CRYPTO_CMAC_ARIA_Kill(CRYPTO_CMAC_ARIA_CONTEXT * pSelf);
Parameters
Parameter | Description |
pSelf | Pointer to MAC context. |
Generic API
The following table lists the CMAC-ARIA functions that conform to the generic MAC API.
CRYPTO_MAC_CMAC_ARIA_Add()
Description
Add data to MAC.
Prototype
void CRYPTO_MAC_CMAC_ARIA_Add( void * pContext,
const U8 * pInput,
unsigned InputLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC context. |
pInput | Pointer to input to add to MAC. |
InputLen | Octet length of the input string. |
CRYPTO_MAC_CMAC_ARIA_Final()
Description
Finish MAC calculation.
Prototype
void CRYPTO_MAC_CMAC_ARIA_Final(void * pContext,
U8 * pMAC,
unsigned MACLen);
Parameters
Parameter | Description |
pContext | Pointer to MAC con |