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.

Functions conforming to an API

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.

Null pointer inputs

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:

Call CRYPTO_OS_Claim(), use the resource, and call CRYPTO_OS_Unclaim() to release it, or
Call CRYPTO_OS_Request() to request access to the resource. If access is granted, emCrypt uses the resource and then calls CRYPTO_OS_Unclaim() to release it. In the case where access to the resource is not granted, emCrypt will not use the resource and will not call CRYPTO_OS_Unclaim().

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

Function	Description
CRYPTO_OS_Init()	Initialize CRYPTO binding to OS.
CRYPTO_OS_Claim()	Claim a hardware resource.
CRYPTO_OS_Request()	Test-and-claim a hardware resource.
CRYPTO_OS_Unclaim()	Release claim on a hardware resource.

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 ****************************/

CRYPTO-OS binding for bare metal

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.

Function	Description
CRYPTO_GetCopyrightText()	Get copyright as printable string.
CRYPTO_GetVersionText()	Get version as printable string.
CRYPTO_Init()	Initialize CRYPTO component.

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:

BLAKE2
MD5
RIPEMD-160
SHA-1
SHA-224
SHA-256
SHA-384
SHA-512
SHA-512/224
SHA-512/256
SHA3-224
SHA3-256
SHA3-384
SHA3-512
SM3

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:

IETF RFC 7693 — The BLAKE2 Cryptographic Hash and Message Authentication Code (MAC)

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.

Function	Description
Message functions
CRYPTO_BLAKE2B_Calc()	Calculate digest.
CRYPTO_BLAKE2B_Calc_512()	Calculate digest, fixed size.
Incremental functions
CRYPTO_BLAKE2B_Init()	Initialize context.
CRYPTO_BLAKE2B_InitEx()	Initialize context, extended.
CRYPTO_BLAKE2B_Add()	Add data to digest.
CRYPTO_BLAKE2B_Get()	Get incremental digest.
CRYPTO_BLAKE2B_Final()	Finalize digest calculation.
CRYPTO_BLAKE2B_Final_512()	Finalize digest calculation, fixed size.
CRYPTO_BLAKE2B_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_BLAKE2B_Install()	Install BLAKE2b hash implementation.
CRYPTO_BLAKE2B_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_BLAKE2B_QueryInstall()	Query BLAKE2b hardware accelerator.

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

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.

Function	Description
CRYPTO_HASH_BLAKE2B_Init()	Initialize context.
CRYPTO_HASH_BLAKE2B_Add()	Add data to digest.
CRYPTO_HASH_BLAKE2B_Get()	Get incremental digest.
CRYPTO_HASH_BLAKE2B_Final()	Finalize digest calculation.
CRYPTO_HASH_BLAKE2B_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_BLAKE2B_RFC7693_SelfTest()	Run BLAKE2 KATs from RFC 7693.
CRYPTO_BLAKE2B_Ref_SelfTest()	Run BLAKE2b reference self-tests.

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:

IETF RFC 7693 — The BLAKE2 Cryptographic Hash and Message Authentication Code (MAC)

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.

Function	Description
Message functions
CRYPTO_BLAKE2S_Calc()	Calculate digest.
CRYPTO_BLAKE2S_Calc_256()	Calculate digest, fixed size.
Incremental functions
CRYPTO_BLAKE2S_Init()	Initialize context.
CRYPTO_BLAKE2S_InitEx()	Initialize context, extended.
CRYPTO_BLAKE2S_Add()	Add data to digest.
CRYPTO_BLAKE2S_Get()	Get incremental digest.
CRYPTO_BLAKE2S_Final()	Finalize digest calculation.
CRYPTO_BLAKE2S_Final_256()	Finalize digest calculation, fixed size.
CRYPTO_BLAKE2S_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_BLAKE2S_Install()	Install BLAKE2s hash implementation.
CRYPTO_BLAKE2S_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_BLAKE2S_QueryInstall()	Query BLAKE2s hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_BLAKE2S_Init()	Initialize context.
CRYPTO_HASH_BLAKE2S_Add()	Add data to digest.
CRYPTO_HASH_BLAKE2S_Get()	Get incremental digest.
CRYPTO_HASH_BLAKE2S_Final()	Finalize digest calculation.
CRYPTO_HASH_BLAKE2S_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_BLAKE2S_RFC7693_SelfTest()	Run BLAKE2 KATs from RFC 7693.

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:

IETF RFC 1321 — The MD5 Message-Digest Algorithm

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.

Function	Description
Message functions
CRYPTO_MD5_Calc()	Calculate digest.
CRYPTO_MD5_Calc_160()	Calculate digest, fixed size.
Incremental functions
CRYPTO_MD5_Init()	Initialize context.
CRYPTO_MD5_Add()	Add data to digest.
CRYPTO_MD5_Get()	Get incremental digest.
CRYPTO_MD5_Final()	Finalize digest calculation.
CRYPTO_MD5_Final_160()	Finalize digest calculation, fixed size.
CRYPTO_MD5_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_MD5_Install()	Install MD5 hash implementation.
CRYPTO_MD5_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_MD5_QueryInstall()	Query MD5 hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_MD5_Init()	Initialize context.
CRYPTO_HASH_MD5_Add()	Add data to digest.
CRYPTO_HASH_MD5_Get()	Get incremental digest.
CRYPTO_HASH_MD5_Final()	Finalize digest calculation.
CRYPTO_HASH_MD5_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_MD5_RFC1321_SelfTest()	Run MD5 test vectors from RFC 1321.

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:

Antoon Bosselaers — The hash function RIPEMD-160

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.

Function	Description
Message functions
CRYPTO_RIPEMD160_Calc()	Calculate digest.
CRYPTO_RIPEMD160_Calc_160()	Calculate digest, fixed size.
Incremental functions
CRYPTO_RIPEMD160_Init()	Initialize context.
CRYPTO_RIPEMD160_Add()	Add data to digest.
CRYPTO_RIPEMD160_Get()	Get incremental digest.
CRYPTO_RIPEMD160_Final()	Finalize digest calculation.
CRYPTO_RIPEMD160_Final_160()	Finalize digest calculation, fixed size.
CRYPTO_RIPEMD160_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_RIPEMD160_Install()	Install RIPEMD-160 hash implementation.
CRYPTO_RIPEMD160_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_RIPEMD160_QueryInstall()	Query RIPEMD-160 hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_RIPEMD160_Init()	Initialize context.
CRYPTO_HASH_RIPEMD160_Add()	Add data to digest.
CRYPTO_HASH_RIPEMD160_Get()	Get incremental digest.
CRYPTO_HASH_RIPEMD160_Final()	Finalize digest calculation.
CRYPTO_HASH_RIPEMD160_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_RIPEMD160_Bosselaers_SelfTest()	Run all RIPEMD160 test vectors defined by Bosselaers.

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:

FIPS PUB 180-4 — Secure Hash Standard (SHS)

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.

Function	Description
Message functions
CRYPTO_SHA1_Calc()	Calculate digest.
CRYPTO_SHA1_Calc_160()	Calculate digest, fixed size.
Incremental functions
CRYPTO_SHA1_Init()	Initialize context.
CRYPTO_SHA1_Add()	Add data to digest.
CRYPTO_SHA1_Get()	Get incremental digest.
CRYPTO_SHA1_Final()	Finalize digest calculation.
CRYPTO_SHA1_Final_160()	Finalize digest calculation, fixed size.
CRYPTO_SHA1_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_SHA1_Install()	Install SHA-1 hash implementation.
CRYPTO_SHA1_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_SHA1_QueryInstall()	Query SHA-1 hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_SHA1_Init()	Initialize context.
CRYPTO_HASH_SHA1_Add()	Add data to digest.
CRYPTO_HASH_SHA1_Get()	Get incremental digest.
CRYPTO_HASH_SHA1_Final()	Finalize digest calculation.
CRYPTO_HASH_SHA1_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_SHA1_FIPS180_SelfTest()	Run SHA-1 KATs from FIPS 180-2.
CRYPTO_SHA1_CAVS_SelfTest()	Run SHA-1 KATs from CAVS.

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:

FIPS PUB 180-4 — Secure Hash Standard (SHS)

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.

Function	Description
Message functions
CRYPTO_SHA224_Calc()	Calculate digest.
CRYPTO_SHA224_Calc_224()	Calculate digest, fixed size.
Incremental functions
CRYPTO_SHA224_Init()	Initialize context.
CRYPTO_SHA224_Add()	Add data to digest.
CRYPTO_SHA224_Get()	Get incremental digest.
CRYPTO_SHA224_Final()	Finalize digest calculation.
CRYPTO_SHA224_Final_224()	Finalize digest calculation, fixed size.
CRYPTO_SHA224_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_SHA224_Install()	Install SHA-224 hash implementation.
CRYPTO_SHA224_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_SHA224_QueryInstall()	Query SHA-224 hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_SHA224_Init()	Initialize context.
CRYPTO_HASH_SHA224_Add()	Add data to digest.
CRYPTO_HASH_SHA224_Get()	Get incremental digest.
CRYPTO_HASH_SHA224_Final()	Finalize digest calculation.
CRYPTO_HASH_SHA224_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_SHA224_CAVS_SelfTest()	Run SHA-224 KATs from CAVS.

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:

FIPS PUB 180-4 — Secure Hash Standard (SHS)

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.

Function	Description
Message functions
CRYPTO_SHA256_Calc()	Calculate digest.
CRYPTO_SHA256_Calc_256()	Calculate digest, fixed size.
Incremental functions
CRYPTO_SHA256_Init()	Initialize context.
CRYPTO_SHA256_Add()	Add data to digest.
CRYPTO_SHA256_Get()	Get incremental digest.
CRYPTO_SHA256_Final()	Finalize digest calculation.
CRYPTO_SHA256_Final_256()	Finalize digest calculation, fixed size.
CRYPTO_SHA256_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_SHA256_Install()	Install SHA-256 hash implementation.
CRYPTO_SHA256_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_SHA256_QueryInstall()	Query SHA-256 hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_SHA256_Init()	Initialize context.
CRYPTO_HASH_SHA256_Add()	Add data to digest.
CRYPTO_HASH_SHA256_Get()	Get incremental digest.
CRYPTO_HASH_SHA256_Final()	Finalize digest calculation.
CRYPTO_HASH_SHA256_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_SHA256_FIPS180_SelfTest()	Run SHA-256 KATs from FIPS 180-2.
CRYPTO_SHA256_CAVS_SelfTest()	Run SHA-256 KATs from CAVS.

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:

FIPS PUB 180-4 — Secure Hash Standard (SHS)

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.

Function	Description
Message functions
CRYPTO_SHA384_Calc()	All-in-one computation of SHA-384 digest over data.
CRYPTO_SHA384_Calc_384()	Calculate digest over message.
Incremental functions
CRYPTO_SHA384_Init()	Initialize context.
CRYPTO_SHA384_Add()	Add data to digest.
CRYPTO_SHA384_Get()	Get incremental digest.
CRYPTO_SHA384_Final()	Finalize digest calculation.
CRYPTO_SHA384_Final_384()	Finalize digest calculation, fixed size.
CRYPTO_SHA384_Kill()	Destroy context.

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

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

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

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.

Function	Description
CRYPTO_HASH_SHA384_Init()	Initialize context.
CRYPTO_HASH_SHA384_Add()	Add data to digest.
CRYPTO_HASH_SHA384_Get()	Get incremental digest.
CRYPTO_HASH_SHA384_Final()	Finalize digest calculation.
CRYPTO_HASH_SHA384_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_SHA384_CAVS_SelfTest()	Run SHA-384 KATs from CAVS.

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:

FIPS PUB 180-4 — Secure Hash Standard (SHS)

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.

Function	Description
Message functions
CRYPTO_SHA512_Calc()	Calculate digest.
CRYPTO_SHA512_Calc_512()	Calculate digest, fixed size.
Incremental functions
CRYPTO_SHA512_Init()	Initialize context.
CRYPTO_SHA512_Add()	Add data to digest.
CRYPTO_SHA512_Get()	Get incremental digest.
CRYPTO_SHA512_Final()	Finalize digest calculation.
CRYPTO_SHA512_Final_512()	Finalize digest calculation, fixed size.
CRYPTO_SHA512_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_SHA512_Install()	Install SHA-512 hash implementation.
CRYPTO_SHA512_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_SHA512_QueryInstall()	Query SHA-512 hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_SHA512_Init()	Initialize context.
CRYPTO_HASH_SHA512_Add()	Add data to digest.
CRYPTO_HASH_SHA512_Get()	Get incremental digest.
CRYPTO_HASH_SHA512_Final()	Finalize digest calculation.
CRYPTO_HASH_SHA512_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_SHA512_FIPS180_SelfTest()	Run SHA-512 KATs from FIPS 180-2.
CRYPTO_SHA512_CAVS_SelfTest()	Run SHA-512 KATs from CAVS.

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:

FIPS PUB 180-4 — Secure Hash Standard (SHS)

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.

Function	Description
Message functions
CRYPTO_SHA512_224_Calc()	Calculate digest.
CRYPTO_SHA512_224_Calc_224()	Calculate digest, fixed size.
Incremental functions
CRYPTO_SHA512_224_Init()	Initialize context.
CRYPTO_SHA512_224_Add()	Add data to digest.
CRYPTO_SHA512_224_Get()	Get incremental digest.
CRYPTO_SHA512_224_Final()	Finalize digest calculation.
CRYPTO_SHA512_224_Final_224()	Finish digest calculation, fixed size.
CRYPTO_SHA512_224_Kill()	Destroy context.

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.

Function	Description
CRYPTO_HASH_SHA512_224_Init()	Initialize context.
CRYPTO_HASH_SHA512_224_Add()	Add data to digest.
CRYPTO_HASH_SHA512_224_Get()	Get incremental digest.
CRYPTO_HASH_SHA512_224_Final()	Finalize digest calculation.
CRYPTO_HASH_SHA512_224_Kill()	Destroy digest.

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

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:

FIPS PUB 180-4 — Secure Hash Standard (SHS)

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.

Function	Description
Message functions
CRYPTO_SHA512_256_Calc()	Calculate digest over message.
CRYPTO_SHA512_256_Calc_256()	Calculate digest over message.
Incremental functions
CRYPTO_SHA512_256_Init()	Initialize context.
CRYPTO_SHA512_256_Add()	Add data to digest.
CRYPTO_SHA512_256_Get()	Get incremental digest.
CRYPTO_SHA512_256_Final()	Finalize digest calculation.
CRYPTO_SHA512_256_Final_256()	Finish digest calculation, fixed size.
CRYPTO_SHA512_256_Kill()	Destroy context.

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.

Function	Description
CRYPTO_HASH_SHA512_256_Init()	Initialize context.
CRYPTO_HASH_SHA512_256_Add()	Add data to digest.
CRYPTO_HASH_SHA512_256_Get()	Get incremental digest.
CRYPTO_HASH_SHA512_256_Final()	Finalize digest calculation.
CRYPTO_HASH_SHA512_256_Kill()	Destroy digest.

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

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:

FIPS PUB 202 — SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions

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.

Function	Description
Message functions
CRYPTO_SHA3_224_Calc()	Calculate digest.
CRYPTO_SHA3_224_Calc_224()	Calculate digest, fixed size.
Incremental functions
CRYPTO_SHA3_224_Init()	Initialize context.
CRYPTO_SHA3_224_Add()	Add data to digest.
CRYPTO_SHA3_224_Get()	Get incremental digest.
CRYPTO_SHA3_224_Final()	Finalize digest calculation.
CRYPTO_SHA3_224_Final_224()	Finalize digest calculation, fixed size.
CRYPTO_SHA3_224_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_SHA3_224_Install()	Install SHA3-224 hash implementation.
CRYPTO_SHA3_224_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_SHA3_224_QueryInstall()	Query SHA3-224 hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_SHA3_224_Init()	Initialize context.
CRYPTO_HASH_SHA3_224_Add()	Add data to digest.
CRYPTO_HASH_SHA3_224_Get()	Get incremental digest.
CRYPTO_HASH_SHA3_224_Final()	Finalize digest calculation.
CRYPTO_HASH_SHA3_224_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_SHA3_224_FIPS202_SelfTest()	Run SHA3-224 KATs from FIPS 202.
CRYPTO_SHA3_224_CAVS_SelfTest()	Run SHA3-224 KATs from CAVS.

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:

FIPS PUB 202 — SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions

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.

Function	Description
Message functions
CRYPTO_SHA3_256_Calc()	Calculate digest.
CRYPTO_SHA3_256_Calc_256()	Calculate digest, fixed size.
Incremental functions
CRYPTO_SHA3_256_Init()	Initialize context.
CRYPTO_SHA3_256_Add()	Add data to digest.
CRYPTO_SHA3_256_Get()	Get incremental digest.
CRYPTO_SHA3_256_Final()	Finalize digest calculation.
CRYPTO_SHA3_256_Final_256()	Finalize digest calculation, fixed size.
CRYPTO_SHA3_256_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_SHA3_256_Install()	Install SHA3-256 hash implementation.
CRYPTO_SHA3_256_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_SHA3_256_QueryInstall()	Query SHA3-256 hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_SHA3_256_Init()	Initialize context.
CRYPTO_HASH_SHA3_256_Add()	Add data to digest.
CRYPTO_HASH_SHA3_256_Get()	Get incremental digest.
CRYPTO_HASH_SHA3_256_Final()	Finalize digest calculation.
CRYPTO_HASH_SHA3_256_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_SHA3_256_FIPS202_SelfTest()	Run SHA3-256 KATs from FIPS 202.
CRYPTO_SHA3_256_CAVS_SelfTest()	Run SHA3-256 KATs from CAVS.

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:

FIPS PUB 202 — SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions

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.

Function	Description
Message functions
CRYPTO_SHA3_384_Calc()	Calculate digest.
CRYPTO_SHA3_384_Calc_384()	Calculate digest, fixed size.
Incremental functions
CRYPTO_SHA3_384_Init()	Initialize context.
CRYPTO_SHA3_384_Add()	Add data to digest.
CRYPTO_SHA3_384_Get()	Get incremental digest.
CRYPTO_SHA3_384_Final()	Finalize digest calculation.
CRYPTO_SHA3_384_Final_384()	Finalize digest calculation, fixed size.
CRYPTO_SHA3_384_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_SHA3_384_Install()	Install SHA3-384 hash implementation.
CRYPTO_SHA3_384_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_SHA3_384_QueryInstall()	Query SHA3-384 hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_SHA3_384_Init()	Initialize context.
CRYPTO_HASH_SHA3_384_Add()	Add data to digest.
CRYPTO_HASH_SHA3_384_Get()	Get incremental digest.
CRYPTO_HASH_SHA3_384_Final()	Finalize digest calculation.
CRYPTO_HASH_SHA3_384_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_SHA3_384_FIPS202_SelfTest()	Run SHA3-384 KATs from FIPS 202.
CRYPTO_SHA3_384_CAVS_SelfTest()	Run SHA3-384 KATs from CAVS.

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:

FIPS PUB 202 — SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions

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.

Function	Description
Message functions
CRYPTO_SHA3_512_Calc()	Calculate digest.
CRYPTO_SHA3_512_Calc_512()	Calculate digest, fixed size.
Incremental functions
CRYPTO_SHA3_512_Init()	Initialize context.
CRYPTO_SHA3_512_Add()	Add data to digest.
CRYPTO_SHA3_512_Get()	Get incremental digest.
CRYPTO_SHA3_512_Final()	Finalize digest calculation.
CRYPTO_SHA3_512_Final_512()	Finalize digest calculation, fixed size.
CRYPTO_SHA3_512_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_SHA3_512_Install()	Install SHA3-512 hash implementation.
CRYPTO_SHA3_512_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_SHA3_512_QueryInstall()	Query SHA3-512 hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_SHA3_512_Init()	Initialize context.
CRYPTO_HASH_SHA3_512_Add()	Add data to digest.
CRYPTO_HASH_SHA3_512_Get()	Get incremental digest.
CRYPTO_HASH_SHA3_512_Final()	Finalize digest calculation.
CRYPTO_HASH_SHA3_512_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_SHA3_512_FIPS202_SelfTest()	Run SHA3-512 KATs from FIPS 202.
CRYPTO_SHA3_512_CAVS_SelfTest()	Run SHA3-512 KATs from CAVS.

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:

draft-sca-cfrg-sm3-02 — The SM3 Cryptographic Hash Function

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.

Function	Description
Message functions
CRYPTO_SM3_Calc()	Calculate digest.
CRYPTO_SM3_Calc_256()	Calculate digest, fixed size.
Incremental functions
CRYPTO_SM3_Init()	Initialize context.
CRYPTO_SM3_Add()	Add data to digest.
CRYPTO_SM3_Get()	Get incremental digest.
CRYPTO_SM3_Final()	Finalize digest calculation.
CRYPTO_SM3_Final_256()	Finalize digest calculation, fixed size.
CRYPTO_SM3_Kill()	Destroy context.
Setup and hardware acceleration
CRYPTO_SM3_Install()	Install SM3 hash implementation.
CRYPTO_SM3_IsInstalled()	Query whether hash algorithm is installed.
CRYPTO_SM3_QueryInstall()	Query SM3 hardware accelerator.

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

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

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

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.

Function	Description
CRYPTO_HASH_SM3_Init()	Initialize context.
CRYPTO_HASH_SM3_Add()	Add data to digest.
CRYPTO_HASH_SM3_Get()	Get incremental digest.
CRYPTO_HASH_SM3_Final()	Finalize digest calculation.
CRYPTO_HASH_SM3_Kill()	Destroy digest.

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

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.

Function	Description
CRYPTO_SM3_GBT_SelfTest()	Run SM3 KATs from GBT.

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.

Function	Description
Message functions
CRYPTO_GHASH_Calc()	Calculate digest over message.
Incremental functions
CRYPTO_GHASH_InitEx()	Initialize context.
CRYPTO_GHASH_Add()	Add data to digest.
CRYPTO_GHASH_Final()	Finalize digest calculation.
CRYPTO_GHASH_Kill()	Destroy context.

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:

CMAC-AES
CMAC-TDES
CMAC-CAST
CMAC-SEED
CMAC-ARIA
CMAC-Camellia
CMAC-Twofish
CMAC-Blowfish
GMAC-AES
GMAC-SEED
GMAC-ARIA
GMAC-Camellia
GMAC-Twofish
HMAC-MD5
HMAC-RIPEMD-160
HMAC-SHA-1
HMAC-SHA-224
HMAC-SHA-256
HMAC-SHA-384
HMAC-SHA-512
HMAC-SHA-512/224
HMAC-SHA-512/256
HMAC-SHA3-224
HMAC-SHA3-256
HMAC-SHA3-384
HMAC-SHA3-512
XCBC-AES
XCBC-SEED
XCBC-ARIA
XCBC-Camellia
XCBC-Twofish
KMAC
Poly1305
Poly1305-AES
Poly1305-ARIA
Poly1305-SEED
Poly1305-Camellia
Poly1305-Twofish
Michael

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:

NIST SP 800-38B — Recommendation for Block Cipher Modes of Operation: The CMAC Mode for Authentication

AES is specified by the following document:

FIPS PUB 197 — Specification for the Advanced Encryption Standard (AES)

Type-safe API

The following table lists the CMAC-AES type-safe API functions.

Function	Description
Message functions
CRYPTO_CMAC_AES_Calc()	Calculate MAC.
CRYPTO_CMAC_AES_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_CMAC_AES_Init()	Initialize context.
CRYPTO_CMAC_AES_InitEx()	Initialize context, include subkey.
CRYPTO_CMAC_AES_Add()	Add data to MAC.
CRYPTO_CMAC_AES_Final()	Finish MAC calculation.
CRYPTO_CMAC_AES_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_CMAC_AES_Kill()	Destroy context.

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.

Function	Description
CRYPTO_MAC_CMAC_AES_Init()	Initialize context.
CRYPTO_MAC_CMAC_AES_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_CMAC_AES_Add()	Add data to MAC.
CRYPTO_MAC_CMAC_AES_Final()	Finish MAC calculation.
CRYPTO_MAC_CMAC_AES_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_CMAC_AES_Kill()	Destroy MAC context.

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.

Function	Description
CRYPTO_CMAC_AES_CAVS_SelfTest()	Run AES-CMAC self-test.

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:

NIST SP 800-38B — Recommendation for Block Cipher Modes of Operation: The CMAC Mode for Authentication

DES and TDES are specified by the following document:

FIPS PUB 46-3 — Data Encryption Standard (DES)

Type-safe API

The following table lists the CMAC-TDES type-safe API functions.

Function	Description
Message functions
CRYPTO_CMAC_TDES_Calc()	Calculate MAC.
CRYPTO_CMAC_TDES_Calc_64()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_CMAC_TDES_Init()	Initialize context.
CRYPTO_CMAC_TDES_InitEx()	Initialize context, include subkey.
CRYPTO_CMAC_TDES_Add()	Add data to MAC.
CRYPTO_CMAC_TDES_Final()	Finish MAC calculation.
CRYPTO_CMAC_TDES_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_CMAC_TDES_Kill()	Destroy context.

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.

Function	Description
CRYPTO_MAC_CMAC_TDES_Init()	Initialize context.
CRYPTO_MAC_CMAC_TDES_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_CMAC_TDES_Add()	Add data to MAC.
CRYPTO_MAC_CMAC_TDES_Final()	Finish MAC calculation.
CRYPTO_MAC_CMAC_TDES_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_MAC_CMAC_TDES_Kill()	Destroy MAC context.

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.

Function	Description
CRYPTO_CMAC_TDES_CAVS_SelfTest()	Run AES-CMAC self-test.

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:

NIST SP 800-38B — Recommendation for Block Cipher Modes of Operation: The CMAC Mode for Authentication

Type-safe API

The following table lists the CMAC-IDEA type-safe API functions.

Function	Description
Message functions
CRYPTO_CMAC_IDEA_Calc()	Calculate MAC.
CRYPTO_CMAC_IDEA_Calc_64()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_CMAC_IDEA_Init()	Initialize context.
CRYPTO_CMAC_IDEA_InitEx()	Initialize context, include subkey.
CRYPTO_CMAC_IDEA_Add()	Add data to MAC.
CRYPTO_CMAC_IDEA_Final()	Finish MAC calculation.
CRYPTO_CMAC_IDEA_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_CMAC_IDEA_Kill()	Destroy context.

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.

Function	Description
CRYPTO_MAC_CMAC_IDEA_Init()	Initialize context.
CRYPTO_MAC_CMAC_IDEA_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_CMAC_IDEA_Add()	Add data to MAC.
CRYPTO_MAC_CMAC_IDEA_Final()	Finish MAC calculation.
CRYPTO_MAC_CMAC_IDEA_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_MAC_CMAC_IDEA_Kill()	Destroy MAC context.

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.

Function	Description
Message functions
CRYPTO_CMAC_CAST_Calc()	Calculate MAC.
CRYPTO_CMAC_CAST_Calc_64()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_CMAC_CAST_Init()	Initialize context.
CRYPTO_CMAC_CAST_InitEx()	Initialize context, include subkey.
CRYPTO_CMAC_CAST_Add()	Add data to MAC.
CRYPTO_CMAC_CAST_Final()	Finish MAC calculation.
CRYPTO_CMAC_CAST_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_CMAC_CAST_Kill()	Destroy context.

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.

Function	Description
CRYPTO_MAC_CMAC_CAST_Init()	Initialize context.
CRYPTO_MAC_CMAC_CAST_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_CMAC_CAST_Add()	Add data to MAC.
CRYPTO_MAC_CMAC_CAST_Final()	Finish MAC calculation.
CRYPTO_MAC_CMAC_CAST_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_MAC_CMAC_CAST_Kill()	Destroy MAC context.

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:

NIST SP 800-38B — Recommendation for Block Cipher Modes of Operation: The CMAC Mode for Authentication

SEED is specified by the following document:

IETF RFC 4269 — The SEED Encryption Algorithm

Type-safe API

The following table lists the CMAC-SEED type-safe API functions.

Function	Description
Message functions
CRYPTO_CMAC_SEED_Calc()	Calculate MAC.
CRYPTO_CMAC_SEED_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_CMAC_SEED_Init()	Initialize context.
CRYPTO_CMAC_SEED_InitEx()	Initialize context, include subkey.
CRYPTO_CMAC_SEED_Add()	Add data to MAC.
CRYPTO_CMAC_SEED_Final()	Finish MAC calculation.
CRYPTO_CMAC_SEED_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_CMAC_SEED_Kill()	Destroy context.

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.

Function	Description
CRYPTO_MAC_CMAC_SEED_Init()	Initialize context.
CRYPTO_MAC_CMAC_SEED_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_CMAC_SEED_Add()	Add data to MAC.
CRYPTO_MAC_CMAC_SEED_Final()	Finish MAC calculation.
CRYPTO_MAC_CMAC_SEED_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_CMAC_SEED_Kill()	Destroy MAC context.

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:

NIST SP 800-38B — Recommendation for Block Cipher Modes of Operation: The CMAC Mode for Authentication

ARIA is specified by the following document:

IETF RFC 5794 — A Description of the ARIA Encryption Algorithm

Type-safe API

The following table lists the CMAC-ARIA type-safe API functions.

Function	Description
Message functions
CRYPTO_CMAC_ARIA_Calc()	Calculate MAC.
CRYPTO_CMAC_ARIA_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_CMAC_ARIA_Init()	Initialize context.
CRYPTO_CMAC_ARIA_InitEx()	Initialize context, include subkey.
CRYPTO_CMAC_ARIA_Add()	Add data to MAC.
CRYPTO_CMAC_ARIA_Final()	Finish MAC calculation.
CRYPTO_CMAC_ARIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_CMAC_ARIA_Kill()	Destroy context.

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.

Function	Description
CRYPTO_MAC_CMAC_ARIA_Init()	Initialize context.
CRYPTO_MAC_CMAC_ARIA_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_CMAC_ARIA_Add()	Add data to MAC.
CRYPTO_MAC_CMAC_ARIA_Final()	Finish MAC calculation.
CRYPTO_MAC_CMAC_ARIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_CMAC_ARIA_Kill()	Destroy MAC context.

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