emCrypt User Guide & Reference Manual

Cryptographic algorithm library.

emCrypt 2.44, July 12, 2024

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    24400

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:

• BLAKE2b and BLAKE2s
• 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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_BLAKE2B_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_BLAKE2B_Final(CRYPTO_BLAKE2B_CONTEXT * pSelf,
                          U8                     * pOutput,
                          unsigned                 OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_BLAKE2B_Final_512()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_BLAKE2B_Final_512(CRYPTO_BLAKE2B_CONTEXT * pSelf,
                              U8                     * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 64 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_BLAKE2B_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_BLAKE2B_Get(CRYPTO_BLAKE2B_CONTEXT * pSelf,
                        U8                     * pOutput,
                        unsigned                 OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_BLAKE2B_Init()

Description

Initialize context.

Prototype

void CRYPTO_BLAKE2B_Init(CRYPTO_BLAKE2B_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_BLAKE2B_InitEx()

Description

Initialize context, extended.

Prototype

void CRYPTO_BLAKE2B_InitEx(      CRYPTO_BLAKE2B_CONTEXT * pSelf,
                                 unsigned                 DigestLen,
                           const U8                     * pKey,
                                 unsigned                 KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
DigestLen	Octet length of the (final) digest octet string.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_BLAKE2B_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_BLAKE2B_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_BLAKE2B_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_BLAKE2B_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the BLAKE2b self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_BLAKE2S_Calc_256()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_BLAKE2S_Calc_256(      U8       * pOutput,
                             const U8       * pInput,
                                   unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 32 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_BLAKE2S_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_BLAKE2S_Final(CRYPTO_BLAKE2S_CONTEXT * pSelf,
                          U8                     * pOutput,
                          unsigned                 OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_BLAKE2S_Final_256()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_BLAKE2S_Final_256(CRYPTO_BLAKE2S_CONTEXT * pSelf,
                              U8                     * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 32 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_BLAKE2S_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_BLAKE2S_Get(CRYPTO_BLAKE2S_CONTEXT * pSelf,
                        U8                     * pOutput,
                        unsigned                 OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_BLAKE2S_Init()

Description

Initialize context.

Prototype

void CRYPTO_BLAKE2S_Init(CRYPTO_BLAKE2S_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_BLAKE2S_InitEx()

Description

Initialize context, extended.

Prototype

void CRYPTO_BLAKE2S_InitEx(      CRYPTO_BLAKE2S_CONTEXT * pSelf,
                                 unsigned                 DigestLen,
                           const U8                     * pKey,
                                 unsigned                 KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
DigestLen	Octet length of the (final) digest octet string.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_BLAKE2S_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_BLAKE2S_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_BLAKE2S_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_BLAKE2S_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the BLAKE2s self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_MD5_Calc_160()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_MD5_Calc_160(      U8       * pOutput,
                         const U8       * pInput,
                               unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 20 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_MD5_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_MD5_Final(CRYPTO_MD5_CONTEXT * pSelf,
                      U8                 * pOutput,
                      unsigned             OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_MD5_Final_160()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_MD5_Final_160(CRYPTO_MD5_CONTEXT * pSelf,
                          U8                 * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 20 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_MD5_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_MD5_Get(CRYPTO_MD5_CONTEXT * pSelf,
                    U8                 * pOutput,
                    unsigned             OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_MD5_Init()

Description

Initialize context.

Prototype

void CRYPTO_MD5_Init(CRYPTO_MD5_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_MD5_Install()

Description

Install MD5 hash implementation.

Prototype

void CRYPTO_MD5_Install(const CRYPTO_HASH_API * pHWAPI,
                        const CRYPTO_HASH_API * pSWAPI);

Parameters

Parameter	Description
pHWAPI	Pointer to API to use as the preferred implementation.
pSWAPI	Pointer to API to use as the fallback implementation.

CRYPTO_MD5_IsInstalled()

Description

Query whether hash algorithm is installed.

Prototype

int CRYPTO_MD5_IsInstalled(void);

Return value

= 0	Hash algorithm is not installed.
≠ 0	Hash algorithm is installed.

CRYPTO_MD5_Kill()

Description

Destroy context.

Prototype

void CRYPTO_MD5_Kill(CRYPTO_MD5_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_MD5_QueryInstall()

Description

Query MD5 hardware accelerator.

Prototype

void CRYPTO_MD5_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
                             const CRYPTO_HASH_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the preferred API pointer.
ppSWAPI	Pointer to object that receives the fallback API pointer.

Generic API

The following table lists the MD5 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_MD5_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_MD5_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_MD5_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_MD5_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the MD5 self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_RIPEMD160_Calc_160()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_RIPEMD160_Calc_160(      U8       * pOutput,
                               const U8       * pInput,
                                     unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 20 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_RIPEMD160_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_RIPEMD160_Final(CRYPTO_RIPEMD160_CONTEXT * pSelf,
                            U8                       * pOutput,
                            unsigned                   OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_RIPEMD160_Final_160()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_RIPEMD160_Final_160(CRYPTO_RIPEMD160_CONTEXT * pSelf,
                                U8                       * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 20 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_RIPEMD160_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_RIPEMD160_Get(CRYPTO_RIPEMD160_CONTEXT * pSelf,
                          U8                       * pOutput,
                          unsigned                   OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_RIPEMD160_Init()

Description

Initialize context.

Prototype

void CRYPTO_RIPEMD160_Init(CRYPTO_RIPEMD160_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_RIPEMD160_Install()

Description

Install RIPEMD-160 hash implementation.

Prototype

void CRYPTO_RIPEMD160_Install(const CRYPTO_HASH_API * pHWAPI,
                              const CRYPTO_HASH_API * pSWAPI);

Parameters

Parameter	Description
pHWAPI	Pointer to API to use as the preferred implementation.
pSWAPI	Pointer to API to use as the fallback implementation.

CRYPTO_RIPEMD160_IsInstalled()

Description

Query whether hash algorithm is installed.

Prototype

int CRYPTO_RIPEMD160_IsInstalled(void);

Return value

= 0	Hash algorithm is not installed.
≠ 0	Hash algorithm is installed.

CRYPTO_RIPEMD160_Kill()

Description

Destroy context.

Prototype

void CRYPTO_RIPEMD160_Kill(CRYPTO_RIPEMD160_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_RIPEMD160_QueryInstall()

Description

Query RIPEMD-160 hardware accelerator.

Prototype

void CRYPTO_RIPEMD160_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
                                   const CRYPTO_HASH_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the preferred API pointer.
ppSWAPI	Pointer to object that receives the fallback API pointer.

Generic API

The following table lists the RIPEMD-160 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_RIPEMD160_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_RIPEMD160_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_RIPEMD160_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_RIPEMD160_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the RIPEMD-160 self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA1_Calc_160()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_SHA1_Calc_160(      U8       * pOutput,
                          const U8       * pInput,
                                unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 20 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA1_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_SHA1_Final(CRYPTO_SHA1_CONTEXT * pSelf,
                       U8                  * pOutput,
                       unsigned              OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA1_Final_160()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_SHA1_Final_160(CRYPTO_SHA1_CONTEXT * pSelf,
                           U8                  * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 20 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA1_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_SHA1_Get(CRYPTO_SHA1_CONTEXT * pSelf,
                     U8                  * pOutput,
                     unsigned              OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_SHA1_Init()

Description

Initialize context.

Prototype

void CRYPTO_SHA1_Init(CRYPTO_SHA1_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_SHA1_Install()

Description

Install SHA-1 hash implementation.

Prototype

void CRYPTO_SHA1_Install(const CRYPTO_HASH_API * pHWAPI,
                         const CRYPTO_HASH_API * pSWAPI);

Parameters

Parameter	Description
pHWAPI	Pointer to API to use as the preferred implementation.
pSWAPI	Pointer to API to use as the fallback implementation.

CRYPTO_SHA1_IsInstalled()

Description

Query whether hash algorithm is installed.

Prototype

int CRYPTO_SHA1_IsInstalled(void);

Return value

= 0	Hash algorithm is not installed.
≠ 0	Hash algorithm is installed.

CRYPTO_SHA1_Kill()

Description

Destroy context.

Prototype

void CRYPTO_SHA1_Kill(CRYPTO_SHA1_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA1_QueryInstall()

Description

Query SHA-1 hardware accelerator.

Prototype

void CRYPTO_SHA1_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
                              const CRYPTO_HASH_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the preferred API pointer.
ppSWAPI	Pointer to object that receives the fallback API pointer.

Generic API

The following table lists the SHA-1 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SHA1_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SHA1_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SHA1_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SHA1_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the SHA-1 self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA224_Calc_224()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_SHA224_Calc_224(      U8       * pOutput,
                            const U8       * pInput,
                                  unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 28 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA224_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_SHA224_Final(CRYPTO_SHA224_CONTEXT * pSelf,
                         U8                    * pOutput,
                         unsigned                OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA224_Final_224()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_SHA224_Final_224(CRYPTO_SHA224_CONTEXT * pSelf,
                             U8                    * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 28 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA224_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_SHA224_Get(CRYPTO_SHA224_CONTEXT * pSelf,
                       U8                    * pOutput,
                       unsigned                OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_SHA224_Init()

Description

Initialize context.

Prototype

void CRYPTO_SHA224_Init(CRYPTO_SHA224_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_SHA224_Install()

Description

Install SHA-224 hash implementation.

Prototype

void CRYPTO_SHA224_Install(const CRYPTO_HASH_API * pHWAPI,
                           const CRYPTO_HASH_API * pSWAPI);

Parameters

Parameter	Description
pHWAPI	Pointer to API to use as the preferred implementation.
pSWAPI	Pointer to API to use as the fallback implementation.

CRYPTO_SHA224_IsInstalled()

Description

Query whether hash algorithm is installed.

Prototype

int CRYPTO_SHA224_IsInstalled(void);

Return value

= 0	Hash algorithm is not installed.
≠ 0	Hash algorithm is installed.

CRYPTO_SHA224_Kill()

Description

Destroy context.

Prototype

void CRYPTO_SHA224_Kill(CRYPTO_SHA224_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA224_QueryInstall()

Description

Query SHA-224 hardware accelerator.

Prototype

void CRYPTO_SHA224_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
                                const CRYPTO_HASH_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the preferred API pointer.
ppSWAPI	Pointer to object that receives the fallback API pointer.

Generic API

The following table lists the SHA-224 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SHA224_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SHA224_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SHA224_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SHA224_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the SHA-224 self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA256_Calc_256()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_SHA256_Calc_256(      U8       * pOutput,
                            const U8       * pInput,
                                  unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 32 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA256_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_SHA256_Final(CRYPTO_SHA256_CONTEXT * pSelf,
                         U8                    * pOutput,
                         unsigned                OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA256_Final_256()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_SHA256_Final_256(CRYPTO_SHA256_CONTEXT * pSelf,
                             U8                    * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 32 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA256_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_SHA256_Get(CRYPTO_SHA256_CONTEXT * pSelf,
                       U8                    * pOutput,
                       unsigned                OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_SHA256_Init()

Description

Initialize context.

Prototype

void CRYPTO_SHA256_Init(CRYPTO_SHA256_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_SHA256_Install()

Description

Install SHA-256 hash implementation.

Prototype

void CRYPTO_SHA256_Install(const CRYPTO_HASH_API * pHWAPI,
                           const CRYPTO_HASH_API * pSWAPI);

Parameters

Parameter	Description
pHWAPI	Pointer to API to use as the preferred implementation.
pSWAPI	Pointer to API to use as the fallback implementation.

CRYPTO_SHA256_IsInstalled()

Description

Query whether hash algorithm is installed.

Prototype

int CRYPTO_SHA256_IsInstalled(void);

Return value

= 0	Hash algorithm is not installed.
≠ 0	Hash algorithm is installed.

CRYPTO_SHA256_Kill()

Description

Destroy context.

Prototype

void CRYPTO_SHA256_Kill(CRYPTO_SHA256_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA256_QueryInstall()

Description

Query SHA-256 hardware accelerator.

Prototype

void CRYPTO_SHA256_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
                                const CRYPTO_HASH_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the preferred API pointer.
ppSWAPI	Pointer to object that receives the fallback API pointer.

Generic API

The following table lists the SHA-256 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SHA256_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SHA256_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SHA256_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SHA256_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the SHA-256 self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA384_Calc_384()

Description

Calculate digest over message.

Prototype

void CRYPTO_SHA384_Calc_384(      U8       * pOutput,
                            const U8       * pInput,
                                  unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 48 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA384_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_SHA384_Final(CRYPTO_SHA384_CONTEXT * pSelf,
                         U8                    * pOutput,
                         unsigned                OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA384_Final_384()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_SHA384_Final_384(CRYPTO_SHA384_CONTEXT * pSelf,
                             U8                    * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 32 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA384_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_SHA384_Get(CRYPTO_SHA384_CONTEXT * pSelf,
                       U8                    * pOutput,
                       unsigned                OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_SHA384_Init()

Description

Initialize context.

Prototype

void CRYPTO_SHA384_Init(CRYPTO_SHA384_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_SHA384_Kill()

Description

Destroy context.

Prototype

void CRYPTO_SHA384_Kill(CRYPTO_SHA384_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Generic API

The following table lists the SHA-384 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SHA384_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SHA384_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SHA384_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SHA384_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the SHA-384 self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA512_Calc_512()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_SHA512_Calc_512(      U8       * pOutput,
                            const U8       * pInput,
                                  unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 64 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA512_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_SHA512_Final(CRYPTO_SHA512_CONTEXT * pSelf,
                         U8                    * pOutput,
                         unsigned                OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA512_Final_512()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_SHA512_Final_512(CRYPTO_SHA512_CONTEXT * pSelf,
                             U8                    * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 64 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA512_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_SHA512_Get(CRYPTO_SHA512_CONTEXT * pSelf,
                       U8                    * pOutput,
                       unsigned                OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_SHA512_Init()

Description

Initialize context.

Prototype

void CRYPTO_SHA512_Init(CRYPTO_SHA512_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_SHA512_Install()

Description

Install SHA-512 hash implementation.

Prototype

void CRYPTO_SHA512_Install(const CRYPTO_HASH_API * pHWAPI,
                           const CRYPTO_HASH_API * pSWAPI);

Parameters

Parameter	Description
pHWAPI	Pointer to API to use as the preferred implementation.
pSWAPI	Pointer to API to use as the fallback implementation.

CRYPTO_SHA512_IsInstalled()

Description

Query whether hash algorithm is installed.

Prototype

int CRYPTO_SHA512_IsInstalled(void);

Return value

= 0	Hash algorithm is not installed.
≠ 0	Hash algorithm is installed.

CRYPTO_SHA512_Kill()

Description

Destroy context.

Prototype

void CRYPTO_SHA512_Kill(CRYPTO_SHA512_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA512_QueryInstall()

Description

Query SHA-512 hardware accelerator.

Prototype

void CRYPTO_SHA512_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
                                const CRYPTO_HASH_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the preferred API pointer.
ppSWAPI	Pointer to object that receives the fallback API pointer.

Generic API

The following table lists the SHA-512 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SHA512_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SHA512_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SHA512_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SHA512_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the SHA-512 self-test API functions.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SHA512_224_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SHA512_224_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SHA512_224_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SHA512_224_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

SHA-512/256

Standards reference

SHA-512/256 is specified by the following document:

• 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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SHA512_256_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SHA512_256_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SHA512_256_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SHA512_256_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

SHA3-224

Standards reference

SHA3-224 is specified by the following document:

• 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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA3_224_Calc_224()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_SHA3_224_Calc_224(      U8       * pOutput,
                              const U8       * pInput,
                                    unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 28 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA3_224_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_SHA3_224_Final(CRYPTO_SHA3_224_CONTEXT * pSelf,
                           U8                      * pOutput,
                           unsigned                  OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_224_Final_224()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_SHA3_224_Final_224(CRYPTO_SHA3_224_CONTEXT * pSelf,
                               U8                      * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 28 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_224_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_SHA3_224_Get(CRYPTO_SHA3_224_CONTEXT * pSelf,
                         U8                      * pOutput,
                         unsigned                  OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_SHA3_224_Init()

Description

Initialize context.

Prototype

void CRYPTO_SHA3_224_Init(CRYPTO_SHA3_224_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_SHA3_224_Install()

Description

Install SHA3-224 hash implementation.

Prototype

void CRYPTO_SHA3_224_Install(const CRYPTO_HASH_API * pHWAPI,
                             const CRYPTO_HASH_API * pSWAPI);

Parameters

Parameter	Description
pHWAPI	Pointer to API to use as the preferred implementation.
pSWAPI	Pointer to API to use as the fallback implementation.

CRYPTO_SHA3_224_IsInstalled()

Description

Query whether hash algorithm is installed.

Prototype

int CRYPTO_SHA3_224_IsInstalled(void);

Return value

= 0	Hash algorithm is not installed.
≠ 0	Hash algorithm is installed.

CRYPTO_SHA3_224_Kill()

Description

Destroy context.

Prototype

void CRYPTO_SHA3_224_Kill(CRYPTO_SHA3_224_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_224_QueryInstall()

Description

Query SHA3-224 hardware accelerator.

Prototype

void CRYPTO_SHA3_224_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
                                  const CRYPTO_HASH_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the preferred API pointer.
ppSWAPI	Pointer to object that receives the fallback API pointer.

Generic API

The following table lists the SHA3-224 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SHA3_224_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SHA3_224_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SHA3_224_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SHA3_224_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the SHA3-224 self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA3_256_Calc_256()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_SHA3_256_Calc_256(      U8       * pOutput,
                              const U8       * pInput,
                                    unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 32 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA3_256_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_SHA3_256_Final(CRYPTO_SHA3_256_CONTEXT * pSelf,
                           U8                      * pOutput,
                           unsigned                  OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_256_Final_256()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_SHA3_256_Final_256(CRYPTO_SHA3_256_CONTEXT * pSelf,
                               U8                      * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 32 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_256_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_SHA3_256_Get(CRYPTO_SHA3_256_CONTEXT * pSelf,
                         U8                      * pOutput,
                         unsigned                  OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_SHA3_256_Init()

Description

Initialize context.

Prototype

void CRYPTO_SHA3_256_Init(CRYPTO_SHA3_256_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_SHA3_256_Install()

Description

Install SHA3-256 hash implementation.

Prototype

void CRYPTO_SHA3_256_Install(const CRYPTO_HASH_API * pHWAPI,
                             const CRYPTO_HASH_API * pSWAPI);

Parameters

Parameter	Description
pHWAPI	Pointer to API to use as the preferred implementation.
pSWAPI	Pointer to API to use as the fallback implementation.

CRYPTO_SHA3_256_IsInstalled()

Description

Query whether hash algorithm is installed.

Prototype

int CRYPTO_SHA3_256_IsInstalled(void);

Return value

= 0	Hash algorithm is not installed.
≠ 0	Hash algorithm is installed.

CRYPTO_SHA3_256_Kill()

Description

Destroy context.

Prototype

void CRYPTO_SHA3_256_Kill(CRYPTO_SHA3_256_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_256_QueryInstall()

Description

Query SHA3-256 hardware accelerator.

Prototype

void CRYPTO_SHA3_256_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
                                  const CRYPTO_HASH_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the preferred API pointer.
ppSWAPI	Pointer to object that receives the fallback API pointer.

Generic API

The following table lists the SHA3-256 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SHA3_256_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SHA3_256_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SHA3_256_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SHA3_256_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the SHA3-256 self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA3_384_Calc_384()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_SHA3_384_Calc_384(      U8       * pOutput,
                              const U8       * pInput,
                                    unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 48 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA3_384_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_SHA3_384_Final(CRYPTO_SHA3_384_CONTEXT * pSelf,
                           U8                      * pOutput,
                           unsigned                  OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_384_Final_384()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_SHA3_384_Final_384(CRYPTO_SHA3_384_CONTEXT * pSelf,
                               U8                      * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 48 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_384_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_SHA3_384_Get(CRYPTO_SHA3_384_CONTEXT * pSelf,
                         U8                      * pOutput,
                         unsigned                  OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_SHA3_384_Init()

Description

Initialize context.

Prototype

void CRYPTO_SHA3_384_Init(CRYPTO_SHA3_384_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_SHA3_384_Install()

Description

Install SHA3-384 hash implementation.

Prototype

void CRYPTO_SHA3_384_Install(const CRYPTO_HASH_API * pHWAPI,
                             const CRYPTO_HASH_API * pSWAPI);

Parameters

Parameter	Description
pHWAPI	Pointer to API to use as the preferred implementation.
pSWAPI	Pointer to API to use as the fallback implementation.

CRYPTO_SHA3_384_IsInstalled()

Description

Query whether hash algorithm is installed.

Prototype

int CRYPTO_SHA3_384_IsInstalled(void);

Return value

= 0	Hash algorithm is not installed.
≠ 0	Hash algorithm is installed.

CRYPTO_SHA3_384_Kill()

Description

Destroy context.

Prototype

void CRYPTO_SHA3_384_Kill(CRYPTO_SHA3_384_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_384_QueryInstall()

Description

Query SHA3-384 hardware accelerator.

Prototype

void CRYPTO_SHA3_384_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
                                  const CRYPTO_HASH_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the preferred API pointer.
ppSWAPI	Pointer to object that receives the fallback API pointer.

Generic API

The following table lists the SHA3-384 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SHA3_384_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SHA3_384_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SHA3_384_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SHA3_384_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the SHA3-384 self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA3_512_Calc_512()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_SHA3_512_Calc_512(      U8       * pOutput,
                              const U8       * pInput,
                                    unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 64 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SHA3_512_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_SHA3_512_Final(CRYPTO_SHA3_512_CONTEXT * pSelf,
                           U8                      * pOutput,
                           unsigned                  OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_512_Final_512()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_SHA3_512_Final_512(CRYPTO_SHA3_512_CONTEXT * pSelf,
                               U8                      * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 64 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_512_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_SHA3_512_Get(CRYPTO_SHA3_512_CONTEXT * pSelf,
                         U8                      * pOutput,
                         unsigned                  OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_SHA3_512_Init()

Description

Initialize context.

Prototype

void CRYPTO_SHA3_512_Init(CRYPTO_SHA3_512_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_SHA3_512_Install()

Description

Install SHA3-512 hash implementation.

Prototype

void CRYPTO_SHA3_512_Install(const CRYPTO_HASH_API * pHWAPI,
                             const CRYPTO_HASH_API * pSWAPI);

Parameters

Parameter	Description
pHWAPI	Pointer to API to use as the preferred implementation.
pSWAPI	Pointer to API to use as the fallback implementation.

CRYPTO_SHA3_512_IsInstalled()

Description

Query whether hash algorithm is installed.

Prototype

int CRYPTO_SHA3_512_IsInstalled(void);

Return value

= 0	Hash algorithm is not installed.
≠ 0	Hash algorithm is installed.

CRYPTO_SHA3_512_Kill()

Description

Destroy context.

Prototype

void CRYPTO_SHA3_512_Kill(CRYPTO_SHA3_512_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SHA3_512_QueryInstall()

Description

Query SHA3-512 hardware accelerator.

Prototype

void CRYPTO_SHA3_512_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
                                  const CRYPTO_HASH_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the preferred API pointer.
ppSWAPI	Pointer to object that receives the fallback API pointer.

Generic API

The following table lists the SHA3-512 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SHA3_512_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SHA3_512_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SHA3_512_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SHA3_512_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the SHA3-512 self-test API functions.

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

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SM3_Calc_256()

Description

Calculate digest, fixed size.

Prototype

void CRYPTO_SM3_Calc_256(      U8       * pOutput,
                         const U8       * pInput,
                               unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the message digest, 32 octets.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

Additional information

It is possible to truncate the digest by specifying OutputLen less than the full digest length: in this case, the leftmost (most significant) octets of the digest are written to the message digest buffer.

CRYPTO_SM3_Final()

Description

Finalize digest calculation.

Prototype

void CRYPTO_SM3_Final(CRYPTO_SM3_CONTEXT * pSelf,
                      U8                 * pOutput,
                      unsigned             OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SM3_Final_256()

Description

Finalize digest calculation, fixed size.

Prototype

void CRYPTO_SM3_Final_256(CRYPTO_SM3_CONTEXT * pSelf,
                          U8                 * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest, 32 octets.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SM3_Get()

Description

Get incremental digest.

Prototype

void CRYPTO_SM3_Get(CRYPTO_SM3_CONTEXT * pSelf,
                    U8                 * pOutput,
                    unsigned             OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to hash context.
pOutput	Pointer to object that receives the message digest.
OutputLen	Octet length of the digest.

Additional information

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_SM3_Init()

Description

Initialize context.

Prototype

void CRYPTO_SM3_Init(CRYPTO_SM3_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

CRYPTO_SM3_Install()

Description

Install SM3 hash implementation.

Prototype

void CRYPTO_SM3_Install(const CRYPTO_HASH_API * pHWAPI,
                        const CRYPTO_HASH_API * pSWAPI);

Parameters

Parameter	Description
pHWAPI	Pointer to API to use as the preferred implementation.
pSWAPI	Pointer to API to use as the fallback implementation.

CRYPTO_SM3_IsInstalled()

Description

Query whether hash algorithm is installed.

Prototype

int CRYPTO_SM3_IsInstalled(void);

Return value

= 0	Hash algorithm is not installed.
≠ 0	Hash algorithm is installed.

CRYPTO_SM3_Kill()

Description

Destroy context.

Prototype

void CRYPTO_SM3_Kill(CRYPTO_SM3_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

CRYPTO_SM3_QueryInstall()

Description

Query SM3 hardware accelerator.

Prototype

void CRYPTO_SM3_QueryInstall(const CRYPTO_HASH_API ** ppHWAPI,
                             const CRYPTO_HASH_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the preferred API pointer.
ppSWAPI	Pointer to object that receives the fallback API pointer.

Generic API

The following table lists the SM3 functions that conform to the generic hash API.

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

This function computes the current message digest and writes it to the receiving object. The hash context is not invalidated and additional data can be added to the hash context in order to continue hashing.

CRYPTO_HASH_SM3_Init()

Description

Initialize context.

Prototype

void CRYPTO_HASH_SM3_Init(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

CRYPTO_HASH_SM3_Kill()

Description

Destroy digest.

Prototype

void CRYPTO_HASH_SM3_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to hash context.

Additional information

After calling this function, the context is destroyed and must be reinitialized to be used again. The entire hash context is set to zero to ensure no cryptographic material remains in memory.

Self-test API

The following table lists the SM3 self-test API functions.

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
• CMAC-SM4
• GMAC-AES
• GMAC-SEED
• GMAC-ARIA
• GMAC-Camellia
• GMAC-Twofish
• GMAC-SM4
• 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
• XCBC-SM4
• KMAC
• Poly1305
• Poly1305-AES
• Poly1305-ARIA
• Poly1305-SEED
• Poly1305-Camellia
• Poly1305-Twofish
• Poly1305-SM4
• 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.

CMAC-SM4

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

SM4 is specified by the following document:

• draft-crypto-sm4-00 — The SM4 Block Cipher Algorithm And Its Modes Of Operations

Type-safe API

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

Function	Description
Message functions
CRYPTO_CMAC_SM4_Calc()	Calculate MAC.
CRYPTO_CMAC_SM4_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_CMAC_SM4_Init()	Initialize context.
CRYPTO_CMAC_SM4_InitEx()	Initialize context, include subkey.
CRYPTO_CMAC_SM4_Add()	Add data to MAC.
CRYPTO_CMAC_SM4_Final()	Finish MAC calculation.
CRYPTO_CMAC_SM4_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_CMAC_SM4_Kill()	Destroy context.

CRYPTO_CMAC_SM4_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_CMAC_SM4_Add(      CRYPTO_CMAC_SM4_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_SM4_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_CMAC_SM4_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_SM4_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_CMAC_SM4_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_SM4_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_CMAC_SM4_Final(CRYPTO_CMAC_SM4_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_SM4_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_CMAC_SM4_Final_128(CRYPTO_CMAC_SM4_CONTEXT * pSelf,
                               U8                      * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC, 16 octets.

CRYPTO_CMAC_SM4_Init()

Description

Initialize context.

Prototype

void CRYPTO_CMAC_SM4_Init(      CRYPTO_CMAC_SM4_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_SM4_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_CMAC_SM4_InitEx(      CRYPTO_CMAC_SM4_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_SM4_Kill()

Description

Destroy context.

Prototype

void CRYPTO_CMAC_SM4_Kill(CRYPTO_CMAC_SM4_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the CMAC-SM4 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_CMAC_SM4_Init()	Initialize context.
CRYPTO_MAC_CMAC_SM4_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_CMAC_SM4_Add()	Add data to MAC.
CRYPTO_MAC_CMAC_SM4_Final()	Finish MAC calculation.
CRYPTO_MAC_CMAC_SM4_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_CMAC_SM4_Kill()	Destroy MAC context.

CRYPTO_MAC_CMAC_SM4_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_CMAC_SM4_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_SM4_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_CMAC_SM4_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_SM4_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_CMAC_SM4_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_SM4_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_CMAC_SM4_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_SM4_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_CMAC_SM4_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_SM4_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_CMAC_SM4_Kill(void * pContext);

Parameters

Parameter	Description
pContext	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 context.
pMAC	Pointer to object that receives the MAC.
MACLen	Octet length of the MAC.

CRYPTO_MAC_CMAC_ARIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_CMAC_ARIA_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_ARIA_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_CMAC_ARIA_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_ARIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_CMAC_ARIA_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_ARIA_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_CMAC_ARIA_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

CMAC-Camellia

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

Camellia is specified by the following document:

• IETF RFC 3713 — A Description of the Camellia Encryption Algorithm

Type-safe API

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

Function	Description
Message functions
CRYPTO_CMAC_CAMELLIA_Calc()	Calculate MAC.
CRYPTO_CMAC_CAMELLIA_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_CMAC_CAMELLIA_Init()	Initialize context.
CRYPTO_CMAC_CAMELLIA_InitEx()	Initialize context, include subkey.
CRYPTO_CMAC_CAMELLIA_Add()	Add data to MAC.
CRYPTO_CMAC_CAMELLIA_Final()	Finish MAC calculation.
CRYPTO_CMAC_CAMELLIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_CMAC_CAMELLIA_Kill()	Destroy context.

CRYPTO_CMAC_CAMELLIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_CMAC_CAMELLIA_Add(      CRYPTO_CMAC_CAMELLIA_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_CAMELLIA_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_CMAC_CAMELLIA_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_CAMELLIA_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_CMAC_CAMELLIA_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_CAMELLIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_CMAC_CAMELLIA_Final(CRYPTO_CMAC_CAMELLIA_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_CAMELLIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_CMAC_CAMELLIA_Final_128(CRYPTO_CMAC_CAMELLIA_CONTEXT * pSelf,
                                    U8                           * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC, 16 octets.

CRYPTO_CMAC_CAMELLIA_Init()

Description

Initialize context.

Prototype

void CRYPTO_CMAC_CAMELLIA_Init(      CRYPTO_CMAC_CAMELLIA_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_CAMELLIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_CMAC_CAMELLIA_InitEx(      CRYPTO_CMAC_CAMELLIA_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_CAMELLIA_Kill()

Description

Destroy context.

Prototype

void CRYPTO_CMAC_CAMELLIA_Kill(CRYPTO_CMAC_CAMELLIA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the CMAC-Camellia functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_CMAC_CAMELLIA_Init()	Initialize context.
CRYPTO_MAC_CMAC_CAMELLIA_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_CMAC_CAMELLIA_Add()	Add data to MAC.
CRYPTO_MAC_CMAC_CAMELLIA_Final()	Finish MAC calculation.
CRYPTO_MAC_CMAC_CAMELLIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_CMAC_CAMELLIA_Kill()	Destroy MAC context.

CRYPTO_MAC_CMAC_CAMELLIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_CMAC_CAMELLIA_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_CAMELLIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_CMAC_CAMELLIA_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_CAMELLIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_CMAC_CAMELLIA_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_CAMELLIA_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_CMAC_CAMELLIA_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_CAMELLIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_CMAC_CAMELLIA_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_CAMELLIA_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_CMAC_CAMELLIA_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

CMAC-Twofish

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

Twofish is specified by the following document:

• Schneier at al — Twofish: A 128-Bit Block Cipher

Type-safe API

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

Function	Description
Message functions
CRYPTO_CMAC_TWOFISH_Calc()	Calculate MAC.
CRYPTO_CMAC_TWOFISH_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_CMAC_TWOFISH_Init()	Initialize context.
CRYPTO_CMAC_TWOFISH_InitEx()	Initialize context, include subkey.
CRYPTO_CMAC_TWOFISH_Add()	Add data to MAC.
CRYPTO_CMAC_TWOFISH_Final()	Finish MAC calculation.
CRYPTO_CMAC_TWOFISH_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_CMAC_TWOFISH_Kill()	Destroy context.

CRYPTO_CMAC_TWOFISH_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_CMAC_TWOFISH_Add(      CRYPTO_CMAC_TWOFISH_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_TWOFISH_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_CMAC_TWOFISH_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_TWOFISH_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_CMAC_TWOFISH_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_TWOFISH_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_CMAC_TWOFISH_Final(CRYPTO_CMAC_TWOFISH_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_TWOFISH_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_CMAC_TWOFISH_Final_128(CRYPTO_CMAC_TWOFISH_CONTEXT * pSelf,
                                   U8                          * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC, 16 octets.

CRYPTO_CMAC_TWOFISH_Init()

Description

Initialize context.

Prototype

void CRYPTO_CMAC_TWOFISH_Init(      CRYPTO_CMAC_TWOFISH_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_TWOFISH_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_CMAC_TWOFISH_InitEx(      CRYPTO_CMAC_TWOFISH_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_TWOFISH_Kill()

Description

Destroy context.

Prototype

void CRYPTO_CMAC_TWOFISH_Kill(CRYPTO_CMAC_TWOFISH_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the CMAC-Twofish functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_CMAC_TWOFISH_Init()	Initialize context.
CRYPTO_MAC_CMAC_TWOFISH_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_CMAC_TWOFISH_Add()	Add data to MAC.
CRYPTO_MAC_CMAC_TWOFISH_Final()	Finish MAC calculation.
CRYPTO_MAC_CMAC_TWOFISH_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_CMAC_TWOFISH_Kill()	Destroy MAC context.

CRYPTO_MAC_CMAC_TWOFISH_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_CMAC_TWOFISH_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_TWOFISH_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_CMAC_TWOFISH_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_TWOFISH_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_CMAC_TWOFISH_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_TWOFISH_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_CMAC_TWOFISH_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_TWOFISH_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_CMAC_TWOFISH_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_TWOFISH_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_CMAC_TWOFISH_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

CMAC-Blowfish

Type-safe API

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

Function	Description
Message functions
CRYPTO_CMAC_BLOWFISH_Calc()	Calculate MAC.
CRYPTO_CMAC_BLOWFISH_Calc_64()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_CMAC_BLOWFISH_Init()	Initialize context.
CRYPTO_CMAC_BLOWFISH_InitEx()	Initialize context, include subkey.
CRYPTO_CMAC_BLOWFISH_Add()	Add data to MAC.
CRYPTO_CMAC_BLOWFISH_Final()	Finish MAC calculation.
CRYPTO_CMAC_BLOWFISH_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_CMAC_BLOWFISH_Kill()	Destroy context.

CRYPTO_CMAC_BLOWFISH_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_CMAC_BLOWFISH_Add(      CRYPTO_CMAC_BLOWFISH_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_BLOWFISH_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_CMAC_BLOWFISH_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_BLOWFISH_Calc_64()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_CMAC_BLOWFISH_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_BLOWFISH_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_CMAC_BLOWFISH_Final(CRYPTO_CMAC_BLOWFISH_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_BLOWFISH_Final_64()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_CMAC_BLOWFISH_Final_64(CRYPTO_CMAC_BLOWFISH_CONTEXT * pSelf,
                                   U8                           * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC, 8 octets.

CRYPTO_CMAC_BLOWFISH_Init()

Description

Initialize context.

Prototype

void CRYPTO_CMAC_BLOWFISH_Init(      CRYPTO_CMAC_BLOWFISH_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_BLOWFISH_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_CMAC_BLOWFISH_InitEx(      CRYPTO_CMAC_BLOWFISH_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_BLOWFISH_Kill()

Description

Destroy context.

Prototype

void CRYPTO_CMAC_BLOWFISH_Kill(CRYPTO_CMAC_BLOWFISH_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the CMAC-Blowfish functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_CMAC_BLOWFISH_Init()	Initialize context.
CRYPTO_MAC_CMAC_BLOWFISH_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_CMAC_BLOWFISH_Add()	Add data to MAC.
CRYPTO_MAC_CMAC_BLOWFISH_Final()	Finish MAC calculation.
CRYPTO_MAC_CMAC_BLOWFISH_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_MAC_CMAC_BLOWFISH_Kill()	Destroy MAC context.

CRYPTO_MAC_CMAC_BLOWFISH_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_CMAC_BLOWFISH_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_BLOWFISH_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_CMAC_BLOWFISH_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_BLOWFISH_Final_64()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_CMAC_BLOWFISH_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_BLOWFISH_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_CMAC_BLOWFISH_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_BLOWFISH_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_CMAC_BLOWFISH_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_BLOWFISH_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_CMAC_BLOWFISH_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

CMAC-PRESENT

Type-safe API

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

Function	Description
Message functions
CRYPTO_CMAC_PRESENT_Calc()	Calculate MAC.
CRYPTO_CMAC_PRESENT_Calc_64()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_CMAC_PRESENT_Init()	Initialize context.
CRYPTO_CMAC_PRESENT_InitEx()	Initialize context, include subkey.
CRYPTO_CMAC_PRESENT_Add()	Add data to MAC.
CRYPTO_CMAC_PRESENT_Final()	Finish MAC calculation.
CRYPTO_CMAC_PRESENT_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_CMAC_PRESENT_Kill()	Destroy context.

CRYPTO_CMAC_PRESENT_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_CMAC_PRESENT_Add(      CRYPTO_CMAC_PRESENT_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_PRESENT_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_CMAC_PRESENT_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_PRESENT_Calc_64()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_CMAC_PRESENT_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_PRESENT_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_CMAC_PRESENT_Final(CRYPTO_CMAC_PRESENT_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_PRESENT_Final_64()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_CMAC_PRESENT_Final_64(CRYPTO_CMAC_PRESENT_CONTEXT * pSelf,
                                  U8                          * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC, 8 octets.

CRYPTO_CMAC_PRESENT_Init()

Description

Initialize context.

Prototype

void CRYPTO_CMAC_PRESENT_Init(      CRYPTO_CMAC_PRESENT_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_PRESENT_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_CMAC_PRESENT_InitEx(      CRYPTO_CMAC_PRESENT_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_PRESENT_Kill()

Description

Destroy context.

Prototype

void CRYPTO_CMAC_PRESENT_Kill(CRYPTO_CMAC_PRESENT_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the CMAC-PRESENT functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_CMAC_PRESENT_Init()	Initialize context.
CRYPTO_MAC_CMAC_PRESENT_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_CMAC_PRESENT_Add()	Add data to MAC.
CRYPTO_MAC_CMAC_PRESENT_Final()	Finish MAC calculation.
CRYPTO_MAC_CMAC_PRESENT_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_MAC_CMAC_PRESENT_Kill()	Destroy MAC context.

CRYPTO_MAC_CMAC_PRESENT_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_CMAC_PRESENT_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_PRESENT_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_CMAC_PRESENT_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_PRESENT_Final_64()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_CMAC_PRESENT_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_PRESENT_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_CMAC_PRESENT_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_PRESENT_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_CMAC_PRESENT_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_PRESENT_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_CMAC_PRESENT_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

GMAC-AES

Standards reference

GMAC is specified by the following document:

• NIST SP 800-38D — Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC

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 GMAC-AES type-safe API functions.

Function	Description
Message functions
CRYPTO_GMAC_AES_Calc()	Calculate MAC.
CRYPTO_GMAC_AES_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_GMAC_AES_InitEx()	Initialize context, include subkey.
CRYPTO_GMAC_AES_Add()	Add data to MAC.
CRYPTO_GMAC_AES_Final()	Finish MAC calculation.
CRYPTO_GMAC_AES_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_GMAC_AES_Kill()	Destroy GMAC context.

CRYPTO_GMAC_AES_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_GMAC_AES_Add(      CRYPTO_GMAC_AES_CONTEXT * pSelf,
                         const U8                      * pInput,
                               unsigned                  InputLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pInput	Pointer to input 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_GMAC_AES_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_GMAC_AES_Calc(      U8       * pOutput,
                                unsigned   OutputLen,
                          const U8       * pKey,
                                unsigned   KeyLen,
                          const U8       * pIV,
                                unsigned   IVLen,
                          const U8       * pInput,
                                unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC.
OutputLen	Octet length of the MAC.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_AES_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_GMAC_AES_Calc_128(      U8       * pOutput,
                              const U8       * pKey,
                                    unsigned   KeyLen,
                              const U8       * pIV,
                                    unsigned   IVLen,
                              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.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_AES_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_GMAC_AES_Final(CRYPTO_GMAC_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_GMAC_AES_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_GMAC_AES_Final_128(CRYPTO_GMAC_AES_CONTEXT * pSelf,
                               U8                      * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pOutput	Pointer to object that receives the MAC, 16 octets.

CRYPTO_GMAC_AES_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_GMAC_AES_InitEx(      CRYPTO_GMAC_AES_CONTEXT * pSelf,
                            const U8                      * pKey,
                                  unsigned                  KeyLen,
                            const U8                      * pIV,
                                  unsigned                  IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_GMAC_AES_Kill()

Description

Destroy GMAC context.

Prototype

void CRYPTO_GMAC_AES_Kill(CRYPTO_GMAC_AES_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the GMAC-AES functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_GMAC_AES_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_GMAC_AES_Add()	Add data to MAC.
CRYPTO_MAC_GMAC_AES_Final()	Finish MAC calculation.
CRYPTO_MAC_GMAC_AES_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_GMAC_AES_Kill()	Destroy MAC context.

CRYPTO_MAC_GMAC_AES_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_GMAC_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_GMAC_AES_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_GMAC_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_GMAC_AES_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_GMAC_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_GMAC_AES_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_GMAC_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_GMAC_AES_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_GMAC_AES_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

GMAC-SEED

Standards reference

GMAC is specified by the following document:

• NIST SP 800-38D — Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC

SEED is specified by the following document:

• IETF RFC 4269 — The SEED Encryption Algorithm

Type-safe API

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

Function	Description
Message functions
CRYPTO_GMAC_SEED_Calc()	Calculate MAC.
CRYPTO_GMAC_SEED_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_GMAC_SEED_InitEx()	Initialize context, include subkey.
CRYPTO_GMAC_SEED_Add()	Add data to MAC.
CRYPTO_GMAC_SEED_Final()	Finish MAC calculation.
CRYPTO_GMAC_SEED_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_GMAC_SEED_Kill()	Destroy GMAC context.

CRYPTO_GMAC_SEED_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_GMAC_SEED_Add(      CRYPTO_GMAC_SEED_CONTEXT * pSelf,
                          const U8                       * pInput,
                                unsigned                   InputLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pInput	Pointer to input 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_GMAC_SEED_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_GMAC_SEED_Calc(      U8       * pOutput,
                                 unsigned   OutputLen,
                           const U8       * pKey,
                                 unsigned   KeyLen,
                           const U8       * pIV,
                                 unsigned   IVLen,
                           const U8       * pInput,
                                 unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC.
OutputLen	Octet length of the MAC.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_SEED_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_GMAC_SEED_Calc_128(      U8       * pOutput,
                               const U8       * pKey,
                                     unsigned   KeyLen,
                               const U8       * pIV,
                                     unsigned   IVLen,
                               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.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_SEED_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_GMAC_SEED_Final(CRYPTO_GMAC_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_GMAC_SEED_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_GMAC_SEED_Final_128(CRYPTO_GMAC_SEED_CONTEXT * pSelf,
                                U8                       * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pOutput	Pointer to object that receives the MAC, 16 octets.

CRYPTO_GMAC_SEED_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_GMAC_SEED_InitEx(      CRYPTO_GMAC_SEED_CONTEXT * pSelf,
                             const U8                       * pKey,
                                   unsigned                   KeyLen,
                             const U8                       * pIV,
                                   unsigned                   IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_GMAC_SEED_Kill()

Description

Destroy GMAC context.

Prototype

void CRYPTO_GMAC_SEED_Kill(CRYPTO_GMAC_SEED_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the GMAC-SEED functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_GMAC_SEED_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_GMAC_SEED_Add()	Add data to MAC.
CRYPTO_MAC_GMAC_SEED_Final()	Finish MAC calculation.
CRYPTO_MAC_GMAC_SEED_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_GMAC_SEED_Kill()	Destroy MAC context.

CRYPTO_MAC_GMAC_SEED_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_GMAC_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_GMAC_SEED_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_GMAC_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_GMAC_SEED_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_GMAC_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_GMAC_SEED_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_GMAC_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_GMAC_SEED_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_GMAC_SEED_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

GMAC-ARIA

Standards reference

GMAC is specified by the following document:

• NIST SP 800-38D — Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC

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 GMAC-ARIA type-safe API functions.

Function	Description
Message functions
CRYPTO_GMAC_ARIA_Calc()	Calculate MAC.
CRYPTO_GMAC_ARIA_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_GMAC_ARIA_InitEx()	Initialize context, include subkey.
CRYPTO_GMAC_ARIA_Add()	Add data to MAC.
CRYPTO_GMAC_ARIA_Final()	Finish MAC calculation.
CRYPTO_GMAC_ARIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_GMAC_ARIA_Kill()	Destroy GMAC context.

CRYPTO_GMAC_ARIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_GMAC_ARIA_Add(      CRYPTO_GMAC_ARIA_CONTEXT * pSelf,
                          const U8                       * pInput,
                                unsigned                   InputLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pInput	Pointer to input 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_GMAC_ARIA_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_GMAC_ARIA_Calc(      U8       * pOutput,
                                 unsigned   OutputLen,
                           const U8       * pKey,
                                 unsigned   KeyLen,
                           const U8       * pIV,
                                 unsigned   IVLen,
                           const U8       * pInput,
                                 unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC.
OutputLen	Octet length of the MAC.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_ARIA_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_GMAC_ARIA_Calc_128(      U8       * pOutput,
                               const U8       * pKey,
                                     unsigned   KeyLen,
                               const U8       * pIV,
                                     unsigned   IVLen,
                               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.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_ARIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_GMAC_ARIA_Final(CRYPTO_GMAC_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_GMAC_ARIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_GMAC_ARIA_Final_128(CRYPTO_GMAC_ARIA_CONTEXT * pSelf,
                                U8                       * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pOutput	Pointer to object that receives the MAC, 16 octets.

CRYPTO_GMAC_ARIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_GMAC_ARIA_InitEx(      CRYPTO_GMAC_ARIA_CONTEXT * pSelf,
                             const U8                       * pKey,
                                   unsigned                   KeyLen,
                             const U8                       * pIV,
                                   unsigned                   IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_GMAC_ARIA_Kill()

Description

Destroy GMAC context.

Prototype

void CRYPTO_GMAC_ARIA_Kill(CRYPTO_GMAC_ARIA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the GMAC-ARIA functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_GMAC_ARIA_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_GMAC_ARIA_Add()	Add data to MAC.
CRYPTO_MAC_GMAC_ARIA_Final()	Finish MAC calculation.
CRYPTO_MAC_GMAC_ARIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_GMAC_ARIA_Kill()	Destroy MAC context.

CRYPTO_MAC_GMAC_ARIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_GMAC_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_GMAC_ARIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_GMAC_ARIA_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_GMAC_ARIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_GMAC_ARIA_Final_128(void * pContext,
                                    U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_GMAC_ARIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_GMAC_ARIA_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_GMAC_ARIA_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_GMAC_ARIA_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

GMAC-Camellia

Standards reference

GMAC is specified by the following document:

• NIST SP 800-38D — Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC

Camellia is specified by the following document:

• IETF RFC 3713 — A Description of the Camellia Encryption Algorithm

Type-safe API

The following table lists the GMAC-Camellia type-safe API functions.

Function	Description
Message functions
CRYPTO_GMAC_CAMELLIA_Calc()	Calculate MAC.
CRYPTO_GMAC_CAMELLIA_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_GMAC_CAMELLIA_InitEx()	Initialize context, include subkey.
CRYPTO_GMAC_CAMELLIA_Add()	Add data to MAC.
CRYPTO_GMAC_CAMELLIA_Final()	Finish MAC calculation.
CRYPTO_GMAC_CAMELLIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_GMAC_CAMELLIA_Kill()	Destroy GMAC context.

CRYPTO_GMAC_CAMELLIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_GMAC_CAMELLIA_Add(      CRYPTO_GMAC_CAMELLIA_CONTEXT * pSelf,
                              const U8                           * pInput,
                                    unsigned                       InputLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pInput	Pointer to input 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_GMAC_CAMELLIA_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_GMAC_CAMELLIA_Calc(      U8       * pOutput,
                                     unsigned   OutputLen,
                               const U8       * pKey,
                                     unsigned   KeyLen,
                               const U8       * pIV,
                                     unsigned   IVLen,
                               const U8       * pInput,
                                     unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC.
OutputLen	Octet length of the MAC.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_CAMELLIA_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_GMAC_CAMELLIA_Calc_128(      U8       * pOutput,
                                   const U8       * pKey,
                                         unsigned   KeyLen,
                                   const U8       * pIV,
                                         unsigned   IVLen,
                                   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.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_CAMELLIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_GMAC_CAMELLIA_Final(CRYPTO_GMAC_CAMELLIA_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_GMAC_CAMELLIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_GMAC_CAMELLIA_Final_128(CRYPTO_GMAC_CAMELLIA_CONTEXT * pSelf,
                                    U8                           * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pOutput	Pointer to object that receives the MAC, 16 octets.

CRYPTO_GMAC_CAMELLIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_GMAC_CAMELLIA_InitEx(      CRYPTO_GMAC_CAMELLIA_CONTEXT * pSelf,
                                 const U8                           * pKey,
                                       unsigned                       KeyLen,
                                 const U8                           * pIV,
                                       unsigned                       IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_GMAC_CAMELLIA_Kill()

Description

Destroy GMAC context.

Prototype

void CRYPTO_GMAC_CAMELLIA_Kill(CRYPTO_GMAC_CAMELLIA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the GMAC-Camellia functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_GMAC_CAMELLIA_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_GMAC_CAMELLIA_Add()	Add data to MAC.
CRYPTO_MAC_GMAC_CAMELLIA_Final()	Finish MAC calculation.
CRYPTO_MAC_GMAC_CAMELLIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_GMAC_CAMELLIA_Kill()	Destroy MAC context.

CRYPTO_MAC_GMAC_CAMELLIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_GMAC_CAMELLIA_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_GMAC_CAMELLIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_GMAC_CAMELLIA_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_GMAC_CAMELLIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_GMAC_CAMELLIA_Final_128(void * pContext,
                                        U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_GMAC_CAMELLIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_GMAC_CAMELLIA_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_GMAC_CAMELLIA_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_GMAC_CAMELLIA_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

GMAC-Twofish

Standards reference

GMAC is specified by the following document:

• NIST SP 800-38D — Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC

Twofish is specified by the following document:

• Schneier at al — Twofish: A 128-Bit Block Cipher

Type-safe API

The following table lists the GMAC-Twofish type-safe API functions.

Function	Description
Message functions
CRYPTO_GMAC_TWOFISH_Calc()	Calculate MAC.
CRYPTO_GMAC_TWOFISH_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_GMAC_TWOFISH_InitEx()	Initialize context, include subkey.
CRYPTO_GMAC_TWOFISH_Add()	Add data to MAC.
CRYPTO_GMAC_TWOFISH_Final()	Finish MAC calculation.
CRYPTO_GMAC_TWOFISH_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_GMAC_TWOFISH_Kill()	Destroy GMAC context.

CRYPTO_GMAC_TWOFISH_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_GMAC_TWOFISH_Add(      CRYPTO_GMAC_TWOFISH_CONTEXT * pSelf,
                             const U8                          * pInput,
                                   unsigned                      InputLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pInput	Pointer to input 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_GMAC_TWOFISH_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_GMAC_TWOFISH_Calc(      U8       * pOutput,
                                    unsigned   OutputLen,
                              const U8       * pKey,
                                    unsigned   KeyLen,
                              const U8       * pIV,
                                    unsigned   IVLen,
                              const U8       * pInput,
                                    unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC.
OutputLen	Octet length of the MAC.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_TWOFISH_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_GMAC_TWOFISH_Calc_128(      U8       * pOutput,
                                  const U8       * pKey,
                                        unsigned   KeyLen,
                                  const U8       * pIV,
                                        unsigned   IVLen,
                                  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.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_TWOFISH_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_GMAC_TWOFISH_Final(CRYPTO_GMAC_TWOFISH_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_GMAC_TWOFISH_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_GMAC_TWOFISH_Final_128(CRYPTO_GMAC_TWOFISH_CONTEXT * pSelf,
                                   U8                          * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pOutput	Pointer to object that receives the MAC, 16 octets.

CRYPTO_GMAC_TWOFISH_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_GMAC_TWOFISH_InitEx(      CRYPTO_GMAC_TWOFISH_CONTEXT * pSelf,
                                const U8                          * pKey,
                                      unsigned                      KeyLen,
                                const U8                          * pIV,
                                      unsigned                      IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_GMAC_TWOFISH_Kill()

Description

Destroy GMAC context.

Prototype

void CRYPTO_GMAC_TWOFISH_Kill(CRYPTO_GMAC_TWOFISH_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the GMAC-Twofish functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_GMAC_TWOFISH_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_GMAC_TWOFISH_Add()	Add data to MAC.
CRYPTO_MAC_GMAC_TWOFISH_Final()	Finish MAC calculation.
CRYPTO_MAC_GMAC_TWOFISH_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_GMAC_TWOFISH_Kill()	Destroy MAC context.

CRYPTO_MAC_GMAC_TWOFISH_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_GMAC_TWOFISH_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_GMAC_TWOFISH_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_GMAC_TWOFISH_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_GMAC_TWOFISH_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_GMAC_TWOFISH_Final_128(void * pContext,
                                       U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_GMAC_TWOFISH_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_GMAC_TWOFISH_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_GMAC_TWOFISH_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_GMAC_TWOFISH_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

GMAC-SM4

Standards reference

GMAC is specified by the following document:

• NIST SP 800-38D — Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC

SM4 is specified by the following document:

• draft-crypto-sm4-00 — The SM4 Block Cipher Algorithm And Its Modes Of Operations

Type-safe API

The following table lists the GMAC-SM4 type-safe API functions.

Function	Description
Message functions
CRYPTO_GMAC_SM4_Calc()	Calculate MAC.
CRYPTO_GMAC_SM4_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_GMAC_SM4_InitEx()	Initialize context, include subkey.
CRYPTO_GMAC_SM4_Add()	Add data to MAC.
CRYPTO_GMAC_SM4_Final()	Finish MAC calculation.
CRYPTO_GMAC_SM4_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_GMAC_SM4_Kill()	Destroy GMAC context.

CRYPTO_GMAC_SM4_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_GMAC_SM4_Add(      CRYPTO_GMAC_SM4_CONTEXT * pSelf,
                         const U8                      * pInput,
                               unsigned                  InputLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pInput	Pointer to input 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_GMAC_SM4_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_GMAC_SM4_Calc(      U8       * pOutput,
                                unsigned   OutputLen,
                          const U8       * pKey,
                                unsigned   KeyLen,
                          const U8       * pIV,
                                unsigned   IVLen,
                          const U8       * pInput,
                                unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC.
OutputLen	Octet length of the MAC.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_SM4_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_GMAC_SM4_Calc_128(      U8       * pOutput,
                              const U8       * pKey,
                                    unsigned   KeyLen,
                              const U8       * pIV,
                                    unsigned   IVLen,
                              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.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_GMAC_SM4_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_GMAC_SM4_Final(CRYPTO_GMAC_SM4_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_GMAC_SM4_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_GMAC_SM4_Final_128(CRYPTO_GMAC_SM4_CONTEXT * pSelf,
                               U8                      * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pOutput	Pointer to object that receives the MAC, 16 octets.

CRYPTO_GMAC_SM4_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_GMAC_SM4_InitEx(      CRYPTO_GMAC_SM4_CONTEXT * pSelf,
                            const U8                      * pKey,
                                  unsigned                  KeyLen,
                            const U8                      * pIV,
                                  unsigned                  IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_GMAC_SM4_Kill()

Description

Destroy GMAC context.

Prototype

void CRYPTO_GMAC_SM4_Kill(CRYPTO_GMAC_SM4_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the GMAC-SM4 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_GMAC_SM4_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_GMAC_SM4_Add()	Add data to MAC.
CRYPTO_MAC_GMAC_SM4_Final()	Finish MAC calculation.
CRYPTO_MAC_GMAC_SM4_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_GMAC_SM4_Kill()	Destroy MAC context.

CRYPTO_MAC_GMAC_SM4_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_GMAC_SM4_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_GMAC_SM4_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_GMAC_SM4_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_GMAC_SM4_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_GMAC_SM4_Final_128(void * pContext,
                                   U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_GMAC_SM4_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_GMAC_SM4_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_GMAC_SM4_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_GMAC_SM4_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

HMAC-MD5

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

MD5 is specified by the following document:

• IETF RFC 1321 — The MD5 Message-Digest Algorithm

Type-safe API

The following table lists the HMAC-MD5 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_MD5_Calc()	Calculate MAC.
CRYPTO_HMAC_MD5_Calc_160()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_MD5_Init()	Initialize context.
CRYPTO_HMAC_MD5_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_MD5_Add()	Add data to MAC.
CRYPTO_HMAC_MD5_Final()	Finalize MAC calculation.
CRYPTO_HMAC_MD5_Final_160()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_MD5_Kill()	Destroy HMAC context.
CRYPTO_HMAC_MD5_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_MD5_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_MD5_Add(      CRYPTO_HMAC_MD5_CONTEXT * pSelf,
                         const U8                      * pInput,
                               unsigned                  InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-MD5 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_MD5_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_MD5_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_MD5_Calc_160()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_MD5_Calc_160(      U8       * pOutput,
                              const U8       * pKey,
                                    unsigned   KeyLen,
                              const U8       * pInput,
                                    unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 20 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_MD5_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_MD5_Final(CRYPTO_HMAC_MD5_CONTEXT * pSelf,
                           U8                      * pOutput,
                           unsigned                  OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-MD5 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_MD5_Final_160()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_MD5_Final_160(CRYPTO_HMAC_MD5_CONTEXT * pSelf,
                               U8                      * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-MD5 context.
pOutput	Pointer to object that receives the MAC, 20 octets.

CRYPTO_HMAC_MD5_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_MD5_Init(      CRYPTO_HMAC_MD5_CONTEXT * pSelf,
                          const U8                      * pKey,
                                unsigned                  KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-MD5 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_MD5_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_MD5_InitEx(      CRYPTO_HMAC_MD5_CONTEXT * pSelf,
                            const U8                      * pKey,
                                  unsigned                  KeyLen,
                            const U8                      * pIV,
                                  unsigned                  IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_MD5_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_MD5_Kill(CRYPTO_HMAC_MD5_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_MD5_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_MD5_Reset(CRYPTO_HMAC_MD5_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-MD5 context.

Generic API

The following table lists the HMAC-MD5 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_MD5_Init()	Initialize context.
CRYPTO_MAC_HMAC_MD5_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_HMAC_MD5_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_MD5_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_MD5_Final_96()	Finish computation of the HMAC-MD5-96 HMAC and write to the output buffer.
CRYPTO_MAC_HMAC_MD5_Final_160()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_MD5_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_MD5_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_MD5_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_HMAC_MD5_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_MD5_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_HMAC_MD5_Final_96()

Description

Finish computation of the HMAC-MD5-96 HMAC and write to the output buffer.

Prototype

void CRYPTO_MAC_HMAC_MD5_Final_96(void * pSelf,
                                  U8   * pMAC);

Parameters

Parameter	Description
pSelf	HMAC-MD5 context.
pMAC	Pointer to object that receives MAC of CRYPTO_MD5_96_DIGEST_BYTE_COUNT octets.

CRYPTO_MAC_HMAC_MD5_Final_160()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_MD5_Final_160(void * pContext,
                                   U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_MD5_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_MD5_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_HMAC_MD5_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_HMAC_MD5_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_HMAC_MD5_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_MD5_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

HMAC-RIPEMD-160

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

MD5 is specified by the following document:

• Antoon Bosselaers — The hash function RIPEMD-160

Type-safe API

The following table lists the HMAC-RIPEMD-160 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_RIPEMD160_Calc()	Calculate MAC.
CRYPTO_HMAC_RIPEMD160_Calc_160()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_RIPEMD160_Init()	Initialize context.
CRYPTO_HMAC_RIPEMD160_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_RIPEMD160_Add()	Add data to MAC.
CRYPTO_HMAC_RIPEMD160_Final()	Finalize MAC calculation.
CRYPTO_HMAC_RIPEMD160_Final_160()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_RIPEMD160_Kill()	Destroy HMAC context.
CRYPTO_HMAC_RIPEMD160_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_RIPEMD160_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_RIPEMD160_Add(      CRYPTO_HMAC_RIPEMD160_CONTEXT * pSelf,
                               const U8                            * pInput,
                                     unsigned                        InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-RIPEMD-160 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_RIPEMD160_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_RIPEMD160_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_RIPEMD160_Calc_160()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_RIPEMD160_Calc_160(      U8       * pOutput,
                                    const U8       * pKey,
                                          unsigned   KeyLen,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 20 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_RIPEMD160_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_RIPEMD160_Final(CRYPTO_HMAC_RIPEMD160_CONTEXT * pSelf,
                                 U8                            * pOutput,
                                 unsigned                        OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-RIPEMD-160 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_RIPEMD160_Final_160()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_RIPEMD160_Final_160(CRYPTO_HMAC_RIPEMD160_CONTEXT * pSelf,
                                     U8                            * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-RIPEMD-160 context.
pOutput	Pointer to object that receives the MAC, 20 octets.

CRYPTO_HMAC_RIPEMD160_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_RIPEMD160_Init(      CRYPTO_HMAC_RIPEMD160_CONTEXT * pSelf,
                                const U8                            * pKey,
                                      unsigned                        KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-RIPEMD-160 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_RIPEMD160_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_RIPEMD160_InitEx(      CRYPTO_HMAC_RIPEMD160_CONTEXT * pSelf,
                                  const U8                            * pKey,
                                        unsigned                        KeyLen,
                                  const U8                            * pIV,
                                        unsigned                        IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_RIPEMD160_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_RIPEMD160_Kill(CRYPTO_HMAC_RIPEMD160_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_RIPEMD160_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_RIPEMD160_Reset(CRYPTO_HMAC_RIPEMD160_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-RIPEMD160 context.

Generic API

The following table lists the HMAC-RIPEMD-160 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_RIPEMD160_Init()	Initialize context.
CRYPTO_MAC_HMAC_RIPEMD160_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_HMAC_RIPEMD160_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_RIPEMD160_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_RIPEMD160_Final_160()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_RIPEMD160_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_RIPEMD160_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_RIPEMD160_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_HMAC_RIPEMD160_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_RIPEMD160_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_HMAC_RIPEMD160_Final_160()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_RIPEMD160_Final_160(void * pContext,
                                         U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_RIPEMD160_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_RIPEMD160_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_HMAC_RIPEMD160_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_HMAC_RIPEMD160_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_HMAC_RIPEMD160_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_RIPEMD160_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

HMAC-SHA-1

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SHA-1 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SHA-1 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SHA1_Calc()	Calculate MAC.
CRYPTO_HMAC_SHA1_Calc_160()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SHA1_Init()	Initialize context.
CRYPTO_HMAC_SHA1_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_SHA1_Add()	Add data to MAC.
CRYPTO_HMAC_SHA1_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SHA1_Final_160()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SHA1_Kill()	Destroy HMAC context.
CRYPTO_HMAC_SHA1_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_SHA1_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SHA1_Add(      CRYPTO_HMAC_SHA1_CONTEXT * pSelf,
                          const U8                       * pInput,
                                unsigned                   InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-1 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SHA1_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SHA1_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA1_Calc_160()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SHA1_Calc_160(      U8       * pOutput,
                               const U8       * pKey,
                                     unsigned   KeyLen,
                               const U8       * pInput,
                                     unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 20 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA1_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SHA1_Final(CRYPTO_HMAC_SHA1_CONTEXT * pSelf,
                            U8                       * pOutput,
                            unsigned                   OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-1 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SHA1_Final_160()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SHA1_Final_160(CRYPTO_HMAC_SHA1_CONTEXT * pSelf,
                                U8                       * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-1 context.
pOutput	Pointer to object that receives the MAC, 20 octets.

CRYPTO_HMAC_SHA1_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SHA1_Init(      CRYPTO_HMAC_SHA1_CONTEXT * pSelf,
                           const U8                       * pKey,
                                 unsigned                   KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-1 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SHA1_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_SHA1_InitEx(      CRYPTO_HMAC_SHA1_CONTEXT * pSelf,
                             const U8                       * pKey,
                                   unsigned                   KeyLen,
                             const U8                       * pIV,
                                   unsigned                   IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_SHA1_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SHA1_Kill(CRYPTO_HMAC_SHA1_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_SHA1_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SHA1_Reset(CRYPTO_HMAC_SHA1_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA1 context.

Generic API

The following table lists the HMAC-SHA-1 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SHA1_Init()	Initialize context.
CRYPTO_MAC_HMAC_SHA1_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_HMAC_SHA1_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SHA1_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SHA1_Final_96()	Finish computation of the HMAC-SHA1-96 HMAC and write to the output buffer.
CRYPTO_MAC_HMAC_SHA1_Final_160()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SHA1_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SHA1_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SHA1_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_HMAC_SHA1_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SHA1_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_HMAC_SHA1_Final_96()

Description

Finish computation of the HMAC-SHA1-96 HMAC and write to the output buffer.

Prototype

void CRYPTO_MAC_HMAC_SHA1_Final_96(void * pSelf,
                                   U8   * pMAC);

Parameters

Parameter	Description
pSelf	HMAC-SHA1 context.
pMAC	Pointer to object that receives MAC of CRYPTO_SHA1_96_DIGEST_BYTE_COUNT octets.

CRYPTO_MAC_HMAC_SHA1_Final_160()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SHA1_Final_160(void * pContext,
                                    U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SHA1_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SHA1_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_HMAC_SHA1_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_HMAC_SHA1_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_HMAC_SHA1_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SHA1_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Self-test API

The following table lists the HMAC-SHA-1 self-test API functions.

Function	Description
CRYPTO_HMAC_SHA1_RFC2202_SelfTest()	Run all RFC 2202 HMAC-SHA-1 test vectors.
CRYPTO_HMAC_SHA1_CAVS_SelfTest()	Run AES-CMAC self-test.

CRYPTO_HMAC_SHA1_RFC2202_SelfTest()

Description

Run all RFC 2202 HMAC-SHA-1 test vectors.

Prototype

void CRYPTO_HMAC_SHA1_RFC2202_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_HMAC_SHA1_CAVS_SelfTest()

Description

Run AES-CMAC self-test.

Prototype

void CRYPTO_HMAC_SHA1_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-SHA-224

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SHA-224 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SHA-224 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SHA224_Calc()	Calculate MAC.
CRYPTO_HMAC_SHA224_Calc_224()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SHA224_Init()	Initialize context.
CRYPTO_HMAC_SHA224_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_SHA224_Add()	Add data to MAC.
CRYPTO_HMAC_SHA224_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SHA224_Final_224()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SHA224_Kill()	Destroy HMAC context.
CRYPTO_HMAC_SHA224_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_SHA224_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SHA224_Add(      CRYPTO_HMAC_SHA224_CONTEXT * pSelf,
                            const U8                         * pInput,
                                  unsigned                     InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-224 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SHA224_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SHA224_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA224_Calc_224()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SHA224_Calc_224(      U8       * pOutput,
                                 const U8       * pKey,
                                       unsigned   KeyLen,
                                 const U8       * pInput,
                                       unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 28 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA224_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SHA224_Final(CRYPTO_HMAC_SHA224_CONTEXT * pSelf,
                              U8                         * pOutput,
                              unsigned                     OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-224 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SHA224_Final_224()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SHA224_Final_224(CRYPTO_HMAC_SHA224_CONTEXT * pSelf,
                                  U8                         * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-224 context.
pOutput	Pointer to object that receives the MAC, 28 octets.

CRYPTO_HMAC_SHA224_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SHA224_Init(      CRYPTO_HMAC_SHA224_CONTEXT * pSelf,
                             const U8                         * pKey,
                                   unsigned                     KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-224 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SHA224_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_SHA224_InitEx(      CRYPTO_HMAC_SHA224_CONTEXT * pSelf,
                               const U8                         * pKey,
                                     unsigned                     KeyLen,
                               const U8                         * pIV,
                                     unsigned                     IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_SHA224_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SHA224_Kill(CRYPTO_HMAC_SHA224_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_SHA224_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SHA224_Reset(CRYPTO_HMAC_SHA224_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA224 context.

Generic API

The following table lists the HMAC-SHA-224 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SHA224_Init()	Initialize context.
CRYPTO_MAC_HMAC_SHA224_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_HMAC_SHA224_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SHA224_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SHA224_Final_224()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SHA224_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SHA224_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SHA224_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_HMAC_SHA224_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SHA224_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_HMAC_SHA224_Final_224()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SHA224_Final_224(void * pContext,
                                      U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SHA224_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SHA224_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_HMAC_SHA224_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_HMAC_SHA224_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_HMAC_SHA224_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SHA224_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Self-test API

The following table lists the HMAC-SHA-224 self-test API functions.

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

CRYPTO_HMAC_SHA224_CAVS_SelfTest()

Description

Run AES-CMAC self-test.

Prototype

void CRYPTO_HMAC_SHA224_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-SHA-256

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SHA-256 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SHA-256 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SHA256_Calc()	Calculate MAC.
CRYPTO_HMAC_SHA256_Calc_256()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SHA256_Init()	Initialize context.
CRYPTO_HMAC_SHA256_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_SHA256_Add()	Add data to MAC.
CRYPTO_HMAC_SHA256_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SHA256_Final_256()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SHA256_Reset()	Reset MAC to initial state.
CRYPTO_HMAC_SHA256_Kill()	Destroy HMAC context.

CRYPTO_HMAC_SHA256_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SHA256_Add(      CRYPTO_HMAC_SHA256_CONTEXT * pSelf,
                            const U8                         * pInput,
                                  unsigned                     InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-256 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SHA256_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SHA256_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA256_Calc_256()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SHA256_Calc_256(      U8       * pOutput,
                                 const U8       * pKey,
                                       unsigned   KeyLen,
                                 const U8       * pInput,
                                       unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 32 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA256_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SHA256_Final(CRYPTO_HMAC_SHA256_CONTEXT * pSelf,
                              U8                         * pOutput,
                              unsigned                     OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-256 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SHA256_Final_256()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SHA256_Final_256(CRYPTO_HMAC_SHA256_CONTEXT * pSelf,
                                  U8                         * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-256 context.
pOutput	Pointer to object that receives the MAC, 32 octets.

CRYPTO_HMAC_SHA256_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SHA256_Init(      CRYPTO_HMAC_SHA256_CONTEXT * pSelf,
                             const U8                         * pKey,
                                   unsigned                     KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-256 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SHA256_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_SHA256_InitEx(      CRYPTO_HMAC_SHA256_CONTEXT * pSelf,
                               const U8                         * pKey,
                                     unsigned                     KeyLen,
                               const U8                         * pIV,
                                     unsigned                     IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_SHA256_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SHA256_Reset(CRYPTO_HMAC_SHA256_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA256 context.

CRYPTO_HMAC_SHA256_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SHA256_Kill(CRYPTO_HMAC_SHA256_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the HMAC-SHA-256 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SHA256_Init()	Initialize context.
CRYPTO_MAC_HMAC_SHA256_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_HMAC_SHA256_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SHA256_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SHA256_Final_256()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SHA256_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SHA256_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SHA256_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_HMAC_SHA256_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SHA256_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_HMAC_SHA256_Final_256()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SHA256_Final_256(void * pContext,
                                      U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SHA256_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SHA256_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_HMAC_SHA256_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_HMAC_SHA256_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_HMAC_SHA256_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SHA256_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Self-test API

The following table lists the HMAC-SHA-256 self-test API functions.

Function	Description
CRYPTO_HMAC_SHA256_CAVS_SelfTest()	Run AES-CMAC self-test.
CRYPTO_HMAC_SHA256_RFC4231_SelfTest()	Run all RFC 4231 HMAC-SHA-256 test vectors.

CRYPTO_HMAC_SHA256_CAVS_SelfTest()

Description

Run AES-CMAC self-test.

Prototype

void CRYPTO_HMAC_SHA256_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_HMAC_SHA256_RFC4231_SelfTest()

Description

Run all RFC 4231 HMAC-SHA-256 test vectors.

Prototype

void CRYPTO_HMAC_SHA256_RFC4231_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-SHA-384

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SHA-384 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SHA-384 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SHA384_Calc()	Calculate MAC.
CRYPTO_HMAC_SHA384_Calc_384()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SHA384_Add()	Add data to MAC.
CRYPTO_HMAC_SHA384_Init()	Initialize context.
CRYPTO_HMAC_SHA384_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_SHA384_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SHA384_Final_384()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SHA384_Kill()	Destroy HMAC context.
CRYPTO_HMAC_SHA384_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_SHA384_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SHA384_Add(      CRYPTO_HMAC_SHA384_CONTEXT * pSelf,
                            const U8                         * pInput,
                                  unsigned                     InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-384 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SHA384_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SHA384_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA384_Calc_384()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SHA384_Calc_384(      U8       * pOutput,
                                 const U8       * pKey,
                                       unsigned   KeyLen,
                                 const U8       * pInput,
                                       unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 48 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA384_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SHA384_Final(CRYPTO_HMAC_SHA384_CONTEXT * pSelf,
                              U8                         * pOutput,
                              unsigned                     OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-384 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SHA384_Final_384()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SHA384_Final_384(CRYPTO_HMAC_SHA384_CONTEXT * pSelf,
                                  U8                         * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-384 context.
pOutput	Pointer to object that receives the MAC, 48 octets.

CRYPTO_HMAC_SHA384_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SHA384_Init(      CRYPTO_HMAC_SHA384_CONTEXT * pSelf,
                             const U8                         * pKey,
                                   unsigned                     KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-384 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SHA384_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_SHA384_InitEx(      CRYPTO_HMAC_SHA384_CONTEXT * pSelf,
                               const U8                         * pKey,
                                     unsigned                     KeyLen,
                               const U8                         * pIV,
                                     unsigned                     IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_SHA384_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SHA384_Kill(CRYPTO_HMAC_SHA384_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_SHA384_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SHA384_Reset(CRYPTO_HMAC_SHA384_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA384 context.

Generic API

The following table lists the HMAC-SHA-384 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SHA384_Init()	Initialize context.
CRYPTO_MAC_HMAC_SHA384_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_HMAC_SHA384_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SHA384_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SHA384_Final_384()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SHA384_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SHA384_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SHA384_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_HMAC_SHA384_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SHA384_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_HMAC_SHA384_Final_384()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SHA384_Final_384(void * pContext,
                                      U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SHA384_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SHA384_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_HMAC_SHA384_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_HMAC_SHA384_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_HMAC_SHA384_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SHA384_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Self-test API

The following table lists the HMAC-SHA-384 self-test API functions.

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

CRYPTO_HMAC_SHA384_CAVS_SelfTest()

Description

Run AES-CMAC self-test.

Prototype

void CRYPTO_HMAC_SHA384_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-SHA-512

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SHA-512 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SHA-512 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SHA512_Calc()	Calculate MAC.
CRYPTO_HMAC_SHA512_Calc_512()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SHA512_Add()	Add data to MAC.
CRYPTO_HMAC_SHA512_Init()	Initialize context.
CRYPTO_HMAC_SHA512_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_SHA512_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SHA512_Final_512()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SHA512_Kill()	Destroy HMAC context.
CRYPTO_HMAC_SHA512_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_SHA512_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SHA512_Add(      CRYPTO_HMAC_SHA512_CONTEXT * pSelf,
                            const U8                         * pInput,
                                  unsigned                     InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SHA512_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SHA512_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA512_Calc_512()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SHA512_Calc_512(      U8       * pOutput,
                                 const U8       * pKey,
                                       unsigned   KeyLen,
                                 const U8       * pInput,
                                       unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 64 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA512_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SHA512_Final(CRYPTO_HMAC_SHA512_CONTEXT * pSelf,
                              U8                         * pOutput,
                              unsigned                     OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SHA512_Final_512()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SHA512_Final_512(CRYPTO_HMAC_SHA512_CONTEXT * pSelf,
                                  U8                         * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512 context.
pOutput	Pointer to object that receives the MAC, 64 octets.

CRYPTO_HMAC_SHA512_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SHA512_Init(      CRYPTO_HMAC_SHA512_CONTEXT * pSelf,
                             const U8                         * pKey,
                                   unsigned                     KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SHA512_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_SHA512_InitEx(      CRYPTO_HMAC_SHA512_CONTEXT * pSelf,
                               const U8                         * pKey,
                                     unsigned                     KeyLen,
                               const U8                         * pIV,
                                     unsigned                     IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_SHA512_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SHA512_Kill(CRYPTO_HMAC_SHA512_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_SHA512_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SHA512_Reset(CRYPTO_HMAC_SHA512_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA512 context.

Generic API

The following table lists the HMAC-SHA-512 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SHA512_Init()	Initialize context.
CRYPTO_MAC_HMAC_SHA512_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SHA512_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SHA512_Final_512()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SHA512_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SHA512_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SHA512_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_HMAC_SHA512_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SHA512_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_HMAC_SHA512_Final_512()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SHA512_Final_512(void * pContext,
                                      U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SHA512_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SHA512_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_HMAC_SHA512_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SHA512_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Self-test API

The following table lists the HMAC-SHA-512 self-test API functions.

Function	Description
CRYPTO_HMAC_SHA512_CAVS_SelfTest()	Run AES-CMAC self-test.
CRYPTO_HMAC_SHA512_RFC4231_SelfTest()	Run all HMAC-SHA-512 RFC 4231 test vectors.

CRYPTO_HMAC_SHA512_CAVS_SelfTest()

Description

Run AES-CMAC self-test.

Prototype

void CRYPTO_HMAC_SHA512_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_HMAC_SHA512_RFC4231_SelfTest()

Description

Run all HMAC-SHA-512 RFC 4231 test vectors.

Prototype

void CRYPTO_HMAC_SHA512_RFC4231_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-SHA-512/224

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SHA-512/224 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SHA-512/224 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SHA512_224_Calc()	Calculate MAC.
CRYPTO_HMAC_SHA512_224_Calc_224()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SHA512_224_Add()	Add data to MAC.
CRYPTO_HMAC_SHA512_224_Init()	Initialize context.
CRYPTO_HMAC_SHA512_224_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_SHA512_224_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SHA512_224_Final_224()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SHA512_224_Kill()	Destroy HMAC context.
CRYPTO_HMAC_SHA512_224_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_SHA512_224_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SHA512_224_Add(      CRYPTO_HMAC_SHA512_224_CONTEXT * pSelf,
                                const U8                             * pInput,
                                      unsigned                         InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512/224 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SHA512_224_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SHA512_224_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA512_224_Calc_224()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SHA512_224_Calc_224(      U8       * pOutput,
                                     const U8       * pKey,
                                           unsigned   KeyLen,
                                     const U8       * pInput,
                                           unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 28 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA512_224_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SHA512_224_Final(CRYPTO_HMAC_SHA512_224_CONTEXT * pSelf,
                                  U8                             * pOutput,
                                  unsigned                         OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512/224 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SHA512_224_Final_224()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SHA512_224_Final_224(CRYPTO_HMAC_SHA512_224_CONTEXT * pSelf,
                                      U8                             * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512/224 context.
pOutput	Pointer to object that receives the MAC, 28 octets.

CRYPTO_HMAC_SHA512_224_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SHA512_224_Init(      CRYPTO_HMAC_SHA512_224_CONTEXT * pSelf,
                                 const U8                             * pKey,
                                       unsigned                         KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512/224 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SHA512_224_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_SHA512_224_InitEx(      CRYPTO_HMAC_SHA512_224_CONTEXT * pSelf,
                                   const U8                             * pKey,
                                         unsigned                         KeyLen,
                                   const U8                             * pIV,
                                         unsigned                         IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_SHA512_224_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SHA512_224_Kill(CRYPTO_HMAC_SHA512_224_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_SHA512_224_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SHA512_224_Reset(CRYPTO_HMAC_SHA512_224_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA512_224 context.

Generic API

The following table lists the HMAC-SHA-512/224 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SHA512_224_Init()	Initialize context.
CRYPTO_MAC_HMAC_SHA512_224_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_HMAC_SHA512_224_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SHA512_224_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SHA512_224_Final_224()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SHA512_224_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SHA512_224_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SHA512_224_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_HMAC_SHA512_224_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SHA512_224_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_HMAC_SHA512_224_Final_224()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SHA512_224_Final_224(void * pContext,
                                          U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SHA512_224_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SHA512_224_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_HMAC_SHA512_224_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_HMAC_SHA512_224_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_HMAC_SHA512_224_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SHA512_224_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

HMAC-SHA-512/256

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SHA-512/256 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SHA-512/256 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SHA512_256_Calc()	Calculate MAC.
CRYPTO_HMAC_SHA512_256_Calc_256()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SHA512_256_Add()	Add data to MAC.
CRYPTO_HMAC_SHA512_256_Init()	Initialize context.
CRYPTO_HMAC_SHA512_256_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_SHA512_256_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SHA512_256_Final_256()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SHA512_256_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_SHA512_256_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SHA512_256_Add(      CRYPTO_HMAC_SHA512_256_CONTEXT * pSelf,
                                const U8                             * pInput,
                                      unsigned                         InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512/256 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SHA512_256_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SHA512_256_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA512_256_Calc_256()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SHA512_256_Calc_256(      U8       * pOutput,
                                     const U8       * pKey,
                                           unsigned   KeyLen,
                                     const U8       * pInput,
                                           unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 32 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA512_256_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SHA512_256_Final(CRYPTO_HMAC_SHA512_256_CONTEXT * pSelf,
                                  U8                             * pOutput,
                                  unsigned                         OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512/256 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SHA512_256_Final_256()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SHA512_256_Final_256(CRYPTO_HMAC_SHA512_256_CONTEXT * pSelf,
                                      U8                             * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512/256 context.
pOutput	Pointer to object that receives the MAC, 32 octets.

CRYPTO_HMAC_SHA512_256_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SHA512_256_Init(      CRYPTO_HMAC_SHA512_256_CONTEXT * pSelf,
                                 const U8                             * pKey,
                                       unsigned                         KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA-512/256 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SHA512_256_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_SHA512_256_InitEx(      CRYPTO_HMAC_SHA512_256_CONTEXT * pSelf,
                                   const U8                             * pKey,
                                         unsigned                         KeyLen,
                                   const U8                             * pIV,
                                         unsigned                         IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_SHA512_256_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SHA512_256_Kill(CRYPTO_HMAC_SHA512_256_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_SHA512_256_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SHA512_256_Reset(CRYPTO_HMAC_SHA512_256_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA512_256 context.

Generic API

The following table lists the HMAC-SHA-512/256 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SHA512_256_Init()	Initialize context.
CRYPTO_MAC_HMAC_SHA512_256_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_HMAC_SHA512_256_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SHA512_256_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SHA512_256_Final_256()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SHA512_256_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SHA512_256_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SHA512_256_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_HMAC_SHA512_256_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SHA512_256_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_HMAC_SHA512_256_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_HMAC_SHA512_256_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_HMAC_SHA512_256_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SHA512_256_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_HMAC_SHA512_256_Final_256()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SHA512_256_Final_256(void * pContext,
                                          U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SHA512_256_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SHA512_256_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

HMAC-SHA3-224

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SHA3-224 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SHA3-224 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SHA3_224_Calc()	Calculate MAC.
CRYPTO_HMAC_SHA3_224_Calc_224()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SHA3_224_Init()	Initialize context.
CRYPTO_HMAC_SHA3_224_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_SHA3_224_Add()	Add data to MAC.
CRYPTO_HMAC_SHA3_224_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SHA3_224_Final_224()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SHA3_224_Kill()	Destroy HMAC context.
CRYPTO_HMAC_SHA3_224_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_SHA3_224_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SHA3_224_Add(      CRYPTO_HMAC_SHA3_224_CONTEXT * pSelf,
                              const U8                           * pInput,
                                    unsigned                       InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-224 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SHA3_224_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SHA3_224_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA3_224_Calc_224()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SHA3_224_Calc_224(      U8       * pOutput,
                                   const U8       * pKey,
                                         unsigned   KeyLen,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 28 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA3_224_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SHA3_224_Final(CRYPTO_HMAC_SHA3_224_CONTEXT * pSelf,
                                U8                           * pOutput,
                                unsigned                       OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-224 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SHA3_224_Final_224()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SHA3_224_Final_224(CRYPTO_HMAC_SHA3_224_CONTEXT * pSelf,
                                    U8                           * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-224 context.
pOutput	Pointer to object that receives the MAC, 28 octets.

CRYPTO_HMAC_SHA3_224_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SHA3_224_Init(      CRYPTO_HMAC_SHA3_224_CONTEXT * pSelf,
                               const U8                           * pKey,
                                     unsigned                       KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-224 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SHA3_224_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_SHA3_224_InitEx(      CRYPTO_HMAC_SHA3_224_CONTEXT * pSelf,
                                 const U8                           * pKey,
                                       unsigned                       KeyLen,
                                 const U8                           * pIV,
                                       unsigned                       IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_SHA3_224_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SHA3_224_Kill(CRYPTO_HMAC_SHA3_224_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_SHA3_224_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SHA3_224_Reset(CRYPTO_HMAC_SHA3_224_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3_224 context.

Generic API

The following table lists the HMAC-SHA3-224 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SHA3_224_Init()	Initialize context.
CRYPTO_MAC_HMAC_SHA3_224_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SHA3_224_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SHA3_224_Final_224()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SHA3_224_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SHA3_224_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SHA3_224_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_HMAC_SHA3_224_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SHA3_224_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_HMAC_SHA3_224_Final_224()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SHA3_224_Final_224(void * pContext,
                                        U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SHA3_224_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SHA3_224_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_HMAC_SHA3_224_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SHA3_224_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

HMAC-SHA3-256

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SHA3-256 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SHA3-256 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SHA3_256_Calc()	Calculate MAC.
CRYPTO_HMAC_SHA3_256_Calc_256()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SHA3_256_Init()	Initialize context.
CRYPTO_HMAC_SHA3_256_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_SHA3_256_Add()	Add data to MAC.
CRYPTO_HMAC_SHA3_256_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SHA3_256_Final_256()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SHA3_256_Kill()	Destroy HMAC context.
CRYPTO_HMAC_SHA3_256_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_SHA3_256_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SHA3_256_Add(      CRYPTO_HMAC_SHA3_256_CONTEXT * pSelf,
                              const U8                           * pInput,
                                    unsigned                       InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-256 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SHA3_256_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SHA3_256_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA3_256_Calc_256()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SHA3_256_Calc_256(      U8       * pOutput,
                                   const U8       * pKey,
                                         unsigned   KeyLen,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 32 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA3_256_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SHA3_256_Final(CRYPTO_HMAC_SHA3_256_CONTEXT * pSelf,
                                U8                           * pOutput,
                                unsigned                       OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-256 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SHA3_256_Final_256()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SHA3_256_Final_256(CRYPTO_HMAC_SHA3_256_CONTEXT * pSelf,
                                    U8                           * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-256 context.
pOutput	Pointer to object that receives the MAC, 32 octets.

CRYPTO_HMAC_SHA3_256_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SHA3_256_Init(      CRYPTO_HMAC_SHA3_256_CONTEXT * pSelf,
                               const U8                           * pKey,
                                     unsigned                       KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-256 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SHA3_256_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_SHA3_256_InitEx(      CRYPTO_HMAC_SHA3_256_CONTEXT * pSelf,
                                 const U8                           * pKey,
                                       unsigned                       KeyLen,
                                 const U8                           * pIV,
                                       unsigned                       IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_SHA3_256_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SHA3_256_Kill(CRYPTO_HMAC_SHA3_256_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_SHA3_256_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SHA3_256_Reset(CRYPTO_HMAC_SHA3_256_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3_256 context.

Generic API

The following table lists the HMAC-SHA3-256 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SHA3_256_Init()	Initialize context.
CRYPTO_MAC_HMAC_SHA3_256_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SHA3_256_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SHA3_256_Final_256()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SHA3_256_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SHA3_256_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SHA3_256_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_HMAC_SHA3_256_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SHA3_256_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_HMAC_SHA3_256_Final_256()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SHA3_256_Final_256(void * pContext,
                                        U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SHA3_256_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SHA3_256_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_HMAC_SHA3_256_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SHA3_256_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

HMAC-SHA3-384

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SHA3-384 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SHA3-384 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SHA3_384_Calc()	Calculate MAC.
CRYPTO_HMAC_SHA3_384_Calc_384()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SHA3_384_Add()	Add data to MAC.
CRYPTO_HMAC_SHA3_384_Init()	Initialize context.
CRYPTO_HMAC_SHA3_384_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_SHA3_384_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SHA3_384_Final_384()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SHA3_384_Kill()	Destroy HMAC context.
CRYPTO_HMAC_SHA3_384_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_SHA3_384_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SHA3_384_Add(      CRYPTO_HMAC_SHA3_384_CONTEXT * pSelf,
                              const U8                           * pInput,
                                    unsigned                       InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-384 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SHA3_384_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SHA3_384_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA3_384_Calc_384()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SHA3_384_Calc_384(      U8       * pOutput,
                                   const U8       * pKey,
                                         unsigned   KeyLen,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 48 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA3_384_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SHA3_384_Final(CRYPTO_HMAC_SHA3_384_CONTEXT * pSelf,
                                U8                           * pOutput,
                                unsigned                       OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-384 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SHA3_384_Final_384()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SHA3_384_Final_384(CRYPTO_HMAC_SHA3_384_CONTEXT * pSelf,
                                    U8                           * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-384 context.
pOutput	Pointer to object that receives the MAC, 48 octets.

CRYPTO_HMAC_SHA3_384_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SHA3_384_Init(      CRYPTO_HMAC_SHA3_384_CONTEXT * pSelf,
                               const U8                           * pKey,
                                     unsigned                       KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-384 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SHA3_384_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_SHA3_384_InitEx(      CRYPTO_HMAC_SHA3_384_CONTEXT * pSelf,
                                 const U8                           * pKey,
                                       unsigned                       KeyLen,
                                 const U8                           * pIV,
                                       unsigned                       IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_SHA3_384_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SHA3_384_Kill(CRYPTO_HMAC_SHA3_384_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_SHA3_384_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SHA3_384_Reset(CRYPTO_HMAC_SHA3_384_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3_384 context.

Generic API

The following table lists the HMAC-SHA3-384 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SHA3_384_Init()	Initialize context.
CRYPTO_MAC_HMAC_SHA3_384_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SHA3_384_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SHA3_384_Final_384()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SHA3_384_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SHA3_384_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SHA3_384_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_HMAC_SHA3_384_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SHA3_384_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_HMAC_SHA3_384_Final_384()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SHA3_384_Final_384(void * pContext,
                                        U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SHA3_384_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SHA3_384_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_HMAC_SHA3_384_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SHA3_384_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

HMAC-SHA3-512

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SHA3-512 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SHA3-512 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SHA3_512_Calc()	Calculate MAC.
CRYPTO_HMAC_SHA3_512_Calc_512()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SHA3_512_Add()	Add data to MAC.
CRYPTO_HMAC_SHA3_512_Init()	Initialize context.
CRYPTO_HMAC_SHA3_512_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SHA3_512_Final_512()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SHA3_512_Kill()	Destroy HMAC context.
CRYPTO_HMAC_SHA3_512_Reset()	Reset MAC to initial state.

CRYPTO_HMAC_SHA3_512_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SHA3_512_Add(      CRYPTO_HMAC_SHA3_512_CONTEXT * pSelf,
                              const U8                           * pInput,
                                    unsigned                       InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-512 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SHA3_512_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SHA3_512_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA3_512_Calc_512()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SHA3_512_Calc_512(      U8       * pOutput,
                                   const U8       * pKey,
                                         unsigned   KeyLen,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 64 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SHA3_512_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SHA3_512_Final(CRYPTO_HMAC_SHA3_512_CONTEXT * pSelf,
                                U8                           * pOutput,
                                unsigned                       OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-512 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SHA3_512_Final_512()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SHA3_512_Final_512(CRYPTO_HMAC_SHA3_512_CONTEXT * pSelf,
                                    U8                           * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-512 context.
pOutput	Pointer to object that receives the MAC, 64 octets.

CRYPTO_HMAC_SHA3_512_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SHA3_512_Init(      CRYPTO_HMAC_SHA3_512_CONTEXT * pSelf,
                               const U8                           * pKey,
                                     unsigned                       KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3-512 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SHA3_512_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SHA3_512_Kill(CRYPTO_HMAC_SHA3_512_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

CRYPTO_HMAC_SHA3_512_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SHA3_512_Reset(CRYPTO_HMAC_SHA3_512_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SHA3_512 context.

Generic API

The following table lists the HMAC-SHA3-512 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SHA512_Init()	Initialize context.
CRYPTO_MAC_HMAC_SHA512_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SHA512_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SHA512_Final_512()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SHA512_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SHA3_512_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SHA3_512_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_HMAC_SHA3_512_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SHA3_512_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_HMAC_SHA3_512_Final_512()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SHA3_512_Final_512(void * pContext,
                                        U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SHA3_512_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SHA3_512_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_HMAC_SHA3_512_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SHA3_512_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

HMAC-SM3

Standards reference

HMAC is specified by the following document:

• FIPS PUB 198-1 — The Keyed-Hash Message Authentication Code (HMAC)

It has an associated IETF RFC:

• IETF RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

SM3 is specified by the following document:

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

Type-safe API

The following table lists the HMAC-SM3 type-safe API functions.

Function	Description
Message functions
CRYPTO_HMAC_SM3_Calc()	Calculate MAC.
CRYPTO_HMAC_SM3_Calc_256()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_HMAC_SM3_Init()	Initialize context.
CRYPTO_HMAC_SM3_InitEx()	Initialize context, include subkey.
CRYPTO_HMAC_SM3_Add()	Add data to MAC.
CRYPTO_HMAC_SM3_Final()	Finalize MAC calculation.
CRYPTO_HMAC_SM3_Final_256()	Finalize MAC calculation, fixed size.
CRYPTO_HMAC_SM3_Reset()	Reset MAC to initial state.
CRYPTO_HMAC_SM3_Kill()	Destroy HMAC context.

CRYPTO_HMAC_SM3_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_HMAC_SM3_Add(      CRYPTO_HMAC_SM3_CONTEXT * pSelf,
                         const U8                      * pInput,
                               unsigned                  InputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SM3 context.
pInput	Pointer to input octet string to add.
InputLen	Octet length of the input 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_HMAC_SM3_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_HMAC_SM3_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SM3_Calc_256()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_HMAC_SM3_Calc_256(      U8       * pOutput,
                              const U8       * pKey,
                                    unsigned   KeyLen,
                              const U8       * pInput,
                                    unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 32 octets.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_HMAC_SM3_Final()

Description

Finalize MAC calculation.

Prototype

void CRYPTO_HMAC_SM3_Final(CRYPTO_HMAC_SM3_CONTEXT * pSelf,
                           U8                      * pOutput,
                           unsigned                  OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SM3 context.
pOutput	Pointer to object that receive the MAC.
OutputLen	Octet length of the MAC.

CRYPTO_HMAC_SM3_Final_256()

Description

Finalize MAC calculation, fixed size.

Prototype

void CRYPTO_HMAC_SM3_Final_256(CRYPTO_HMAC_SM3_CONTEXT * pSelf,
                               U8                      * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SM3 context.
pOutput	Pointer to object that receives the MAC, 32 octets.

CRYPTO_HMAC_SM3_Init()

Description

Initialize context.

Prototype

void CRYPTO_HMAC_SM3_Init(      CRYPTO_HMAC_SM3_CONTEXT * pSelf,
                          const U8                      * pKey,
                                unsigned                  KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SM3 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_HMAC_SM3_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_HMAC_SM3_InitEx(      CRYPTO_HMAC_SM3_CONTEXT * pSelf,
                            const U8                      * pKey,
                                  unsigned                  KeyLen,
                            const U8                      * pIV,
                                  unsigned                  IVLen);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector (unused).
IVLen	Octet length of the initialization vector (unused).

Additional information

As the HMAC algorithm does not support subkeys, the initialization vector is accepted but otherwise ignored.

CRYPTO_HMAC_SM3_Reset()

Description

Reset MAC to initial state.

Prototype

void CRYPTO_HMAC_SM3_Reset(CRYPTO_HMAC_SM3_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to HMAC-SM3 context.

CRYPTO_HMAC_SM3_Kill()

Description

Destroy HMAC context.

Prototype

void CRYPTO_HMAC_SM3_Kill(CRYPTO_HMAC_SM3_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the HMAC-SM3 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_HMAC_SM3_Init()	Initialize context.
CRYPTO_MAC_HMAC_SM3_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_HMAC_SM3_Add()	Add data to MAC.
CRYPTO_MAC_HMAC_SM3_Final()	Finish MAC calculation.
CRYPTO_MAC_HMAC_SM3_Final_256()	Finish MAC calculation, fixed size.
CRYPTO_MAC_HMAC_SM3_Kill()	Destroy MAC context.

CRYPTO_MAC_HMAC_SM3_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_HMAC_SM3_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_HMAC_SM3_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_HMAC_SM3_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_HMAC_SM3_Final_256()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_HMAC_SM3_Final_256(void * pContext,
                                   U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_HMAC_SM3_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_HMAC_SM3_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_HMAC_SM3_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_HMAC_SM3_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_HMAC_SM3_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_HMAC_SM3_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

XCBC-AES

Standards reference

AES-XCBC-MAC is specified by the following document:

• IETF RFC 3566 — The AES-XCBC-MAC-96 Algorithm and Its Use With IPsec

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 XCBC-AES type-safe API functions.

Function	Description
Message functions
CRYPTO_XCBC_AES_Calc()	Calculate MAC.
CRYPTO_XCBC_AES_Calc_96()	Calculate MAC, fixed size, truncated.
CRYPTO_XCBC_AES_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_XCBC_AES_Init()	Initialize context.
CRYPTO_XCBC_AES_InitEx()	Initialize context, include subkey.
CRYPTO_XCBC_AES_Add()	Add data to MAC.
CRYPTO_XCBC_AES_Final()	Finish MAC calculation.
CRYPTO_XCBC_AES_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_XCBC_AES_Kill()	Destroy context.

CRYPTO_XCBC_AES_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_XCBC_AES_Add(      CRYPTO_XCBC_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_XCBC_AES_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_XCBC_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_XCBC_AES_Calc_96()

Description

Calculate MAC, fixed size, truncated.

Prototype

void CRYPTO_XCBC_AES_Calc_96(      U8       * pOutput,
                             const U8       * pKey,
                                   unsigned   KeyLen,
                             const U8       * pInput,
                                   unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 12 octets.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_XCBC_AES_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_XCBC_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_XCBC_AES_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_XCBC_AES_Final(CRYPTO_XCBC_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_XCBC_AES_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_XCBC_AES_Final_128(CRYPTO_XCBC_AES_CONTEXT * pSelf,
                               U8                      * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC, 16 octets.

CRYPTO_XCBC_AES_Init()

Description

Initialize context.

Prototype

void CRYPTO_XCBC_AES_Init(      CRYPTO_XCBC_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, fixed at 16 for AES-XCBC-MAC.

CRYPTO_XCBC_AES_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_XCBC_AES_InitEx(      CRYPTO_XCBC_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, fixed at 16 for AES-XCBC-MAC.
pIV	Pointer to initialization vector (ignored).
IVLen	Octet length of the initialization vector (must be zero).

CRYPTO_XCBC_AES_Kill()

Description

Destroy context.

Prototype

void CRYPTO_XCBC_AES_Kill(CRYPTO_XCBC_AES_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the XCBC-AES functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_XCBC_AES_Init()	Initialize context.
CRYPTO_MAC_XCBC_AES_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_XCBC_AES_Add()	Add data to MAC.
CRYPTO_MAC_XCBC_AES_Final()	Finish MAC calculation.
CRYPTO_MAC_XCBC_AES_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_XCBC_AES_Kill()	Destroy MAC context.

CRYPTO_MAC_XCBC_AES_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_XCBC_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_XCBC_AES_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_XCBC_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_XCBC_AES_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_XCBC_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_XCBC_AES_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_XCBC_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_XCBC_AES_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_XCBC_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_XCBC_AES_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_XCBC_AES_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Self-test API

The following table lists the XCBC-AES self-test API functions.

Function	Description
CRYPTO_XCBC_AES_RFC3566_SelfTest()	Run SM3 KATs from GBT.

CRYPTO_XCBC_AES_RFC3566_SelfTest()

Description

Run SM3 KATs from GBT.

Prototype

void CRYPTO_XCBC_AES_RFC3566_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

XCBC-SEED

Standards reference

SEED-XCBC-MAC uses the AES-XCBC-MAC algorithm with SEED substituted for AES as the cipher.

AES-XCBC-MAC is specified by the following document:

• IETF RFC 3566 — The AES-XCBC-MAC-96 Algorithm and Its Use With IPsec

SEED is specified by the following document:

• IETF RFC 4269 — The SEED Encryption Algorithm

Type-safe API

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

Function	Description
Message functions
CRYPTO_XCBC_SEED_Calc()	Calculate MAC.
CRYPTO_XCBC_SEED_Calc_96()	Calculate MAC, fixed size, truncated.
CRYPTO_XCBC_SEED_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_XCBC_SEED_Init()	Initialize context.
CRYPTO_XCBC_SEED_InitEx()	Initialize context, include subkey.
CRYPTO_XCBC_SEED_Add()	Add data to MAC.
CRYPTO_XCBC_SEED_Final()	Finish MAC calculation.
CRYPTO_XCBC_SEED_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_XCBC_SEED_Kill()	Destroy context.

CRYPTO_XCBC_SEED_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_XCBC_SEED_Add(      CRYPTO_XCBC_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_XCBC_SEED_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_XCBC_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_XCBC_SEED_Calc_96()

Description

Calculate MAC, fixed size, truncated.

Prototype

void CRYPTO_XCBC_SEED_Calc_96(      U8       * pOutput,
                              const U8       * pKey,
                                    unsigned   KeyLen,
                              const U8       * pInput,
                                    unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 12 octets.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_XCBC_SEED_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_XCBC_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_XCBC_SEED_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_XCBC_SEED_Final(CRYPTO_XCBC_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_XCBC_SEED_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_XCBC_SEED_Final_128(CRYPTO_XCBC_SEED_CONTEXT * pSelf,
                                U8                       * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC, 16 octets.

CRYPTO_XCBC_SEED_Init()

Description

Initialize context.

Prototype

void CRYPTO_XCBC_SEED_Init(      CRYPTO_XCBC_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, fixed at 16 for SEED-XCBC-MAC.

CRYPTO_XCBC_SEED_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_XCBC_SEED_InitEx(      CRYPTO_XCBC_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, fixed at 16 for SEED-XCBC-MAC.
pIV	Pointer to initialization vector (ignored).
IVLen	Octet length of the initialization vector (must be zero).

CRYPTO_XCBC_SEED_Kill()

Description

Destroy context.

Prototype

void CRYPTO_XCBC_SEED_Kill(CRYPTO_XCBC_SEED_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the XCBC-SEED functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_XCBC_SEED_Init()	Initialize context.
CRYPTO_MAC_XCBC_SEED_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_XCBC_SEED_Add()	Add data to MAC.
CRYPTO_MAC_XCBC_SEED_Final()	Finish MAC calculation.
CRYPTO_MAC_XCBC_SEED_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_XCBC_SEED_Kill()	Destroy MAC context.

CRYPTO_MAC_XCBC_SEED_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_XCBC_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_XCBC_SEED_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_XCBC_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_XCBC_SEED_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_XCBC_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_XCBC_SEED_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_XCBC_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_XCBC_SEED_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_XCBC_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_XCBC_SEED_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_XCBC_SEED_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

XCBC-ARIA

Standards reference

ARIA-XCBC-MAC uses the AES-XCBC-MAC algorithm with ARIA substituted for AES as the cipher.

AES-XCBC-MAC is specified by the following document:

• IETF RFC 3566 — The AES-XCBC-MAC-96 Algorithm and Its Use With IPsec

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 XCBC-ARIA type-safe API functions.

Function	Description
Message functions
CRYPTO_XCBC_ARIA_Calc()	Calculate MAC.
CRYPTO_XCBC_ARIA_Calc_96()	Calculate MAC, fixed size, truncated.
CRYPTO_XCBC_ARIA_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_XCBC_ARIA_Init()	Initialize context.
CRYPTO_XCBC_ARIA_InitEx()	Initialize context, include subkey.
CRYPTO_XCBC_ARIA_Add()	Add data to MAC.
CRYPTO_XCBC_ARIA_Final()	Finish MAC calculation.
CRYPTO_XCBC_ARIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_XCBC_ARIA_Kill()	Destroy context.

CRYPTO_XCBC_ARIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_XCBC_ARIA_Add(      CRYPTO_XCBC_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_XCBC_ARIA_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_XCBC_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_XCBC_ARIA_Calc_96()

Description

Calculate MAC, fixed size, truncated.

Prototype

void CRYPTO_XCBC_ARIA_Calc_96(      U8       * pOutput,
                              const U8       * pKey,
                                    unsigned   KeyLen,
                              const U8       * pInput,
                                    unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 12 octets.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_XCBC_ARIA_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_XCBC_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_XCBC_ARIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_XCBC_ARIA_Final(CRYPTO_XCBC_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_XCBC_ARIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_XCBC_ARIA_Final_128(CRYPTO_XCBC_ARIA_CONTEXT * pSelf,
                                U8                       * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC, 16 octets.

CRYPTO_XCBC_ARIA_Init()

Description

Initialize context.

Prototype

void CRYPTO_XCBC_ARIA_Init(      CRYPTO_XCBC_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, fixed at 16 for ARIA-XCBC-MAC.

CRYPTO_XCBC_ARIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_XCBC_ARIA_InitEx(      CRYPTO_XCBC_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, fixed at 16 for ARIA-XCBC-MAC.
pIV	Pointer to initialization vector (ignored).
IVLen	Octet length of the initialization vector (must be zero).

CRYPTO_XCBC_ARIA_Kill()

Description

Destroy context.

Prototype

void CRYPTO_XCBC_ARIA_Kill(CRYPTO_XCBC_ARIA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the XCBC-ARIA functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_XCBC_ARIA_Init()	Initialize context.
CRYPTO_MAC_XCBC_ARIA_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_XCBC_ARIA_Add()	Add data to MAC.
CRYPTO_MAC_XCBC_ARIA_Final()	Finish MAC calculation.
CRYPTO_MAC_XCBC_ARIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_XCBC_ARIA_Kill()	Destroy MAC context.

CRYPTO_MAC_XCBC_ARIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_XCBC_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_XCBC_ARIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_XCBC_ARIA_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_XCBC_ARIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_XCBC_ARIA_Final_128(void * pContext,
                                    U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_XCBC_ARIA_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_XCBC_ARIA_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_XCBC_ARIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_XCBC_ARIA_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_XCBC_ARIA_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_XCBC_ARIA_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

XCBC-Camellia

Standards reference

Camellia-XCBC-MAC uses the AES-XCBC-MAC algorithm with Camellia substituted for AES as the cipher.

AES-XCBC-MAC is specified by the following document:

• IETF RFC 3566 — The AES-XCBC-MAC-96 Algorithm and Its Use With IPsec

Camellia is specified by the following document:

• IETF RFC 3713 — A Description of the Camellia Encryption Algorithm

Type-safe API

The following table lists the XCBC-Camellia type-safe API functions.

Function	Description
Message functions
CRYPTO_XCBC_CAMELLIA_Calc()	Calculate MAC.
CRYPTO_XCBC_CAMELLIA_Calc_96()	Calculate MAC, fixed size, truncated.
CRYPTO_XCBC_CAMELLIA_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_XCBC_CAMELLIA_Init()	Initialize context.
CRYPTO_XCBC_CAMELLIA_InitEx()	Initialize context, include subkey.
CRYPTO_XCBC_CAMELLIA_Add()	Add data to MAC.
CRYPTO_XCBC_CAMELLIA_Final()	Finish MAC calculation.
CRYPTO_XCBC_CAMELLIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_XCBC_CAMELLIA_Kill()	Destroy context.

CRYPTO_XCBC_CAMELLIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_XCBC_CAMELLIA_Add(      CRYPTO_XCBC_CAMELLIA_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_XCBC_CAMELLIA_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_XCBC_CAMELLIA_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_XCBC_CAMELLIA_Calc_96()

Description

Calculate MAC, fixed size, truncated.

Prototype

void CRYPTO_XCBC_CAMELLIA_Calc_96(      U8       * pOutput,
                                  const U8       * pKey,
                                        unsigned   KeyLen,
                                  const U8       * pInput,
                                        unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 12 octets.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_XCBC_CAMELLIA_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_XCBC_CAMELLIA_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_XCBC_CAMELLIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_XCBC_CAMELLIA_Final(CRYPTO_XCBC_CAMELLIA_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_XCBC_CAMELLIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_XCBC_CAMELLIA_Final_128(CRYPTO_XCBC_CAMELLIA_CONTEXT * pSelf,
                                    U8                           * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC, 16 octets.

CRYPTO_XCBC_CAMELLIA_Init()

Description

Initialize context.

Prototype

void CRYPTO_XCBC_CAMELLIA_Init(      CRYPTO_XCBC_CAMELLIA_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, fixed at 16 for CAMELLIA-XCBC-MAC.

CRYPTO_XCBC_CAMELLIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_XCBC_CAMELLIA_InitEx(      CRYPTO_XCBC_CAMELLIA_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, fixed at 16 for CAMELLIA-XCBC-MAC.
pIV	Pointer to initialization vector (ignored).
IVLen	Octet length of the initialization vector (must be zero).

CRYPTO_XCBC_CAMELLIA_Kill()

Description

Destroy context.

Prototype

void CRYPTO_XCBC_CAMELLIA_Kill(CRYPTO_XCBC_CAMELLIA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the XCBC-Camellia functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_XCBC_CAMELLIA_Init()	Initialize context.
CRYPTO_MAC_XCBC_CAMELLIA_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_XCBC_CAMELLIA_Add()	Add data to MAC.
CRYPTO_MAC_XCBC_CAMELLIA_Final()	Finish MAC calculation.
CRYPTO_MAC_XCBC_CAMELLIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_XCBC_CAMELLIA_Kill()	Destroy MAC context.

CRYPTO_MAC_XCBC_CAMELLIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_XCBC_CAMELLIA_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_XCBC_CAMELLIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_XCBC_CAMELLIA_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_XCBC_CAMELLIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_XCBC_CAMELLIA_Final_128(void * pContext,
                                        U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_XCBC_CAMELLIA_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_XCBC_CAMELLIA_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_XCBC_CAMELLIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_XCBC_CAMELLIA_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_XCBC_CAMELLIA_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_XCBC_CAMELLIA_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

XCBC-Twofish

Standards reference

Twofish-XCBC-MAC uses the AES-XCBC-MAC algorithm with Twofish substituted for AES as the cipher.

AES-XCBC-MAC is specified by the following document:

• IETF RFC 3566 — The AES-XCBC-MAC-96 Algorithm and Its Use With IPsec

Twofish is specified by the following document:

• Schneier at al — Twofish: A 128-Bit Block Cipher

Type-safe API

The following table lists the XCBC-Twofish type-safe API functions.

Function	Description
Message functions
CRYPTO_XCBC_TWOFISH_Calc()	Calculate MAC.
CRYPTO_XCBC_TWOFISH_Calc_96()	Calculate MAC, fixed size, truncated.
CRYPTO_XCBC_TWOFISH_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_XCBC_TWOFISH_Init()	Initialize context.
CRYPTO_XCBC_TWOFISH_InitEx()	Initialize context, include subkey.
CRYPTO_XCBC_TWOFISH_Add()	Add data to MAC.
CRYPTO_XCBC_TWOFISH_Final()	Finish MAC calculation.
CRYPTO_XCBC_TWOFISH_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_XCBC_TWOFISH_Kill()	Destroy context.

CRYPTO_XCBC_TWOFISH_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_XCBC_TWOFISH_Add(      CRYPTO_XCBC_TWOFISH_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_XCBC_TWOFISH_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_XCBC_TWOFISH_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_XCBC_TWOFISH_Calc_96()

Description

Calculate MAC, fixed size, truncated.

Prototype

void CRYPTO_XCBC_TWOFISH_Calc_96(      U8       * pOutput,
                                 const U8       * pKey,
                                       unsigned   KeyLen,
                                 const U8       * pInput,
                                       unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 12 octets.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_XCBC_TWOFISH_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_XCBC_TWOFISH_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_XCBC_TWOFISH_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_XCBC_TWOFISH_Final(CRYPTO_XCBC_TWOFISH_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_XCBC_TWOFISH_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_XCBC_TWOFISH_Final_128(CRYPTO_XCBC_TWOFISH_CONTEXT * pSelf,
                                   U8                          * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC, 16 octets.

CRYPTO_XCBC_TWOFISH_Init()

Description

Initialize context.

Prototype

void CRYPTO_XCBC_TWOFISH_Init(      CRYPTO_XCBC_TWOFISH_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, fixed at 16 for TWOFISH-XCBC-MAC.

CRYPTO_XCBC_TWOFISH_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_XCBC_TWOFISH_InitEx(      CRYPTO_XCBC_TWOFISH_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, fixed at 16 for TWOFISH-XCBC-MAC.
pIV	Pointer to initialization vector (ignored).
IVLen	Octet length of the initialization vector (must be zero).

CRYPTO_XCBC_TWOFISH_Kill()

Description

Destroy context.

Prototype

void CRYPTO_XCBC_TWOFISH_Kill(CRYPTO_XCBC_TWOFISH_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the XCBC-Twofish functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_XCBC_TWOFISH_Init()	Initialize context.
CRYPTO_MAC_XCBC_TWOFISH_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_XCBC_TWOFISH_Add()	Add data to MAC.
CRYPTO_MAC_XCBC_TWOFISH_Final()	Finish MAC calculation.
CRYPTO_MAC_XCBC_TWOFISH_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_XCBC_TWOFISH_Kill()	Destroy MAC context.

CRYPTO_MAC_XCBC_TWOFISH_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_XCBC_TWOFISH_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_XCBC_TWOFISH_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_XCBC_TWOFISH_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_XCBC_TWOFISH_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_XCBC_TWOFISH_Final_128(void * pContext,
                                       U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_XCBC_TWOFISH_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_XCBC_TWOFISH_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_XCBC_TWOFISH_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_XCBC_TWOFISH_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_XCBC_TWOFISH_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_XCBC_TWOFISH_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

XCBC-SM4

Standards reference

SM4-XCBC-MAC uses the AES-XCBC-MAC algorithm with SM4 substituted for AES as the cipher.

AES-XCBC-MAC is specified by the following document:

• IETF RFC 3566 — The AES-XCBC-MAC-96 Algorithm and Its Use With IPsec

SM4 is specified by the following document:

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

Type-safe API

The following table lists the XCBC-SM4 type-safe API functions.

Function	Description
Message functions
CRYPTO_XCBC_SM4_Calc()	Calculate MAC.
CRYPTO_XCBC_SM4_Calc_96()	Calculate MAC, fixed size, truncated.
CRYPTO_XCBC_SM4_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_XCBC_SM4_Init()	Initialize context.
CRYPTO_XCBC_SM4_InitEx()	Initialize context, include subkey.
CRYPTO_XCBC_SM4_Add()	Add data to MAC.
CRYPTO_XCBC_SM4_Final()	Finish MAC calculation.
CRYPTO_XCBC_SM4_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_XCBC_SM4_Kill()	Destroy context.

CRYPTO_XCBC_SM4_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_XCBC_SM4_Add(      CRYPTO_XCBC_SM4_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_XCBC_SM4_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_XCBC_SM4_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_XCBC_SM4_Calc_96()

Description

Calculate MAC, fixed size, truncated.

Prototype

void CRYPTO_XCBC_SM4_Calc_96(      U8       * pOutput,
                             const U8       * pKey,
                                   unsigned   KeyLen,
                             const U8       * pInput,
                                   unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the MAC, 12 octets.
pKey	Pointer to cipher key.
KeyLen	Octet length of the cipher key.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_XCBC_SM4_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_XCBC_SM4_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_XCBC_SM4_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_XCBC_SM4_Final(CRYPTO_XCBC_SM4_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_XCBC_SM4_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_XCBC_SM4_Final_128(CRYPTO_XCBC_SM4_CONTEXT * pSelf,
                               U8                      * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC, 16 octets.

CRYPTO_XCBC_SM4_Init()

Description

Initialize context.

Prototype

void CRYPTO_XCBC_SM4_Init(      CRYPTO_XCBC_SM4_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, fixed at 16 for SM4-XCBC-MAC.

CRYPTO_XCBC_SM4_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_XCBC_SM4_InitEx(      CRYPTO_XCBC_SM4_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, fixed at 16 for SM4-XCBC-MAC.
pIV	Pointer to initialization vector (ignored).
IVLen	Octet length of the initialization vector (must be zero).

CRYPTO_XCBC_SM4_Kill()

Description

Destroy context.

Prototype

void CRYPTO_XCBC_SM4_Kill(CRYPTO_XCBC_SM4_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the XCBC-SM4 functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_XCBC_SM4_Init()	Initialize context.
CRYPTO_MAC_XCBC_SM4_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_XCBC_SM4_Add()	Add data to MAC.
CRYPTO_MAC_XCBC_SM4_Final()	Finish MAC calculation.
CRYPTO_MAC_XCBC_SM4_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_XCBC_SM4_Kill()	Destroy MAC context.

CRYPTO_MAC_XCBC_SM4_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_XCBC_SM4_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_XCBC_SM4_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_XCBC_SM4_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_XCBC_SM4_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_XCBC_SM4_Final_128(void * pContext,
                                   U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_XCBC_SM4_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_XCBC_SM4_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_XCBC_SM4_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_XCBC_SM4_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_XCBC_SM4_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_XCBC_SM4_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

KMAC

Standards reference

KMAC is specified by the following document:

• NIST SP 800-185 — SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash

Type-safe API

The following table lists the KMAC type-safe API functions.

Function	Description
Incremental functions
CRYPTO_KMAC_Init()	Initialize KMAC.
CRYPTO_KMAC_128_Init()	Initialize KMAC128.
CRYPTO_KMAC_256_Init()	Initialize KMAC256.
CRYPTO_KMAC_Add()	Add data to MAC.
CRYPTO_KMAC_Get()	Get KMAC.

CRYPTO_KMAC_Init()

Description

Initialize KMAC.

Prototype

void CRYPTO_KMAC_Init(      CRYPTO_KMAC_CONTEXT * pSelf,
                      const U8                  * pKey,
                            unsigned              KeyLen,
                      const U8                  * pCust,
                            unsigned              CustLen,
                            unsigned              Security);

Parameters

Parameter	Description
pSelf	Pointer to KMAC context.
pKey	Pointer to key string.
KeyLen	Octet length of the key string.
pCust	Pointer to customization string, S.
CustLen	Octet length of the customization string.
Security	Security strength in bits.

CRYPTO_KMAC_128_Init()

Description

Initialize KMAC128.

Prototype

void CRYPTO_KMAC_128_Init(      CRYPTO_KMAC_CONTEXT * pSelf,
                          const U8                  * pKey,
                                unsigned              KeyLen,
                          const U8                  * pCust,
                                unsigned              CustLen);

Parameters

Parameter	Description
pSelf	Pointer to KMAC context.
pKey	Pointer to key string.
KeyLen	Octet length of the key string.
pCust	Pointer to customization string, S.
CustLen	Octet length of the customization string.

CRYPTO_KMAC_256_Init()

Description

Initialize KMAC256.

Prototype

void CRYPTO_KMAC_256_Init(      CRYPTO_KMAC_CONTEXT * pSelf,
                          const U8                  * pKey,
                                unsigned              KeyLen,
                          const U8                  * pCust,
                                unsigned              CustLen);

Parameters

Parameter	Description
pSelf	Pointer to KMAC context.
pKey	Pointer to key string.
KeyLen	Octet length of the key string.
pCust	Pointer to customization string, S.
CustLen	Octet length of the customization string.

CRYPTO_KMAC_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_KMAC_Add(      CRYPTO_KMAC_CONTEXT * pSelf,
                     const U8                  * pInput,
                           unsigned              InputLen);

Parameters

Parameter	Description
pSelf	Pointer to KMAC context.
pInput	Pointer to input string to add to MAC.
InputLen	Octet length of the input string.

CRYPTO_KMAC_Get()

Description

Get KMAC.

Prototype

void CRYPTO_KMAC_Get(CRYPTO_KMAC_CONTEXT * pSelf,
                     U8                  * pMAC,
                     unsigned              MACLen);

Parameters

Parameter	Description
pSelf	Pointer to KMAC context.
pMAC	Pointer to object that receives the MAC.
MACLen	Octet length of the requested MAC.

Self-test API

The following table lists the KMAC self-test API functions.

Function	Description
CRYPTO_KMAC_CSRC_SelfTest()	Run all CSRC KMAC validation tests.

CRYPTO_KMAC_CSRC_SelfTest()

Description

Run all CSRC KMAC validation tests.

Prototype

void CRYPTO_KMAC_CSRC_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Poly1305

Type-safe API

The following table lists the Poly1305 type-safe API functions.

Function	Description
Message functions
CRYPTO_POLY1305_Calc()	Calculate MAC.
CRYPTO_POLY1305_Calc_128()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_POLY1305_Init()	Initialize MAC.
CRYPTO_POLY1305_Init_256()	Initialize MAC, 256-bit key.
CRYPTO_POLY1305_Add()	Add data to MAC.
CRYPTO_POLY1305_Final()	Finalize MAC.
CRYPTO_POLY1305_Final_128()	Finalize MAC, fixed size.
CRYPTO_POLY1305_Kill()	Destroy MAC.
CRYPTO_POLY1305_Clamp()	Clamp key.

CRYPTO_POLY1305_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_POLY1305_Add(      CRYPTO_POLY1305_CONTEXT * pSelf,
                         const U8                      * pInput,
                               unsigned                  InputLen);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305 context.
pInput	Pointer to input string to add to MAC.
InputLen	Octet length of the input string.

CRYPTO_POLY1305_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_POLY1305_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_POLY1305_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_POLY1305_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 key.
KeyLen	Octet length of the key.
pInput	Pointer to message.
InputLen	Octet length of the message.

CRYPTO_POLY1305_Final()

Description

Finalize MAC.

Prototype

void CRYPTO_POLY1305_Final(CRYPTO_POLY1305_CONTEXT * pSelf,
                           U8                      * pMAC,
                           unsigned                  MACLen);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305 context.
pMAC	Pointer to object that receives the MAC.
MACLen	Octet length of the requested MAC.

CRYPTO_POLY1305_Final_128()

Description

Finalize MAC, fixed size.

Prototype

void CRYPTO_POLY1305_Final_128(CRYPTO_POLY1305_CONTEXT * pSelf,
                               U8                      * pMAC);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305 context.
pMAC	Pointer to object that receives the MAC, 16 octets.

CRYPTO_POLY1305_Init()

Description

Initialize MAC.

Prototype

void CRYPTO_POLY1305_Init(      CRYPTO_POLY1305_CONTEXT * pSelf,
                          const U8                      * pKey,
                                unsigned                  KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305 context.
pKey	Pointer to key string.
KeyLen	Octet length of the key string, must be 32.

CRYPTO_POLY1305_Init_256()

Description

Initialize MAC, 256-bit key.

Prototype

void CRYPTO_POLY1305_Init_256(      CRYPTO_POLY1305_CONTEXT * pSelf,
                              const U8                      * pKey);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305 context.
pKey	Pointer to key string, 32 octets.

CRYPTO_POLY1305_Kill()

Description

Destroy MAC.

Prototype

void CRYPTO_POLY1305_Kill(CRYPTO_POLY1305_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305 context.

CRYPTO_POLY1305_Clamp()

Description

Clamp key.

Prototype

void CRYPTO_POLY1305_Clamp(U8 * pKey);

Parameters

Parameter	Description
pKey	Pointer to key to clamp, 32 octets.

Additional information

The Poly1305 key “rs” is the concatenation of two 16-byte octet strings, r and s, where the initial 16-byte octet string s must be modified to clear a proportion of bits before use.

Key octets with indexes 3, 7, 11, and 15 are required to have their top four bits clear and octets with indexes 4, 8, and 12 are required to have their bottom two bits clear.

Self-test API

The following table lists the Poly1305 self-test API functions.

Function	Description
CRYPTO_POLY1305_Bernstein_SelfTest()	Run Poly1305 KAT from Bernstein’s NaCl.

CRYPTO_POLY1305_Bernstein_SelfTest()

Description

Run Poly1305 KAT from Bernstein’s NaCl.

Prototype

void CRYPTO_POLY1305_Bernstein_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Poly1305-AES

Type-safe API

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

Function	Description
Message functions
CRYPTO_POLY1305_AES_Calc()	Calculate MAC.
CRYPTO_POLY1305_AES_Calc_128()	Calculate MAC, fixed size.
CRYPTO_POLY1305_AES_Verify()	Verify MAC.
CRYPTO_POLY1305_AES_Verify_128()	Verify MAC, fixed size.
Incremental functions
CRYPTO_POLY1305_AES_InitEx_256_128()	Initialize MAC.
CRYPTO_POLY1305_AES_Add()	Add to MAC.
CRYPTO_POLY1305_AES_Final()	Compute MAC.
CRYPTO_POLY1305_AES_Final_128()	Compute MAC, fixed size.
CRYPTO_POLY1305_AES_Kill()	Destroy MAC context.
Key functions
CRYPTO_POLY1305_AES_Clamp()	Clamp key.

CRYPTO_POLY1305_AES_Add()

Description

Add to MAC.

Prototype

void CRYPTO_POLY1305_AES_Add(      CRYPTO_POLY1305_AES_CONTEXT * pSelf,
                             const U8                          * pInput,
                                   unsigned                      InputLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context, encrypt mode.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_POLY1305_AES_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_POLY1305_AES_Calc(      U8       * pTag,
                                    unsigned   TagLen,
                              const U8       * pKey,
                              const U8       * pIV,
                              const U8       * pInput,
                                    unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag.
TagLen	Octet length of the requested authentication tag, at most 16 octets.
pKey	Pointer to key octet string, 32 octets.
pIV	Pointer to IV octet string, 16 octets.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_AES_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_POLY1305_AES_Calc_128(      U8       * pTag,
                                  const U8       * pKey,
                                  const U8       * pIV,
                                  const U8       * pInput,
                                        unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_AES_Clamp()

Description

Clamp key.

Prototype

void CRYPTO_POLY1305_AES_Clamp(U8 * pKey);

Parameters

Parameter	Description
pKey	Pointer to key to clamp, 32 octets.

CRYPTO_POLY1305_AES_Final()

Description

Compute MAC.

Prototype

void CRYPTO_POLY1305_AES_Final(CRYPTO_POLY1305_AES_CONTEXT * pSelf,
                               U8                          * pOutput,
                               unsigned                      OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-AES context.
pOutput	Pointer to object that receives the authentication tag.
OutputLen	Octet length of the requested authentication tag.

CRYPTO_POLY1305_AES_Final_128()

Description

Compute MAC, fixed size.

Prototype

void CRYPTO_POLY1305_AES_Final_128(CRYPTO_POLY1305_AES_CONTEXT * pSelf,
                                   U8                          * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-AES context.
pOutput	Pointer to object that receives the authentication tag, 16 octets.

CRYPTO_POLY1305_AES_InitEx_256_128()

Description

Initialize MAC.

Prototype

void CRYPTO_POLY1305_AES_InitEx_256_128(      CRYPTO_POLY1305_AES_CONTEXT * pSelf,
                                        const U8                          * pKey,
                                        const U8                          * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-AES context.
pKey	Pointer to key octet string, 32 bytes.
pIV	Pointer to IV octet string, 16 bytes.

CRYPTO_POLY1305_AES_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_POLY1305_AES_Kill(CRYPTO_POLY1305_AES_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-AES context.

CRYPTO_POLY1305_AES_Verify()

Description

Verify MAC.

Prototype

int CRYPTO_POLY1305_AES_Verify(const U8       * pTag,
                                     unsigned   TagLen,
                               const U8       * pKey,
                               const U8       * pIV,
                               const U8       * pInput,
                                     unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag.
TagLen	Octet length of the authentication tag.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_POLY1305_AES_Verify_128()

Description

Verify MAC, fixed size.

Prototype

int CRYPTO_POLY1305_AES_Verify_128(const U8       * pTag,
                                   const U8       * pKey,
                                   const U8       * pIV,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Generic API

The following table lists the Poly1305-AES functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_POLY1305_AES_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_POLY1305_AES_Add()	Add data to MAC.
CRYPTO_MAC_POLY1305_AES_Final()	Finish MAC calculation.
CRYPTO_MAC_POLY1305_AES_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_POLY1305_AES_Kill()	Destroy MAC context.

CRYPTO_MAC_POLY1305_AES_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_POLY1305_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_POLY1305_AES_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_POLY1305_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_POLY1305_AES_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_POLY1305_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_POLY1305_AES_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_POLY1305_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_POLY1305_AES_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_POLY1305_AES_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Self-test API

The following table lists the Poly1305 self-test API functions.

Function	Description
CRYPTO_POLY1305_AES_Bernstein_SelfTest()	Run Poly1305-AES KATs from Bernstein.

CRYPTO_POLY1305_AES_Bernstein_SelfTest()

Description

Run Poly1305-AES KATs from Bernstein.

Prototype

void CRYPTO_POLY1305_AES_Bernstein_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Poly1305-SEED

Type-safe API

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

Function	Description
Message functions
CRYPTO_POLY1305_SEED_Calc()	Calculate MAC.
CRYPTO_POLY1305_SEED_Calc_128()	Calculate MAC, fixed size.
CRYPTO_POLY1305_SEED_Verify()	Verify MAC.
CRYPTO_POLY1305_SEED_Verify_128()	Verify MAC, fixed size.
Incremental functions
CRYPTO_POLY1305_SEED_InitEx_256_128()	Initialize MAC.
CRYPTO_POLY1305_SEED_Add()	Add to MAC.
CRYPTO_POLY1305_SEED_Final()	Compute MAC.
CRYPTO_POLY1305_SEED_Final_128()	Compute MAC, fixed size.
CRYPTO_POLY1305_SEED_Kill()	Destroy MAC context.
Key functions
CRYPTO_POLY1305_SEED_Clamp()	Clamp key.

CRYPTO_POLY1305_SEED_Add()

Description

Add to MAC.

Prototype

void CRYPTO_POLY1305_SEED_Add(      CRYPTO_POLY1305_SEED_CONTEXT * pSelf,
                              const U8                           * pInput,
                                    unsigned                       InputLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context, encrypt mode.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_POLY1305_SEED_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_POLY1305_SEED_Calc(      U8       * pTag,
                                     unsigned   TagLen,
                               const U8       * pKey,
                               const U8       * pIV,
                               const U8       * pInput,
                                     unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag.
TagLen	Octet length of the requested authentication tag, at most 16 octets.
pKey	Pointer to key octet string, 32 octets.
pIV	Pointer to IV octet string, 16 octets.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_SEED_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_POLY1305_SEED_Calc_128(      U8       * pTag,
                                   const U8       * pKey,
                                   const U8       * pIV,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_SEED_Clamp()

Description

Clamp key.

Prototype

void CRYPTO_POLY1305_SEED_Clamp(U8 * pKey);

Parameters

Parameter	Description
pKey	Pointer to key to clamp, 32 octets.

CRYPTO_POLY1305_SEED_Final()

Description

Compute MAC.

Prototype

void CRYPTO_POLY1305_SEED_Final(CRYPTO_POLY1305_SEED_CONTEXT * pSelf,
                                U8                           * pOutput,
                                unsigned                       OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-SEED context.
pOutput	Pointer to object that receives the authentication tag.
OutputLen	Octet length of the requested authentication tag.

CRYPTO_POLY1305_SEED_Final_128()

Description

Compute MAC, fixed size.

Prototype

void CRYPTO_POLY1305_SEED_Final_128(CRYPTO_POLY1305_SEED_CONTEXT * pSelf,
                                    U8                           * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-SEED context.
pOutput	Pointer to object that receives the authentication tag, 16 octets.

CRYPTO_POLY1305_SEED_InitEx_256_128()

Description

Initialize MAC.

Prototype

void CRYPTO_POLY1305_SEED_InitEx_256_128
                                       (      CRYPTO_POLY1305_SEED_CONTEXT * pSelf,
                                        const U8                           * pKey,
                                        const U8                           * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-SEED context.
pKey	Pointer to key octet string, 32 bytes.
pIV	Pointer to IV octet string, 16 bytes.

CRYPTO_POLY1305_SEED_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_POLY1305_SEED_Kill(CRYPTO_POLY1305_SEED_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-SEED context.

CRYPTO_POLY1305_SEED_Verify()

Description

Verify MAC.

Prototype

int CRYPTO_POLY1305_SEED_Verify(const U8       * pTag,
                                      unsigned   TagLen,
                                const U8       * pKey,
                                const U8       * pIV,
                                const U8       * pInput,
                                      unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag.
TagLen	Octet length of the authentication tag.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_POLY1305_SEED_Verify_128()

Description

Verify MAC, fixed size.

Prototype

int CRYPTO_POLY1305_SEED_Verify_128(const U8       * pTag,
                                    const U8       * pKey,
                                    const U8       * pIV,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Generic API

The following table lists the Poly1305-SEED functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_POLY1305_SEED_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_POLY1305_SEED_Add()	Add data to MAC.
CRYPTO_MAC_POLY1305_SEED_Final()	Finish MAC calculation.
CRYPTO_MAC_POLY1305_SEED_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_POLY1305_SEED_Kill()	Destroy MAC context.

CRYPTO_MAC_POLY1305_SEED_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_POLY1305_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_POLY1305_SEED_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_POLY1305_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_POLY1305_SEED_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_POLY1305_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_POLY1305_SEED_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_POLY1305_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_POLY1305_SEED_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_POLY1305_SEED_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Poly1305-ARIA

Type-safe API

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

Function	Description
Message functions
CRYPTO_POLY1305_ARIA_Calc()	Calculate MAC.
CRYPTO_POLY1305_ARIA_Calc_128()	Calculate MAC, fixed size.
CRYPTO_POLY1305_ARIA_Verify()	Verify MAC.
CRYPTO_POLY1305_ARIA_Verify_128()	Verify MAC, fixed size.
Incremental functions
CRYPTO_POLY1305_ARIA_InitEx_256_128()	Initialize MAC.
CRYPTO_POLY1305_ARIA_Add()	Add to MAC.
CRYPTO_POLY1305_ARIA_Final()	Compute MAC.
CRYPTO_POLY1305_ARIA_Final_128()	Compute MAC, fixed size.
CRYPTO_POLY1305_ARIA_Kill()	Destroy MAC context.
Key functions
CRYPTO_POLY1305_ARIA_Clamp()	Clamp key.

CRYPTO_POLY1305_ARIA_Add()

Description

Add to MAC.

Prototype

void CRYPTO_POLY1305_ARIA_Add(      CRYPTO_POLY1305_ARIA_CONTEXT * pSelf,
                              const U8                           * pInput,
                                    unsigned                       InputLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context, encrypt mode.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_POLY1305_ARIA_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_POLY1305_ARIA_Calc(      U8       * pTag,
                                     unsigned   TagLen,
                               const U8       * pKey,
                               const U8       * pIV,
                               const U8       * pInput,
                                     unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag.
TagLen	Octet length of the requested authentication tag, at most 16 octets.
pKey	Pointer to key octet string, 32 octets.
pIV	Pointer to IV octet string, 16 octets.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_ARIA_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_POLY1305_ARIA_Calc_128(      U8       * pTag,
                                   const U8       * pKey,
                                   const U8       * pIV,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_ARIA_Clamp()

Description

Clamp key.

Prototype

void CRYPTO_POLY1305_ARIA_Clamp(U8 * pKey);

Parameters

Parameter	Description
pKey	Pointer to key to clamp, 32 octets.

CRYPTO_POLY1305_ARIA_Final()

Description

Compute MAC.

Prototype

void CRYPTO_POLY1305_ARIA_Final(CRYPTO_POLY1305_ARIA_CONTEXT * pSelf,
                                U8                           * pOutput,
                                unsigned                       OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-ARIA context.
pOutput	Pointer to object that receives the authentication tag.
OutputLen	Octet length of the requested authentication tag.

CRYPTO_POLY1305_ARIA_Final_128()

Description

Compute MAC, fixed size.

Prototype

void CRYPTO_POLY1305_ARIA_Final_128(CRYPTO_POLY1305_ARIA_CONTEXT * pSelf,
                                    U8                           * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-ARIA context.
pOutput	Pointer to object that receives the authentication tag, 16 octets.

CRYPTO_POLY1305_ARIA_InitEx_256_128()

Description

Initialize MAC.

Prototype

void CRYPTO_POLY1305_ARIA_InitEx_256_128
                                       (      CRYPTO_POLY1305_ARIA_CONTEXT * pSelf,
                                        const U8                           * pKey,
                                        const U8                           * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-ARIA context.
pKey	Pointer to key octet string, 32 bytes.
pIV	Pointer to IV octet string, 16 bytes.

CRYPTO_POLY1305_ARIA_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_POLY1305_ARIA_Kill(CRYPTO_POLY1305_ARIA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-ARIA context.

CRYPTO_POLY1305_ARIA_Verify()

Description

Verify MAC.

Prototype

int CRYPTO_POLY1305_ARIA_Verify(const U8       * pTag,
                                      unsigned   TagLen,
                                const U8       * pKey,
                                const U8       * pIV,
                                const U8       * pInput,
                                      unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag.
TagLen	Octet length of the authentication tag.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_POLY1305_ARIA_Verify_128()

Description

Verify MAC, fixed size.

Prototype

int CRYPTO_POLY1305_ARIA_Verify_128(const U8       * pTag,
                                    const U8       * pKey,
                                    const U8       * pIV,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Generic API

The following table lists the Poly1305-ARIA functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_POLY1305_ARIA_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_POLY1305_ARIA_Add()	Add data to MAC.
CRYPTO_MAC_POLY1305_ARIA_Final()	Finish MAC calculation.
CRYPTO_MAC_POLY1305_ARIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_POLY1305_ARIA_Kill()	Destroy MAC context.

CRYPTO_MAC_POLY1305_ARIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_POLY1305_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_POLY1305_ARIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_POLY1305_ARIA_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_POLY1305_ARIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_POLY1305_ARIA_Final_128(void * pContext,
                                        U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_POLY1305_ARIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_POLY1305_ARIA_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_POLY1305_ARIA_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_POLY1305_ARIA_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Poly1305-Camellia

Type-safe API

The following table lists the Poly1305-Camellia type-safe API functions.

Function	Description
Message functions
CRYPTO_POLY1305_CAMELLIA_Calc()	Calculate MAC.
CRYPTO_POLY1305_CAMELLIA_Calc_128()	Calculate MAC, fixed size.
CRYPTO_POLY1305_CAMELLIA_Verify()	Verify MAC.
CRYPTO_POLY1305_CAMELLIA_Verify_128()	Verify MAC, fixed size.
Incremental functions
CRYPTO_POLY1305_CAMELLIA_InitEx_256_128()	Initialize MAC.
CRYPTO_POLY1305_CAMELLIA_Add()	Add to MAC.
CRYPTO_POLY1305_CAMELLIA_Final()	Compute MAC.
CRYPTO_POLY1305_CAMELLIA_Final_128()	Compute MAC, fixed size.
CRYPTO_POLY1305_CAMELLIA_Kill()	Destroy MAC context.
Key functions
CRYPTO_POLY1305_CAMELLIA_Clamp()	Clamp key.

CRYPTO_POLY1305_CAMELLIA_Add()

Description

Add to MAC.

Prototype

void CRYPTO_POLY1305_CAMELLIA_Add
                               (      CRYPTO_POLY1305_CAMELLIA_CONTEXT * pSelf,
                                const U8                               * pInput,
                                      unsigned                           InputLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context, encrypt mode.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_POLY1305_CAMELLIA_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_POLY1305_CAMELLIA_Calc(      U8       * pTag,
                                         unsigned   TagLen,
                                   const U8       * pKey,
                                   const U8       * pIV,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag.
TagLen	Octet length of the requested authentication tag, at most 16 octets.
pKey	Pointer to key octet string, 32 octets.
pIV	Pointer to IV octet string, 16 octets.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_CAMELLIA_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_POLY1305_CAMELLIA_Calc_128(      U8       * pTag,
                                       const U8       * pKey,
                                       const U8       * pIV,
                                       const U8       * pInput,
                                             unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_CAMELLIA_Clamp()

Description

Clamp key.

Prototype

void CRYPTO_POLY1305_CAMELLIA_Clamp(U8 * pKey);

Parameters

Parameter	Description
pKey	Pointer to key to clamp, 32 octets.

CRYPTO_POLY1305_CAMELLIA_Final()

Description

Compute MAC.

Prototype

void CRYPTO_POLY1305_CAMELLIA_Final(CRYPTO_POLY1305_CAMELLIA_CONTEXT * pSelf,
                                    U8                               * pOutput,
                                    unsigned                           OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-Camellia context.
pOutput	Pointer to object that receives the authentication tag.
OutputLen	Octet length of the requested authentication tag.

CRYPTO_POLY1305_CAMELLIA_Final_128()

Description

Compute MAC, fixed size.

Prototype

void CRYPTO_POLY1305_CAMELLIA_Final_128
                                      (CRYPTO_POLY1305_CAMELLIA_CONTEXT * pSelf,
                                       U8                               * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-Camellia context.
pOutput	Pointer to object that receives the authentication tag, 16 octets.

CRYPTO_POLY1305_CAMELLIA_InitEx_256_128()

Description

Initialize MAC.

Prototype

void CRYPTO_POLY1305_CAMELLIA_InitEx_256_128
                                   (      CRYPTO_POLY1305_CAMELLIA_CONTEXT * pSelf,
                                    const U8                               * pKey,
                                    const U8                               * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-Camellia context.
pKey	Pointer to key octet string, 32 bytes.
pIV	Pointer to IV octet string, 16 bytes.

CRYPTO_POLY1305_CAMELLIA_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_POLY1305_CAMELLIA_Kill(CRYPTO_POLY1305_CAMELLIA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-Camellia context.

CRYPTO_POLY1305_CAMELLIA_Verify()

Description

Verify MAC.

Prototype

int CRYPTO_POLY1305_CAMELLIA_Verify(const U8       * pTag,
                                          unsigned   TagLen,
                                    const U8       * pKey,
                                    const U8       * pIV,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag.
TagLen	Octet length of the authentication tag.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_POLY1305_CAMELLIA_Verify_128()

Description

Verify MAC, fixed size.

Prototype

int CRYPTO_POLY1305_CAMELLIA_Verify_128(const U8       * pTag,
                                        const U8       * pKey,
                                        const U8       * pIV,
                                        const U8       * pInput,
                                              unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Generic API

The following table lists the Poly1305-Camellia functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_POLY1305_CAMELLIA_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_POLY1305_CAMELLIA_Add()	Add data to MAC.
CRYPTO_MAC_POLY1305_CAMELLIA_Final()	Finish MAC calculation.
CRYPTO_MAC_POLY1305_CAMELLIA_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_POLY1305_CAMELLIA_Kill()	Destroy MAC context.

CRYPTO_MAC_POLY1305_CAMELLIA_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_POLY1305_CAMELLIA_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_POLY1305_CAMELLIA_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_POLY1305_CAMELLIA_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_POLY1305_CAMELLIA_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_POLY1305_CAMELLIA_Final_128(void * pContext,
                                            U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_POLY1305_CAMELLIA_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_POLY1305_CAMELLIA_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_POLY1305_CAMELLIA_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_POLY1305_CAMELLIA_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Poly1305-Twofish

Type-safe API

The following table lists the Poly1305-Twofish type-safe API functions.

Function	Description
Message functions
CRYPTO_POLY1305_TWOFISH_Calc()	Calculate MAC.
CRYPTO_POLY1305_TWOFISH_Calc_128()	Calculate MAC, fixed size.
CRYPTO_POLY1305_TWOFISH_Verify()	Verify MAC.
CRYPTO_POLY1305_TWOFISH_Verify_128()	Verify MAC, fixed size.
Incremental functions
CRYPTO_POLY1305_TWOFISH_InitEx_256_128()	Initialize MAC.
CRYPTO_POLY1305_TWOFISH_Add()	Add to MAC.
CRYPTO_POLY1305_TWOFISH_Final()	Compute MAC.
CRYPTO_POLY1305_TWOFISH_Final_128()	Compute MAC, fixed size.
CRYPTO_POLY1305_TWOFISH_Kill()	Destroy MAC context.
Key functions
CRYPTO_POLY1305_TWOFISH_Clamp()	Clamp key.

CRYPTO_POLY1305_TWOFISH_Add()

Description

Add to MAC.

Prototype

void CRYPTO_POLY1305_TWOFISH_Add(      CRYPTO_POLY1305_TWOFISH_CONTEXT * pSelf,
                                 const U8                              * pInput,
                                       unsigned                          InputLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context, encrypt mode.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_POLY1305_TWOFISH_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_POLY1305_TWOFISH_Calc(      U8       * pTag,
                                        unsigned   TagLen,
                                  const U8       * pKey,
                                  const U8       * pIV,
                                  const U8       * pInput,
                                        unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag.
TagLen	Octet length of the requested authentication tag, at most 16 octets.
pKey	Pointer to key octet string, 32 octets.
pIV	Pointer to IV octet string, 16 octets.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_TWOFISH_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_POLY1305_TWOFISH_Calc_128(      U8       * pTag,
                                      const U8       * pKey,
                                      const U8       * pIV,
                                      const U8       * pInput,
                                            unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_TWOFISH_Clamp()

Description

Clamp key.

Prototype

void CRYPTO_POLY1305_TWOFISH_Clamp(U8 * pKey);

Parameters

Parameter	Description
pKey	Pointer to key to clamp, 32 octets.

CRYPTO_POLY1305_TWOFISH_Final()

Description

Compute MAC.

Prototype

void CRYPTO_POLY1305_TWOFISH_Final(CRYPTO_POLY1305_TWOFISH_CONTEXT * pSelf,
                                   U8                              * pOutput,
                                   unsigned                          OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-Twofish context.
pOutput	Pointer to object that receives the authentication tag.
OutputLen	Octet length of the requested authentication tag.

CRYPTO_POLY1305_TWOFISH_Final_128()

Description

Compute MAC, fixed size.

Prototype

void CRYPTO_POLY1305_TWOFISH_Final_128(CRYPTO_POLY1305_TWOFISH_CONTEXT * pSelf,
                                       U8                              * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-Twofish context.
pOutput	Pointer to object that receives the authentication tag, 16 octets.

CRYPTO_POLY1305_TWOFISH_InitEx_256_128()

Description

Initialize MAC.

Prototype

void CRYPTO_POLY1305_TWOFISH_InitEx_256_128
                                    (      CRYPTO_POLY1305_TWOFISH_CONTEXT * pSelf,
                                     const U8                              * pKey,
                                     const U8                              * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-Twofish context.
pKey	Pointer to key octet string, 32 bytes.
pIV	Pointer to IV octet string, 16 bytes.

CRYPTO_POLY1305_TWOFISH_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_POLY1305_TWOFISH_Kill(CRYPTO_POLY1305_TWOFISH_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-Twofish context.

CRYPTO_POLY1305_TWOFISH_Verify()

Description

Verify MAC.

Prototype

int CRYPTO_POLY1305_TWOFISH_Verify(const U8       * pTag,
                                         unsigned   TagLen,
                                   const U8       * pKey,
                                   const U8       * pIV,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag.
TagLen	Octet length of the authentication tag.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_POLY1305_TWOFISH_Verify_128()

Description

Verify MAC, fixed size.

Prototype

int CRYPTO_POLY1305_TWOFISH_Verify_128(const U8       * pTag,
                                       const U8       * pKey,
                                       const U8       * pIV,
                                       const U8       * pInput,
                                             unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Generic API

The following table lists the Poly1305-Twofish functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_POLY1305_TWOFISH_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_POLY1305_TWOFISH_Add()	Add data to MAC.
CRYPTO_MAC_POLY1305_TWOFISH_Final()	Finish MAC calculation.
CRYPTO_MAC_POLY1305_TWOFISH_Final_128()	Finish MAC calculation, fixed size.
CRYPTO_MAC_POLY1305_TWOFISH_Kill()	Destroy MAC context.

CRYPTO_MAC_POLY1305_TWOFISH_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_POLY1305_TWOFISH_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_POLY1305_TWOFISH_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_POLY1305_TWOFISH_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_POLY1305_TWOFISH_Final_128()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_POLY1305_TWOFISH_Final_128(void * pContext,
                                           U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_POLY1305_TWOFISH_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_POLY1305_TWOFISH_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_POLY1305_TWOFISH_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_POLY1305_TWOFISH_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Poly1305-SM4

Type-safe API

The following table lists the Poly1305-SM4 type-safe API functions.

Function	Description
Message functions
CRYPTO_POLY1305_SM4_Calc()	Calculate MAC.
CRYPTO_POLY1305_SM4_Calc_128()	Calculate MAC, fixed size.
CRYPTO_POLY1305_SM4_Verify()	Verify MAC.
CRYPTO_POLY1305_SM4_Verify_128()	Verify MAC, fixed size.
Incremental functions
CRYPTO_POLY1305_SM4_InitEx_256_128()	Initialize MAC.
CRYPTO_POLY1305_SM4_Add()	Add to MAC.
CRYPTO_POLY1305_SM4_Final()	Compute MAC.
CRYPTO_POLY1305_SM4_Final_128()	Compute MAC, fixed size.
CRYPTO_POLY1305_SM4_Kill()	Destroy MAC context.
Key functions
CRYPTO_POLY1305_SM4_Clamp()	Clamp key.

CRYPTO_POLY1305_SM4_Add()

Description

Add to MAC.

Prototype

void CRYPTO_POLY1305_SM4_Add(      CRYPTO_POLY1305_SM4_CONTEXT * pSelf,
                             const U8                          * pInput,
                                   unsigned                      InputLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context, encrypt mode.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_POLY1305_SM4_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_POLY1305_SM4_Calc(      U8       * pTag,
                                    unsigned   TagLen,
                              const U8       * pKey,
                              const U8       * pIV,
                              const U8       * pInput,
                                    unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag.
TagLen	Octet length of the requested authentication tag, at most 16 octets.
pKey	Pointer to key octet string, 32 octets.
pIV	Pointer to IV octet string, 16 octets.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_SM4_Calc_128()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_POLY1305_SM4_Calc_128(      U8       * pTag,
                                  const U8       * pKey,
                                  const U8       * pIV,
                                  const U8       * pInput,
                                        unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that receives the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

CRYPTO_POLY1305_SM4_Clamp()

Description

Clamp key.

Prototype

void CRYPTO_POLY1305_SM4_Clamp(U8 * pKey);

Parameters

Parameter	Description
pKey	Pointer to key to clamp, 32 octets.

CRYPTO_POLY1305_SM4_Final()

Description

Compute MAC.

Prototype

void CRYPTO_POLY1305_SM4_Final(CRYPTO_POLY1305_SM4_CONTEXT * pSelf,
                               U8                          * pOutput,
                               unsigned                      OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-SM4 context.
pOutput	Pointer to object that receives the authentication tag.
OutputLen	Octet length of the requested authentication tag.

CRYPTO_POLY1305_SM4_Final_128()

Description

Compute MAC, fixed size.

Prototype

void CRYPTO_POLY1305_SM4_Final_128(CRYPTO_POLY1305_SM4_CONTEXT * pSelf,
                                   U8                          * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-SM4 context.
pOutput	Pointer to object that receives the authentication tag, 16 octets.

CRYPTO_POLY1305_SM4_InitEx_256_128()

Description

Initialize MAC.

Prototype

void CRYPTO_POLY1305_SM4_InitEx_256_128(      CRYPTO_POLY1305_SM4_CONTEXT * pSelf,
                                        const U8                          * pKey,
                                        const U8                          * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-SM4 context.
pKey	Pointer to key octet string, 32 bytes.
pIV	Pointer to IV octet string, 16 bytes.

CRYPTO_POLY1305_SM4_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_POLY1305_SM4_Kill(CRYPTO_POLY1305_SM4_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Poly1305-SM4 context.

CRYPTO_POLY1305_SM4_Verify()

Description

Verify MAC.

Prototype

int CRYPTO_POLY1305_SM4_Verify(const U8       * pTag,
                                     unsigned   TagLen,
                               const U8       * pKey,
                               const U8       * pIV,
                               const U8       * pInput,
                                     unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag.
TagLen	Octet length of the authentication tag.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_POLY1305_SM4_Verify_128()

Description

Verify MAC, fixed size.

Prototype

int CRYPTO_POLY1305_SM4_Verify_128(const U8       * pTag,
                                   const U8       * pKey,
                                   const U8       * pIV,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pTag	Pointer to object that contains the authentication tag, 16 octets.
pKey	Pointer to key octet string.
pIV	Pointer to IV octet string.
pInput	Pointer to the message octet string.
InputLen	Octet length of the message octet string.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Michael

Type-safe API

The following table lists the Michael type-safe API functions.

Function	Description
Message functions
CRYPTO_MICHAEL_Calc()	Calculate MAC.
CRYPTO_MICHAEL_Calc_64()	Calculate MAC, fixed size.
Incremental functions
CRYPTO_MICHAEL_Init()	Initialize context.
CRYPTO_MICHAEL_Init_64()	Initialize context, fixed size.
CRYPTO_MICHAEL_Add()	Add data to MAC.
CRYPTO_MICHAEL_Final()	Finish MAC calculation.
CRYPTO_MICHAEL_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_MICHAEL_Kill()	Destroy context.

CRYPTO_MICHAEL_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MICHAEL_Add(      CRYPTO_MICHAEL_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_MICHAEL_Calc()

Description

Calculate MAC.

Prototype

void CRYPTO_MICHAEL_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.
OutputLen	Octet length of the MAC.
pKey	Pointer to key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_MICHAEL_Calc_64()

Description

Calculate MAC, fixed size.

Prototype

void CRYPTO_MICHAEL_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 key octet string.
KeyLen	Octet length of the key octet string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_MICHAEL_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MICHAEL_Final(CRYPTO_MICHAEL_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_MICHAEL_Final_64()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MICHAEL_Final_64(CRYPTO_MICHAEL_CONTEXT * pSelf,
                             U8                     * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pOutput	Pointer to object that receives the MAC, 8 octets.

CRYPTO_MICHAEL_Init()

Description

Initialize context.

Prototype

void CRYPTO_MICHAEL_Init(      CRYPTO_MICHAEL_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_MICHAEL_Init_64()

Description

Initialize context, fixed size.

Prototype

void CRYPTO_MICHAEL_Init_64(      CRYPTO_MICHAEL_CONTEXT * pSelf,
                            const U8                     * pKey);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.
pKey	Pointer to cipher key, 8 octets.

CRYPTO_MICHAEL_Kill()

Description

Destroy context.

Prototype

void CRYPTO_MICHAEL_Kill(CRYPTO_MICHAEL_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to MAC context.

Generic API

The following table lists the Michael functions that conform to the generic MAC API.

Function	Description
CRYPTO_MAC_MICHAEL_Init()	Initialize context.
CRYPTO_MAC_MICHAEL_InitEx()	Initialize context, include subkey.
CRYPTO_MAC_MICHAEL_Add()	Add data to MAC.
CRYPTO_MAC_MICHAEL_Final()	Finish MAC calculation.
CRYPTO_MAC_MICHAEL_Final_64()	Finish MAC calculation, fixed size.
CRYPTO_MAC_MICHAEL_Kill()	Destroy MAC context.

CRYPTO_MAC_MICHAEL_Add()

Description

Add data to MAC.

Prototype

void CRYPTO_MAC_MICHAEL_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_MICHAEL_Final()

Description

Finish MAC calculation.

Prototype

void CRYPTO_MAC_MICHAEL_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_MICHAEL_Final_64()

Description

Finish MAC calculation, fixed size.

Prototype

void CRYPTO_MAC_MICHAEL_Final_64(void * pContext,
                                 U8   * pMAC);

Parameters

Parameter	Description
pContext	Pointer to MAC context.
pMAC	Pointer to object that receives the MAC.

CRYPTO_MAC_MICHAEL_Init()

Description

Initialize context.

Prototype

void CRYPTO_MAC_MICHAEL_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_MICHAEL_InitEx()

Description

Initialize context, include subkey.

Prototype

void CRYPTO_MAC_MICHAEL_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_MICHAEL_Kill()

Description

Destroy MAC context.

Prototype

void CRYPTO_MAC_MICHAEL_Kill(void * pContext);

Parameters

Parameter	Description
pContext	Pointer to MAC context.

Self-test API

The following table lists the MICHAEL self-test API functions.

Function	Description
CRYPTO_MICHAEL_802v11_SelfTest()	Run Michael test vectors from 802.11-2016.

CRYPTO_MICHAEL_802v11_SelfTest()

Description

Run Michael test vectors from 802.11-2016.

Prototype

void CRYPTO_MICHAEL_802v11_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Symmetric encryption (secret key)

emCrypt implements the following ciphers:

• DES
• AES
• IDEA
• SEED
• ARIA
• Camellia
• CAST
• ChaCha20
• Blowfish
• Twofish
• PRESENT
• RC4

Introduction

In general a symmetric encryption or decryption is performed in two steps:

• Initializing using the cipher key. This will determine the direction of the operation (encryption or decryption).
• Encrypting or decrypting data.

The initialization prepares the key for the operation and stores it into a data structure called a cipher context. The cipher context is maintained by the cipher functions, only the memory must be provided by the caller. It can be used for multiple encryption or decryption operations with the same key and may be discarded if the key is no longer used. Encryption and decryption can not be intermixed with the same cipher context.

The API functions are named in the same way for all cipher algorithms:

• CRYPTO_<cipher_name_and_mode>_InitEncrypt() for initializing and preparing the key for encryption operations.
• CRYPTO_<cipher_name_and_mode>_Encrypt() to encrypt data.

Respectively:

• CRYPTO_<cipher_name_and_mode>_InitDecrypt() for initializing and preparing the key for decryption operations.
• CRYPTO_<cipher_name_and_mode>_Decrypt() to decrypt data.

Example

//
// Example for an AES encryption.
//
static const U8          Key[16] = { 0x08, 0x15, 0x85, 0xa1, ..., 0x5b, 0xa3 };
CRYPTO_AES_CONTEXT       AES_Context;
//
// Prepare the key for encryption.
//
CRYPTO_AES_InitEncrypt(&AES_Context, Key, sizeof(Key));
//
// Encrypt data.
//
CRYPTO_AES_ECB_Encrypt(&AES_Context, pChiperData, pClearData, DataLen);
//
// Encrypt more data.
//
CRYPTO_AES_ECB_Encrypt(&AES_Context, pChiperData2, pClearData2, Data2Len);
//
// From now, AES_Context is not used any more.
// For security reasons, clear the key from memory.
//
CRYPTO_AES_Kill(&AES_Context);

Besides the type-safe API functions described above, there are also generic API functions, that use a void pointer to take the cipher context. These are useful, if the API functions shall be called via functions pointers to dynamically choose different cipher algorithms. When using the generic functions the caller is responsible to provide the correct context (or memory areas) via the void pointer argument.

DES

Standards reference

DES is specified by the following document:

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

Algorithm parameters

Block size

#define CRYPTO_TDES_BLOCK_BYTE_COUNT   16

The number of bytes in a single TDES block.

Key size

#define CRYPTO_TDES_1KEY_SIZE    8
#define CRYPTO_TDES_2KEY_SIZE   16
#define CRYPTO_TDES_3KEY_SIZE   24

The number of bytes for three TDES keying options:

Keying mode	Description
CRYPTO_TDES_1KEY_SIZE	All three keys are identical with K1 = K2 = K3.
CRYPTO_TDES_2KEY_SIZE	K1 and K2 are independent and K3 = K1.
CRYPTO_TDES_3KEY_SIZE	All three keys are independent.

Configuration and resource use

Default

#define CRYPTO_CONFIG_DES_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize DES and 3DES to place tables in RAM rather than flash. Optimization levels are 0 through 5 with larger numbers generally producing better performance.

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.38 KB	Flash	2.1 KB	1.3 KB		3.4 KB
1	0.38 KB	Flash	2.1 KB	2.1 KB		4.2 KB
2	0.38 KB	Flash	2.1 KB	5.3 KB		7.4 KB
3	0.38 KB	RAM	2.1 KB	1.3 KB		3.4 KB
4	0.38 KB	RAM	2.1 KB	2.1 KB		4.2 KB
5	0.38 KB	RAM	2.1 KB	5.3 KB		7.4 KB

Type-safe API

The following table lists the DES type-safe API functions.

Function	Description
Installation and hardware assist
CRYPTO_TDES_Install()	Install cipher.
CRYPTO_TDES_IsInstalled()	Query whether cipher is installed.
CRYPTO_TDES_QueryInstall()	Query installed cipher.
Setup
CRYPTO_TDES_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_TDES_InitEncryptEx()	Initialize, expand key, encrypt mode.
CRYPTO_TDES_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_TDES_InitDecryptEx()	Initialize, expand key, decrypt mode.
CRYPTO_TDES_Kill()	Clear TDES context.
Single blocks
CRYPTO_TDES_Encrypt()	Encrypt block.
CRYPTO_TDES_Decrypt()	Decrypt block.
Basic modes
CRYPTO_TDES_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_TDES_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_TDES_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_TDES_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_TDES_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_TDES_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_TDES_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_TDES_CTR_Decrypt()	Decrypt, CTR mode.
Formatting
CRYPTO_TDES_CheckParity()	Check parity of DES key.
CRYPTO_TDES_CorrectParity()	Correct parity of DES key.
CRYPTO_TDES_InsertParity()	Insert parity bits into key.

CRYPTO_TDES_Install()

Description

Install cipher.

Prototype

void CRYPTO_TDES_Install(const CRYPTO_CIPHER_API * pHWAPI,
                         const CRYPTO_CIPHER_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_TDES_IsInstalled()

Description

Query whether cipher is installed.

Prototype

int CRYPTO_TDES_IsInstalled(void);

Return value

= 0	Cipher is not installed.
≠ 0	Cipher is installed.

CRYPTO_TDES_QueryInstall()

Description

Query installed cipher.

Prototype

void CRYPTO_TDES_QueryInstall(const CRYPTO_CIPHER_API ** ppHWAPI,
                              const CRYPTO_CIPHER_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the pointer to the preferred API.
ppSWAPI	Pointer to object that receives the pointer to the fallback API.

CRYPTO_TDES_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_TDES_InitEncrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                             const U8                  * pKey,
                                   unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_TDES_InitEncryptEx()

Description

Initialize, expand key, encrypt mode.

Prototype

void CRYPTO_TDES_InitEncryptEx(      CRYPTO_TDES_CONTEXT * pSelf,
                               const U8                  * pKey,
                                     unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_TDES_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_TDES_InitDecrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                             const U8                  * pKey,
                                   unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_TDES_InitDecryptEx()

Description

Initialize, expand key, decrypt mode.

Prototype

void CRYPTO_TDES_InitDecryptEx(      CRYPTO_TDES_CONTEXT * pSelf,
                               const U8                  * pKey,
                                     unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_TDES_Kill()

Description

Clear TDES context.

Prototype

void CRYPTO_TDES_Kill(CRYPTO_TDES_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.

CRYPTO_TDES_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_TDES_Encrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                               U8                  * pOutput,
                         const U8                  * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_TDES_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_TDES_Decrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                               U8                  * pOutput,
                         const U8                  * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_TDES_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_TDES_ECB_Encrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen);

Parameters

Parameter	Description
pSelf	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_TDES_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_TDES_ECB_Decrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen);

Parameters

Parameter	Description
pSelf	Pointer to TDES context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_TDES_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_TDES_CBC_Encrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_TDES_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_TDES_CBC_Decrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to TDES context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_TDES_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_TDES_OFB_Encrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_TDES_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_TDES_OFB_Decrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_TDES_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_TDES_CTR_Encrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pCTR,
                                   unsigned              CTRIndex,
                                   unsigned              CTRLen);

Parameters

Parameter	Description
pSelf	Initialized TDES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_TDES_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_TDES_CTR_Decrypt(      CRYPTO_TDES_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pCTR,
                                   unsigned              CTRIndex,
                                   unsigned              CTRLen);

Parameters

Parameter	Description
pSelf	Initialized TDES context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_TDES_CheckParity()

Description

Check parity of DES key.

Prototype

int CRYPTO_TDES_CheckParity(const U8       * pKey,
                                  unsigned   KeyLen);

Parameters

Parameter	Description
pKey	Pointer to key.
KeyLen	Octet length of the key.

Return value

≥ 0	Success, parity is correct.
< 0	Failure, at least one parity bit in error.

Additional information

The low-order bit of each key byte contains the parity.

CRYPTO_TDES_CorrectParity()

Description

Correct parity of DES key.

Prototype

void CRYPTO_TDES_CorrectParity(U8       * pKey,
                               unsigned   KeyLen);

Parameters

Parameter	Description
pKey	Pointer to key.
KeyLen	Octet length of the key.

Additional information

The low-order bits of each key byte are corrected to odd parity.

CRYPTO_TDES_InsertParity()

Description

Insert parity bits into key.

Prototype

unsigned CRYPTO_TDES_InsertParity(      U8       * pOutput,
                                  const U8       * pInput,
                                        unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to expanded key with odd parity inserted.
pInput	Pointer to input key without parity.
InputLen	Octet length of the input key.

Return value

Octet length of the expanded key.

Additional information

The input key, which has no parity bits, is expanded to a longer key with the low-order bits of each expanded octet set to odd parity.

The number of output bytes is 8*(InputLen/7) so a 21-octet TDES key will expand to a 24-octet TDES key with parity inserted.

Generic API

The following table lists the TDES functions that conform to the generic cipher API.

Function	Description
Setup
CRYPTO_CIPHER_TDES_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CIPHER_TDES_64_InitEncrypt()	Initialize, encrypt mode, 64-bit key.
CRYPTO_CIPHER_TDES_128_InitEncrypt()	Initialize, encrypt mode, 128-bit key.
CRYPTO_CIPHER_TDES_192_InitEncrypt()	Initialize, encrypt mode, 192-bit key.
CRYPTO_CIPHER_TDES_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CIPHER_TDES_64_InitDecrypt()	Initialize, decrypt mode, 64-bit key.
CRYPTO_CIPHER_TDES_128_InitDecrypt()	Initialize, decrypt mode, 128-bit key.
CRYPTO_CIPHER_TDES_192_InitDecrypt()	Initialize, decrypt mode, 192-bit key.
Single blocks
CRYPTO_CIPHER_TDES_Encrypt()	Encrypt block.
CRYPTO_CIPHER_TDES_Decrypt()	Decrypt block.
Basic modes
CRYPTO_CIPHER_TDES_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_TDES_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_TDES_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_TDES_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_TDES_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_TDES_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_TDES_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_TDES_CTR_0_8_Encrypt()	Encrypt, CTR(0,8) mode.
CRYPTO_CIPHER_TDES_CTR_4_4_Encrypt()	Encrypt, CTR(4,4) mode.
CRYPTO_CIPHER_TDES_CTR_Decrypt()	Decrypt, CTR mode.
CRYPTO_CIPHER_TDES_CTR_0_8_Decrypt()	Decrypt, CTR(0,8) mode.
CRYPTO_CIPHER_TDES_CTR_4_4_Decrypt()	Decrypt, CTR(4,4) mode.

CRYPTO_CIPHER_TDES_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CIPHER_TDES_InitEncrypt(      void     * pContext,
                                    const U8       * pKey,
                                          unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to TDES context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_TDES_64_InitEncrypt()

Description

Initialize, encrypt mode, 64-bit key.

Prototype

void CRYPTO_CIPHER_TDES_64_InitEncrypt(      void * pContext,
                                       const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TDES context.
pKey	Pointer to key.

CRYPTO_CIPHER_TDES_128_InitEncrypt()

Description

Initialize, encrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_TDES_128_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TDES context.
pKey	Pointer to key.

CRYPTO_CIPHER_TDES_192_InitEncrypt()

Description

Initialize, encrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_TDES_192_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TDES context.
pKey	Pointer to key.

CRYPTO_CIPHER_TDES_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CIPHER_TDES_InitDecrypt(      void     * pContext,
                                    const U8       * pKey,
                                          unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to TDES context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_TDES_64_InitDecrypt()

Description

Initialize, decrypt mode, 64-bit key.

Prototype

void CRYPTO_CIPHER_TDES_64_InitDecrypt(      void * pContext,
                                       const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TDES context.
pKey	Pointer to key.

CRYPTO_CIPHER_TDES_128_InitDecrypt()

Description

Initialize, decrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_TDES_128_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TDES context.
pKey	Pointer to key.

CRYPTO_CIPHER_TDES_192_InitDecrypt()

Description

Initialize, decrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_TDES_192_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TDES context.
pKey	Pointer to key.

CRYPTO_CIPHER_TDES_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CIPHER_TDES_Encrypt(      void * pContext,
                                      U8   * pOutput,
                                const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to TDES context.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CIPHER_TDES_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CIPHER_TDES_Decrypt(      void * pContext,
                                      U8   * pOutput,
                                const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to TDES context.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CIPHER_TDES_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_TDES_ECB_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_TDES_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_TDES_ECB_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to TDES context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_TDES_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_TDES_CBC_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_TDES_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_TDES_CBC_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to TDES context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_TDES_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_TDES_OFB_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_TDES_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_TDES_OFB_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to TDES context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_TDES_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_TDES_CTR_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pCTR,
                                          unsigned   CTRIndex,
                                          unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_TDES_CTR_0_8_Encrypt()

Description

Encrypt, CTR(0,8) mode.

Prototype

void CRYPTO_CIPHER_TDES_CTR_0_8_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…7].

CRYPTO_CIPHER_TDES_CTR_4_4_Encrypt()

Description

Encrypt, CTR(4,4) mode.

Prototype

void CRYPTO_CIPHER_TDES_CTR_4_4_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[4…7].

CRYPTO_CIPHER_TDES_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_TDES_CTR_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pCTR,
                                          unsigned   CTRIndex,
                                          unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_TDES_CTR_0_8_Decrypt()

Description

Decrypt, CTR(0,8) mode.

Prototype

void CRYPTO_CIPHER_TDES_CTR_0_8_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…7].

CRYPTO_CIPHER_TDES_CTR_4_4_Decrypt()

Description

Decrypt, CTR(4,4) mode.

Prototype

void CRYPTO_CIPHER_TDES_CTR_4_4_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to TDES context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[4…7].

Self-test API

The following table lists the TDES self-test API functions.

Function	Description
CRYPTO_TDES_ECB_CAVS_SelfTest()	Run CAVS TDES self-test.
CRYPTO_TDES_CBC_CAVS_SelfTest()	Run CAVS TDES self-test.

CRYPTO_TDES_ECB_CAVS_SelfTest()

Description

Run CAVS TDES self-test.

Prototype

void CRYPTO_TDES_ECB_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_TDES_CBC_CAVS_SelfTest()

Description

Run CAVS TDES self-test.

Prototype

void CRYPTO_TDES_CBC_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

AES

Standards reference

AES is specified by the following document:

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

Algorithm parameters

Block size

#define CRYPTO_AES_BLOCK_SIZE    16

The number of bytes in a single AES block.

Key size

#define CRYPTO_AES128_KEY_SIZE   16
#define CRYPTO_AES192_KEY_SIZE   24
#define CRYPTO_AES256_KEY_SIZE   32

The number of bytes for each of the supported key sizes.

Configuration and resource use

Default

#define CRYPTO_CONFIG_AES_OPTIMIZE     2

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize AES to use tables for matrix multiplication. Optimization levels are 0 through 7 with larger numbers generally producing better performance.

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.24 KB	Flash	2.0 KB	3.2 KB		5.2 KB
1	0.24 KB	Flash	2.0 KB	2.7 KB		4.7 KB
2	0.24 KB	Flash	8.5 KB	2.4 KB		10.9 KB
3	0.24 KB	Flash	1.9 KB	12.5 KB		14.4 KB
4	0.24 KB	RAM	2.0 KB	3.2 KB		5.2 KB
5	0.24 KB	RAM	2.0 KB	2.7 KB		4.7 KB
6	0.24 KB	RAM	8.5 KB	2.4 KB		10.9 KB
7	0.24 KB	RAM	1.9 KB	12.5 KB		14.4 KB

Hardware acceleration

The following processors provide hardware acceleration for AES:

• NXP LPC18Sxx and LPC43Sxx, see LPC18S and LPC43S AES ROM (Add-on).
• NXP Kinetis, see Kinetis CAU coprocessor (Add-on).
• STMicroelectronics STM32F4 and STM32F7, see STM32 CRYP coprocessor (Add-on).
• STMicroelectronics STM32L4 see STM32 AES coprocessor (Add-on).
• EFM32 Pearl and Jade Gecko, see EFM32 CRYPTO coprocessor (Add-on).

Type-safe API

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

Function	Description
Installation and hardware assist
CRYPTO_AES_Install()	Install cipher.
CRYPTO_AES_IsInstalled()	Query whether cipher is installed.
CRYPTO_AES_QueryInstall()	Query installed cipher.
Setup
CRYPTO_AES_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_AES_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_AES_Kill()	Clear AES context.
Single-block AES
CRYPTO_AES_Encrypt()	Encrypt block.
CRYPTO_AES_Decrypt()	Decrypt block.
Basic cipher modes
CRYPTO_AES_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_AES_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_AES_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_AES_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_AES_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_AES_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_AES_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_AES_CTR_Decrypt()	Decrypt, CTR mode.
AEAD modes
CRYPTO_AES_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_AES_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_AES_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_AES_GCM_Decrypt()	Decrypt, GCM mode.
Incremental AES-GCM
CRYPTO_AES_GCM_InitEncrypt()	Initialize AES-GCM incremental encryption.
CRYPTO_AES_GCM_InitDecrypt()	Initialize AES-GCM incremental decryption.
CRYPTO_AES_GCM_AddAAD()	Add additional authenticated data.
CRYPTO_AES_GCM_AddAADDone()	Flag all additional authenticated data added.
CRYPTO_AES_GCM_Add()	Add data.
CRYPTO_AES_GCM_AddDone()	Flag all data added.
CRYPTO_AES_GCM_ExitEncrypt()	Finalize AES-GCM incremental encryption.
CRYPTO_AES_GCM_ExitDecrypt()	Finalize AES-GCM incremental decryption.

CRYPTO_AES_Install()

Description

Install cipher.

Prototype

void CRYPTO_AES_Install(const CRYPTO_CIPHER_API * pHWAPI,
                        const CRYPTO_CIPHER_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_AES_IsInstalled()

Description

Query whether cipher is installed.

Prototype

int CRYPTO_AES_IsInstalled(void);

Return value

= 0	Cipher is not installed.
≠ 0	Cipher is installed.

CRYPTO_AES_QueryInstall()

Description

Query installed cipher.

Prototype

void CRYPTO_AES_QueryInstall(const CRYPTO_CIPHER_API ** ppHWAPI,
                             const CRYPTO_CIPHER_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the pointer to the preferred API.
ppSWAPI	Pointer to object that receives the pointer to the fallback API.

CRYPTO_AES_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_AES_InitEncrypt(      CRYPTO_AES_CONTEXT * pSelf,
                            const U8                 * pKey,
                                  unsigned             KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_AES_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_AES_InitDecrypt(      CRYPTO_AES_CONTEXT * pSelf,
                            const U8                 * pKey,
                                  unsigned             KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_AES_Kill()

Description

Clear AES context.

Prototype

void CRYPTO_AES_Kill(CRYPTO_AES_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.

CRYPTO_AES_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_AES_Encrypt(      CRYPTO_AES_CONTEXT * pSelf,
                              U8                 * pOutput,
                        const U8                 * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_AES_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_AES_Decrypt(      CRYPTO_AES_CONTEXT * pSelf,
                              U8                 * pOutput,
                        const U8                 * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_AES_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_AES_ECB_Encrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen);

Parameters

Parameter	Description
pSelf	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_AES_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_AES_ECB_Decrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen);

Parameters

Parameter	Description
pSelf	Pointer to AES context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_AES_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_AES_CBC_Encrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pIV);

Parameters

Parameter	Description
pSelf	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_AES_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_AES_CBC_Decrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pIV);

Parameters

Parameter	Description
pSelf	Pointer to AES context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_AES_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_AES_OFB_Encrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pIV);

Parameters

Parameter	Description
pSelf	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_AES_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_AES_OFB_Decrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pIV);

Parameters

Parameter	Description
pSelf	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_AES_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_AES_CTR_Encrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pCTR,
                                  unsigned             CTRIndex,
                                  unsigned             CTRLen);

Parameters

Parameter	Description
pSelf	Initialized AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_AES_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_AES_CTR_Decrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pCTR,
                                  unsigned             CTRIndex,
                                  unsigned             CTRLen);

Parameters

Parameter	Description
pSelf	Initialized AES context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_AES_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_AES_CCM_Encrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                  U8                 * pOutput,
                                  U8                 * pTag,
                                  unsigned             TagLen,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                            const U8                 * pAAD,
                                  unsigned             AADLen,
                            const U8                 * pIV,
                                  unsigned             IVLen);

Parameters

Parameter	Description
pSelf	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_AES_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_AES_CCM_Decrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                 U8                 * pOutput,
                           const U8                 * pTag,
                                 unsigned             TagLen,
                           const U8                 * pInput,
                                 unsigned             InputLen,
                           const U8                 * pAAD,
                                 unsigned             AADLen,
                           const U8                 * pIV,
                                 unsigned             IVLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_AES_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_AES_GCM_Encrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                  U8                 * pOutput,
                                  U8                 * pTag,
                                  unsigned             TagLen,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                            const U8                 * pAAD,
                                  unsigned             AADLen,
                            const U8                 * pIV,
                                  unsigned             IVLen);

Parameters

Parameter	Description
pSelf	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the initialization vector.

CRYPTO_AES_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_AES_GCM_Decrypt(      CRYPTO_AES_CONTEXT * pSelf,
                                 U8                 * pOutput,
                           const U8                 * pTag,
                                 unsigned             TagLen,
                           const U8                 * pInput,
                                 unsigned             InputLen,
                           const U8                 * pAAD,
                                 unsigned             AADLen,
                           const U8                 * pIV,
                                 unsigned             IVLen);

Parameters

Parameter	Description
pSelf	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_AES_GCM_InitEncrypt()

Description

Initialize AES-GCM incremental encryption.

Prototype

void CRYPTO_AES_GCM_InitEncrypt(      CRYPTO_AES_GCM_CONTEXT * pSelf,
                                const U8                     * pKey,
                                      unsigned                 KeyLen,
                                const U8                     * pIV,
                                      unsigned                 IVLen);

Parameters

Parameter	Description
pSelf	Pointer to AES-GCM cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

Additional information

The flow to encrypt data is as follows:

• Call CRYPTO_AES_GCM_InitEncrypt() to initialize the context.
• Optionally call CRYPTO_AES_GCM_AddAAD() to add any authentication data.
• Call CRYPTO_AES_GCM_AddAADDone() to indicate authentication data added.
• Optionally call CRYPTO_AES_GCM_Add() to add data to encrypt.
• Call CRYPTO_AES_GCM_AddDone() to indicate data added.
• Call CRYPTO_AES_GCM_ExitEncrypt() to retrieve the authentication tag.

CRYPTO_AES_GCM_InitDecrypt()

Description

Initialize AES-GCM incremental decryption.

Prototype

void CRYPTO_AES_GCM_InitDecrypt(      CRYPTO_AES_GCM_CONTEXT * pSelf,
                                const U8                     * pKey,
                                      unsigned                 KeyLen,
                                const U8                     * pIV,
                                      unsigned                 IVLen);

Parameters

Parameter	Description
pSelf	Pointer to AES-GCM cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

Additional information

The flow to decrypt data is as follows:

• Call CRYPTO_AES_GCM_InitDecrypt() to initialize the context.
• Optionally call CRYPTO_AES_GCM_AddAAD() to add any authentication data.
• Call CRYPTO_AES_GCM_AddAADDone() to indicate authentication data added.
• Optionally call CRYPTO_AES_GCM_Add() to add data to decrypt.
• Call CRYPTO_AES_GCM_AddDone() to indicate data added.
• Call CRYPTO_AES_GCM_ExitDecrypt() to verify the authentication tag.

CRYPTO_AES_GCM_AddAAD()

Description

Add additional authenticated data.

Prototype

void CRYPTO_AES_GCM_AddAAD(      CRYPTO_AES_GCM_CONTEXT * pSelf,
                           const U8                     * pAAD,
                                 unsigned                 AADLen);

Parameters

Parameter	Description
pSelf	Pointer to AES-GCM cipher context.
pAAD	Pointer to authenticated data to add.
AADLen	Octet length of the authenticated data to add.

Additional information

CRYPTO_AES_GCM_AddAAD() can be called multiple times to incrementally add authenticated data.

CRYPTO_AES_GCM_AddAADDone()

Description

Flag all additional authenticated data added.

Prototype

void CRYPTO_AES_GCM_AddAADDone(CRYPTO_AES_GCM_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to AES-GCM cipher context.

CRYPTO_AES_GCM_Add()

Description

Add data.

Prototype

unsigned CRYPTO_AES_GCM_Add(      CRYPTO_AES_GCM_CONTEXT * pSelf,
                                  U8                     * pOutput,
                            const U8                     * pInput,
                                  unsigned                 InputLen);

Parameters

Parameter	Description
pSelf	Pointer to AES-GCM cipher context.
pOutput	Pointer to object which receives the ciphered data.
pInput	Pointer to input data.
InputLen	Octet length of the input data.

Return value

Number of ciphered octets written to the object pointed to by pOutput.

Additional information

CRYPTO_AES_GCM_Add() can be called multiple times to incrementally add data.

CRYPTO_AES_GCM_AddDone()

Description

Flag all data added.

Prototype

unsigned CRYPTO_AES_GCM_AddDone(CRYPTO_AES_GCM_CONTEXT * pSelf,
                                U8                     * pOutput);

Parameters

Parameter	Description
pSelf	Pointer to AES-GCM cipher context.
pOutput	Pointer to object which receives residual ciphered data.

Return value

Number of ciphered octets written to the object pointed to by pOutput.

CRYPTO_AES_GCM_ExitEncrypt()

Description

Finalize AES-GCM incremental encryption.

Prototype

void CRYPTO_AES_GCM_ExitEncrypt(CRYPTO_AES_GCM_CONTEXT * pSelf,
                                U8                     * pTag,
                                unsigned                 TagLen);

Parameters

Parameter	Description
pSelf	Pointer to AES-GCM cipher context.
pTag	Pointer to object that receives the tag calculated over data.
TagLen	Octet length of the authentication tag.

CRYPTO_AES_GCM_ExitDecrypt()

Description

Finalize AES-GCM incremental decryption.

Prototype

int CRYPTO_AES_GCM_ExitDecrypt(      CRYPTO_AES_GCM_CONTEXT * pSelf,
                               const U8                     * pTag,
                                     unsigned                 TagLen);

Parameters

Parameter	Description
pSelf	Pointer to AES-GCM cipher context.
pTag	Pointer to object that contains the tag calculated over data.
TagLen	Octet length of the authentication tag.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Generic API

The following table lists the AES functions that conform to the generic cipher API.

Function	Description
Setup
CRYPTO_CIPHER_AES_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CIPHER_AES_128_InitEncrypt()	Initialize, encrypt mode, 128-bit key.
CRYPTO_CIPHER_AES_192_InitEncrypt()	Initialize, encrypt mode, 192-bit key.
CRYPTO_CIPHER_AES_256_InitEncrypt()	Initialize, encrypt mode, 256-bit key.
CRYPTO_CIPHER_AES_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CIPHER_AES_128_InitDecrypt()	Initialize, decrypt mode, 128-bit key.
CRYPTO_CIPHER_AES_192_InitDecrypt()	Initialize, decrypt mode, 192-bit key.
CRYPTO_CIPHER_AES_256_InitDecrypt()	Initialize, decrypt mode, 256-bit key.
Basic cipher modes
CRYPTO_CIPHER_AES_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_AES_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_AES_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_AES_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_AES_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_AES_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_AES_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_AES_CTR_0_16_Encrypt()	Encrypt, CTR(0,16) mode.
CRYPTO_CIPHER_AES_CTR_12_4_Encrypt()	Encrypt, CTR(12,4) mode.
CRYPTO_CIPHER_AES_CTR_Decrypt()	Decrypt, CTR mode.
CRYPTO_CIPHER_AES_CTR_0_16_Decrypt()	Decrypt, CTR(0,16) mode.
CRYPTO_CIPHER_AES_CTR_12_4_Decrypt()	Decrypt, CTR(12,4) mode.
AEAD modes
CRYPTO_CIPHER_AES_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_CIPHER_AES_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_CIPHER_AES_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_CIPHER_AES_GCM_Decrypt()	Decrypt, GCM mode.

CRYPTO_CIPHER_AES_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CIPHER_AES_InitEncrypt(      void     * pContext,
                                   const U8       * pKey,
                                         unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to AES context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_AES_128_InitEncrypt()

Description

Initialize, encrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_AES_128_InitEncrypt(      void * pContext,
                                       const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to AES context.
pKey	Pointer to key.

CRYPTO_CIPHER_AES_192_InitEncrypt()

Description

Initialize, encrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_AES_192_InitEncrypt(      void * pContext,
                                       const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to AES context.
pKey	Pointer to key.

CRYPTO_CIPHER_AES_256_InitEncrypt()

Description

Initialize, encrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_AES_256_InitEncrypt(      void * pContext,
                                       const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to AES context.
pKey	Pointer to key.

CRYPTO_CIPHER_AES_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CIPHER_AES_InitDecrypt(      void     * pContext,
                                   const U8       * pKey,
                                         unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to AES context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_AES_128_InitDecrypt()

Description

Initialize, decrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_AES_128_InitDecrypt(      void * pContext,
                                       const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to AES context.
pKey	Pointer to key.

CRYPTO_CIPHER_AES_192_InitDecrypt()

Description

Initialize, decrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_AES_192_InitDecrypt(      void * pContext,
                                       const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to AES context.
pKey	Pointer to key.

CRYPTO_CIPHER_AES_256_InitDecrypt()

Description

Initialize, decrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_AES_256_InitDecrypt(      void * pContext,
                                       const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to AES context.
pKey	Pointer to key.

CRYPTO_CIPHER_AES_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CIPHER_AES_Encrypt(      void * pContext,
                                     U8   * pOutput,
                               const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to AES context.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CIPHER_AES_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CIPHER_AES_Decrypt(      void * pContext,
                                     U8   * pOutput,
                               const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to AES context.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CIPHER_AES_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_AES_ECB_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_AES_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_AES_ECB_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to AES context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_AES_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_AES_CBC_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_AES_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_AES_CBC_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to AES context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_AES_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_AES_OFB_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_AES_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_AES_OFB_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to AES context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_AES_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_AES_CTR_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pCTR,
                                         unsigned   CTRIndex,
                                         unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_AES_CTR_0_16_Encrypt()

Description

Encrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_AES_CTR_0_16_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_AES_CTR_12_4_Encrypt()

Description

Encrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_AES_CTR_12_4_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_AES_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_AES_CTR_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pCTR,
                                         unsigned   CTRIndex,
                                         unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_AES_CTR_0_16_Decrypt()

Description

Decrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_AES_CTR_0_16_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_AES_CTR_12_4_Decrypt()

Description

Decrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_AES_CTR_12_4_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_AES_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_CIPHER_AES_CCM_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                         U8       * pTag,
                                         unsigned   TagLen,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                   const U8       * pAAD,
                                         unsigned   AADLen,
                                   const U8       * pIV,
                                         unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_CIPHER_AES_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_CIPHER_AES_CCM_Decrypt(      void     * pContext,
                                        U8       * pOutput,
                                  const U8       * pTag,
                                        unsigned   TagLen,
                                  const U8       * pInput,
                                        unsigned   InputLen,
                                  const U8       * pAAD,
                                        unsigned   AADLen,
                                  const U8       * pIV,
                                        unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_CIPHER_AES_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_CIPHER_AES_GCM_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                         U8       * pTag,
                                         unsigned   TagLen,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                   const U8       * pAAD,
                                         unsigned   AADLen,
                                   const U8       * pIV,
                                         unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the encrypted data.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_CIPHER_AES_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_CIPHER_AES_GCM_Decrypt(      void     * pContext,
                                        U8       * pOutput,
                                  const U8       * pTag,
                                        unsigned   TagLen,
                                  const U8       * pInput,
                                        unsigned   InputLen,
                                  const U8       * pAAD,
                                        unsigned   AADLen,
                                  const U8       * pIV,
                                        unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to AES context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted input.
InputLen	Octet length of encrypted input.
pAAD	Pointer to additional data to be authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Self-test API

The following table lists the AES self-test API functions.

Function	Description
CRYPTO_AES_128_CBC_CAVS_SelfTest()	Run CAVS AES-128 self-test.
CRYPTO_AES_192_CBC_CAVS_SelfTest()	Run CAVS AES-192 self-test.
CRYPTO_AES_256_CBC_CAVS_SelfTest()	Run CAVS AES-256 self-test.
CRYPTO_AES_128_ECB_CAVS_SelfTest()	Run CAVS AES-128 self-test.
CRYPTO_AES_192_ECB_CAVS_SelfTest()	Run CAVS AES-192 self-test.
CRYPTO_AES_256_ECB_CAVS_SelfTest()	Run CAVS AES-256 self-test.
CRYPTO_AES_RFC3602_SelfTest()	Run AES KATs from RFC 3602.
CRYPTO_AES_128_CCM_CAVS_SelfTest()	Run CAVS AES-128 self-test.
CRYPTO_AES_192_CCM_CAVS_SelfTest()	Run CAVS AES-192 self-test.
CRYPTO_AES_256_CCM_CAVS_SelfTest()	Run CAVS AES-256 self-test.
CRYPTO_AES_128_GCM_CAVS_SelfTest()	Run CAVS AES-128 self-test.
CRYPTO_AES_192_GCM_CAVS_SelfTest()	Run CAVS AES-192 self-test.
CRYPTO_AES_256_GCM_CAVS_SelfTest()	Run CAVS AES-256 self-test.
CRYPTO_AES_CCM_SP800x38C_SelfTest()	Run AES-CCM KATs from SP 800-38C.

CRYPTO_AES_128_CBC_CAVS_SelfTest()

Description

Run CAVS AES-128 self-test.

Prototype

void CRYPTO_AES_128_CBC_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_192_CBC_CAVS_SelfTest()

Description

Run CAVS AES-192 self-test.

Prototype

void CRYPTO_AES_192_CBC_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_256_CBC_CAVS_SelfTest()

Description

Run CAVS AES-256 self-test.

Prototype

void CRYPTO_AES_256_CBC_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_128_ECB_CAVS_SelfTest()

Description

Run CAVS AES-128 self-test.

Prototype

void CRYPTO_AES_128_ECB_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_192_ECB_CAVS_SelfTest()

Description

Run CAVS AES-192 self-test.

Prototype

void CRYPTO_AES_192_ECB_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_256_ECB_CAVS_SelfTest()

Description

Run CAVS AES-256 self-test.

Prototype

void CRYPTO_AES_256_ECB_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_128_CCM_CAVS_SelfTest()

Description

Run CAVS AES-128 self-test.

Prototype

void CRYPTO_AES_128_CCM_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_192_CCM_CAVS_SelfTest()

Description

Run CAVS AES-192 self-test.

Prototype

void CRYPTO_AES_192_CCM_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_256_CCM_CAVS_SelfTest()

Description

Run CAVS AES-256 self-test.

Prototype

void CRYPTO_AES_256_CCM_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_CCM_SP800x38C_SelfTest()

Description

Run AES-CCM KATs from SP 800-38C.

Prototype

void CRYPTO_AES_CCM_SP800x38C_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_128_GCM_CAVS_SelfTest()

Description

Run CAVS AES-128 self-test.

Prototype

void CRYPTO_AES_128_GCM_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_192_GCM_CAVS_SelfTest()

Description

Run CAVS AES-192 self-test.

Prototype

void CRYPTO_AES_192_GCM_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_256_GCM_CAVS_SelfTest()

Description

Run CAVS AES-256 self-test.

Prototype

void CRYPTO_AES_256_GCM_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_AES_RFC3602_SelfTest()

Description

Run AES KATs from RFC 3602.

Prototype

void CRYPTO_AES_RFC3602_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

IDEA

Algorithm parameters

Block size

#define CRYPTO_IDEA_BLOCK_SIZE    8

The number of bytes in a single IDEA block.

Key size

#define CRYPTO_IDEA_KEY_SIZE      16

The number of bytes for the single the supported key size.

Type-safe API

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

Function	Description
Installation and hardware assist
CRYPTO_IDEA_Install()	Install cipher.
CRYPTO_IDEA_IsInstalled()	Query whether cipher is installed.
CRYPTO_IDEA_QueryInstall()	Query installed cipher.
Setup
CRYPTO_IDEA_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_IDEA_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_IDEA_Kill()	Clear IDEA context.
Single blocks
CRYPTO_IDEA_Encrypt()	Encrypt block.
CRYPTO_IDEA_Decrypt()	Decrypt block.
Basic modes
CRYPTO_IDEA_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_IDEA_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_IDEA_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_IDEA_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_IDEA_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_IDEA_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_IDEA_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_IDEA_CTR_Decrypt()	Decrypt, CTR mode.

CRYPTO_IDEA_Install()

Description

Install cipher.

Prototype

void CRYPTO_IDEA_Install(const CRYPTO_CIPHER_API * pHWAPI,
                         const CRYPTO_CIPHER_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_IDEA_IsInstalled()

Description

Query whether cipher is installed.

Prototype

int CRYPTO_IDEA_IsInstalled(void);

Return value

= 0	Cipher is not installed.
≠ 0	Cipher is installed.

CRYPTO_IDEA_QueryInstall()

Description

Query installed cipher.

Prototype

void CRYPTO_IDEA_QueryInstall(const CRYPTO_CIPHER_API ** ppHWAPI,
                              const CRYPTO_CIPHER_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the pointer to the preferred API.
ppSWAPI	Pointer to object that receives the pointer to the fallback API.

CRYPTO_IDEA_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_IDEA_InitEncrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                             const U8                  * pKey,
                                   unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_IDEA_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_IDEA_InitDecrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                             const U8                  * pKey,
                                   unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_IDEA_Kill()

Description

Clear IDEA context.

Prototype

void CRYPTO_IDEA_Kill(CRYPTO_IDEA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.

CRYPTO_IDEA_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_IDEA_Encrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                               U8                  * pOutput,
                         const U8                  * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_IDEA_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_IDEA_Decrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                               U8                  * pOutput,
                         const U8                  * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_IDEA_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_IDEA_ECB_Encrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen);

Parameters

Parameter	Description
pSelf	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_IDEA_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_IDEA_ECB_Decrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen);

Parameters

Parameter	Description
pSelf	Pointer to IDEA context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_IDEA_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_IDEA_CBC_Encrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_IDEA_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_IDEA_CBC_Decrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to IDEA context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_IDEA_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_IDEA_CTR_Encrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pCTR,
                                   unsigned              CTRIndex,
                                   unsigned              CTRLen);

Parameters

Parameter	Description
pSelf	Initialized IDEA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_IDEA_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_IDEA_CTR_Decrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pCTR,
                                   unsigned              CTRIndex,
                                   unsigned              CTRLen);

Parameters

Parameter	Description
pSelf	Initialized IDEA context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_IDEA_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_IDEA_OFB_Encrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_IDEA_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_IDEA_OFB_Decrypt(      CRYPTO_IDEA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

Generic API

The following table lists the IDEA functions that conform to the generic cipher API.

Function	Description
Setup
CRYPTO_CIPHER_IDEA_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CIPHER_IDEA_128_InitEncrypt()	Initialize, encrypt mode, 128-bit key.
CRYPTO_CIPHER_IDEA_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CIPHER_IDEA_128_InitDecrypt()	Initialize, decrypt mode, 128-bit key.
Basic modes
CRYPTO_CIPHER_IDEA_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_IDEA_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_IDEA_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_IDEA_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_IDEA_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_IDEA_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_IDEA_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_IDEA_CTR_0_8_Encrypt()	Encrypt, CTR(0,8) mode.
CRYPTO_CIPHER_IDEA_CTR_4_4_Encrypt()	Encrypt, CTR(4,4) mode.
CRYPTO_CIPHER_IDEA_CTR_Decrypt()	Decrypt, CTR mode.
CRYPTO_CIPHER_IDEA_CTR_0_8_Decrypt()	Decrypt, CTR(0,8) mode.
CRYPTO_CIPHER_IDEA_CTR_4_4_Decrypt()	Decrypt, CTR(4,4) mode.

CRYPTO_CIPHER_IDEA_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CIPHER_IDEA_InitEncrypt(      void     * pContext,
                                    const U8       * pKey,
                                          unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to IDEA context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_IDEA_128_InitEncrypt()

Description

Initialize, encrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_IDEA_128_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to IDEA context.
pKey	Pointer to key.

CRYPTO_CIPHER_IDEA_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CIPHER_IDEA_InitDecrypt(      void     * pContext,
                                    const U8       * pKey,
                                          unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to IDEA context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_IDEA_128_InitDecrypt()

Description

Initialize, decrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_IDEA_128_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to IDEA context.
pKey	Pointer to key.

CRYPTO_CIPHER_IDEA_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CIPHER_IDEA_Encrypt(      void * pContext,
                                      U8   * pOutput,
                                const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to IDEA context.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CIPHER_IDEA_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CIPHER_IDEA_Decrypt(      void * pContext,
                                      U8   * pOutput,
                                const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to IDEA context.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CIPHER_IDEA_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_IDEA_ECB_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_IDEA_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_IDEA_ECB_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_IDEA_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_IDEA_CBC_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_IDEA_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_IDEA_CBC_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_IDEA_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_IDEA_OFB_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_IDEA_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_IDEA_OFB_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_IDEA_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_IDEA_CTR_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pCTR,
                                          unsigned   CTRIndex,
                                          unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_IDEA_CTR_0_8_Encrypt()

Description

Encrypt, CTR(0,8) mode.

Prototype

void CRYPTO_CIPHER_IDEA_CTR_0_8_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…7].

CRYPTO_CIPHER_IDEA_CTR_4_4_Encrypt()

Description

Encrypt, CTR(4,4) mode.

Prototype

void CRYPTO_CIPHER_IDEA_CTR_4_4_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[4…7].

CRYPTO_CIPHER_IDEA_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_IDEA_CTR_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pCTR,
                                          unsigned   CTRIndex,
                                          unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_IDEA_CTR_0_8_Decrypt()

Description

Decrypt, CTR(0,8) mode.

Prototype

void CRYPTO_CIPHER_IDEA_CTR_0_8_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…7].

CRYPTO_CIPHER_IDEA_CTR_4_4_Decrypt()

Description

Decrypt, CTR(4,4) mode.

Prototype

void CRYPTO_CIPHER_IDEA_CTR_4_4_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to IDEA context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[4…7].

Self-test API

The following table lists the IDEA self-test API functions.

Function	Description
CRYPTO_IDEA_Ascom_SelfTest()	Run IDEA KATs from Ascom.

CRYPTO_IDEA_Ascom_SelfTest()

Description

Run IDEA KATs from Ascom.

Prototype

void CRYPTO_IDEA_Ascom_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

SEED

Standards reference

SEED is specified by the following document:

• IETF RFC 4269 — The SEED Encryption Algorithm

Algorithm parameters

Block size

#define CRYPTO_SEED_BLOCK_SIZE    16

The number of bytes in a single SEED block.

Key size

#define CRYPTO_SEED_KEY_SIZE      16

The number of bytes for the single the supported key size.

Configuration and resource use

Default

#define CRYPTO_CONFIG_SEED_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize SEED to place tables in RAM rather than flash and to optimized the table sizes. Optimization levels are 0 through 3 with larger numbers generally producing better performance.

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.14 KB	Flash	0.5 KB	0.5 KB		1.0 KB
1	0.14 KB	Flash	4.0 KB	0.4 KB		4.4 KB
2	0.14 KB	RAM	0.5 KB	0.5 KB		1.0 KB
3	0.14 KB	RAM	4.0 KB	0.4 KB		4.4 KB

Type-safe API

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

Function	Description
Installation and hardware assist
CRYPTO_SEED_Install()	Install cipher.
CRYPTO_SEED_IsInstalled()	Query whether cipher is installed.
CRYPTO_SEED_QueryInstall()	Query installed cipher.
Setup
CRYPTO_SEED_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_SEED_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_SEED_Kill()	Clear SEED context.
Single blocks
CRYPTO_SEED_Encrypt()	Encrypt block.
CRYPTO_SEED_Decrypt()	Decrypt block.
Basic modes
CRYPTO_SEED_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_SEED_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_SEED_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_SEED_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_SEED_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_SEED_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_SEED_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_SEED_CTR_Decrypt()	Decrypt, CTR mode.
AEAD modes
CRYPTO_SEED_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_SEED_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_SEED_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_SEED_GCM_Decrypt()	Decrypt, GCM mode.

CRYPTO_SEED_Install()

Description

Install cipher.

Prototype

void CRYPTO_SEED_Install(const CRYPTO_CIPHER_API * pHWAPI,
                         const CRYPTO_CIPHER_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_SEED_IsInstalled()

Description

Query whether cipher is installed.

Prototype

int CRYPTO_SEED_IsInstalled(void);

Return value

= 0	Cipher is not installed.
≠ 0	Cipher is installed.

CRYPTO_SEED_QueryInstall()

Description

Query installed cipher.

Prototype

void CRYPTO_SEED_QueryInstall(const CRYPTO_CIPHER_API ** ppHWAPI,
                              const CRYPTO_CIPHER_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the pointer to the preferred API.
ppSWAPI	Pointer to object that receives the pointer to the fallback API.

CRYPTO_SEED_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_SEED_InitEncrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                             const U8                  * pKey,
                                   unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_SEED_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_SEED_InitDecrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                             const U8                  * pKey,
                                   unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_SEED_Kill()

Description

Clear SEED context.

Prototype

void CRYPTO_SEED_Kill(CRYPTO_SEED_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.

CRYPTO_SEED_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_SEED_Encrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                               U8                  * pOutput,
                         const U8                  * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_SEED_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_SEED_Decrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                               U8                  * pOutput,
                         const U8                  * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_SEED_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_SEED_ECB_Encrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen);

Parameters

Parameter	Description
pSelf	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_SEED_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_SEED_ECB_Decrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen);

Parameters

Parameter	Description
pSelf	Pointer to SEED context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_SEED_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_SEED_CBC_Encrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_SEED_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_SEED_CBC_Decrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to SEED context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_SEED_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_SEED_CTR_Encrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pCTR,
                                   unsigned              CTRIndex,
                                   unsigned              CTRLen);

Parameters

Parameter	Description
pSelf	Initialized SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_SEED_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_SEED_CTR_Decrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pCTR,
                                   unsigned              CTRIndex,
                                   unsigned              CTRLen);

Parameters

Parameter	Description
pSelf	Initialized SEED context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_SEED_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_SEED_OFB_Encrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_SEED_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_SEED_OFB_Decrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_SEED_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_SEED_CCM_Encrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                   U8                  * pOutput,
                                   U8                  * pTag,
                                   unsigned              TagLen,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                             const U8                  * pAAD,
                                   unsigned              AADLen,
                             const U8                  * pIV,
                                   unsigned              IVLen);

Parameters

Parameter	Description
pSelf	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_SEED_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_SEED_CCM_Decrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                  U8                  * pOutput,
                            const U8                  * pTag,
                                  unsigned              TagLen,
                            const U8                  * pInput,
                                  unsigned              InputLen,
                            const U8                  * pAAD,
                                  unsigned              AADLen,
                            const U8                  * pIV,
                                  unsigned              IVLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_SEED_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_SEED_GCM_Encrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                   U8                  * pOutput,
                                   U8                  * pTag,
                                   unsigned              TagLen,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                             const U8                  * pAAD,
                                   unsigned              AADLen,
                             const U8                  * pIV,
                                   unsigned              IVLen);

Parameters

Parameter	Description
pSelf	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the initialization vector.

CRYPTO_SEED_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_SEED_GCM_Decrypt(      CRYPTO_SEED_CONTEXT * pSelf,
                                  U8                  * pOutput,
                            const U8                  * pTag,
                                  unsigned              TagLen,
                            const U8                  * pInput,
                                  unsigned              InputLen,
                            const U8                  * pAAD,
                                  unsigned              AADLen,
                            const U8                  * pIV,
                                  unsigned              IVLen);

Parameters

Parameter	Description
pSelf	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Generic API

The following table lists the SEED functions that conform to the generic cipher API.

Function	Description
Setup
CRYPTO_CIPHER_SEED_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CIPHER_SEED_128_InitEncrypt()	Initialize, encrypt mode, 128-bit key.
CRYPTO_CIPHER_SEED_192_InitEncrypt()	Initialize, encrypt mode, 192-bit key.
CRYPTO_CIPHER_SEED_256_InitEncrypt()	Initialize, encrypt mode, 256-bit key.
CRYPTO_CIPHER_SEED_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CIPHER_SEED_128_InitDecrypt()	Initialize, decrypt mode, 128-bit key.
CRYPTO_CIPHER_SEED_192_InitDecrypt()	Initialize, decrypt mode, 192-bit key.
CRYPTO_CIPHER_SEED_256_InitDecrypt()	Initialize, decrypt mode, 256-bit key.
Basic modes
CRYPTO_CIPHER_SEED_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_SEED_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_SEED_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_SEED_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_SEED_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_SEED_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_SEED_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_SEED_CTR_0_16_Encrypt()	Encrypt, CTR(0,16) mode.
CRYPTO_CIPHER_SEED_CTR_12_4_Encrypt()	Encrypt, CTR(12,4) mode.
CRYPTO_CIPHER_SEED_CTR_Decrypt()	Decrypt, CTR mode.
CRYPTO_CIPHER_SEED_CTR_0_16_Decrypt()	Decrypt, CTR(0,16) mode.
CRYPTO_CIPHER_SEED_CTR_12_4_Decrypt()	Decrypt, CTR(12,4) mode.
AEAD modes
CRYPTO_CIPHER_SEED_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_CIPHER_SEED_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_CIPHER_SEED_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_CIPHER_SEED_GCM_Decrypt()	Decrypt, GCM mode.

CRYPTO_CIPHER_SEED_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CIPHER_SEED_InitEncrypt(      void     * pContext,
                                    const U8       * pKey,
                                          unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to SEED context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_SEED_128_InitEncrypt()

Description

Initialize, encrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_SEED_128_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to SEED context.
pKey	Pointer to key.

CRYPTO_CIPHER_SEED_192_InitDecrypt()

Description

Initialize, decrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_SEED_192_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to SEED context.
pKey	Pointer to key.

CRYPTO_CIPHER_SEED_256_InitEncrypt()

Description

Initialize, encrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_SEED_256_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to SEED context.
pKey	Pointer to key.

CRYPTO_CIPHER_SEED_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CIPHER_SEED_InitDecrypt(      void     * pContext,
                                    const U8       * pKey,
                                          unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to SEED context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_SEED_128_InitDecrypt()

Description

Initialize, decrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_SEED_128_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to SEED context.
pKey	Pointer to key.

CRYPTO_CIPHER_SEED_192_InitEncrypt()

Description

Initialize, encrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_SEED_192_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to SEED context.
pKey	Pointer to key.

CRYPTO_CIPHER_SEED_256_InitDecrypt()

Description

Initialize, decrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_SEED_256_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to SEED context.
pKey	Pointer to key.

CRYPTO_CIPHER_SEED_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CIPHER_SEED_Encrypt(      void * pContext,
                                      U8   * pOutput,
                                const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to SEED context.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CIPHER_SEED_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CIPHER_SEED_Decrypt(      void * pContext,
                                      U8   * pOutput,
                                const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to SEED context.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CIPHER_SEED_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_SEED_ECB_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_SEED_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_SEED_ECB_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to SEED context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_SEED_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_SEED_CBC_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_SEED_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_SEED_CBC_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to SEED context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_SEED_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_SEED_OFB_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_SEED_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_SEED_OFB_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to SEED context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_SEED_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_SEED_CTR_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pCTR,
                                          unsigned   CTRIndex,
                                          unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_SEED_CTR_0_16_Encrypt()

Description

Encrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_SEED_CTR_0_16_Encrypt(      void     * pContext,
                                               U8       * pOutput,
                                         const U8       * pInput,
                                               unsigned   InputLen,
                                               U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_SEED_CTR_12_4_Encrypt()

Description

Encrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_SEED_CTR_12_4_Encrypt(      void     * pContext,
                                               U8       * pOutput,
                                         const U8       * pInput,
                                               unsigned   InputLen,
                                               U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_SEED_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_SEED_CTR_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pCTR,
                                          unsigned   CTRIndex,
                                          unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_SEED_CTR_0_16_Decrypt()

Description

Decrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_SEED_CTR_0_16_Decrypt(      void     * pContext,
                                               U8       * pOutput,
                                         const U8       * pInput,
                                               unsigned   InputLen,
                                               U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_SEED_CTR_12_4_Decrypt()

Description

Decrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_SEED_CTR_12_4_Decrypt(      void     * pContext,
                                               U8       * pOutput,
                                         const U8       * pInput,
                                               unsigned   InputLen,
                                               U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_SEED_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_CIPHER_SEED_CCM_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                          U8       * pTag,
                                          unsigned   TagLen,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                    const U8       * pAAD,
                                          unsigned   AADLen,
                                    const U8       * pIV,
                                          unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_CIPHER_SEED_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_CIPHER_SEED_CCM_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pTag,
                                         unsigned   TagLen,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                   const U8       * pAAD,
                                         unsigned   AADLen,
                                   const U8       * pIV,
                                         unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_CIPHER_SEED_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_CIPHER_SEED_GCM_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                          U8       * pTag,
                                          unsigned   TagLen,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                    const U8       * pAAD,
                                          unsigned   AADLen,
                                    const U8       * pIV,
                                          unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the encrypted data.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_CIPHER_SEED_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_CIPHER_SEED_GCM_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pTag,
                                         unsigned   TagLen,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                   const U8       * pAAD,
                                         unsigned   AADLen,
                                   const U8       * pIV,
                                         unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to SEED context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted input.
InputLen	Octet length of encrypted input.
pAAD	Pointer to additional data to be authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Self-test API

The following table lists the SEED self-test API functions.

Function	Description
CRYPTO_SEED_RFC4269_SelfTest()	Run SEED KATs from RFC 4269.

CRYPTO_SEED_RFC4269_SelfTest()

Description

Run SEED KATs from RFC 4269.

Prototype

void CRYPTO_SEED_RFC4269_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

ARIA

Standards reference

ARIA is specified by the following document:

• IETF RFC 5794 — A Description of the ARIA Encryption Algorithm

Algorithm parameters

Block size

#define CRYPTO_ARIA_BLOCK_SIZE    16

The number of bytes in a single ARIA block.

Key size

#define CRYPTO_ARIA128_KEY_SIZE   16
#define CRYPTO_ARIA192_KEY_SIZE   24
#define CRYPTO_ARIA256_KEY_SIZE   32

The number of bytes for each of the supported key sizes.

Configuration and resource use

Default

#define CRYPTO_CONFIG_ARIA_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize ARIA to place tables in RAM rather than flash.

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.28 KB	Flash	1.0 KB	1.9 KB		2.9 KB
1	0.28 KB	RAM	1.0 KB	1.9 KB		2.9 KB

Type-safe API

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

Function	Description
Installation and hardware assist
CRYPTO_ARIA_Install()	Install cipher.
CRYPTO_ARIA_IsInstalled()	Query whether cipher is installed.
CRYPTO_ARIA_QueryInstall()	Query installed cipher.
Setup
CRYPTO_ARIA_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_ARIA_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_ARIA_Kill()	Clear ARIA context.
Single blocks
CRYPTO_ARIA_Encrypt()	Encrypt block.
CRYPTO_ARIA_Decrypt()	Decrypt block.
Basic modes
CRYPTO_ARIA_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_ARIA_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_ARIA_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_ARIA_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_ARIA_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_ARIA_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_ARIA_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_ARIA_CTR_Decrypt()	Decrypt, CTR mode.
AEAD modes
CRYPTO_ARIA_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_ARIA_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_ARIA_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_ARIA_GCM_Decrypt()	Decrypt, GCM mode.

CRYPTO_ARIA_Install()

Description

Install cipher.

Prototype

void CRYPTO_ARIA_Install(const CRYPTO_CIPHER_API * pHWAPI,
                         const CRYPTO_CIPHER_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_ARIA_IsInstalled()

Description

Query whether cipher is installed.

Prototype

int CRYPTO_ARIA_IsInstalled(void);

Return value

= 0	Cipher is not installed.
≠ 0	Cipher is installed.

CRYPTO_ARIA_QueryInstall()

Description

Query installed cipher.

Prototype

void CRYPTO_ARIA_QueryInstall(const CRYPTO_CIPHER_API ** ppHWAPI,
                              const CRYPTO_CIPHER_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the pointer to the preferred API.
ppSWAPI	Pointer to object that receives the pointer to the fallback API.

CRYPTO_ARIA_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_ARIA_InitEncrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                             const U8                  * pKey,
                                   unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_ARIA_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_ARIA_InitDecrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                             const U8                  * pKey,
                                   unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_ARIA_Kill()

Description

Clear ARIA context.

Prototype

void CRYPTO_ARIA_Kill(CRYPTO_ARIA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.

CRYPTO_ARIA_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_ARIA_Encrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                               U8                  * pOutput,
                         const U8                  * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_ARIA_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_ARIA_Decrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                               U8                  * pOutput,
                         const U8                  * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_ARIA_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_ARIA_ECB_Encrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen);

Parameters

Parameter	Description
pSelf	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_ARIA_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_ARIA_ECB_Decrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen);

Parameters

Parameter	Description
pSelf	Pointer to ARIA context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_ARIA_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_ARIA_CBC_Encrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_ARIA_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_ARIA_CBC_Decrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to ARIA context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_ARIA_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_ARIA_CTR_Encrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pCTR,
                                   unsigned              CTRIndex,
                                   unsigned              CTRLen);

Parameters

Parameter	Description
pSelf	Initialized ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_ARIA_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_ARIA_CTR_Decrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pCTR,
                                   unsigned              CTRIndex,
                                   unsigned              CTRLen);

Parameters

Parameter	Description
pSelf	Initialized ARIA context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_ARIA_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_ARIA_OFB_Encrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_ARIA_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_ARIA_OFB_Decrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_ARIA_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_ARIA_CCM_Encrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                                   U8                  * pTag,
                                   unsigned              TagLen,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                             const U8                  * pAAD,
                                   unsigned              AADLen,
                             const U8                  * pIV,
                                   unsigned              IVLen);

Parameters

Parameter	Description
pSelf	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_ARIA_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_ARIA_CCM_Decrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                  U8                  * pOutput,
                            const U8                  * pTag,
                                  unsigned              TagLen,
                            const U8                  * pInput,
                                  unsigned              InputLen,
                            const U8                  * pAAD,
                                  unsigned              AADLen,
                            const U8                  * pIV,
                                  unsigned              IVLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_ARIA_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_ARIA_GCM_Encrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                   U8                  * pOutput,
                                   U8                  * pTag,
                                   unsigned              TagLen,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                             const U8                  * pAAD,
                                   unsigned              AADLen,
                             const U8                  * pIV,
                                   unsigned              IVLen);

Parameters

Parameter	Description
pSelf	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the initialization vector.

CRYPTO_ARIA_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_ARIA_GCM_Decrypt(      CRYPTO_ARIA_CONTEXT * pSelf,
                                  U8                  * pOutput,
                            const U8                  * pTag,
                                  unsigned              TagLen,
                            const U8                  * pInput,
                                  unsigned              InputLen,
                            const U8                  * pAAD,
                                  unsigned              AADLen,
                            const U8                  * pIV,
                                  unsigned              IVLen);

Parameters

Parameter	Description
pSelf	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Generic API

The following table lists the ARIA functions that conform to the generic cipher API.

Function	Description
Setup
CRYPTO_CIPHER_ARIA_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CIPHER_ARIA_128_InitEncrypt()	Initialize, encrypt mode, 128-bit key.
CRYPTO_CIPHER_ARIA_192_InitEncrypt()	Initialize, encrypt mode, 192-bit key.
CRYPTO_CIPHER_ARIA_256_InitEncrypt()	Initialize, encrypt mode, 256-bit key.
CRYPTO_CIPHER_ARIA_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CIPHER_ARIA_128_InitDecrypt()	Initialize, decrypt mode, 128-bit key.
CRYPTO_CIPHER_ARIA_192_InitDecrypt()	Initialize, decrypt mode, 192-bit key.
CRYPTO_CIPHER_ARIA_256_InitDecrypt()	Initialize, decrypt mode, 256-bit key.
Basic modes
CRYPTO_CIPHER_ARIA_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_ARIA_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_ARIA_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_ARIA_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_ARIA_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_ARIA_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_ARIA_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_ARIA_CTR_0_16_Encrypt()	Encrypt, CTR(0,16) mode.
CRYPTO_CIPHER_ARIA_CTR_12_4_Encrypt()	Encrypt, CTR(12,4) mode.
CRYPTO_CIPHER_ARIA_CTR_Decrypt()	Decrypt, CTR mode.
CRYPTO_CIPHER_ARIA_CTR_0_16_Decrypt()	Decrypt, CTR(0,16) mode.
CRYPTO_CIPHER_ARIA_CTR_12_4_Decrypt()	Decrypt, CTR(12,4) mode.
AEAD modes
CRYPTO_CIPHER_ARIA_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_CIPHER_ARIA_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_CIPHER_ARIA_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_CIPHER_ARIA_GCM_Decrypt()	Decrypt, GCM mode.

CRYPTO_CIPHER_ARIA_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CIPHER_ARIA_InitEncrypt(      void     * pContext,
                                    const U8       * pKey,
                                          unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to ARIA context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_ARIA_128_InitEncrypt()

Description

Initialize, encrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_ARIA_128_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to ARIA context.
pKey	Pointer to key.

CRYPTO_CIPHER_ARIA_192_InitDecrypt()

Description

Initialize, decrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_ARIA_192_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to ARIA context.
pKey	Pointer to key.

CRYPTO_CIPHER_ARIA_256_InitEncrypt()

Description

Initialize, encrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_ARIA_256_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to ARIA context.
pKey	Pointer to key.

CRYPTO_CIPHER_ARIA_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CIPHER_ARIA_InitDecrypt(      void     * pContext,
                                    const U8       * pKey,
                                          unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to ARIA context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_ARIA_128_InitDecrypt()

Description

Initialize, decrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_ARIA_128_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to ARIA context.
pKey	Pointer to key.

CRYPTO_CIPHER_ARIA_192_InitEncrypt()

Description

Initialize, encrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_ARIA_192_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to ARIA context.
pKey	Pointer to key.

CRYPTO_CIPHER_ARIA_256_InitDecrypt()

Description

Initialize, decrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_ARIA_256_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to ARIA context.
pKey	Pointer to key.

CRYPTO_CIPHER_ARIA_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CIPHER_ARIA_Encrypt(      void * pContext,
                                      U8   * pOutput,
                                const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to ARIA context.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CIPHER_ARIA_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CIPHER_ARIA_Decrypt(      void * pContext,
                                      U8   * pOutput,
                                const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to ARIA context.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CIPHER_ARIA_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_ARIA_ECB_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_ARIA_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_ARIA_ECB_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_ARIA_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_ARIA_CBC_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_ARIA_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_ARIA_CBC_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_ARIA_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_ARIA_OFB_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_ARIA_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_ARIA_OFB_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_ARIA_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_ARIA_CTR_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pCTR,
                                          unsigned   CTRIndex,
                                          unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_ARIA_CTR_0_16_Encrypt()

Description

Encrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_ARIA_CTR_0_16_Encrypt(      void     * pContext,
                                               U8       * pOutput,
                                         const U8       * pInput,
                                               unsigned   InputLen,
                                               U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_ARIA_CTR_12_4_Encrypt()

Description

Encrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_ARIA_CTR_12_4_Encrypt(      void     * pContext,
                                               U8       * pOutput,
                                         const U8       * pInput,
                                               unsigned   InputLen,
                                               U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_ARIA_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_ARIA_CTR_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pCTR,
                                          unsigned   CTRIndex,
                                          unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_ARIA_CTR_0_16_Decrypt()

Description

Decrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_ARIA_CTR_0_16_Decrypt(      void     * pContext,
                                               U8       * pOutput,
                                         const U8       * pInput,
                                               unsigned   InputLen,
                                               U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_ARIA_CTR_12_4_Decrypt()

Description

Decrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_ARIA_CTR_12_4_Decrypt(      void     * pContext,
                                               U8       * pOutput,
                                         const U8       * pInput,
                                               unsigned   InputLen,
                                               U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_ARIA_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_CIPHER_ARIA_CCM_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                          U8       * pTag,
                                          unsigned   TagLen,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                    const U8       * pAAD,
                                          unsigned   AADLen,
                                    const U8       * pIV,
                                          unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_CIPHER_ARIA_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_CIPHER_ARIA_CCM_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pTag,
                                         unsigned   TagLen,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                   const U8       * pAAD,
                                         unsigned   AADLen,
                                   const U8       * pIV,
                                         unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_CIPHER_ARIA_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_CIPHER_ARIA_GCM_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                          U8       * pTag,
                                          unsigned   TagLen,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                    const U8       * pAAD,
                                          unsigned   AADLen,
                                    const U8       * pIV,
                                          unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted data.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_CIPHER_ARIA_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_CIPHER_ARIA_GCM_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pTag,
                                         unsigned   TagLen,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                   const U8       * pAAD,
                                         unsigned   AADLen,
                                   const U8       * pIV,
                                         unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to ARIA context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted input.
InputLen	Octet length of encrypted input.
pAAD	Pointer to additional data to be authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Self-test API

The following table lists the ARIA self-test API functions.

Function	Description
CRYPTO_ARIA_RFC5794_SelfTest()	Run ARIA KATs from RFC 5794.

CRYPTO_ARIA_RFC5794_SelfTest()

Description

Run ARIA KATs from RFC 5794.

Prototype

void CRYPTO_ARIA_RFC5794_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Camellia

Standards reference

Camellia is specified by the following document:

• IETF RFC 3713 — A Description of the Camellia Encryption Algorithm

The CBC, CTR, and CCM modes for Camellia are defined by this document:

• IETF RFC 5529 — Modes of Operation for Camellia for Use with IPsec

Algorithm parameters

Block size

#define CRYPTO_CAMELLIA_BLOCK_SIZE    16

The number of bytes in a single Camellia block.

Key size

#define CRYPTO_CAMELLIA128_KEY_SIZE   16
#define CRYPTO_CAMELLIA192_KEY_SIZE   24
#define CRYPTO_CAMELLIA256_KEY_SIZE   32

The number of bytes for each of the supported key sizes.

Configuration and resource use

Default

#define CRYPTO_CONFIG_CAMELLIA_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize Camellia to use more efficient tables. Optimization levels are 0 (smallest) to 3 (fastest).

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.27 KB	Flash	1.0 KB	28.8 KB		29.8 KB
1	0.27 KB	Flash	4.0 KB	20.7 KB		24.7 KB
2	0.27 KB	RAM	1.0 KB	28.8 KB		29.8 KB
3	0.27 KB	RAM	4.0 KB	20.7 KB		24.7 KB

Type-safe API

The following table lists the Camellia type-safe API functions.

Function	Description
Installation and hardware assist
CRYPTO_CAMELLIA_Install()	Install cipher.
CRYPTO_CAMELLIA_IsInstalled()	Query whether cipher is installed.
CRYPTO_CAMELLIA_QueryInstall()	Query installed cipher.
Setup
CRYPTO_CAMELLIA_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CAMELLIA_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CAMELLIA_Kill()	Clear Camellia context.
Single blocks
CRYPTO_CAMELLIA_Encrypt()	Encrypt block.
CRYPTO_CAMELLIA_Decrypt()	Decrypt block.
Basic modes
CRYPTO_CAMELLIA_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CAMELLIA_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CAMELLIA_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CAMELLIA_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CAMELLIA_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CAMELLIA_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CAMELLIA_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CAMELLIA_CTR_Decrypt()	Decrypt, CTR mode.
AEAD modes
CRYPTO_CAMELLIA_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_CAMELLIA_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_CAMELLIA_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_CAMELLIA_GCM_Decrypt()	Decrypt, GCM mode.

CRYPTO_CAMELLIA_Install()

Description

Install cipher.

Prototype

void CRYPTO_CAMELLIA_Install(const CRYPTO_CIPHER_API * pHWAPI,
                             const CRYPTO_CIPHER_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_CAMELLIA_IsInstalled()

Description

Query whether cipher is installed.

Prototype

int CRYPTO_CAMELLIA_IsInstalled(void);

Return value

= 0	Cipher is not installed.
≠ 0	Cipher is installed.

CRYPTO_CAMELLIA_QueryInstall()

Description

Query installed cipher.

Prototype

void CRYPTO_CAMELLIA_QueryInstall(const CRYPTO_CIPHER_API ** ppHWAPI,
                                  const CRYPTO_CIPHER_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the pointer to the preferred API.
ppSWAPI	Pointer to object that receives the pointer to the fallback API.

CRYPTO_CAMELLIA_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CAMELLIA_InitEncrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                 const U8                      * pKey,
                                       unsigned                  KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CAMELLIA_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CAMELLIA_InitDecrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                 const U8                      * pKey,
                                       unsigned                  KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CAMELLIA_Kill()

Description

Clear Camellia context.

Prototype

void CRYPTO_CAMELLIA_Kill(CRYPTO_CAMELLIA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.

CRYPTO_CAMELLIA_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CAMELLIA_Encrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                   U8                      * pOutput,
                             const U8                      * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CAMELLIA_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CAMELLIA_Decrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                   U8                      * pOutput,
                             const U8                      * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CAMELLIA_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CAMELLIA_ECB_Encrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen);

Parameters

Parameter	Description
pSelf	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CAMELLIA_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CAMELLIA_ECB_Decrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen);

Parameters

Parameter	Description
pSelf	Pointer to Camellia context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CAMELLIA_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CAMELLIA_CBC_Encrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_CAMELLIA_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CAMELLIA_CBC_Decrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Camellia context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_CAMELLIA_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CAMELLIA_OFB_Encrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_CAMELLIA_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CAMELLIA_OFB_Decrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_CAMELLIA_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CAMELLIA_CTR_Encrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pCTR,
                                       unsigned                  CTRIndex,
                                       unsigned                  CTRLen);

Parameters

Parameter	Description
pSelf	Initialized Camellia context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_CAMELLIA_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CAMELLIA_CTR_Decrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pCTR,
                                       unsigned                  CTRIndex,
                                       unsigned                  CTRLen);

Parameters

Parameter	Description
pSelf	Initialized Camellia context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_CAMELLIA_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_CAMELLIA_CCM_Encrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                       U8                      * pTag,
                                       unsigned                  TagLen,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                 const U8                      * pAAD,
                                       unsigned                  AADLen,
                                 const U8                      * pIV,
                                       unsigned                  IVLen);

Parameters

Parameter	Description
pSelf	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_CAMELLIA_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_CAMELLIA_CCM_Decrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                      U8                      * pOutput,
                                const U8                      * pTag,
                                      unsigned                  TagLen,
                                const U8                      * pInput,
                                      unsigned                  InputLen,
                                const U8                      * pAAD,
                                      unsigned                  AADLen,
                                const U8                      * pIV,
                                      unsigned                  IVLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_CAMELLIA_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_CAMELLIA_GCM_Encrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                       U8                      * pTag,
                                       unsigned                  TagLen,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                 const U8                      * pAAD,
                                       unsigned                  AADLen,
                                 const U8                      * pIV,
                                       unsigned                  IVLen);

Parameters

Parameter	Description
pSelf	Pointer to CAMELLIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the initialization vector.

CRYPTO_CAMELLIA_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_CAMELLIA_GCM_Decrypt(      CRYPTO_CAMELLIA_CONTEXT * pSelf,
                                      U8                      * pOutput,
                                const U8                      * pTag,
                                      unsigned                  TagLen,
                                const U8                      * pInput,
                                      unsigned                  InputLen,
                                const U8                      * pAAD,
                                      unsigned                  AADLen,
                                const U8                      * pIV,
                                      unsigned                  IVLen);

Parameters

Parameter	Description
pSelf	Pointer to CAMELLIA context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Generic API

The following table lists the Camellia functions that conform to the generic cipher API.

Function	Description
Setup
CRYPTO_CIPHER_CAMELLIA_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CIPHER_CAMELLIA_128_InitEncrypt()	Initialize, encrypt mode, 128-bit key.
CRYPTO_CIPHER_CAMELLIA_192_InitEncrypt()	Initialize, encrypt mode, 192-bit key.
CRYPTO_CIPHER_CAMELLIA_256_InitEncrypt()	Initialize, encrypt mode, 256-bit key.
CRYPTO_CIPHER_CAMELLIA_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CIPHER_CAMELLIA_128_InitDecrypt()	Initialize, decrypt mode, 128-bit key.
CRYPTO_CIPHER_CAMELLIA_192_InitDecrypt()	Initialize, decrypt mode, 192-bit key.
CRYPTO_CIPHER_CAMELLIA_256_InitDecrypt()	Initialize, decrypt mode, 256-bit key.
Single blocks
CRYPTO_CIPHER_CAMELLIA_Encrypt()	Encrypt block.
CRYPTO_CIPHER_CAMELLIA_Decrypt()	Decrypt block.
Basic modes
CRYPTO_CIPHER_CAMELLIA_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_CAMELLIA_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_CAMELLIA_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_CAMELLIA_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_CAMELLIA_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_CAMELLIA_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_CAMELLIA_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_CAMELLIA_CTR_Decrypt()	Decrypt, CTR mode.
CRYPTO_CIPHER_CAMELLIA_CTR_0_16_Encrypt()	Encrypt, CTR(0,16) mode.
CRYPTO_CIPHER_CAMELLIA_CTR_0_16_Decrypt()	Decrypt, CTR(0,16) mode.
CRYPTO_CIPHER_CAMELLIA_CTR_12_4_Encrypt()	Encrypt, CTR(12,4) mode.
CRYPTO_CIPHER_CAMELLIA_CTR_12_4_Decrypt()	Decrypt, CTR(12,4) mode.
AEAD modes
CRYPTO_CIPHER_CAMELLIA_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_CIPHER_CAMELLIA_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_CIPHER_CAMELLIA_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_CIPHER_CAMELLIA_GCM_Decrypt()	Decrypt, GCM mode.

CRYPTO_CIPHER_CAMELLIA_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_InitEncrypt(      void     * pContext,
                                        const U8       * pKey,
                                              unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to Camellia context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_CAMELLIA_128_InitEncrypt()

Description

Initialize, encrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_CAMELLIA_128_InitEncrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to Camellia context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAMELLIA_192_InitEncrypt()

Description

Initialize, encrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_CAMELLIA_192_InitEncrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to Camellia context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAMELLIA_256_InitEncrypt()

Description

Initialize, encrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_CAMELLIA_256_InitEncrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to Camellia context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAMELLIA_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_InitDecrypt(      void     * pContext,
                                        const U8       * pKey,
                                              unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to Camellia context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_CAMELLIA_128_InitDecrypt()

Description

Initialize, decrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_CAMELLIA_128_InitDecrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to Camellia context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAMELLIA_192_InitDecrypt()

Description

Initialize, decrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_CAMELLIA_192_InitDecrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to Camellia context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAMELLIA_256_InitDecrypt()

Description

Initialize, decrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_CAMELLIA_256_InitDecrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to Camellia context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAMELLIA_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CIPHER_CAMELLIA_Encrypt(      void * pContext,
                                          U8   * pOutput,
                                    const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to Camellia context.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CIPHER_CAMELLIA_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CIPHER_CAMELLIA_Decrypt(      void * pContext,
                                          U8   * pOutput,
                                    const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to Camellia context.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CIPHER_CAMELLIA_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_ECB_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_CAMELLIA_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_ECB_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_CAMELLIA_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_CBC_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_CAMELLIA_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_CBC_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_CAMELLIA_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_OFB_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_CAMELLIA_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_OFB_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_CAMELLIA_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_CTR_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR,
                                              unsigned   CTRIndex,
                                              unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_CAMELLIA_CTR_0_16_Encrypt()

Description

Encrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_CTR_0_16_Encrypt(      void     * pContext,
                                                   U8       * pOutput,
                                             const U8       * pInput,
                                                   unsigned   InputLen,
                                                   U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_CAMELLIA_CTR_12_4_Encrypt()

Description

Encrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_CTR_12_4_Encrypt(      void     * pContext,
                                                   U8       * pOutput,
                                             const U8       * pInput,
                                                   unsigned   InputLen,
                                                   U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_CAMELLIA_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_CTR_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR,
                                              unsigned   CTRIndex,
                                              unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_CAMELLIA_CTR_0_16_Decrypt()

Description

Decrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_CTR_0_16_Decrypt(      void     * pContext,
                                                   U8       * pOutput,
                                             const U8       * pInput,
                                                   unsigned   InputLen,
                                                   U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_CAMELLIA_CTR_12_4_Decrypt()

Description

Decrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_CTR_12_4_Decrypt(      void     * pContext,
                                                   U8       * pOutput,
                                             const U8       * pInput,
                                                   unsigned   InputLen,
                                                   U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to Camellia context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_CAMELLIA_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_CCM_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                              U8       * pTag,
                                              unsigned   TagLen,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                        const U8       * pAAD,
                                              unsigned   AADLen,
                                        const U8       * pIV,
                                              unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_CIPHER_CAMELLIA_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_CIPHER_CAMELLIA_CCM_Decrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pTag,
                                             unsigned   TagLen,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                       const U8       * pAAD,
                                             unsigned   AADLen,
                                       const U8       * pIV,
                                             unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_CIPHER_CAMELLIA_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_CIPHER_CAMELLIA_GCM_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                              U8       * pTag,
                                              unsigned   TagLen,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                        const U8       * pAAD,
                                              unsigned   AADLen,
                                        const U8       * pIV,
                                              unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to CAMELLIA context, encrypt mode.
pOutput	Pointer to object that receives the encrypted data.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_CIPHER_CAMELLIA_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_CIPHER_CAMELLIA_GCM_Decrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pTag,
                                             unsigned   TagLen,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                       const U8       * pAAD,
                                             unsigned   AADLen,
                                       const U8       * pIV,
                                             unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to CAMELLIA context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted input.
InputLen	Octet length of encrypted input.
pAAD	Pointer to additional data to be authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Self-test API

The following table lists the Camellia self-test API functions.

Function	Description
CRYPTO_CAMELLIA_NTT_SelfTest()	Run Camellia self-tests from NTT.
CRYPTO_CAMELLIA_RFC5528_SelfTest()	Run RFC 5528 Camellia-CTR tests.

CRYPTO_CAMELLIA_NTT_SelfTest()

Description

Run Camellia self-tests from NTT.

Prototype

void CRYPTO_CAMELLIA_NTT_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CRYPTO_CAMELLIA_RFC5528_SelfTest()

Description

Run RFC 5528 Camellia-CTR tests.

Prototype

void CRYPTO_CAMELLIA_RFC5528_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CAST

Algorithm parameters

Block size

#define CRYPTO_CAST_BLOCK_SIZE    8

The number of bytes in a single CAST-5 block.

Key size

#define CRYPTO_CAST128_KEY_SIZE   16
#define CRYPTO_CAST192_KEY_SIZE   24
#define CRYPTO_CAST256_KEY_SIZE   32

The number of bytes for each of the supported key sizes.

Configuration and resource use

Default

#define CRYPTO_CONFIG_CAST_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize CAST to place tables in RAM rather than flash. Optimization levels are 0 through 1 with larger numbers generally producing better performance.

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.10 KB	Flash	8.0 KB	3.5 KB		11.5 KB
1	0.10 KB	RAM	8.0 KB	3.7 KB		11.7 KB

Type-safe API

The following table lists the CAST type-safe API functions.

Function	Description
Installation and hardware assist
CRYPTO_CAST_Install()	Install cipher.
CRYPTO_CAST_IsInstalled()	Query whether cipher is installed.
CRYPTO_CAST_QueryInstall()	Query installed cipher.
Setup
CRYPTO_CAST_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CAST_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CAST_Kill()	Clear CAST context.
Single blocks
CRYPTO_CAST_Encrypt()	Encrypt block.
CRYPTO_CAST_Decrypt()	Decrypt block.
Basic modes
CRYPTO_CAST_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CAST_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CAST_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CAST_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CAST_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CAST_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CAST_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CAST_CTR_Decrypt()	Decrypt, CTR mode.

CRYPTO_CAST_Install()

Description

Install cipher.

Prototype

void CRYPTO_CAST_Install(const CRYPTO_CIPHER_API * pHWAPI,
                         const CRYPTO_CIPHER_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_CAST_IsInstalled()

Description

Query whether cipher is installed.

Prototype

int CRYPTO_CAST_IsInstalled(void);

Return value

= 0	Cipher is not installed.
≠ 0	Cipher is installed.

CRYPTO_CAST_QueryInstall()

Description

Query installed cipher.

Prototype

void CRYPTO_CAST_QueryInstall(const CRYPTO_CIPHER_API ** ppHWAPI,
                              const CRYPTO_CIPHER_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the pointer to the preferred API.
ppSWAPI	Pointer to object that receives the pointer to the fallback API.

CRYPTO_CAST_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CAST_InitEncrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                             const U8                  * pKey,
                                   unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CAST_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CAST_InitDecrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                             const U8                  * pKey,
                                   unsigned              KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CAST_Kill()

Description

Clear CAST context.

Prototype

void CRYPTO_CAST_Kill(CRYPTO_CAST_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.

CRYPTO_CAST_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CAST_Encrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                               U8                  * pOutput,
                         const U8                  * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CAST_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CAST_Decrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                               U8                  * pOutput,
                         const U8                  * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CAST_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CAST_ECB_Decrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen);

Parameters

Parameter	Description
pSelf	Pointer to CAST context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CAST_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CAST_ECB_Encrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen);

Parameters

Parameter	Description
pSelf	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CAST_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CAST_CBC_Decrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to CAST context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_CAST_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CAST_CBC_Encrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_CAST_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CAST_OFB_Decrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_CAST_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CAST_OFB_Encrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pIV);

Parameters

Parameter	Description
pSelf	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_CAST_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CAST_CTR_Decrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pCTR,
                                   unsigned              CTRIndex,
                                   unsigned              CTRLen);

Parameters

Parameter	Description
pSelf	Initialized CAST context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_CAST_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CAST_CTR_Encrypt(      CRYPTO_CAST_CONTEXT * pSelf,
                                   U8                  * pOutput,
                             const U8                  * pInput,
                                   unsigned              InputLen,
                                   U8                  * pCTR,
                                   unsigned              CTRIndex,
                                   unsigned              CTRLen);

Parameters

Parameter	Description
pSelf	Initialized CAST context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Generic API

The following table lists the CAST functions that conform to the generic cipher API.

Function	Description
Setup
CRYPTO_CIPHER_CAST_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CIPHER_CAST_128_InitEncrypt()	Initialize, encrypt mode, 128-bit key.
CRYPTO_CIPHER_CAST_192_InitEncrypt()	Initialize, encrypt mode, 192-bit key.
CRYPTO_CIPHER_CAST_256_InitEncrypt()	Initialize, encrypt mode, 256-bit key.
CRYPTO_CIPHER_CAST_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CIPHER_CAST_128_InitDecrypt()	Initialize, decrypt mode, 128-bit key.
CRYPTO_CIPHER_CAST_192_InitDecrypt()	Initialize, decrypt mode, 192-bit key.
CRYPTO_CIPHER_CAST_256_InitDecrypt()	Initialize, decrypt mode, 256-bit key.
Single blocks
CRYPTO_CIPHER_CAST_Encrypt()	Encrypt block.
CRYPTO_CIPHER_CAST_Decrypt()	Decrypt block.
Basic modes
CRYPTO_CIPHER_CAST_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_CAST_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_CAST_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_CAST_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_CAST_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_CAST_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_CAST_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_CAST_CTR_0_8_Encrypt()	Encrypt, CTR(0,8) mode.
CRYPTO_CIPHER_CAST_CTR_4_4_Encrypt()	Encrypt, CTR(4,4) mode.
CRYPTO_CIPHER_CAST_CTR_Decrypt()	Decrypt, CTR mode.
CRYPTO_CIPHER_CAST_CTR_0_8_Decrypt()	Decrypt, CTR(0,8) mode.
CRYPTO_CIPHER_CAST_CTR_4_4_Decrypt()	Decrypt, CTR(4,4) mode.

CRYPTO_CIPHER_CAST_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CIPHER_CAST_InitEncrypt(      void     * pContext,
                                    const U8       * pKey,
                                          unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to CAST context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_CAST_128_InitEncrypt()

Description

Initialize, encrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_CAST_128_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to CAST context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAST_192_InitEncrypt()

Description

Initialize, encrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_CAST_192_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to CAST context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAST_256_InitEncrypt()

Description

Initialize, encrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_CAST_256_InitEncrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to CAST context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAST_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CIPHER_CAST_InitDecrypt(      void     * pContext,
                                    const U8       * pKey,
                                          unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to CAST context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_CAST_128_InitDecrypt()

Description

Initialize, decrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_CAST_128_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to CAST context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAST_192_InitDecrypt()

Description

Initialize, decrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_CAST_192_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to CAST context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAST_256_InitDecrypt()

Description

Initialize, decrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_CAST_256_InitDecrypt(      void * pContext,
                                        const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to CAST context.
pKey	Pointer to key.

CRYPTO_CIPHER_CAST_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CIPHER_CAST_Encrypt(      void * pContext,
                                      U8   * pOutput,
                                const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to CAST context.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CIPHER_CAST_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CIPHER_CAST_Decrypt(      void * pContext,
                                      U8   * pOutput,
                                const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to CAST context.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CIPHER_CAST_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_CAST_ECB_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_CAST_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_CAST_ECB_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to CAST context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_CAST_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_CAST_CBC_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_CAST_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_CAST_CBC_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to CAST context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_CAST_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_CAST_OFB_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_CAST_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_CAST_OFB_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to CAST context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_CAST_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_CAST_CTR_Encrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pCTR,
                                          unsigned   CTRIndex,
                                          unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_CAST_CTR_0_8_Encrypt()

Description

Encrypt, CTR(0,8) mode.

Prototype

void CRYPTO_CIPHER_CAST_CTR_0_8_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…7].

CRYPTO_CIPHER_CAST_CTR_4_4_Encrypt()

Description

Encrypt, CTR(4,4) mode.

Prototype

void CRYPTO_CIPHER_CAST_CTR_4_4_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[4…7].

CRYPTO_CIPHER_CAST_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_CAST_CTR_Decrypt(      void     * pContext,
                                          U8       * pOutput,
                                    const U8       * pInput,
                                          unsigned   InputLen,
                                          U8       * pCTR,
                                          unsigned   CTRIndex,
                                          unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_CAST_CTR_0_8_Decrypt()

Description

Decrypt, CTR(0,8) mode.

Prototype

void CRYPTO_CIPHER_CAST_CTR_0_8_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…7].

CRYPTO_CIPHER_CAST_CTR_4_4_Decrypt()

Description

Decrypt, CTR(4,4) mode.

Prototype

void CRYPTO_CIPHER_CAST_CTR_4_4_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to CAST context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[4…7].

Self-test API

The following table lists the CAST self-test API functions.

Function	Description
CRYPTO_CAST_RFC2144_SelfTest()	Run CAST KATs from RFC2144.

CRYPTO_CAST_RFC2144_SelfTest()

Description

Run CAST KATs from RFC2144.

Prototype

void CRYPTO_CAST_RFC2144_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

ChaCha20

Algorithm parameters

Block size

#define CRYPTO_CHACHA20_BLOCK_SIZE   64

The number of bytes in a single ChaCha20 block.

Key size

#define CRYPTO_CHACHA20_KEY_SIZE     32

The number of bytes for a single supported key size.

Standards reference

ChaCha20 is specified by the following document:

• IETF RFC 7539 — ChaCha20 and Poly1305 for IETF Protocols

Type-safe API

The following table lists the ChaCha20 type-safe API functions.

Setup
CRYPTO_CHACHA20_InitEncrypt_32_96()	Initialize cipher in encryption mode, 32-bit counter, 96-bit IV.
CRYPTO_CHACHA20_InitDecrypt_32_96()	Initialize cipher in decryption mode.
CRYPTO_CHACHA20_InitEncrypt_64_64()	Initialize cipher in encryption mode, 64-bit counter, 64-bit IV.
CRYPTO_CHACHA20_InitDecrypt_64_64()	Initialize cipher in decryption mode.
CRYPTO_CHACHA20_SetPos()	Set block position.
CRYPTO_CHACHA20_SetIV()	Set nonce.
CRYPTO_CHACHA20_Kill()	Destroy cipher context.
AEAD mode
CRYPTO_CHACHA20_POLY1305_GenKey()	Generate Poly1305 key using ChaCha20.
CRYPTO_CHACHA20_POLY1305_Encrypt()	Encrypt, Poly1305 mode.
CRYPTO_CHACHA20_POLY1305_Decrypt()	Decrypt, Poly1305 mode.

CRYPTO_CHACHA20_InitEncrypt_32_96()

Description

Initialize cipher in encryption mode, 32-bit counter, 96-bit IV.

Prototype

void CRYPTO_CHACHA20_InitEncrypt_32_96(      CRYPTO_CHACHA20_CONTEXT * pSelf,
                                       const U8                      * pKey,
                                             unsigned                  KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context.
pKey	Pointer to key octet string.
KeyLen	Octet length of key octet string.

CRYPTO_CHACHA20_InitDecrypt_32_96()

Description

Initialize cipher in decryption mode.

Prototype

void CRYPTO_CHACHA20_InitDecrypt_32_96(      CRYPTO_CHACHA20_CONTEXT * pSelf,
                                       const U8                      * pKey,
                                             unsigned                  KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context.
pKey	Pointer to key octet string.
KeyLen	Octet length of key octet string.

CRYPTO_CHACHA20_InitEncrypt_64_64()

Description

Initialize cipher in encryption mode, 64-bit counter, 64-bit IV.

Prototype

void CRYPTO_CHACHA20_InitEncrypt_64_64(      CRYPTO_CHACHA20_CONTEXT * pSelf,
                                       const U8                      * pKey,
                                             unsigned                  KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context.
pKey	Pointer to key octet string.
KeyLen	Octet length of key octet string.

CRYPTO_CHACHA20_InitDecrypt_64_64()

Description

Initialize cipher in decryption mode.

Prototype

void CRYPTO_CHACHA20_InitDecrypt_64_64(      CRYPTO_CHACHA20_CONTEXT * pSelf,
                                       const U8                      * pKey,
                                             unsigned                  KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context.
pKey	Pointer to key octet string.
KeyLen	Octet length of key octet string.

CRYPTO_CHACHA20_SetPos()

Description

Set block position.

Prototype

void CRYPTO_CHACHA20_SetPos(CRYPTO_CHACHA20_CONTEXT * pSelf,
                            U64                       Pos);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context.
Pos	Block number, 32 bits in IETF mode, otherwise 64 bits.

CRYPTO_CHACHA20_SetIV()

Description

Set nonce.

Prototype

void CRYPTO_CHACHA20_SetIV(      CRYPTO_CHACHA20_CONTEXT * pSelf,
                           const U8                      * pIV);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context.
pIV	Pointer to nonce octet string, 12 octets in IETF mode, otherwise 8 octets.

CRYPTO_CHACHA20_Kill()

Description

Destroy cipher context.

Prototype

void CRYPTO_CHACHA20_Kill(CRYPTO_CHACHA20_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context.

CRYPTO_CHACHA20_POLY1305_GenKey()

Description

Generate Poly1305 key using ChaCha20.

Prototype

void CRYPTO_CHACHA20_POLY1305_GenKey(      U8 * pOutput,
                                     const U8 * pKey,
                                     const U8 * pNonce);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the one-time key, 32 octets.
pKey	Pointer to key octet string, 32 octets.
pNonce	Pointer to nonce octet string, 12 octets.

Additional information

The Poly1305 key is generated according to RFC 7539.

CRYPTO_CHACHA20_POLY1305_Encrypt()

Description

Encrypt, Poly1305 mode.

Prototype

void CRYPTO_CHACHA20_POLY1305_Encrypt(      CRYPTO_CHACHA20_CONTEXT * pSelf,
                                            U8                      * pOutput,
                                            U8                      * pTag,
                                            unsigned                  TagLen,
                                      const U8                      * pInput,
                                            unsigned                  InputLen,
                                      const U8                      * pAAD,
                                            unsigned                  AADLen,
                                      const U8                      * pIV,
                                            unsigned                  IVLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted data.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data, 16 octets.
TagLen	Octet length of the tag, 16 octets.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector, 12 octets in IETF mode, otherwise 8 octets.

CRYPTO_CHACHA20_POLY1305_Decrypt()

Description

Decrypt, Poly1305 mode.

Prototype

int CRYPTO_CHACHA20_POLY1305_Decrypt(      CRYPTO_CHACHA20_CONTEXT * pSelf,
                                           U8                      * pOutput,
                                     const U8                      * pTag,
                                           unsigned                  TagLen,
                                     const U8                      * pInput,
                                           unsigned                  InputLen,
                                     const U8                      * pAAD,
                                           unsigned                  AADLen,
                                     const U8                      * pIV,
                                           unsigned                  IVLen);

Parameters

Parameter	Description
pSelf	Pointer to ChaCha20 context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted input.
InputLen	Octet length of encrypted input.
pAAD	Pointer to additional data to be authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector, 12 octets in IETF mode, otherwise 8 octets.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Self-test API

The following table lists the ChaCha20 self-test API functions.

Function	Description
CRYPTO_CHACHA20_RFC7539_SelfTest()	Run ChaCha20 KATs from RFC 7539.

CRYPTO_CHACHA20_RFC7539_SelfTest()

Description

Run ChaCha20 KATs from RFC 7539.

Prototype

void CRYPTO_CHACHA20_RFC7539_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Blowfish

Algorithm parameters

Block size

#define CRYPTO_BLOWFISH_BLOCK_SIZE    16

The number of bytes in a single Blowfish a block.

Key size

#define CRYPTO_BLOWFISH128_KEY_SIZE   16
#define CRYPTO_BLOWFISH192_KEY_SIZE   24
#define CRYPTO_BLOWFISH256_KEY_SIZE   32

The number of bytes for each of the supported key sizes.

Type-safe API

The following table lists the Blowfish type-safe API functions.

Function	Description
Installation and hardware assist
CRYPTO_BLOWFISH_Install()	Install cipher.
CRYPTO_BLOWFISH_IsInstalled()	Query whether cipher is installed.
CRYPTO_BLOWFISH_QueryInstall()	Query installed cipher.
Setup
CRYPTO_BLOWFISH_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_BLOWFISH_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_BLOWFISH_Kill()	Clear BLOWFISH context.
Single blocks
CRYPTO_BLOWFISH_Encrypt()	Encrypt block.
CRYPTO_BLOWFISH_Decrypt()	Decrypt block.
Basic modes
CRYPTO_BLOWFISH_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_BLOWFISH_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_BLOWFISH_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_BLOWFISH_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_BLOWFISH_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_BLOWFISH_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_BLOWFISH_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_BLOWFISH_CTR_Decrypt()	Decrypt, CTR mode.

CRYPTO_BLOWFISH_Install()

Description

Install cipher.

Prototype

void CRYPTO_BLOWFISH_Install(const CRYPTO_CIPHER_API * pHWAPI,
                             const CRYPTO_CIPHER_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_BLOWFISH_IsInstalled()

Description

Query whether cipher is installed.

Prototype

int CRYPTO_BLOWFISH_IsInstalled(void);

Return value

= 0	Cipher is not installed.
≠ 0	Cipher is installed.

CRYPTO_BLOWFISH_QueryInstall()

Description

Query installed cipher.

Prototype

void CRYPTO_BLOWFISH_QueryInstall(const CRYPTO_CIPHER_API ** ppHWAPI,
                                  const CRYPTO_CIPHER_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the pointer to the preferred API.
ppSWAPI	Pointer to object that receives the pointer to the fallback API.

CRYPTO_BLOWFISH_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_BLOWFISH_InitEncrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                 const U8                      * pKey,
                                       unsigned                  KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_BLOWFISH_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_BLOWFISH_InitDecrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                 const U8                      * pKey,
                                       unsigned                  KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_BLOWFISH_Kill()

Description

Clear BLOWFISH context.

Prototype

void CRYPTO_BLOWFISH_Kill(CRYPTO_BLOWFISH_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.

CRYPTO_BLOWFISH_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_BLOWFISH_Encrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                   U8                      * pOutput,
                             const U8                      * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_BLOWFISH_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_BLOWFISH_Decrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                   U8                      * pOutput,
                             const U8                      * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_BLOWFISH_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_BLOWFISH_ECB_Encrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen);

Parameters

Parameter	Description
pSelf	Pointer to Blowfish context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_BLOWFISH_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_BLOWFISH_ECB_Decrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen);

Parameters

Parameter	Description
pSelf	Pointer to Blowfish context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_BLOWFISH_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_BLOWFISH_CBC_Encrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Blowfish context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_BLOWFISH_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_BLOWFISH_CBC_Decrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Blowfish context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_BLOWFISH_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_BLOWFISH_OFB_Encrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Blowfish context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_BLOWFISH_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_BLOWFISH_OFB_Decrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Blowfish context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_BLOWFISH_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_BLOWFISH_CTR_Encrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pCTR,
                                       unsigned                  CTRIndex,
                                       unsigned                  CTRLen);

Parameters

Parameter	Description
pSelf	Initialized Blowfish context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_BLOWFISH_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_BLOWFISH_CTR_Decrypt(      CRYPTO_BLOWFISH_CONTEXT * pSelf,
                                       U8                      * pOutput,
                                 const U8                      * pInput,
                                       unsigned                  InputLen,
                                       U8                      * pCTR,
                                       unsigned                  CTRIndex,
                                       unsigned                  CTRLen);

Parameters

Parameter	Description
pSelf	Initialized Blowfish context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Configuration and resource use

Default

#define CRYPTO_CONFIG_BLOWFISH_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize Blowfish to use more efficient tables. Optimization levels are 0 to 1.

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	4.0 KB	Flash	4.0 KB	0.7 KB		4.7 KB
1	4.0 KB	RAM	4.0 KB	1.1 KB		5.1 KB

Generic API

The following table lists the Blowfish functions that conform to the generic cipher API.

Function	Description
Setup
CRYPTO_CIPHER_BLOWFISH_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CIPHER_BLOWFISH_128_InitEncrypt()	Initialize, encrypt mode, 128-bit key.
CRYPTO_CIPHER_BLOWFISH_192_InitEncrypt()	Initialize, encrypt mode, 192-bit key.
CRYPTO_CIPHER_BLOWFISH_256_InitEncrypt()	Initialize, encrypt mode, 256-bit key.
CRYPTO_CIPHER_BLOWFISH_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CIPHER_BLOWFISH_128_InitDecrypt()	Initialize, decrypt mode, 128-bit key.
CRYPTO_CIPHER_BLOWFISH_192_InitDecrypt()	Initialize, decrypt mode, 192-bit key.
CRYPTO_CIPHER_BLOWFISH_256_InitDecrypt()	Initialize, decrypt mode, 256-bit key.
Single blocks
CRYPTO_CIPHER_BLOWFISH_Encrypt()	Encrypt block.
CRYPTO_CIPHER_BLOWFISH_Decrypt()	Decrypt block.
Basic modes
CRYPTO_CIPHER_BLOWFISH_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_BLOWFISH_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_BLOWFISH_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_BLOWFISH_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_BLOWFISH_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_BLOWFISH_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_BLOWFISH_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_BLOWFISH_CTR_0_8_Encrypt()	Encrypt, CTR(0,8) mode.
CRYPTO_CIPHER_BLOWFISH_CTR_4_4_Encrypt()	Encrypt, CTR(4,4) mode.
CRYPTO_CIPHER_BLOWFISH_CTR_Decrypt()	Decrypt, CTR mode.
CRYPTO_CIPHER_BLOWFISH_CTR_0_8_Decrypt()	Decrypt, CTR(0,8) mode.
CRYPTO_CIPHER_BLOWFISH_CTR_4_4_Decrypt()	Decrypt, CTR(4,4) mode.

CRYPTO_CIPHER_BLOWFISH_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_InitEncrypt(      void     * pContext,
                                        const U8       * pKey,
                                              unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_BLOWFISH_128_InitEncrypt()

Description

Initialize, encrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_BLOWFISH_128_InitEncrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_BLOWFISH_192_InitEncrypt()

Description

Initialize, encrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_BLOWFISH_192_InitEncrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_BLOWFISH_256_InitEncrypt()

Description

Initialize, encrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_BLOWFISH_256_InitEncrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_BLOWFISH_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_InitDecrypt(      void     * pContext,
                                        const U8       * pKey,
                                              unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_BLOWFISH_128_InitDecrypt()

Description

Initialize, decrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_BLOWFISH_128_InitDecrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_BLOWFISH_192_InitDecrypt()

Description

Initialize, decrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_BLOWFISH_192_InitDecrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_BLOWFISH_256_InitDecrypt()

Description

Initialize, decrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_BLOWFISH_256_InitDecrypt(      void * pContext,
                                            const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_BLOWFISH_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CIPHER_BLOWFISH_Encrypt(      void * pContext,
                                          U8   * pOutput,
                                    const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CIPHER_BLOWFISH_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CIPHER_BLOWFISH_Decrypt(      void * pContext,
                                          U8   * pOutput,
                                    const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CIPHER_BLOWFISH_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_ECB_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_BLOWFISH_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_ECB_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_BLOWFISH_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_CBC_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_BLOWFISH_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_CBC_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_BLOWFISH_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_OFB_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_BLOWFISH_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_OFB_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_BLOWFISH_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_CTR_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR,
                                              unsigned   CTRIndex,
                                              unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_BLOWFISH_CTR_0_8_Encrypt()

Description

Encrypt, CTR(0,8) mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_CTR_0_8_Encrypt(      void     * pContext,
                                                  U8       * pOutput,
                                            const U8       * pInput,
                                                  unsigned   InputLen,
                                                  U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…7].

CRYPTO_CIPHER_BLOWFISH_CTR_4_4_Encrypt()

Description

Encrypt, CTR(4,4) mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_CTR_4_4_Encrypt(      void     * pContext,
                                                  U8       * pOutput,
                                            const U8       * pInput,
                                                  unsigned   InputLen,
                                                  U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[4…7].

CRYPTO_CIPHER_BLOWFISH_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_CTR_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR,
                                              unsigned   CTRIndex,
                                              unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_BLOWFISH_CTR_0_8_Decrypt()

Description

Decrypt, CTR(0,8) mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_CTR_0_8_Decrypt(      void     * pContext,
                                                  U8       * pOutput,
                                            const U8       * pInput,
                                                  unsigned   InputLen,
                                                  U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…7].

CRYPTO_CIPHER_BLOWFISH_CTR_4_4_Decrypt()

Description

Decrypt, CTR(4,4) mode.

Prototype

void CRYPTO_CIPHER_BLOWFISH_CTR_4_4_Decrypt(      void     * pContext,
                                                  U8       * pOutput,
                                            const U8       * pInput,
                                                  unsigned   InputLen,
                                                  U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to BLOWFISH context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[4…7].

Self-test API

The following table lists the Blowfish self-test API functions.

Function	Description
CRYPTO_BLOWFISH_Schneier_SelfTest()	Run Blowfish KATs from Schneier.

CRYPTO_BLOWFISH_Schneier_SelfTest()

Description

Run Blowfish KATs from Schneier.

Prototype

void CRYPTO_BLOWFISH_Schneier_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Twofish

Algorithm parameters

Block size

#define CRYPTO_TWOFISH_BLOCK_SIZE    16

The number of bytes in a single Twofish block.

Key size

#define CRYPTO_TWOFISH128_KEY_SIZE   16
#define CRYPTO_TWOFISH192_KEY_SIZE   24
#define CRYPTO_TWOFISH256_KEY_SIZE   32

The number of bytes for each of the supported key sizes.

Configuration and resource use

Default

#define CRYPTO_CONFIG_TWOFISH_OPTIMIZE     1

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize Twofish to use more efficient tables. Optimization levels are 0 (smallest) to 15 (fastest).

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.2 KB	Flash	0.6 KB	3.4 KB		4.0 KB
1	0.2 KB	Flash	4.6 KB	3.1 KB		7.7 KB
2	0.2 KB	Flash	8.5 KB	3.2 KB		11.7 KB
3	0.2 KB	Flash	12.5 KB	2.8 KB		15.3 KB
4	4.2 KB	Flash	0.6 KB	3.4 KB		4.0 KB
5	4.2 KB	Flash	4.6 KB	3.1 KB		7.7 KB
6	4.2 KB	Flash	8.5 KB	3.2 KB		11.7 KB
7	4.2 KB	Flash	12.5 KB	2.8 KB		15.3 KB
8	0.2 KB	RAM	0.6 KB	3.4 KB		4.0 KB
9	0.2 KB	RAM	4.6 KB	3.1 KB		7.7 KB
10	0.2 KB	RAM	8.5 KB	3.2 KB		11.7 KB
11	0.2 KB	RAM	12.5 KB	2.8 KB		15.3 KB
12	4.2 KB	RAM	0.6 KB	3.4 KB		4.0 KB
13	4.2 KB	RAM	4.6 KB	3.1 KB		7.7 KB
14	4.2 KB	RAM	8.5 KB	3.2 KB		11.7 KB
15	4.2 KB	RAM	12.5 KB	2.8 KB		15.3 KB

Type-safe API

The following table lists the Twofish type-safe API functions.

Function	Description
Installation and hardware assist
CRYPTO_TWOFISH_Install()	Install cipher.
CRYPTO_TWOFISH_IsInstalled()	Query whether cipher is installed.
CRYPTO_TWOFISH_QueryInstall()	Query installed cipher.
Setup
CRYPTO_TWOFISH_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_TWOFISH_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_TWOFISH_Kill()	Clear TWOFISH context.
Single blocks
CRYPTO_TWOFISH_Encrypt()	Encrypt block.
CRYPTO_TWOFISH_Decrypt()	Decrypt block.
Basic modes
CRYPTO_TWOFISH_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_TWOFISH_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_TWOFISH_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_TWOFISH_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_TWOFISH_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_TWOFISH_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_TWOFISH_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_TWOFISH_CTR_Decrypt()	Decrypt, CTR mode.
AEAD modes
CRYPTO_TWOFISH_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_TWOFISH_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_TWOFISH_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_TWOFISH_GCM_Decrypt()	Decrypt, GCM mode.

CRYPTO_TWOFISH_Install()

Description

Install cipher.

Prototype

void CRYPTO_TWOFISH_Install(const CRYPTO_CIPHER_API * pHWAPI,
                            const CRYPTO_CIPHER_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_TWOFISH_IsInstalled()

Description

Query whether cipher is installed.

Prototype

int CRYPTO_TWOFISH_IsInstalled(void);

Return value

= 0	Cipher is not installed.
≠ 0	Cipher is installed.

CRYPTO_TWOFISH_QueryInstall()

Description

Query installed cipher.

Prototype

void CRYPTO_TWOFISH_QueryInstall(const CRYPTO_CIPHER_API ** ppHWAPI,
                                 const CRYPTO_CIPHER_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the pointer to the preferred API.
ppSWAPI	Pointer to object that receives the pointer to the fallback API.

CRYPTO_TWOFISH_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_TWOFISH_InitEncrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                const U8                     * pKey,
                                      unsigned                 KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_TWOFISH_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_TWOFISH_InitDecrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                const U8                     * pKey,
                                      unsigned                 KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_TWOFISH_Kill()

Description

Clear TWOFISH context.

Prototype

void CRYPTO_TWOFISH_Kill(CRYPTO_TWOFISH_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.

CRYPTO_TWOFISH_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_TWOFISH_Encrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                  U8                     * pOutput,
                            const U8                     * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_TWOFISH_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_TWOFISH_Decrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                  U8                     * pOutput,
                            const U8                     * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_TWOFISH_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_TWOFISH_ECB_Encrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen);

Parameters

Parameter	Description
pSelf	Pointer to Twofish context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_TWOFISH_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_TWOFISH_ECB_Decrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen);

Parameters

Parameter	Description
pSelf	Pointer to Twofish context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_TWOFISH_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_TWOFISH_CBC_Encrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Twofish context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_TWOFISH_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_TWOFISH_CBC_Decrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Twofish context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_TWOFISH_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_TWOFISH_OFB_Encrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Twofish context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_TWOFISH_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_TWOFISH_OFB_Decrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pIV);

Parameters

Parameter	Description
pSelf	Pointer to Twofish context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_TWOFISH_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_TWOFISH_CTR_Encrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pCTR,
                                      unsigned                 CTRIndex,
                                      unsigned                 CTRLen);

Parameters

Parameter	Description
pSelf	Initialized Twofish context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_TWOFISH_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_TWOFISH_CTR_Decrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pCTR,
                                      unsigned                 CTRIndex,
                                      unsigned                 CTRLen);

Parameters

Parameter	Description
pSelf	Initialized Twofish context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_TWOFISH_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_TWOFISH_CCM_Encrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                      U8                     * pTag,
                                      unsigned                 TagLen,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                const U8                     * pAAD,
                                      unsigned                 AADLen,
                                const U8                     * pIV,
                                      unsigned                 IVLen);

Parameters

Parameter	Description
pSelf	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_TWOFISH_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_TWOFISH_CCM_Decrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                     U8                     * pOutput,
                               const U8                     * pTag,
                                     unsigned                 TagLen,
                               const U8                     * pInput,
                                     unsigned                 InputLen,
                               const U8                     * pAAD,
                                     unsigned                 AADLen,
                               const U8                     * pIV,
                                     unsigned                 IVLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_TWOFISH_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_TWOFISH_GCM_Encrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                      U8                     * pTag,
                                      unsigned                 TagLen,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                const U8                     * pAAD,
                                      unsigned                 AADLen,
                                const U8                     * pIV,
                                      unsigned                 IVLen);

Parameters

Parameter	Description
pSelf	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the initialization vector.

CRYPTO_TWOFISH_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_TWOFISH_GCM_Decrypt(      CRYPTO_TWOFISH_CONTEXT * pSelf,
                                     U8                     * pOutput,
                               const U8                     * pTag,
                                     unsigned                 TagLen,
                               const U8                     * pInput,
                                     unsigned                 InputLen,
                               const U8                     * pAAD,
                                     unsigned                 AADLen,
                               const U8                     * pIV,
                                     unsigned                 IVLen);

Parameters

Parameter	Description
pSelf	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Generic API

The following table lists the Twofish functions that conform to the generic cipher API.

Function	Description
Setup
CRYPTO_CIPHER_TWOFISH_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CIPHER_TWOFISH_128_InitEncrypt()	Initialize, encrypt mode, 128-bit key.
CRYPTO_CIPHER_TWOFISH_192_InitEncrypt()	Initialize, encrypt mode, 192-bit key.
CRYPTO_CIPHER_TWOFISH_256_InitEncrypt()	Initialize, encrypt mode, 256-bit key.
CRYPTO_CIPHER_TWOFISH_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CIPHER_TWOFISH_128_InitDecrypt()	Initialize, decrypt mode, 128-bit key.
CRYPTO_CIPHER_TWOFISH_192_InitDecrypt()	Initialize, decrypt mode, 192-bit key.
CRYPTO_CIPHER_TWOFISH_256_InitDecrypt()	Initialize, decrypt mode, 256-bit key.
Basic modes
CRYPTO_CIPHER_TWOFISH_Encrypt()	Encrypt block.
CRYPTO_CIPHER_TWOFISH_Decrypt()	Decrypt block.
CRYPTO_CIPHER_TWOFISH_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_TWOFISH_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_TWOFISH_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_TWOFISH_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_TWOFISH_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_TWOFISH_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_TWOFISH_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_TWOFISH_CTR_0_16_Encrypt()	Encrypt, CTR(0,16) mode.
CRYPTO_CIPHER_TWOFISH_CTR_12_4_Encrypt()	Encrypt, CTR(12,4) mode.
CRYPTO_CIPHER_TWOFISH_CTR_Decrypt()	Decrypt, CTR mode.
CRYPTO_CIPHER_TWOFISH_CTR_0_16_Decrypt()	Decrypt, CTR(0,16) mode.
CRYPTO_CIPHER_TWOFISH_CTR_12_4_Decrypt()	Decrypt, CTR(12,4) mode.
AEAD modes
CRYPTO_CIPHER_TWOFISH_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_CIPHER_TWOFISH_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_CIPHER_TWOFISH_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_CIPHER_TWOFISH_GCM_Decrypt()	Decrypt, GCM mode.

CRYPTO_CIPHER_TWOFISH_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_InitEncrypt(      void     * pContext,
                                       const U8       * pKey,
                                             unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_TWOFISH_128_InitEncrypt()

Description

Initialize, encrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_TWOFISH_128_InitEncrypt(      void * pContext,
                                           const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_TWOFISH_192_InitEncrypt()

Description

Initialize, encrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_TWOFISH_192_InitEncrypt(      void * pContext,
                                           const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_TWOFISH_256_InitEncrypt()

Description

Initialize, encrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_TWOFISH_256_InitEncrypt(      void * pContext,
                                           const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_TWOFISH_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_InitDecrypt(      void     * pContext,
                                       const U8       * pKey,
                                             unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_TWOFISH_128_InitDecrypt()

Description

Initialize, decrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_TWOFISH_128_InitDecrypt(      void * pContext,
                                           const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_TWOFISH_192_InitDecrypt()

Description

Initialize, decrypt mode, 192-bit key.

Prototype

void CRYPTO_CIPHER_TWOFISH_192_InitDecrypt(      void * pContext,
                                           const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_TWOFISH_256_InitDecrypt()

Description

Initialize, decrypt mode, 256-bit key.

Prototype

void CRYPTO_CIPHER_TWOFISH_256_InitDecrypt(      void * pContext,
                                           const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context.
pKey	Pointer to key.

CRYPTO_CIPHER_TWOFISH_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CIPHER_TWOFISH_Encrypt(      void * pContext,
                                         U8   * pOutput,
                                   const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CIPHER_TWOFISH_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CIPHER_TWOFISH_Decrypt(      void * pContext,
                                         U8   * pOutput,
                                   const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CIPHER_TWOFISH_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_ECB_Encrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_TWOFISH_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_ECB_Decrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_TWOFISH_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_CBC_Encrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_TWOFISH_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_CBC_Decrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_TWOFISH_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_OFB_Encrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_TWOFISH_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_OFB_Decrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_TWOFISH_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_CTR_Encrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pCTR,
                                             unsigned   CTRIndex,
                                             unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_TWOFISH_CTR_0_16_Encrypt()

Description

Encrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_CTR_0_16_Encrypt(      void     * pContext,
                                                  U8       * pOutput,
                                            const U8       * pInput,
                                                  unsigned   InputLen,
                                                  U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_TWOFISH_CTR_12_4_Encrypt()

Description

Encrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_CTR_12_4_Encrypt(      void     * pContext,
                                                  U8       * pOutput,
                                            const U8       * pInput,
                                                  unsigned   InputLen,
                                                  U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_TWOFISH_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_CTR_Decrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pCTR,
                                             unsigned   CTRIndex,
                                             unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_TWOFISH_CTR_0_16_Decrypt()

Description

Decrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_CTR_0_16_Decrypt(      void     * pContext,
                                                  U8       * pOutput,
                                            const U8       * pInput,
                                                  unsigned   InputLen,
                                                  U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_TWOFISH_CTR_12_4_Decrypt()

Description

Decrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_CTR_12_4_Decrypt(      void     * pContext,
                                                  U8       * pOutput,
                                            const U8       * pInput,
                                                  unsigned   InputLen,
                                                  U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_TWOFISH_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_CCM_Encrypt(      void     * pContext,
                                             U8       * pOutput,
                                             U8       * pTag,
                                             unsigned   TagLen,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                       const U8       * pAAD,
                                             unsigned   AADLen,
                                       const U8       * pIV,
                                             unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_CIPHER_TWOFISH_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_CIPHER_TWOFISH_CCM_Decrypt(      void     * pContext,
                                            U8       * pOutput,
                                      const U8       * pTag,
                                            unsigned   TagLen,
                                      const U8       * pInput,
                                            unsigned   InputLen,
                                      const U8       * pAAD,
                                            unsigned   AADLen,
                                      const U8       * pIV,
                                            unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_CIPHER_TWOFISH_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_CIPHER_TWOFISH_GCM_Encrypt(      void     * pContext,
                                             U8       * pOutput,
                                             U8       * pTag,
                                             unsigned   TagLen,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                       const U8       * pAAD,
                                             unsigned   AADLen,
                                       const U8       * pIV,
                                             unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the encrypted data.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_CIPHER_TWOFISH_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_CIPHER_TWOFISH_GCM_Decrypt(      void     * pContext,
                                            U8       * pOutput,
                                      const U8       * pTag,
                                            unsigned   TagLen,
                                      const U8       * pInput,
                                            unsigned   InputLen,
                                      const U8       * pAAD,
                                            unsigned   AADLen,
                                      const U8       * pIV,
                                            unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to TWOFISH context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted input.
InputLen	Octet length of encrypted input.
pAAD	Pointer to additional data to be authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Self-test API

The following table lists the Twofish self-test API functions.

Function	Description
CRYPTO_TWOFISH_Schneier_SelfTest()	Run Twofish KATs from Schneier.

CRYPTO_TWOFISH_Schneier_SelfTest()

Description

Run Twofish KATs from Schneier.

Prototype

void CRYPTO_TWOFISH_Schneier_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

PRESENT

Algorithm parameters

Block size

#define CRYPTO_PRESENT_BLOCK_SIZE    8

The number of bytes in a single PRESENT block.

Key size

#define CRYPTO_PRESENT80_KEY_SIZE    10
#define CRYPTO_PRESENT128_KEY_SIZE   16

The number of bytes for each of the supported key sizes.

Configuration and resource use

Default

#define CRYPTO_CONFIG_PRESENT_OPTIMIZE     0

Override

To define a non-default value, define this symbol in CRYPTO_Conf.h.

Description

Set this preprocessor symbol nonzero to optimize PRESENT to place tables in RAM rather than flash.

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.26 KB	Flash	0.1 KB	0.7 KB		0.8 KB
1	0.26 KB	RAM	0.1 KB	0.7 KB		0.8 KB

Type-safe API

The following table lists the PRESENT type-safe API functions.

Function	Description
Installation and hardware assist
CRYPTO_PRESENT_Install()	Install cipher.
CRYPTO_PRESENT_IsInstalled()	Query whether cipher is installed.
CRYPTO_PRESENT_QueryInstall()	Query installed cipher.
Setup
CRYPTO_PRESENT_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_PRESENT_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_PRESENT_Kill()	Clear PRESENT context.
Single blocks
CRYPTO_PRESENT_Encrypt()	Encrypt block.
CRYPTO_PRESENT_Decrypt()	Decrypt block.
Basic modes
CRYPTO_PRESENT_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_PRESENT_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_PRESENT_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_PRESENT_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_PRESENT_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_PRESENT_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_PRESENT_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_PRESENT_CTR_Decrypt()	Decrypt, CTR mode.

CRYPTO_PRESENT_Install()

Description

Install cipher.

Prototype

void CRYPTO_PRESENT_Install(const CRYPTO_CIPHER_API * pHWAPI,
                            const CRYPTO_CIPHER_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_PRESENT_IsInstalled()

Description

Query whether cipher is installed.

Prototype

int CRYPTO_PRESENT_IsInstalled(void);

Return value

= 0	Cipher is not installed.
≠ 0	Cipher is installed.

CRYPTO_PRESENT_QueryInstall()

Description

Query installed cipher.

Prototype

void CRYPTO_PRESENT_QueryInstall(const CRYPTO_CIPHER_API ** ppHWAPI,
                                 const CRYPTO_CIPHER_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the pointer to the preferred API.
ppSWAPI	Pointer to object that receives the pointer to the fallback API.

CRYPTO_PRESENT_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_PRESENT_InitEncrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                const U8                     * pKey,
                                      unsigned                 KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_PRESENT_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_PRESENT_InitDecrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                const U8                     * pKey,
                                      unsigned                 KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_PRESENT_Kill()

Description

Clear PRESENT context.

Prototype

void CRYPTO_PRESENT_Kill(CRYPTO_PRESENT_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.

CRYPTO_PRESENT_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_PRESENT_Encrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                  U8                     * pOutput,
                            const U8                     * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_PRESENT_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_PRESENT_Decrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                  U8                     * pOutput,
                            const U8                     * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_PRESENT_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_PRESENT_ECB_Encrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen);

Parameters

Parameter	Description
pSelf	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_PRESENT_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_PRESENT_ECB_Decrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen);

Parameters

Parameter	Description
pSelf	Pointer to PRESENT context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_PRESENT_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_PRESENT_CBC_Encrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pIV);

Parameters

Parameter	Description
pSelf	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_PRESENT_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_PRESENT_CBC_Decrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pIV);

Parameters

Parameter	Description
pSelf	Pointer to PRESENT context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_PRESENT_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_PRESENT_OFB_Encrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pIV);

Parameters

Parameter	Description
pSelf	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_PRESENT_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_PRESENT_OFB_Decrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pIV);

Parameters

Parameter	Description
pSelf	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_PRESENT_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_PRESENT_CTR_Encrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pCTR,
                                      unsigned                 CTRIndex,
                                      unsigned                 CTRLen);

Parameters

Parameter	Description
pSelf	Initialized PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_PRESENT_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_PRESENT_CTR_Decrypt(      CRYPTO_PRESENT_CONTEXT * pSelf,
                                      U8                     * pOutput,
                                const U8                     * pInput,
                                      unsigned                 InputLen,
                                      U8                     * pCTR,
                                      unsigned                 CTRIndex,
                                      unsigned                 CTRLen);

Parameters

Parameter	Description
pSelf	Initialized PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Generic API

The following table lists the PRESENT functions that conform to the generic cipher API.

Function	Description
Setup
CRYPTO_CIPHER_PRESENT_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CIPHER_PRESENT_80_InitEncrypt()	Initialize, encrypt mode, 80-bit key.
CRYPTO_CIPHER_PRESENT_128_InitEncrypt()	Initialize, encrypt mode, 128-bit key.
CRYPTO_CIPHER_PRESENT_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_CIPHER_PRESENT_80_InitDecrypt()	Initialize, decrypt mode, 80-bit key.
CRYPTO_CIPHER_PRESENT_128_InitDecrypt()	Initialize, decrypt mode, 128-bit key.
Basic modes
CRYPTO_CIPHER_PRESENT_Encrypt()	Encrypt block.
CRYPTO_CIPHER_PRESENT_Decrypt()	Decrypt block.
CRYPTO_CIPHER_PRESENT_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_PRESENT_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_PRESENT_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_PRESENT_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_PRESENT_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_PRESENT_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_PRESENT_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_PRESENT_CTR_0_8_Encrypt()	Encrypt, CTR(0,8) mode.
CRYPTO_CIPHER_PRESENT_CTR_4_4_Encrypt()	Encrypt, CTR(4,4) mode.
CRYPTO_CIPHER_PRESENT_CTR_Decrypt()	Decrypt, CTR mode.
CRYPTO_CIPHER_PRESENT_CTR_0_8_Decrypt()	Decrypt, CTR(0,8) mode.
CRYPTO_CIPHER_PRESENT_CTR_4_4_Decrypt()	Decrypt, CTR(4,4) mode.

CRYPTO_CIPHER_PRESENT_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CIPHER_PRESENT_InitEncrypt(      void     * pContext,
                                       const U8       * pKey,
                                             unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_PRESENT_80_InitEncrypt()

Description

Initialize, encrypt mode, 80-bit key.

Prototype

void CRYPTO_CIPHER_PRESENT_80_InitEncrypt(      void * pContext,
                                          const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context.
pKey	Pointer to key.

CRYPTO_CIPHER_PRESENT_128_InitEncrypt()

Description

Initialize, encrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_PRESENT_128_InitEncrypt(      void * pContext,
                                           const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context.
pKey	Pointer to key.

CRYPTO_CIPHER_PRESENT_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CIPHER_PRESENT_InitDecrypt(      void     * pContext,
                                       const U8       * pKey,
                                             unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_PRESENT_80_InitDecrypt()

Description

Initialize, decrypt mode, 80-bit key.

Prototype

void CRYPTO_CIPHER_PRESENT_80_InitDecrypt(      void * pContext,
                                          const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context.
pKey	Pointer to key.

CRYPTO_CIPHER_PRESENT_128_InitDecrypt()

Description

Initialize, decrypt mode, 128-bit key.

Prototype

void CRYPTO_CIPHER_PRESENT_128_InitDecrypt(      void * pContext,
                                           const U8   * pKey);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context.
pKey	Pointer to key.

CRYPTO_CIPHER_PRESENT_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CIPHER_PRESENT_Encrypt(      void * pContext,
                                         U8   * pOutput,
                                   const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CIPHER_PRESENT_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CIPHER_PRESENT_Decrypt(      void * pContext,
                                         U8   * pOutput,
                                   const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CIPHER_PRESENT_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_PRESENT_ECB_Encrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_PRESENT_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_PRESENT_ECB_Decrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_PRESENT_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_PRESENT_CBC_Encrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_PRESENT_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_PRESENT_CBC_Decrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_PRESENT_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_PRESENT_OFB_Encrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_PRESENT_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_PRESENT_OFB_Decrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_PRESENT_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_PRESENT_CTR_Encrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pCTR,
                                             unsigned   CTRIndex,
                                             unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_PRESENT_CTR_0_8_Encrypt()

Description

Encrypt, CTR(0,8) mode.

Prototype

void CRYPTO_CIPHER_PRESENT_CTR_0_8_Encrypt(      void     * pContext,
                                                 U8       * pOutput,
                                           const U8       * pInput,
                                                 unsigned   InputLen,
                                                 U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…7].

CRYPTO_CIPHER_PRESENT_CTR_4_4_Encrypt()

Description

Encrypt, CTR(4,4) mode.

Prototype

void CRYPTO_CIPHER_PRESENT_CTR_4_4_Encrypt(      void     * pContext,
                                                 U8       * pOutput,
                                           const U8       * pInput,
                                                 unsigned   InputLen,
                                                 U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[4…7].

CRYPTO_CIPHER_PRESENT_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_PRESENT_CTR_Decrypt(      void     * pContext,
                                             U8       * pOutput,
                                       const U8       * pInput,
                                             unsigned   InputLen,
                                             U8       * pCTR,
                                             unsigned   CTRIndex,
                                             unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_PRESENT_CTR_0_8_Decrypt()

Description

Decrypt, CTR(0,8) mode.

Prototype

void CRYPTO_CIPHER_PRESENT_CTR_0_8_Decrypt(      void     * pContext,
                                                 U8       * pOutput,
                                           const U8       * pInput,
                                                 unsigned   InputLen,
                                                 U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…7].

CRYPTO_CIPHER_PRESENT_CTR_4_4_Decrypt()

Description

Decrypt, CTR(4,4) mode.

Prototype

void CRYPTO_CIPHER_PRESENT_CTR_4_4_Decrypt(      void     * pContext,
                                                 U8       * pOutput,
                                           const U8       * pInput,
                                                 unsigned   InputLen,
                                                 U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to PRESENT context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[4…7].

Self-test API

The following table lists the PRESENT self-test API functions.

Function	Description
CRYPTO_PRESENT_CHES2007_SelfTest()	Run all PRESENT KAT vectors defined by CHES 2007 PRESENT paper.

CRYPTO_PRESENT_CHES2007_SelfTest()

Description

Run all PRESENT KAT vectors defined by CHES 2007 PRESENT paper.

Prototype

void CRYPTO_PRESENT_CHES2007_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

SM4

Standards reference

SM4 is specified by the following document:

• draft-crypto-sm4-00 — The SM4 Block Cipher Algorithm And Its Modes Of Operations

Algorithm parameters

Block size

#define CRYPTO_SM4_BLOCK_SIZE    16

The number of bytes in a single SM4 block.

Key size

#define CRYPTO_SM4_KEY_SIZE      16

The number of bytes for each of the supported key sizes.

Type-safe API

The following table lists the SM4 type-safe API functions.

Function	Description
Installation and hardware assist
CRYPTO_SM4_Install()	Install cipher.
CRYPTO_SM4_IsInstalled()	Query whether cipher is installed.
CRYPTO_SM4_QueryInstall()	Query installed cipher.
Setup
CRYPTO_SM4_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_SM4_InitDecrypt()	Initialize, decrypt mode.
CRYPTO_SM4_Kill()	Clear SM4 context.
Single-block SM4
CRYPTO_SM4_Encrypt()	Encrypt block.
CRYPTO_SM4_Decrypt()	Decrypt block.
Basic cipher modes
CRYPTO_SM4_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_SM4_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_SM4_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_SM4_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_SM4_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_SM4_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_SM4_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_SM4_CTR_Decrypt()	Decrypt, CTR mode.
AEAD modes
CRYPTO_SM4_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_SM4_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_SM4_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_SM4_GCM_Decrypt()	Decrypt, GCM mode.

CRYPTO_SM4_Install()

Description

Install cipher.

Prototype

void CRYPTO_SM4_Install(const CRYPTO_CIPHER_API * pHWAPI,
                        const CRYPTO_CIPHER_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_SM4_IsInstalled()

Description

Query whether cipher is installed.

Prototype

int CRYPTO_SM4_IsInstalled(void);

Return value

= 0	Cipher is not installed.
≠ 0	Cipher is installed.

CRYPTO_SM4_QueryInstall()

Description

Query installed cipher.

Prototype

void CRYPTO_SM4_QueryInstall(const CRYPTO_CIPHER_API ** ppHWAPI,
                             const CRYPTO_CIPHER_API ** ppSWAPI);

Parameters

Parameter	Description
ppHWAPI	Pointer to object that receives the pointer to the preferred API.
ppSWAPI	Pointer to object that receives the pointer to the fallback API.

CRYPTO_SM4_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_SM4_InitEncrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                            const U8                 * pKey,
                                  unsigned             KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_SM4_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_SM4_InitDecrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                            const U8                 * pKey,
                                  unsigned             KeyLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_SM4_Kill()

Description

Clear SM4 context.

Prototype

void CRYPTO_SM4_Kill(CRYPTO_SM4_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cipher context.

CRYPTO_SM4_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_SM4_Encrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                              U8                 * pOutput,
                        const U8                 * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_SM4_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_SM4_Decrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                              U8                 * pOutput,
                        const U8                 * pInput);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_SM4_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_SM4_ECB_Encrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen);

Parameters

Parameter	Description
pSelf	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_SM4_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_SM4_ECB_Decrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen);

Parameters

Parameter	Description
pSelf	Pointer to SM4 context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_SM4_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_SM4_CBC_Encrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pIV);

Parameters

Parameter	Description
pSelf	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_SM4_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_SM4_CBC_Decrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pIV);

Parameters

Parameter	Description
pSelf	Pointer to SM4 context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_SM4_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_SM4_OFB_Encrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pIV);

Parameters

Parameter	Description
pSelf	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_SM4_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_SM4_OFB_Decrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pIV);

Parameters

Parameter	Description
pSelf	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to initialization vector.

CRYPTO_SM4_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_SM4_CTR_Encrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pCTR,
                                  unsigned             CTRIndex,
                                  unsigned             CTRLen);

Parameters

Parameter	Description
pSelf	Initialized SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_SM4_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_SM4_CTR_Decrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                  U8                 * pOutput,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                                  U8                 * pCTR,
                                  unsigned             CTRIndex,
                                  unsigned             CTRLen);

Parameters

Parameter	Description
pSelf	Initialized SM4 context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

CRYPTO_SM4_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_SM4_CCM_Encrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                  U8                 * pOutput,
                                  U8                 * pTag,
                                  unsigned             TagLen,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                            const U8                 * pAAD,
                                  unsigned             AADLen,
                            const U8                 * pIV,
                                  unsigned             IVLen);

Parameters

Parameter	Description
pSelf	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_SM4_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_SM4_CCM_Decrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                 U8                 * pOutput,
                           const U8                 * pTag,
                                 unsigned             TagLen,
                           const U8                 * pInput,
                                 unsigned             InputLen,
                           const U8                 * pAAD,
                                 unsigned             AADLen,
                           const U8                 * pIV,
                                 unsigned             IVLen);

Parameters

Parameter	Description
pSelf	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_SM4_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_SM4_GCM_Encrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                  U8                 * pOutput,
                                  U8                 * pTag,
                                  unsigned             TagLen,
                            const U8                 * pInput,
                                  unsigned             InputLen,
                            const U8                 * pAAD,
                                  unsigned             AADLen,
                            const U8                 * pIV,
                                  unsigned             IVLen);

Parameters

Parameter	Description
pSelf	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the initialization vector.

CRYPTO_SM4_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_SM4_GCM_Decrypt(      CRYPTO_SM4_CONTEXT * pSelf,
                                 U8                 * pOutput,
                           const U8                 * pTag,
                                 unsigned             TagLen,
                           const U8                 * pInput,
                                 unsigned             InputLen,
                           const U8                 * pAAD,
                                 unsigned             AADLen,
                           const U8                 * pIV,
                                 unsigned             IVLen);

Parameters

Parameter	Description
pSelf	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Generic API

The following table lists the SM4 functions that conform to the generic cipher API.

Function	Description
Setup
CRYPTO_CIPHER_SM4_InitEncrypt()	Initialize, encrypt mode.
CRYPTO_CIPHER_SM4_InitDecrypt()	Initialize, decrypt mode.
Basic cipher modes
CRYPTO_CIPHER_SM4_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_SM4_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_SM4_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_SM4_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_SM4_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_SM4_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_SM4_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_SM4_CTR_0_16_Encrypt()	Encrypt, CTR(0,16) mode.
CRYPTO_CIPHER_SM4_CTR_12_4_Encrypt()	Encrypt, CTR(12,4) mode.
CRYPTO_CIPHER_SM4_CTR_Decrypt()	Decrypt, CTR mode.
CRYPTO_CIPHER_SM4_CTR_0_16_Decrypt()	Decrypt, CTR(0,16) mode.
CRYPTO_CIPHER_SM4_CTR_12_4_Decrypt()	Decrypt, CTR(12,4) mode.
AEAD modes
CRYPTO_CIPHER_SM4_CCM_Encrypt()	Encrypt, CCM mode.
CRYPTO_CIPHER_SM4_CCM_Decrypt()	Decrypt, CCM mode.
CRYPTO_CIPHER_SM4_GCM_Encrypt()	Encrypt, GCM mode.
CRYPTO_CIPHER_SM4_GCM_Decrypt()	Decrypt, GCM mode.

CRYPTO_CIPHER_SM4_InitEncrypt()

Description

Initialize, encrypt mode.

Prototype

void CRYPTO_CIPHER_SM4_InitEncrypt(      void     * pContext,
                                   const U8       * pKey,
                                         unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to SM4 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_SM4_InitDecrypt()

Description

Initialize, decrypt mode.

Prototype

void CRYPTO_CIPHER_SM4_InitDecrypt(      void     * pContext,
                                   const U8       * pKey,
                                         unsigned   KeyLen);

Parameters

Parameter	Description
pContext	Pointer to SM4 context.
pKey	Pointer to key.
KeyLen	Octet length of the key.

CRYPTO_CIPHER_SM4_Encrypt()

Description

Encrypt block.

Prototype

void CRYPTO_CIPHER_SM4_Encrypt(      void * pContext,
                                     U8   * pOutput,
                               const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to SM4 context.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.

CRYPTO_CIPHER_SM4_Decrypt()

Description

Decrypt block.

Prototype

void CRYPTO_CIPHER_SM4_Decrypt(      void * pContext,
                                     U8   * pOutput,
                               const U8   * pInput);

Parameters

Parameter	Description
pContext	Pointer to SM4 context.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.

CRYPTO_CIPHER_SM4_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_SM4_ECB_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_SM4_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_SM4_ECB_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.

CRYPTO_CIPHER_SM4_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_SM4_CBC_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_SM4_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_SM4_CBC_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_SM4_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_SM4_OFB_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_SM4_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_SM4_OFB_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pIV);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, decrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.

CRYPTO_CIPHER_SM4_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_SM4_CTR_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pCTR,
                                         unsigned   CTRIndex,
                                         unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_SM4_CTR_0_16_Encrypt()

Description

Encrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_SM4_CTR_0_16_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_SM4_CTR_12_4_Encrypt()

Description

Encrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_SM4_CTR_12_4_Encrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_SM4_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_SM4_CTR_Decrypt(      void     * pContext,
                                         U8       * pOutput,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                         U8       * pCTR,
                                         unsigned   CTRIndex,
                                         unsigned   CTRLen);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter. On return, the counter is updated such that additional blocks can be decrypted in CTR mode.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.

Additional information

The counter value covers the bytes pCTR[CTRIndex…CTRIndex+CTRLen-1].

CRYPTO_CIPHER_SM4_CTR_0_16_Decrypt()

Description

Decrypt, CTR(0,16) mode.

Prototype

void CRYPTO_CIPHER_SM4_CTR_0_16_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the nonce and counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[0…15].

CRYPTO_CIPHER_SM4_CTR_12_4_Decrypt()

Description

Decrypt, CTR(12,4) mode.

Prototype

void CRYPTO_CIPHER_SM4_CTR_12_4_Decrypt(      void     * pContext,
                                              U8       * pOutput,
                                        const U8       * pInput,
                                              unsigned   InputLen,
                                              U8       * pCTR);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to an object that contains the counter. On return, the counter is updated such that additional blocks can be encrypted in CTR mode.

Additional information

The counter value covers the bytes pCTR[12…15].

CRYPTO_CIPHER_SM4_CCM_Encrypt()

Description

Encrypt, CCM mode.

Prototype

void CRYPTO_CIPHER_SM4_CCM_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                         U8       * pTag,
                                         unsigned   TagLen,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                   const U8       * pAAD,
                                         unsigned   AADLen,
                                   const U8       * pIV,
                                         unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of the data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector for encryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

CRYPTO_CIPHER_SM4_CCM_Decrypt()

Description

Decrypt, CCM mode.

Prototype

int CRYPTO_CIPHER_SM4_CCM_Decrypt(      void     * pContext,
                                        U8       * pOutput,
                                  const U8       * pTag,
                                        unsigned   TagLen,
                                  const U8       * pInput,
                                        unsigned   InputLen,
                                  const U8       * pAAD,
                                        unsigned   AADLen,
                                  const U8       * pIV,
                                        unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to encrypted data.
InputLen	Octet length of encrypted data.
pAAD	Pointer to additional data authenticated by tag but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector for decryption.
IVLen	Octet length of the nonce (IV). IVLen must be between 7 and 13 inclusive.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

CRYPTO_CIPHER_SM4_GCM_Encrypt()

Description

Encrypt, GCM mode.

Prototype

void CRYPTO_CIPHER_SM4_GCM_Encrypt(      void     * pContext,
                                         U8       * pOutput,
                                         U8       * pTag,
                                         unsigned   TagLen,
                                   const U8       * pInput,
                                         unsigned   InputLen,
                                   const U8       * pAAD,
                                         unsigned   AADLen,
                                   const U8       * pIV,
                                         unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the encrypted data.
pTag	Pointer to object that receives the authentication tag calculated over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to data to be encrypted.
InputLen	Octet length of data to be encrypted.
pAAD	Pointer to additional data to be authenticated but not encrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

CRYPTO_CIPHER_SM4_GCM_Decrypt()

Description

Decrypt, GCM mode.

Prototype

int CRYPTO_CIPHER_SM4_GCM_Decrypt(      void     * pContext,
                                        U8       * pOutput,
                                  const U8       * pTag,
                                        unsigned   TagLen,
                                  const U8       * pInput,
                                        unsigned   InputLen,
                                  const U8       * pAAD,
                                        unsigned   AADLen,
                                  const U8       * pIV,
                                        unsigned   IVLen);

Parameters

Parameter	Description
pContext	Pointer to SM4 context, encrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pTag	Pointer to authentication tag to verify over encrypted and additional data.
TagLen	Octet length of the tag.
pInput	Pointer to encrypted input.
InputLen	Octet length of encrypted input.
pAAD	Pointer to additional data to be authenticated but not decrypted.
AADLen	Octet length of additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.

Return value

= 0	Calculated tag and given tag are identical.
≠ 0	Calculated tag and given tag are not identical.

Self-test API

The following table lists the SM4 self-test API functions.

Function	Description
CRYPTO_SM4_GBT_SelfTest()	Run SM4 KATs from GBT.

CRYPTO_SM4_GBT_SelfTest()

Description

Run SM4 KATs from GBT.

Prototype

void CRYPTO_SM4_GBT_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

RC4

Algorithm parameters

Key size

#define CRYPTO_RC4_40_KEY_SIZE     5
#define CRYPTO_RC4_128_KEY_SIZE   16
#define CRYPTO_RC4_256_KEY_SIZE   32

The number of bytes for each of the supported key sizes.

Type-safe API

The following table lists the Twofish type-safe API functions.

Function	Description
Setup
CRYPTO_RC4_Prepare()	Prepare cipher with key.
Stream cipher
CRYPTO_RC4_Encrypt()	Encrypt input to output using current state.
CRYPTO_RC4_Decrypt()	Decrypt input to output using current state.

CRYPTO_RC4_Encrypt()

Description

Encrypt input to output using current state.

Prototype

void CRYPTO_RC4_Encrypt(      CRYPTO_RC4_CONTEXT * pContext,
                              U8                 * pOutput,
                        const U8                 * pInput,
                              unsigned             ByteCnt);

Parameters

Parameter	Description
pContext	Context for cipher.
pOutput	Output data.
pInput	Input data.
ByteCnt	Size of input and output data in bytes.

CRYPTO_RC4_Decrypt()

Description

Decrypt input to output using current state.

Prototype

void CRYPTO_RC4_Decrypt(      CRYPTO_RC4_CONTEXT * pContext,
                              U8                 * pOutput,
                        const U8                 * pInput,
                              unsigned             ByteCnt);

Parameters

Parameter	Description
pContext	Context for cipher.
pOutput	Output data.
pInput	Input data.
ByteCnt	Size of input and output data in bytes.

CRYPTO_RC4_Prepare()

Description

Prepare cipher with key.

Prototype

void CRYPTO_RC4_Prepare(      CRYPTO_RC4_CONTEXT * pContext,
                        const U8                 * pKey,
                              unsigned             KeyByteCnt);

Parameters

Parameter	Description
pContext	Context to prepare.
pKey	Encryption/Decryption key.
KeyByteCnt	Size of encryption key in bytes.

Building blocks

Cipher mode API

The following table lists the generic cipher mode API API functions.

Function	Description
Standard modes
CRYPTO_CIPHER_ECB_Encrypt()	Encrypt, ECB mode.
CRYPTO_CIPHER_ECB_Decrypt()	Decrypt, ECB mode.
CRYPTO_CIPHER_CBC_Encrypt()	Encrypt, CBC mode.
CRYPTO_CIPHER_CBC_Decrypt()	Decrypt, CBC mode.
CRYPTO_CIPHER_OFB_Encrypt()	Encrypt, OFB mode.
CRYPTO_CIPHER_OFB_Decrypt()	Decrypt, OFB mode.
CRYPTO_CIPHER_CTR_Encrypt()	Encrypt, CTR mode.
CRYPTO_CIPHER_CTR_Decrypt()	Decrypt, CTR mode.
AEAD modes
CRYPTO_CIPHER_CCM_Cipher()	Cipher, CCM mode.
CRYPTO_CIPHER_GCM_Cipher()	Cipher, GCM mode.
Building blocks
CRYPTO_CIPHER_GCM_GF128_Multiply()	Multiply in GF(2^8) field.
CRYPTO_CIPHER_GCM_Plain_Cipher()	Cipher, GCM mode, bit-by-bit multiply.
CRYPTO_CIPHER_GCM_Shoup_8b_Cipher()	Cipher, GCM mode, Shoup 8-bit tables.

CRYPTO_CIPHER_ECB_Encrypt()

Description

Encrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_ECB_Encrypt(      void              * pContext,
                                     U8                * pOutput,
                               const U8                * pInput,
                                     unsigned            InputLen,
                               const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pContext	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted data.
pInput	Pointer to object that contains the decrypted data.
InputLen	Octet length of the input and output.
pAPI	Pointer to cipher API.

CRYPTO_CIPHER_ECB_Decrypt()

Description

Decrypt, ECB mode.

Prototype

void CRYPTO_CIPHER_ECB_Decrypt(      void              * pContext,
                                     U8                * pOutput,
                               const U8                * pInput,
                                     unsigned            InputLen,
                               const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pContext	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the decrypted data.
pInput	Pointer to object that contains the encrypted data.
InputLen	Octet length of the input and output.
pAPI	Pointer to cipher API.

CRYPTO_CIPHER_CBC_Encrypt()

Description

Encrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_CBC_Encrypt(      void              * pContext,
                                     U8                * pOutput,
                               const U8                * pInput,
                                     unsigned            InputLen,
                                     U8                * pIV,
                               const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pContext	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.
pAPI	Pointer to cipher API.

CRYPTO_CIPHER_CBC_Decrypt()

Description

Decrypt, CBC mode.

Prototype

void CRYPTO_CIPHER_CBC_Decrypt(      void              * pContext,
                                     U8                * pOutput,
                               const U8                * pInput,
                                     unsigned            InputLen,
                                     U8                * pIV,
                               const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pContext	Pointer to cipher context, decrypt mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pIV	Pointer to object that contains the initialization vector.
pAPI	Pointer to cipher API.

CRYPTO_CIPHER_OFB_Encrypt()

Description

Encrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_OFB_Encrypt(      void              * pContext,
                                     U8                * pOutput,
                               const U8                * pInput,
                                     unsigned            InputLen,
                                     U8                * pIV,
                               const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pContext	Pointer to cipher context, encrypts mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and input.
pIV	Pointer to object containing the initialization vector.
pAPI	Pointer to cipher API.

CRYPTO_CIPHER_OFB_Decrypt()

Description

Decrypt, OFB mode.

Prototype

void CRYPTO_CIPHER_OFB_Decrypt(      void              * pContext,
                                     U8                * pOutput,
                               const U8                * pInput,
                                     unsigned            InputLen,
                                     U8                * pIV,
                               const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pContext	Pointer to cipher context, encrypts mode.
pOutput	Pointer to object that receives the plaintext output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and input.
pIV	Pointer to object containing the initialization vector.
pAPI	Pointer to cipher API.

CRYPTO_CIPHER_CTR_Encrypt()

Description

Encrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_CTR_Encrypt(      void              * pContext,
                                     U8                * pOutput,
                               const U8                * pInput,
                                     unsigned            InputLen,
                                     U8                * pCTR,
                                     unsigned            CTRIndex,
                                     unsigned            CTRLen,
                               const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pContext	Pointer to cipher context, encrypt mode.
pOutput	Pointer to object that receives the encrypted output.
pInput	Pointer to object that contains the plaintext input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.
pAPI	Pointer to cipher API.

Additional information

Decryption in counter mode is identical to encryption as the cipher produces a keystream: the keystream is exclusive-or’d with the plaintext to produce the ciphertext and excludive-or’d with the ciphertext to produce the plaintext.

CRYPTO_CIPHER_CTR_Decrypt()

Description

Decrypt, CTR mode.

Prototype

void CRYPTO_CIPHER_CTR_Decrypt(      void              * pContext,
                                     U8                * pOutput,
                               const U8                * pInput,
                                     unsigned            InputLen,
                                     U8                * pCTR,
                                     unsigned            CTRIndex,
                                     unsigned            CTRLen,
                               const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pContext	Pointer to cipher context initialized in decryption mode.
pOutput	Pointer to object that receives the decrypted output.
pInput	Pointer to object that contains the encrypted input.
InputLen	Octet length of the input and output.
pCTR	Pointer to initialization vector with counter.
CTRIndex	Index of the first byte of the counter within the IV.
CTRLen	Octet length of the counter.
pAPI	Pointer to cipher API.

Additional information

Decryption in counter mode is identical to encryption as the cipher produces a keystream: the keystream is exclusive-or’d with the plaintext to produce the ciphertext and excludive-or’d with the ciphertext to produce the plaintext.

CRYPTO_CIPHER_CCM_Cipher()

Description

Cipher, CCM mode.

Prototype

void CRYPTO_CIPHER_CCM_Cipher(      void              * pSelf,
                                    U8                * pOutput,
                                    U8                * pTag,
                                    unsigned            TagLen,
                              const U8                * pInput,
                                    unsigned            InputLen,
                              const U8                * pAAD,
                                    unsigned            AADLen,
                              const U8                * pIV,
                                    unsigned            IVLen,
                                    int                 Encrypt,
                              const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pSelf	Pointer to cipher context in encryption mode.
pOutput	Encrypted or decrypted data, according to Mode, size is InputLen bytes.
pTag	Pointer to object that receives the authentication tag calculated over data.
TagLen	Octet length of the authentication tag (MAC). TagLen must be 4, 6, 8, 10, 12, 14, or 16.
pInput	Pointer to data to be ciphered.
InputLen	Octet length of the data to be ciphered.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Initialization vector for encryption or decryption.
IVLen	Octet length of the nonce (IV). NLen must be between 7 and 13 inclusive.
Encrypt	Flag — nonzero for encryption, zero for decryption.
pAPI	Pointer to CIPHER API for ciphering.

CRYPTO_CIPHER_GCM_Cipher()

Description

Cipher, GCM mode.

Prototype

void CRYPTO_CIPHER_GCM_Cipher(      void              * pContext,
                                    U8                * pOutput,
                                    U8                * pTag,
                                    unsigned            TagLen,
                              const U8                * pInput,
                                    unsigned            InputLen,
                              const U8                * pAAD,
                                    unsigned            AADLen,
                              const U8                * pIV,
                                    unsigned            IVLen,
                                    int                 Encrypt,
                              const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pContext	Pointer to cipher context initialized in encryption mode.
pOutput	Encrypted or decrypted data, according to Mode, size is InputLen bytes.
pTag	Pointer to object that receives the tag calculated over data.
TagLen	Octet length of the authentication tag.
pInput	Data to be encrypted or decrypted.
InputLen	Octet length of the input data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
Encrypt	Nonzero for encryption, zero for decryption.
pAPI	Pointer to CIPHER API for ciphering.

CRYPTO_CIPHER_GCM_GF128_Multiply()

Description

Multiply in GF(2^8) field.

Prototype

void CRYPTO_CIPHER_GCM_GF128_Multiply(      U8 * pZ,
                                      const U8 * pX,
                                      const U8 * pH);

Parameters

Parameter	Description
pZ	Pointer to output block, may be identical to X.
pX	Pointer to operand #1, usually variable.
pH	Pointer to operand #2, usually fixed.

Additional information

pZ and pX may point to the same array for in-place multiplication, but pZ and pH must be distinct arrays.

CRYPTO_CIPHER_GCM_Plain_Cipher()

Description

Cipher, GCM mode, bit-by-bit multiply.

Prototype

void CRYPTO_CIPHER_GCM_Plain_Cipher(      void              * pContext,
                                          U8                * pOutput,
                                          U8                * pTag,
                                          unsigned            TagLen,
                                    const U8                * pInput,
                                          unsigned            InputLen,
                                    const U8                * pAAD,
                                          unsigned            AADLen,
                                    const U8                * pIV,
                                          unsigned            IVLen,
                                          int                 Encrypt,
                                    const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pContext	Pointer to cipher context initialized in encryption mode.
pOutput	Encrypted or decrypted data, according to Mode, size is InputLen bytes.
pTag	Pointer to object that receives the tag calculated over data.
TagLen	Octet length of the authentication tag.
pInput	Data to be encrypted or decrypted.
InputLen	Octet length of the input data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
Encrypt	Nonzero for encryption, zero for decryption.
pAPI	Pointer to CIPHER API for ciphering.

CRYPTO_CIPHER_GCM_Shoup_8b_Cipher()

Description

Cipher, GCM mode, Shoup 8-bit tables.

Prototype

void CRYPTO_CIPHER_GCM_Shoup_8b_Cipher(      void              * pContext,
                                             U8                * pOutput,
                                             U8                * pTag,
                                             unsigned            TagLen,
                                       const U8                * pInput,
                                             unsigned            InputLen,
                                       const U8                * pAAD,
                                             unsigned            AADLen,
                                       const U8                * pIV,
                                             unsigned            IVLen,
                                             int                 Encrypt,
                                       const CRYPTO_CIPHER_API * pAPI);

Parameters

Parameter	Description
pContext	Pointer to cipher context initialized in encryption mode.
pOutput	Encrypted or decrypted data, according to Mode, size is InputLen bytes.
pTag	Pointer to object that receives the tag calculated over data.
TagLen	Octet length of the authentication tag.
pInput	Data to be encrypted or decrypted.
InputLen	Octet length of the input data to be encrypted.
pAAD	Pointer to additional data authenticated by tag but not encrypted.
AADLen	Octet length of the additional data.
pIV	Pointer to initialization vector.
IVLen	Octet length of the initialization vector.
Encrypt	Nonzero for encryption, zero for decryption.
pAPI	Pointer to CIPHER API for ciphering.

Storage device encryption

emCrypt implements the following storage device encryption algorithms:

• XTS-AES
• XTS-ARIA
• XTS-Camellia
• XTS-SEED
• XTS-Twofish
• XTS-SM4

XTS-AES

Standards reference

XTS-AES is specified by the following document:

• NIST SP 800-38E — Recommendation for Block Cipher Modes of Operation: The XTS-AES Mode for Confidentiality on Storage Devices

Type-safe API

Function	Description
CRYPTO_XTS_AES_Encrypt()	Encipher using XTS-AES.
CRYPTO_XTS_AES_Decrypt()	Decipher using XTS-AES.

CRYPTO_XTS_AES_Encrypt()

Description

Encipher using XTS-AES.

Prototype

void CRYPTO_XTS_AES_Encrypt(      U8       * pOutput,
                                  U64        UnitNumber,
                            const U8       * pInput,
                                  unsigned   InputLen,
                            const U8       * pKey1,
                            const U8       * pKey2,
                                  unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the encrypted data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the plaintext data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

CRYPTO_XTS_AES_Decrypt()

Description

Decipher using XTS-AES.

Prototype

void CRYPTO_XTS_AES_Decrypt(      U8       * pOutput,
                                  U64        UnitNumber,
                            const U8       * pInput,
                                  unsigned   InputLen,
                            const U8       * pKey1,
                            const U8       * pKey2,
                                  unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the plaintext data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the encrypted data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

XTS-ARIA

Type-safe API

Function	Description
CRYPTO_XTS_ARIA_Encrypt()	Encipher using XTS-ARIA.
CRYPTO_XTS_ARIA_Decrypt()	Decipher using XTS-ARIA.

CRYPTO_XTS_ARIA_Encrypt()

Description

Encipher using XTS-ARIA.

Prototype

void CRYPTO_XTS_ARIA_Encrypt(      U8       * pOutput,
                                   U64        UnitNumber,
                             const U8       * pInput,
                                   unsigned   InputLen,
                             const U8       * pKey1,
                             const U8       * pKey2,
                                   unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the encrypted data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the plaintext data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

CRYPTO_XTS_ARIA_Decrypt()

Description

Decipher using XTS-ARIA.

Prototype

void CRYPTO_XTS_ARIA_Decrypt(      U8       * pOutput,
                                   U64        UnitNumber,
                             const U8       * pInput,
                                   unsigned   InputLen,
                             const U8       * pKey1,
                             const U8       * pKey2,
                                   unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the plaintext data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the encrypted data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

XTS-Camellia

Type-safe API

Function	Description
CRYPTO_XTS_CAMELLIA_Encrypt()	Encipher using XTS-Camellia.
CRYPTO_XTS_CAMELLIA_Decrypt()	Decipher using XTS-Camellia.

CRYPTO_XTS_CAMELLIA_Encrypt()

Description

Encipher using XTS-Camellia.

Prototype

void CRYPTO_XTS_CAMELLIA_Encrypt(      U8       * pOutput,
                                       U64        UnitNumber,
                                 const U8       * pInput,
                                       unsigned   InputLen,
                                 const U8       * pKey1,
                                 const U8       * pKey2,
                                       unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the encrypted data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the plaintext data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

CRYPTO_XTS_CAMELLIA_Decrypt()

Description

Decipher using XTS-Camellia.

Prototype

void CRYPTO_XTS_CAMELLIA_Decrypt(      U8       * pOutput,
                                       U64        UnitNumber,
                                 const U8       * pInput,
                                       unsigned   InputLen,
                                 const U8       * pKey1,
                                 const U8       * pKey2,
                                       unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the plaintext data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the encrypted data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

XTS-SEED

Type-safe API

Function	Description
CRYPTO_XTS_SEED_Encrypt()	Encipher using XTS-SEED.
CRYPTO_XTS_SEED_Decrypt()	Decipher using XTS-SEED.

CRYPTO_XTS_SEED_Encrypt()

Description

Encipher using XTS-SEED.

Prototype

void CRYPTO_XTS_SEED_Encrypt(      U8       * pOutput,
                                   U64        UnitNumber,
                             const U8       * pInput,
                                   unsigned   InputLen,
                             const U8       * pKey1,
                             const U8       * pKey2,
                                   unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the encrypted data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the plaintext data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

CRYPTO_XTS_SEED_Decrypt()

Description

Decipher using XTS-SEED.

Prototype

void CRYPTO_XTS_SEED_Decrypt(      U8       * pOutput,
                                   U64        UnitNumber,
                             const U8       * pInput,
                                   unsigned   InputLen,
                             const U8       * pKey1,
                             const U8       * pKey2,
                                   unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the plaintext data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the encrypted data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

XTS-Twofish

Type-safe API

Function	Description
CRYPTO_XTS_TWOFISH_Encrypt()	Encipher using XTS-Twofish.
CRYPTO_XTS_TWOFISH_Decrypt()	Decipher using XTS-Twofish.

CRYPTO_XTS_TWOFISH_Encrypt()

Description

Encipher using XTS-Twofish.

Prototype

void CRYPTO_XTS_TWOFISH_Encrypt(      U8       * pOutput,
                                      U64        UnitNumber,
                                const U8       * pInput,
                                      unsigned   InputLen,
                                const U8       * pKey1,
                                const U8       * pKey2,
                                      unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the encrypted data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the plaintext data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

CRYPTO_XTS_TWOFISH_Decrypt()

Description

Decipher using XTS-Twofish.

Prototype

void CRYPTO_XTS_TWOFISH_Decrypt(      U8       * pOutput,
                                      U64        UnitNumber,
                                const U8       * pInput,
                                      unsigned   InputLen,
                                const U8       * pKey1,
                                const U8       * pKey2,
                                      unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the plaintext data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the encrypted data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

XTS-SM4

Standards reference

SM4 is specified by the following document:

• draft-crypto-sm4-00 — The SM4 Block Cipher Algorithm And Its Modes Of Operations

Type-safe API

Function	Description
CRYPTO_XTS_SM4_Encrypt()	Encipher using XTS-SM4.
CRYPTO_XTS_SM4_Decrypt()	Decipher using XTS-SM4.

CRYPTO_XTS_SM4_Encrypt()

Description

Encipher using XTS-SM4.

Prototype

void CRYPTO_XTS_SM4_Encrypt(      U8       * pOutput,
                                  U64        UnitNumber,
                            const U8       * pInput,
                                  unsigned   InputLen,
                            const U8       * pKey1,
                            const U8       * pKey2,
                                  unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the encrypted data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the plaintext data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

CRYPTO_XTS_SM4_Decrypt()

Description

Decipher using XTS-SM4.

Prototype

void CRYPTO_XTS_SM4_Decrypt(      U8       * pOutput,
                                  U64        UnitNumber,
                            const U8       * pInput,
                                  unsigned   InputLen,
                            const U8       * pKey1,
                            const U8       * pKey2,
                                  unsigned   KeyLen);

Parameters

Parameter	Description
pOutput	Pointer to buffer that receives the plaintext data.
UnitNumber	Data unit number for tweak.
pInput	Pointer to buffer that contains the encrypted data.
InputLen	Number of bytes of data to be encrypted in bytes; must be a multiple of 16.
pKey1	Pointer to key for data decryption.
pKey2	Pointer to key for tweak decryption.
KeyLen	Octet length of ciphering keys pKey1 and pKey2.

Random bit generation

emCrypt implements the following deterministic random bit generators:

• Fortuna
• Hash-DRBG-SHA-1
• Hash-DRBG-SHA-224
• Hash-DRBG-SHA-256
• Hash-DRBG-SHA-384
• Hash-DRBG-SHA-512
• Hash-DRBG-SHA-512/224
• Hash-DRBG-SHA-512/256
• HMAC-DRBG-SHA-1
• HMAC-DRBG-SHA-224
• HMAC-DRBG-SHA-256
• HMAC-DRBG-SHA-384
• HMAC-DRBG-SHA-512
• HMAC-DRBG-SHA-512/224
• HMAC-DRBG-SHA-512/256
• CTR-DRBG-TDES
• CTR-DRBG-AES-128
• CTR-DRBG-AES-192
• CTR-DRBG-AES-256

Installation

Various algorithms, such as generating RSA or elliptic curve keys, require a source of random data. The following details the functions available to install and query the functions used for random bit generation.

API

Function	Description
CRYPTO_RNG_Install()	Install a RNG.
CRYPTO_RNG_InstallEx()	Install a RNG with entropy source.
CRYPTO_RNG_QueryInstall()	Get RNG API.
CRYPTO_RNG_QueryInstallEx()	Get RNG preferred and hardware entropy sources.
CRYPTO_RNG_Get()	Get random data.
CRYPTO_RNG_GetNonzero()	Get nonzero random data.

CRYPTO_RNG_Install()

Description

Install a RNG.

Prototype

void CRYPTO_RNG_Install(const CRYPTO_RNG_API * pSecureAPI);

Parameters

Parameter	Description
pSecureAPI	Pointer to API that acts as the secure RNG source.

CRYPTO_RNG_InstallEx()

Description

Install a RNG with entropy source.

Prototype

void CRYPTO_RNG_InstallEx(const CRYPTO_RNG_API * pSecureAPI,
                          const CRYPTO_RNG_API * pEntropyAPI);

Parameters

Parameter	Description
pSecureAPI	Pointer to API that acts as the secure RNG source.
pEntropyAPI	Pointer to API that provides entropy.

CRYPTO_RNG_QueryInstall()

Description

Get RNG API.

Prototype

void CRYPTO_RNG_QueryInstall(const CRYPTO_RNG_API ** ppSecureAPI);

Parameters

Parameter	Description
ppSecureAPI	Pointer to object that receives the pointer to the secure RNG API.

CRYPTO_RNG_QueryInstallEx()

Description

Get RNG preferred and hardware entropy sources.

Prototype

void CRYPTO_RNG_QueryInstallEx(const CRYPTO_RNG_API ** ppSecureAPI,
                               const CRYPTO_RNG_API ** ppEntropyAPI);

Parameters

Parameter	Description
ppSecureAPI	Pointer to object that receives the pointer to the secure RNG API.
ppEntropyAPI	Pointer to object that receives the pointer to the entropy API.

CRYPTO_RNG_Get()

Description

Get random data.

Prototype

void CRYPTO_RNG_Get(U8       * pData,
                    unsigned   DataLen);

Parameters

Parameter	Description
pData	Pointer to object that receives the random data.
DataLen	Octet length of the random data.

CRYPTO_RNG_GetNonzero()

Description

Get nonzero random data.

Prototype

void CRYPTO_RNG_GetNonzero(U8       * pData,
                           unsigned   DataLen);

Parameters

Parameter	Description
pData	Pointer to object that receives the random data.
DataLen	Octet length of the random data.

Additional information

Every octet in the output object is assured nonzero.

Fortuna

Type-safe API

Function	Description
CRYPTO_FORTUNA_Init()	Initialize Fortuna context.
CRYPTO_FORTUNA_Kill()	Deinitialize Fortuna context.
CRYPTO_FORTUNA_Status()	Return Fortuna RNG status.
CRYPTO_FORTUNA_Add()	Add entropy.
CRYPTO_FORTUNA_AddEx()	Add entropy to pool.
CRYPTO_FORTUNA_Reseed()	Reseed Fortuna context.
CRYPTO_FORTUNA_Get()	Get pseudorandom data.

CRYPTO_FORTUNA_Add()

Description

Add entropy.

Prototype

void CRYPTO_FORTUNA_Add(      CRYPTO_FORTUNA_CONTEXT * pSelf,
                              unsigned                 Source,
                        const U8                     * pData,
                              unsigned                 DataLen);

Parameters

Parameter	Description
pSelf	Pointer to Fortuna context.
Source	Source index of random data.
pData	Pointer to octet string of random data.
DataLen	Octet length of octet string.

CRYPTO_FORTUNA_AddEx()

Description

Add entropy to pool.

Prototype

void CRYPTO_FORTUNA_AddEx(      CRYPTO_FORTUNA_CONTEXT * pSelf,
                                unsigned                 Source,
                                unsigned                 Pool,
                          const U8                     * pData,
                                unsigned                 DataLen);

Parameters

Parameter	Description
pSelf	Pointer to Fortuna context.
Source	Source index of random data.
Pool	Pool to add to entropy to.
pData	Pointer to octet string of random data.
DataLen	Octet length of octet string.

CRYPTO_FORTUNA_Get()

Description

Get pseudorandom data.

Prototype

void CRYPTO_FORTUNA_Get(CRYPTO_FORTUNA_CONTEXT * pSelf,
                        U8                     * pData,
                        unsigned                 DataLen);

Parameters

Parameter	Description
pSelf	Pointer to Fortuna context.
pData	Pointer to object that receives the random data.
DataLen	Octet length of the object.

CRYPTO_FORTUNA_Init()

Description

Initialize Fortuna context.

Prototype

void CRYPTO_FORTUNA_Init(CRYPTO_FORTUNA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Fortuna context.

CRYPTO_FORTUNA_Kill()

Description

Deinitialize Fortuna context.

Prototype

void CRYPTO_FORTUNA_Kill(CRYPTO_FORTUNA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Fortuna context.

CRYPTO_FORTUNA_Reseed()

Description

Reseed Fortuna context.

Prototype

void CRYPTO_FORTUNA_Reseed(CRYPTO_FORTUNA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Fortuna context.

CRYPTO_FORTUNA_Status()

Description

Return Fortuna RNG status.

Prototype

int CRYPTO_FORTUNA_Status(CRYPTO_FORTUNA_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Fortuna context.

Return value

> 0	Fortuna is ready to deliver PRNG data.
= 0	Fortuna needs reseeding.
< 0	Fortuna does not have enough entropy.

Self-test API

The following table lists the Fortuna self-test API functions.

Function	Description
CRYPTO_FORTUNA_Voss_SelfTest()	Run Fortuna KATs defined by Voss.

CRYPTO_FORTUNA_Voss_SelfTest()

Description

Run Fortuna KATs defined by Voss.

Prototype

void CRYPTO_FORTUNA_Voss_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Hash-DRBG-SHA-1

Standards reference

Hash-DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HASH_SHA1_Init()	Initialize a Hash-DRBG-SHA-1 random bit generator.
CRYPTO_DRBG_HASH_SHA1_Reseed()	Reseed a HMAC-DRBG-SHA-1 random bit generator.
CRYPTO_DRBG_HASH_SHA1_Get()	Get data from random bitstream.

CRYPTO_DRBG_HASH_SHA1_Init()

Description

Initialize a Hash-DRBG-SHA-1 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA1_Init(      CRYPTO_DRBG_HASH_SHA1_CONTEXT * pSelf,
                                const U8                            * pEntropy,
                                      unsigned                        EntropyLen,
                                const U8                            * pNonce,
                                      unsigned                        NonceLen,
                                const U8                            * pPerso,
                                      unsigned                        PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HASH_SHA1_Reseed()

Description

Reseed a HMAC-DRBG-SHA-1 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA1_Reseed(      CRYPTO_DRBG_HASH_SHA1_CONTEXT * pSelf,
                                  const U8                            * pEntropy,
                                        unsigned                        EntropyLen,
                                  const U8                            * pAdd,
                                        unsigned                        AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HASH_SHA1_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HASH_SHA1_Get(      CRYPTO_DRBG_HASH_SHA1_CONTEXT * pSelf,
                                     U8                            * pOutput,
                                     unsigned                        OutputLen,
                               const U8                            * pAdd,
                                     unsigned                        AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the Hash-DRBG-SHA-1 self-test API functions.

Function	Description
CRYPTO_DRBG_HASH_SHA1_CAVS_SelfTest()	Run DRBG-SHA-1 KATs from CAVS.

CRYPTO_DRBG_HASH_SHA1_CAVS_SelfTest()

Description

Run DRBG-SHA-1 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HASH_SHA1_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Hash-DRBG-SHA-224

Standards reference

Hash-DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HASH_SHA224_Init()	Initialize a Hash-DRBG-SHA-224 random bit generator.
CRYPTO_DRBG_HASH_SHA224_Reseed()	Reseed a HMAC-DRBG-SHA-224 random bit generator.
CRYPTO_DRBG_HASH_SHA224_Get()	Get data from random bitstream.

CRYPTO_DRBG_HASH_SHA224_Init()

Description

Initialize a Hash-DRBG-SHA-224 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA224_Init
                               (      CRYPTO_DRBG_HASH_SHA224_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pNonce,
                                      unsigned                          NonceLen,
                                const U8                              * pPerso,
                                      unsigned                          PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HASH_SHA224_Reseed()

Description

Reseed a HMAC-DRBG-SHA-224 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA224_Reseed
                               (      CRYPTO_DRBG_HASH_SHA224_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pAdd,
                                      unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HASH_SHA224_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HASH_SHA224_Get(      CRYPTO_DRBG_HASH_SHA224_CONTEXT * pSelf,
                                       U8                              * pOutput,
                                       unsigned                          OutputLen,
                                 const U8                              * pAdd,
                                       unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the Hash-DRBG-SHA-224 self-test API functions.

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

CRYPTO_DRBG_HASH_SHA224_CAVS_SelfTest()

Description

Run DRBG-SHA-224 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HASH_SHA224_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Hash-DRBG-SHA-256

Standards reference

Hash-DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HASH_SHA256_Init()	Initialize a Hash-DRBG-SHA-256 random bit generator.
CRYPTO_DRBG_HASH_SHA256_Reseed()	Reseed a HMAC-DRBG-SHA-256 random bit generator.
CRYPTO_DRBG_HASH_SHA256_Get()	Get data from random bitstream.

CRYPTO_DRBG_HASH_SHA256_Init()

Description

Initialize a Hash-DRBG-SHA-256 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA256_Init
                               (      CRYPTO_DRBG_HASH_SHA256_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pNonce,
                                      unsigned                          NonceLen,
                                const U8                              * pPerso,
                                      unsigned                          PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HASH_SHA256_Reseed()

Description

Reseed a HMAC-DRBG-SHA-256 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA256_Reseed
                               (      CRYPTO_DRBG_HASH_SHA256_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pAdd,
                                      unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HASH_SHA256_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HASH_SHA256_Get(      CRYPTO_DRBG_HASH_SHA256_CONTEXT * pSelf,
                                       U8                              * pOutput,
                                       unsigned                          OutputLen,
                                 const U8                              * pAdd,
                                       unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the Hash-DRBG-SHA-256 self-test API functions.

Function	Description
CRYPTO_DRBG_HASH_SHA256_CAVS_SelfTest()	Run DRBG-SHA-256 KATs from CAVS.

CRYPTO_DRBG_HASH_SHA256_CAVS_SelfTest()

Description

Run DRBG-SHA-256 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HASH_SHA256_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Hash-DRBG-SHA-384

Standards reference

Hash-DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HASH_SHA384_Init()	Initialize a Hash-DRBG-SHA-384 random bit generator.
CRYPTO_DRBG_HASH_SHA384_Reseed()	Reseed a HMAC-DRBG-SHA-384 random bit generator.
CRYPTO_DRBG_HASH_SHA384_Get()	Get data from random bitstream.

CRYPTO_DRBG_HASH_SHA384_Init()

Description

Initialize a Hash-DRBG-SHA-384 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA384_Init
                               (      CRYPTO_DRBG_HASH_SHA384_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pNonce,
                                      unsigned                          NonceLen,
                                const U8                              * pPerso,
                                      unsigned                          PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HASH_SHA384_Reseed()

Description

Reseed a HMAC-DRBG-SHA-384 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA384_Reseed
                               (      CRYPTO_DRBG_HASH_SHA384_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pAdd,
                                      unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HASH_SHA384_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HASH_SHA384_Get(      CRYPTO_DRBG_HASH_SHA384_CONTEXT * pSelf,
                                       U8                              * pOutput,
                                       unsigned                          OutputLen,
                                 const U8                              * pAdd,
                                       unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the Hash-DRBG-SHA-384 self-test API functions.

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

CRYPTO_DRBG_HASH_SHA384_CAVS_SelfTest()

Description

Run DRBG-SHA-384 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HASH_SHA384_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Hash-DRBG-SHA-512

Standards reference

Hash-DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HASH_SHA512_Init()	Initialize a Hash-DRBG-SHA-512 random bit generator.
CRYPTO_DRBG_HASH_SHA512_Reseed()	Reseed a HMAC-DRBG-SHA-512 random bit generator.
CRYPTO_DRBG_HASH_SHA512_Get()	Get data from random bitstream.

CRYPTO_DRBG_HASH_SHA512_Init()

Description

Initialize a Hash-DRBG-SHA-512 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA512_Init
                               (      CRYPTO_DRBG_HASH_SHA512_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pNonce,
                                      unsigned                          NonceLen,
                                const U8                              * pPerso,
                                      unsigned                          PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HASH_SHA512_Reseed()

Description

Reseed a HMAC-DRBG-SHA-512 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA512_Reseed
                               (      CRYPTO_DRBG_HASH_SHA512_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pAdd,
                                      unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HASH_SHA512_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HASH_SHA512_Get(      CRYPTO_DRBG_HASH_SHA512_CONTEXT * pSelf,
                                       U8                              * pOutput,
                                       unsigned                          OutputLen,
                                 const U8                              * pAdd,
                                       unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the Hash-DRBG-SHA-512 self-test API functions.

Function	Description
CRYPTO_DRBG_HASH_SHA512_CAVS_SelfTest()	Run DRBG-SHA-512 KATs from CAVS.

CRYPTO_DRBG_HASH_SHA512_CAVS_SelfTest()

Description

Run DRBG-SHA-512 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HASH_SHA512_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Hash-DRBG-SHA-512/224

Standards reference

Hash-DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HASH_SHA512_224_Init()	Initialize a Hash-DRBG-SHA-512/224 random bit generator.
CRYPTO_DRBG_HASH_SHA512_224_Reseed()	Reseed a HMAC-DRBG-SHA-512/224 random bit generator.
CRYPTO_DRBG_HASH_SHA512_224_Get()	Get data from random bitstream.

CRYPTO_DRBG_HASH_SHA512_224_Init()

Description

Initialize a Hash-DRBG-SHA-512/224 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA512_224_Init
                           (      CRYPTO_DRBG_HASH_SHA512_224_CONTEXT * pSelf,
                            const U8                                  * pEntropy,
                                  unsigned                              EntropyLen,
                            const U8                                  * pNonce,
                                  unsigned                              NonceLen,
                            const U8                                  * pPerso,
                                  unsigned                              PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HASH_SHA512_224_Reseed()

Description

Reseed a HMAC-DRBG-SHA-512/224 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA512_224_Reseed
                           (      CRYPTO_DRBG_HASH_SHA512_224_CONTEXT * pSelf,
                            const U8                                  * pEntropy,
                                  unsigned                              EntropyLen,
                            const U8                                  * pAdd,
                                  unsigned                              AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HASH_SHA512_224_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HASH_SHA512_224_Get
                            (      CRYPTO_DRBG_HASH_SHA512_224_CONTEXT * pSelf,
                                   U8                                  * pOutput,
                                   unsigned                              OutputLen,
                             const U8                                  * pAdd,
                                   unsigned                              AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the Hash-DRBG-SHA-512/224 self-test API functions.

Function	Description
CRYPTO_DRBG_HASH_SHA512_224_CAVS_SelfTest()	Run DRBG-SHA-512/224 KATs from CAVS.

CRYPTO_DRBG_HASH_SHA512_224_CAVS_SelfTest()

Description

Run DRBG-SHA-512/224 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HASH_SHA512_224_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Hash-DRBG-SHA-512/256

Standards reference

Hash-DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HASH_SHA512_256_Init()	Initialize a Hash-DRBG-SHA-512/256 random bit generator.
CRYPTO_DRBG_HASH_SHA512_256_Reseed()	Reseed a HMAC-DRBG-SHA-512/256 random bit generator.
CRYPTO_DRBG_HASH_SHA512_256_Get()	Get data from random bitstream.

CRYPTO_DRBG_HASH_SHA512_256_Init()

Description

Initialize a Hash-DRBG-SHA-512/256 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA512_256_Init
                           (      CRYPTO_DRBG_HASH_SHA512_256_CONTEXT * pSelf,
                            const U8                                  * pEntropy,
                                  unsigned                              EntropyLen,
                            const U8                                  * pNonce,
                                  unsigned                              NonceLen,
                            const U8                                  * pPerso,
                                  unsigned                              PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HASH_SHA512_256_Reseed()

Description

Reseed a HMAC-DRBG-SHA-512/256 random bit generator.

Prototype

void CRYPTO_DRBG_HASH_SHA512_256_Reseed
                           (      CRYPTO_DRBG_HASH_SHA512_256_CONTEXT * pSelf,
                            const U8                                  * pEntropy,
                                  unsigned                              EntropyLen,
                            const U8                                  * pAdd,
                                  unsigned                              AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HASH_SHA512_256_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HASH_SHA512_256_Get
                            (      CRYPTO_DRBG_HASH_SHA512_256_CONTEXT * pSelf,
                                   U8                                  * pOutput,
                                   unsigned                              OutputLen,
                             const U8                                  * pAdd,
                                   unsigned                              AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the Hash-DRBG-SHA-512/256 self-test API functions.

Function	Description
CRYPTO_DRBG_HASH_SHA512_256_CAVS_SelfTest()	Run DRBG-SHA-512/256 KATs from CAVS.

CRYPTO_DRBG_HASH_SHA512_256_CAVS_SelfTest()

Description

Run DRBG-SHA-512/256 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HASH_SHA512_256_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-DRBG-SHA-1

Standards reference

HMAC_DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HMAC_SHA1_Init()	Initialize a HMAC-DRBG-SHA-1 random bit generator.
CRYPTO_DRBG_HMAC_SHA1_Reseed()	Reseed a HMAC-DRBG-SHA-1 random bit generator.
CRYPTO_DRBG_HMAC_SHA1_Get()	Get data from random bitstream.

CRYPTO_DRBG_HMAC_SHA1_Init()

Description

Initialize a HMAC-DRBG-SHA-1 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA1_Init(      CRYPTO_DRBG_HMAC_SHA1_CONTEXT * pSelf,
                                const U8                            * pEntropy,
                                      unsigned                        EntropyLen,
                                const U8                            * pNonce,
                                      unsigned                        NonceLen,
                                const U8                            * pPerso,
                                      unsigned                        PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HMAC_SHA1_Reseed()

Description

Reseed a HMAC-DRBG-SHA-1 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA1_Reseed(      CRYPTO_DRBG_HMAC_SHA1_CONTEXT * pSelf,
                                  const U8                            * pEntropy,
                                        unsigned                        EntropyLen,
                                  const U8                            * pAdd,
                                        unsigned                        AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HMAC_SHA1_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HMAC_SHA1_Get(      CRYPTO_DRBG_HMAC_SHA1_CONTEXT * pSelf,
                                     U8                            * pOutput,
                                     unsigned                        OutputLen,
                               const U8                            * pAdd,
                                     unsigned                        AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the HMAC-DRBG-SHA-1 self-test API functions.

Function	Description
CRYPTO_DRBG_HMAC_SHA1_CAVS_SelfTest()	Run DRBG-HMAC-SHA-1 KATs from CAVS.

CRYPTO_DRBG_HMAC_SHA1_CAVS_SelfTest()

Description

Run DRBG-HMAC-SHA-1 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HMAC_SHA1_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-DRBG-SHA-224

Standards reference

HMAC_DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HMAC_SHA224_Init()	Initialize a HMAC-DRBG-SHA-224 random bit generator.
CRYPTO_DRBG_HMAC_SHA224_Reseed()	Reseed a HMAC-DRBG-SHA-224 random bit generator.
CRYPTO_DRBG_HMAC_SHA224_Get()	Get data from random bitstream.

CRYPTO_DRBG_HMAC_SHA224_Init()

Description

Initialize a HMAC-DRBG-SHA-224 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA224_Init
                               (      CRYPTO_DRBG_HMAC_SHA224_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pNonce,
                                      unsigned                          NonceLen,
                                const U8                              * pPerso,
                                      unsigned                          PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HMAC_SHA224_Reseed()

Description

Reseed a HMAC-DRBG-SHA-224 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA224_Reseed
                               (      CRYPTO_DRBG_HMAC_SHA224_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pAdd,
                                      unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HMAC_SHA224_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HMAC_SHA224_Get(      CRYPTO_DRBG_HMAC_SHA224_CONTEXT * pSelf,
                                       U8                              * pOutput,
                                       unsigned                          OutputLen,
                                 const U8                              * pAdd,
                                       unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the HMAC-DRBG-SHA-224 self-test API functions.

Function	Description
CRYPTO_DRBG_HMAC_SHA224_CAVS_SelfTest()	Run DRBG-HMAC-SHA-224 KATs from CAVS.

CRYPTO_DRBG_HMAC_SHA224_CAVS_SelfTest()

Description

Run DRBG-HMAC-SHA-224 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HMAC_SHA224_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-DRBG-SHA-256

Standards reference

HMAC_DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HMAC_SHA256_Init()	Initialize a HMAC-DRBG-SHA-256 random bit generator.
CRYPTO_DRBG_HMAC_SHA256_Reseed()	Reseed a HMAC-DRBG-SHA-256 random bit generator.
CRYPTO_DRBG_HMAC_SHA256_Get()	Get data from random bitstream.

CRYPTO_DRBG_HMAC_SHA256_Init()

Description

Initialize a HMAC-DRBG-SHA-256 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA256_Init
                               (      CRYPTO_DRBG_HMAC_SHA256_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pNonce,
                                      unsigned                          NonceLen,
                                const U8                              * pPerso,
                                      unsigned                          PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HMAC_SHA256_Reseed()

Description

Reseed a HMAC-DRBG-SHA-256 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA256_Reseed
                               (      CRYPTO_DRBG_HMAC_SHA256_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pAdd,
                                      unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HMAC_SHA256_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HMAC_SHA256_Get(      CRYPTO_DRBG_HMAC_SHA256_CONTEXT * pSelf,
                                       U8                              * pOutput,
                                       unsigned                          OutputLen,
                                 const U8                              * pAdd,
                                       unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the HMAC-DRBG-SHA-256 self-test API functions.

Function	Description
CRYPTO_DRBG_HMAC_SHA256_CAVS_SelfTest()	Run DRBG-HMAC-SHA-256 KATs from CAVS.

CRYPTO_DRBG_HMAC_SHA256_CAVS_SelfTest()

Description

Run DRBG-HMAC-SHA-256 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HMAC_SHA256_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-DRBG-SHA-384

Standards reference

HMAC_DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HMAC_SHA384_Init()	Initialize a HMAC-DRBG-SHA-384 random bit generator.
CRYPTO_DRBG_HMAC_SHA384_Reseed()	Reseed a HMAC-DRBG-SHA-384 random bit generator.
CRYPTO_DRBG_HMAC_SHA384_Get()	Get data from random bitstream.

CRYPTO_DRBG_HMAC_SHA384_Init()

Description

Initialize a HMAC-DRBG-SHA-384 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA384_Init
                               (      CRYPTO_DRBG_HMAC_SHA384_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pNonce,
                                      unsigned                          NonceLen,
                                const U8                              * pPerso,
                                      unsigned                          PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HMAC_SHA384_Reseed()

Description

Reseed a HMAC-DRBG-SHA-384 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA384_Reseed
                               (      CRYPTO_DRBG_HMAC_SHA384_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pAdd,
                                      unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HMAC_SHA384_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HMAC_SHA384_Get(      CRYPTO_DRBG_HMAC_SHA384_CONTEXT * pSelf,
                                       U8                              * pOutput,
                                       unsigned                          OutputLen,
                                 const U8                              * pAdd,
                                       unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the HMAC-DRBG-SHA-384 self-test API functions.

Function	Description
CRYPTO_DRBG_HMAC_SHA384_CAVS_SelfTest()	Run DRBG-HMAC-SHA-384 KATs from CAVS.

CRYPTO_DRBG_HMAC_SHA384_CAVS_SelfTest()

Description

Run DRBG-HMAC-SHA-384 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HMAC_SHA384_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-DRBG-SHA-512

Standards reference

HMAC_DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HMAC_SHA512_Init()	Initialize a HMAC-DRBG-SHA-512 random bit generator.
CRYPTO_DRBG_HMAC_SHA512_Reseed()	Reseed a HMAC-DRBG-SHA-512 random bit generator.
CRYPTO_DRBG_HMAC_SHA512_Get()	Get data from random bitstream.

CRYPTO_DRBG_HMAC_SHA512_Init()

Description

Initialize a HMAC-DRBG-SHA-512 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_Init
                               (      CRYPTO_DRBG_HMAC_SHA512_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pNonce,
                                      unsigned                          NonceLen,
                                const U8                              * pPerso,
                                      unsigned                          PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HMAC_SHA512_Reseed()

Description

Reseed a HMAC-DRBG-SHA-512 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_Reseed
                               (      CRYPTO_DRBG_HMAC_SHA512_CONTEXT * pSelf,
                                const U8                              * pEntropy,
                                      unsigned                          EntropyLen,
                                const U8                              * pAdd,
                                      unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HMAC_SHA512_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_Get(      CRYPTO_DRBG_HMAC_SHA512_CONTEXT * pSelf,
                                       U8                              * pOutput,
                                       unsigned                          OutputLen,
                                 const U8                              * pAdd,
                                       unsigned                          AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the HMAC-DRBG-SHA-512 self-test API functions.

Function	Description
CRYPTO_DRBG_HMAC_SHA512_CAVS_SelfTest()	Run DRBG-HMAC-SHA-512 KATs from CAVS.

CRYPTO_DRBG_HMAC_SHA512_CAVS_SelfTest()

Description

Run DRBG-HMAC-SHA-512 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-DRBG-SHA-512/224

Standards reference

HMAC_DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HMAC_SHA512_224_Init()	Initialize a HMAC-DRBG-SHA-512/224 random bit generator.
CRYPTO_DRBG_HMAC_SHA512_224_Reseed()	Reseed a HMAC-DRBG-SHA-512/224 random bit generator.
CRYPTO_DRBG_HMAC_SHA512_224_Get()	Get data from random bitstream.

CRYPTO_DRBG_HMAC_SHA512_224_Init()

Description

Initialize a HMAC-DRBG-SHA-512/224 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_224_Init
                           (      CRYPTO_DRBG_HMAC_SHA512_224_CONTEXT * pSelf,
                            const U8                                  * pEntropy,
                                  unsigned                              EntropyLen,
                            const U8                                  * pNonce,
                                  unsigned                              NonceLen,
                            const U8                                  * pPerso,
                                  unsigned                              PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HMAC_SHA512_224_Reseed()

Description

Reseed a HMAC-DRBG-SHA-512/224 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_224_Reseed
                           (      CRYPTO_DRBG_HMAC_SHA512_224_CONTEXT * pSelf,
                            const U8                                  * pEntropy,
                                  unsigned                              EntropyLen,
                            const U8                                  * pAdd,
                                  unsigned                              AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HMAC_SHA512_224_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_224_Get
                            (      CRYPTO_DRBG_HMAC_SHA512_224_CONTEXT * pSelf,
                                   U8                                  * pOutput,
                                   unsigned                              OutputLen,
                             const U8                                  * pAdd,
                                   unsigned                              AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the HMAC-DRBG-SHA-512/224 self-test API functions.

Function	Description
CRYPTO_DRBG_HMAC_SHA512_224_CAVS_SelfTest()	Run DRBG-HMAC-SHA-512/224 KATs from CAVS.

CRYPTO_DRBG_HMAC_SHA512_224_CAVS_SelfTest()

Description

Run DRBG-HMAC-SHA-512/224 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_224_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

HMAC-DRBG-SHA-512/256

Standards reference

HMAC_DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_HMAC_SHA512_256_Init()	Initialize a HMAC-DRBG-SHA-512/256 random bit generator.
CRYPTO_DRBG_HMAC_SHA512_256_Reseed()	Reseed a HMAC-DRBG-SHA-512/256 random bit generator.
CRYPTO_DRBG_HMAC_SHA512_256_Get()	Get data from random bitstream.

CRYPTO_DRBG_HMAC_SHA512_256_Init()

Description

Initialize a HMAC-DRBG-SHA-512/256 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_256_Init
                           (      CRYPTO_DRBG_HMAC_SHA512_256_CONTEXT * pSelf,
                            const U8                                  * pEntropy,
                                  unsigned                              EntropyLen,
                            const U8                                  * pNonce,
                                  unsigned                              NonceLen,
                            const U8                                  * pPerso,
                                  unsigned                              PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_HMAC_SHA512_256_Reseed()

Description

Reseed a HMAC-DRBG-SHA-512/256 random bit generator.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_256_Reseed
                           (      CRYPTO_DRBG_HMAC_SHA512_256_CONTEXT * pSelf,
                            const U8                                  * pEntropy,
                                  unsigned                              EntropyLen,
                            const U8                                  * pAdd,
                                  unsigned                              AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_HMAC_SHA512_256_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_256_Get
                            (      CRYPTO_DRBG_HMAC_SHA512_256_CONTEXT * pSelf,
                                   U8                                  * pOutput,
                                   unsigned                              OutputLen,
                             const U8                                  * pAdd,
                                   unsigned                              AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the HMAC-DRBG-SHA-512/256 self-test API functions.

Function	Description
CRYPTO_DRBG_HMAC_SHA512_256_CAVS_SelfTest()	Run DRBG-HMAC-SHA-512/256 KATs from CAVS.

CRYPTO_DRBG_HMAC_SHA512_256_CAVS_SelfTest()

Description

Run DRBG-HMAC-SHA-512/256 KATs from CAVS.

Prototype

void CRYPTO_DRBG_HMAC_SHA512_256_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CTR-DRBG-TDES

Standards reference

CTR_DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_CTR_TDES_Init()	Initialize a CTR-DRBG-TDES random bit generator.
CRYPTO_DRBG_CTR_TDES_Reseed()	Reseed a CTR-DRBG-TDES random bit generator.
CRYPTO_DRBG_CTR_TDES_Get()	Get data from random bitstream.

CRYPTO_DRBG_CTR_TDES_Init()

Description

Initialize a CTR-DRBG-TDES random bit generator.

Prototype

void CRYPTO_DRBG_CTR_TDES_Init(      CRYPTO_DRBG_CTR_TDES_CONTEXT * pSelf,
                               const U8                           * pEntropy,
                                     unsigned                       EntropyLen,
                               const U8                           * pNonce,
                                     unsigned                       NonceLen,
                               const U8                           * pPerso,
                                     unsigned                       PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_CTR_TDES_Reseed()

Description

Reseed a CTR-DRBG-TDES random bit generator.

Prototype

void CRYPTO_DRBG_CTR_TDES_Reseed(      CRYPTO_DRBG_CTR_TDES_CONTEXT * pSelf,
                                 const U8                           * pEntropy,
                                       unsigned                       EntropyLen,
                                 const U8                           * pAdd,
                                       unsigned                       AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_CTR_TDES_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_CTR_TDES_Get(      CRYPTO_DRBG_CTR_TDES_CONTEXT * pSelf,
                                    U8                           * pOutput,
                                    unsigned                       OutputLen,
                              const U8                           * pAdd,
                                    unsigned                       AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the DRBG-CTR-TDES self-test API functions.

Function	Description
CRYPTO_DRBG_CTR_TDES_CAVS_SelfTest()	Run DRBG-CTR-TDES KATs from CAVS.

CRYPTO_DRBG_CTR_TDES_CAVS_SelfTest()

Description

Run DRBG-CTR-TDES KATs from CAVS.

Prototype

void CRYPTO_DRBG_CTR_TDES_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CTR-DRBG-AES-128

Standards reference

CTR_DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_CTR_AES128_Init()	Initialize a CTR-DRBG-AES-128 random bit generator.
CRYPTO_DRBG_CTR_AES128_Reseed()	Reseed a CTR-DRBG-AES-128 random bit generator.
CRYPTO_DRBG_CTR_AES128_Get()	Get data from random bitstream.

CRYPTO_DRBG_CTR_AES128_Init()

Description

Initialize a CTR-DRBG-AES-128 random bit generator.

Prototype

void CRYPTO_DRBG_CTR_AES128_Init(      CRYPTO_DRBG_CTR_AES128_CONTEXT * pSelf,
                                 const U8                             * pEntropy,
                                       unsigned                         EntropyLen,
                                 const U8                             * pNonce,
                                       unsigned                         NonceLen,
                                 const U8                             * pPerso,
                                       unsigned                         PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_CTR_AES128_Reseed()

Description

Reseed a CTR-DRBG-AES-128 random bit generator.

Prototype

void CRYPTO_DRBG_CTR_AES128_Reseed
                                (      CRYPTO_DRBG_CTR_AES128_CONTEXT * pSelf,
                                 const U8                             * pEntropy,
                                       unsigned                         EntropyLen,
                                 const U8                             * pAdd,
                                       unsigned                         AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_CTR_AES128_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_CTR_AES128_Get(      CRYPTO_DRBG_CTR_AES128_CONTEXT * pSelf,
                                      U8                             * pOutput,
                                      unsigned                         OutputLen,
                                const U8                             * pAdd,
                                      unsigned                         AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the DRBG-CTR-AES-128 self-test API functions.

Function	Description
CRYPTO_DRBG_CTR_AES128_CAVS_SelfTest()	Run DRBG-CTR-AES-128 KATs from CAVS.

CRYPTO_DRBG_CTR_AES128_CAVS_SelfTest()

Description

Run DRBG-CTR-AES-128 KATs from CAVS.

Prototype

void CRYPTO_DRBG_CTR_AES128_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CTR-DRBG-AES-192

Standards reference

CTR_DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_CTR_AES192_Init()	Initialize a CTR-DRBG-AES-192 random bit generator.
CRYPTO_DRBG_CTR_AES192_Reseed()	Reseed a CTR-DRBG-AES-192 random bit generator.
CRYPTO_DRBG_CTR_AES192_Get()	Get data from random bitstream.

CRYPTO_DRBG_CTR_AES192_Init()

Description

Initialize a CTR-DRBG-AES-192 random bit generator.

Prototype

void CRYPTO_DRBG_CTR_AES192_Init(      CRYPTO_DRBG_CTR_AES192_CONTEXT * pSelf,
                                 const U8                             * pEntropy,
                                       unsigned                         EntropyLen,
                                 const U8                             * pNonce,
                                       unsigned                         NonceLen,
                                 const U8                             * pPerso,
                                       unsigned                         PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_CTR_AES192_Reseed()

Description

Reseed a CTR-DRBG-AES-192 random bit generator.

Prototype

void CRYPTO_DRBG_CTR_AES192_Reseed
                                (      CRYPTO_DRBG_CTR_AES192_CONTEXT * pSelf,
                                 const U8                             * pEntropy,
                                       unsigned                         EntropyLen,
                                 const U8                             * pAdd,
                                       unsigned                         AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_CTR_AES192_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_CTR_AES192_Get(      CRYPTO_DRBG_CTR_AES192_CONTEXT * pSelf,
                                      U8                             * pOutput,
                                      unsigned                         OutputLen,
                                const U8                             * pAdd,
                                      unsigned                         AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the DRBG-CTR-AES-192 self-test API functions.

Function	Description
CRYPTO_DRBG_CTR_AES192_CAVS_SelfTest()	Run DRBG-CTR-AES-192 KATs from CAVS.

CRYPTO_DRBG_CTR_AES192_CAVS_SelfTest()

Description

Run DRBG-CTR-AES-192 KATs from CAVS.

Prototype

void CRYPTO_DRBG_CTR_AES192_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

CTR-DRBG-AES-256

Standards reference

CTR_DRBG is specified by the following document:

• NIST SP 800-90A — Recommendation for Random Number Generation Using Deterministic Random Bit Generators

Type-safe API

Function	Description
CRYPTO_DRBG_CTR_AES256_Init()	Initialize a CTR-DRBG-AES-265 random bit generator.
CRYPTO_DRBG_CTR_AES256_Reseed()	Reseed a CTR-DRBG-AES-265 random bit generator.
CRYPTO_DRBG_CTR_AES256_Get()	Get data from random bitstream.

CRYPTO_DRBG_CTR_AES256_Init()

Description

Initialize a CTR-DRBG-AES-265 random bit generator.

Prototype

void CRYPTO_DRBG_CTR_AES256_Init(      CRYPTO_DRBG_CTR_AES256_CONTEXT * pSelf,
                                 const U8                             * pEntropy,
                                       unsigned                         EntropyLen,
                                 const U8                             * pNonce,
                                       unsigned                         NonceLen,
                                 const U8                             * pPerso,
                                       unsigned                         PersoLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input octet string.
EntropyLen	Octet length of the entropy input octet string.
pNonce	Pointer to nonce octet string.
NonceLen	Octet length of the nonce octet string.
pPerso	Pointer to personalization octet string.
PersoLen	Octet length of the personalization octet string.

CRYPTO_DRBG_CTR_AES256_Reseed()

Description

Reseed a CTR-DRBG-AES-265 random bit generator.

Prototype

void CRYPTO_DRBG_CTR_AES256_Reseed
                                (      CRYPTO_DRBG_CTR_AES256_CONTEXT * pSelf,
                                 const U8                             * pEntropy,
                                       unsigned                         EntropyLen,
                                 const U8                             * pAdd,
                                       unsigned                         AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pEntropy	Pointer to initial entropy input string.
EntropyLen	Octet length of the entropy input octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

CRYPTO_DRBG_CTR_AES256_Get()

Description

Get data from random bitstream.

Prototype

void CRYPTO_DRBG_CTR_AES256_Get(      CRYPTO_DRBG_CTR_AES256_CONTEXT * pSelf,
                                      U8                             * pOutput,
                                      unsigned                         OutputLen,
                                const U8                             * pAdd,
                                      unsigned                         AddLen);

Parameters

Parameter	Description
pSelf	Pointer to DRBG context.
pOutput	Pointer to object that receives the random data.
OutputLen	Octet length of the random data octet string.
pAdd	Pointer to additional input octet string.
AddLen	Octet length of the additional input octet string.

Self-test API

The following table lists the DRBG-CTR-AES-256 self-test API functions.

Function	Description
CRYPTO_DRBG_CTR_AES256_CAVS_SelfTest()	Run DRBG-CTR-AES-256 KATs from CAVS.

CRYPTO_DRBG_CTR_AES256_CAVS_SelfTest()

Description

Run DRBG-CTR-AES-256 KATs from CAVS.

Prototype

void CRYPTO_DRBG_CTR_AES256_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

Key derivation

emCrypt implements the following key derivation algorithms:

• KDF1
• KDF2
• X9.63 KDF
• HKDF
• PBKDF2

Although NIST has recommendation for other key derivation algorithms, such as the IKE, TLS, and SSH key derivation functions, these key derivation functions are recommended by NIST only in their specific application domain. Therefore emCrypt does not provide these functions and leaves it to individual products to implement any application-specific key derivation function.

KDF1

Standards reference

KDF1 is specified by the following documents:

• ISO/IEC 18033-2 — Encryption algorithms — Part 2: Asymmetric ciphers
• IEEE Std 1363-2000 — IEEE Standard Specifications for Public-Key Cryptography
• IETF RFC 8017 — PKCS #1: RSA Cryptography Specifications Version 2.2

Alternative naming

The function KDF1 is also known as MGF1 in P1363, PKCS #1, and some other standards. MGF1 and KDF1 are identical.

Type-safe API

Function	Description
Plain key derivation
CRYPTO_KDF1_SHA1_Calc()	Derive key using KDF1-SHA-1.
CRYPTO_KDF1_SHA224_Calc()	Derive key using KDF1-SHA-224.
CRYPTO_KDF1_SHA256_Calc()	Derive key using KDF1-SHA-256.
CRYPTO_KDF1_SHA384_Calc()	Derive key using KDF1-SHA-384.
CRYPTO_KDF1_SHA512_Calc()	Derive key using KDF1-SHA-512.
CRYPTO_KDF1_SHA512_224_Calc()	Derive key using KDF1-SHA-512/224.
CRYPTO_KDF1_SHA512_256_Calc()	Derive key using KDF1-SHA-512/256.
CRYPTO_KDF1_SHA3_224_Calc()	Derive key using KDF1-SHA-224.
CRYPTO_KDF1_SHA3_256_Calc()	Derive key using KDF1-SHA-256.
CRYPTO_KDF1_SHA3_384_Calc()	Derive key using KDF1-SHA-384.
CRYPTO_KDF1_SHA3_512_Calc()	Derive key using KDF1-SHA-512.
CRYPTO_KDF1_SM3_Calc()	Derive key using KDF1-SM3.
CRYPTO_KDF1_BLAKE2B_Calc()	Derive key using KDF1-BLAKE2b.
CRYPTO_KDF1_BLAKE2S_Calc()	Derive key using KDF1-BLAKE2s.
Derive key and combine
CRYPTO_KDF1_SHA1_CalcEx()	Derive key using KDF1-SHA-1, combine output.
CRYPTO_KDF1_SHA224_CalcEx()	Derive key using KDF1-SHA-224, combine output.
CRYPTO_KDF1_SHA256_CalcEx()	Derive key using KDF1-SHA-256, combine output.
CRYPTO_KDF1_SHA384_CalcEx()	Derive key using KDF1-SHA-384, combine output.
CRYPTO_KDF1_SHA512_CalcEx()	Derive key using KDF1-SHA-512, combine output.
CRYPTO_KDF1_SHA512_224_CalcEx()	Derive key using KDF1-SHA-512/224, combine output.
CRYPTO_KDF1_SHA512_256_CalcEx()	Derive key using KDF1-SHA-512/256, combine output.
CRYPTO_KDF1_SHA3_224_CalcEx()	Derive key using KDF1-SHA-224, combine output.
CRYPTO_KDF1_SHA3_256_CalcEx()	Derive key using KDF1-SHA-256, combine output.
CRYPTO_KDF1_SHA3_384_CalcEx()	Derive key using KDF1-SHA-384, combine output.
CRYPTO_KDF1_SHA3_512_CalcEx()	Derive key using KDF1-SHA-512, combine output.
CRYPTO_KDF1_SM3_CalcEx()	Derive key using KDF1-SM3, combine output.
CRYPTO_KDF1_BLAKE2B_CalcEx()	Derive key using KDF1-BLAKE2b, combine output.
CRYPTO_KDF1_BLAKE2S_CalcEx()	Derive key using KDF1-BLAKE2s, combine output.

CRYPTO_KDF1_SHA1_Calc()

Description

Derive key using KDF1-SHA-1.

Prototype

void CRYPTO_KDF1_SHA1_Calc(const U8       * pSeed,
                                 unsigned   SeedLen,
                                 U8       * pOutput,
                                 unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SHA1_CalcEx()

Description

Derive key using KDF1-SHA-1, combine output.

Prototype

void CRYPTO_KDF1_SHA1_CalcEx(const U8              * pSeed,
                                   unsigned          SeedLen,
                                   U8              * pOutput,
                                   unsigned          OutputLen,
                                   CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_SHA224_Calc()

Description

Derive key using KDF1-SHA-224.

Prototype

void CRYPTO_KDF1_SHA224_Calc(const U8       * pSeed,
                                   unsigned   SeedLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SHA224_CalcEx()

Description

Derive key using KDF1-SHA-224, combine output.

Prototype

void CRYPTO_KDF1_SHA224_CalcEx(const U8              * pSeed,
                                     unsigned          SeedLen,
                                     U8              * pOutput,
                                     unsigned          OutputLen,
                                     CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_SHA256_Calc()

Description

Derive key using KDF1-SHA-256.

Prototype

void CRYPTO_KDF1_SHA256_Calc(const U8       * pSeed,
                                   unsigned   SeedLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SHA256_CalcEx()

Description

Derive key using KDF1-SHA-256, combine output.

Prototype

void CRYPTO_KDF1_SHA256_CalcEx(const U8              * pSeed,
                                     unsigned          SeedLen,
                                     U8              * pOutput,
                                     unsigned          OutputLen,
                                     CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_SHA384_Calc()

Description

Derive key using KDF1-SHA-384.

Prototype

void CRYPTO_KDF1_SHA384_Calc(const U8       * pSeed,
                                   unsigned   SeedLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SHA384_CalcEx()

Description

Derive key using KDF1-SHA-384, combine output.

Prototype

void CRYPTO_KDF1_SHA384_CalcEx(const U8              * pSeed,
                                     unsigned          SeedLen,
                                     U8              * pOutput,
                                     unsigned          OutputLen,
                                     CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_SHA512_Calc()

Description

Derive key using KDF1-SHA-512.

Prototype

void CRYPTO_KDF1_SHA512_Calc(const U8       * pSeed,
                                   unsigned   SeedLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SHA512_CalcEx()

Description

Derive key using KDF1-SHA-512, combine output.

Prototype

void CRYPTO_KDF1_SHA512_CalcEx(const U8              * pSeed,
                                     unsigned          SeedLen,
                                     U8              * pOutput,
                                     unsigned          OutputLen,
                                     CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_SHA512_224_Calc()

Description

Derive key using KDF1-SHA-512/224.

Prototype

void CRYPTO_KDF1_SHA512_224_Calc(const U8       * pSeed,
                                       unsigned   SeedLen,
                                       U8       * pOutput,
                                       unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SHA512_224_CalcEx()

Description

Derive key using KDF1-SHA-512/224, combine output.

Prototype

void CRYPTO_KDF1_SHA512_224_CalcEx(const U8              * pSeed,
                                         unsigned          SeedLen,
                                         U8              * pOutput,
                                         unsigned          OutputLen,
                                         CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_SHA512_256_Calc()

Description

Derive key using KDF1-SHA-512/256.

Prototype

void CRYPTO_KDF1_SHA512_256_Calc(const U8       * pSeed,
                                       unsigned   SeedLen,
                                       U8       * pOutput,
                                       unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SHA512_256_CalcEx()

Description

Derive key using KDF1-SHA-512/256, combine output.

Prototype

void CRYPTO_KDF1_SHA512_256_CalcEx(const U8              * pSeed,
                                         unsigned          SeedLen,
                                         U8              * pOutput,
                                         unsigned          OutputLen,
                                         CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_SHA3_224_Calc()

Description

Derive key using KDF1-SHA-224.

Prototype

void CRYPTO_KDF1_SHA3_224_Calc(const U8       * pSeed,
                                     unsigned   SeedLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SHA3_224_CalcEx()

Description

Derive key using KDF1-SHA-224, combine output.

Prototype

void CRYPTO_KDF1_SHA3_224_CalcEx(const U8              * pSeed,
                                       unsigned          SeedLen,
                                       U8              * pOutput,
                                       unsigned          OutputLen,
                                       CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_SHA3_256_Calc()

Description

Derive key using KDF1-SHA-256.

Prototype

void CRYPTO_KDF1_SHA3_256_Calc(const U8       * pSeed,
                                     unsigned   SeedLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SHA3_256_CalcEx()

Description

Derive key using KDF1-SHA-256, combine output.

Prototype

void CRYPTO_KDF1_SHA3_256_CalcEx(const U8              * pSeed,
                                       unsigned          SeedLen,
                                       U8              * pOutput,
                                       unsigned          OutputLen,
                                       CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_SHA3_384_Calc()

Description

Derive key using KDF1-SHA-384.

Prototype

void CRYPTO_KDF1_SHA3_384_Calc(const U8       * pSeed,
                                     unsigned   SeedLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SHA3_384_CalcEx()

Description

Derive key using KDF1-SHA-384, combine output.

Prototype

void CRYPTO_KDF1_SHA3_384_CalcEx(const U8              * pSeed,
                                       unsigned          SeedLen,
                                       U8              * pOutput,
                                       unsigned          OutputLen,
                                       CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_SHA3_512_Calc()

Description

Derive key using KDF1-SHA-512.

Prototype

void CRYPTO_KDF1_SHA3_512_Calc(const U8       * pSeed,
                                     unsigned   SeedLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SHA3_512_CalcEx()

Description

Derive key using KDF1-SHA-512, combine output.

Prototype

void CRYPTO_KDF1_SHA3_512_CalcEx(const U8              * pSeed,
                                       unsigned          SeedLen,
                                       U8              * pOutput,
                                       unsigned          OutputLen,
                                       CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_SM3_Calc()

Description

Derive key using KDF1-SM3.

Prototype

void CRYPTO_KDF1_SM3_Calc(const U8       * pSeed,
                                unsigned   SeedLen,
                                U8       * pOutput,
                                unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_SM3_CalcEx()

Description

Derive key using KDF1-SM3, combine output.

Prototype

void CRYPTO_KDF1_SM3_CalcEx(const U8              * pSeed,
                                  unsigned          SeedLen,
                                  U8              * pOutput,
                                  unsigned          OutputLen,
                                  CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_BLAKE2B_Calc()

Description

Derive key using KDF1-BLAKE2b.

Prototype

void CRYPTO_KDF1_BLAKE2B_Calc(const U8       * pSeed,
                                    unsigned   SeedLen,
                                    U8       * pOutput,
                                    unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_BLAKE2B_CalcEx()

Description

Derive key using KDF1-BLAKE2b, combine output.

Prototype

void CRYPTO_KDF1_BLAKE2B_CalcEx(const U8              * pSeed,
                                      unsigned          SeedLen,
                                      U8              * pOutput,
                                      unsigned          OutputLen,
                                      CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF1_BLAKE2S_Calc()

Description

Derive key using KDF1-BLAKE2s.

Prototype

void CRYPTO_KDF1_BLAKE2S_Calc(const U8       * pSeed,
                                    unsigned   SeedLen,
                                    U8       * pOutput,
                                    unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF1_BLAKE2S_CalcEx()

Description

Derive key using KDF1-BLAKE2s, combine output.

Prototype

void CRYPTO_KDF1_BLAKE2S_CalcEx(const U8              * pSeed,
                                      unsigned          SeedLen,
                                      U8              * pOutput,
                                      unsigned          OutputLen,
                                      CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

KDF2

Standards reference

KDF2 is specified by the following documents:

• ISO/IEC 18033-2 — Encryption algorithms — Part 2: Asymmetric ciphers
• IEEE Std 1363-2000 — IEEE Standard Specifications for Public-Key Cryptography

Type-safe API

Function	Description
CRYPTO_KDF2_SHA1_Calc()	Derive key using KDF2-SHA-1.
CRYPTO_KDF2_SHA224_Calc()	Derive key using KDF2-SHA-224.
CRYPTO_KDF2_SHA256_Calc()	Derive key using KDF2-SHA-256.
CRYPTO_KDF2_SHA384_Calc()	Derive key using KDF2-SHA-384.
CRYPTO_KDF2_SHA512_Calc()	Derive key using KDF2-SHA-512.
CRYPTO_KDF2_SHA512_224_Calc()	Derive key using KDF2-SHA-512/224.
CRYPTO_KDF2_SHA512_256_Calc()	Derive key using KDF2-SHA-512/256.
CRYPTO_KDF2_SHA3_224_Calc()	Derive key using KDF2-SHA3-224.
CRYPTO_KDF2_SHA3_256_Calc()	Derive key using KDF2-SHA3-256.
CRYPTO_KDF2_SHA3_384_Calc()	Derive key using KDF2-SHA3-384.
CRYPTO_KDF2_SHA3_512_Calc()	Derive key using KDF2-SHA3-512.
CRYPTO_KDF2_SM3_Calc()	Derive key using KDF2-SM3.
CRYPTO_KDF2_BLAKE2B_Calc()	Derive key using KDF2-BLAKE2b.
CRYPTO_KDF2_BLAKE2S_Calc()	Derive key using KDF2-BLAKE2s.
Derive key and combine
CRYPTO_KDF2_SHA1_CalcEx()	Derive key using KDF2-SHA-1, combine output.
CRYPTO_KDF2_SHA224_CalcEx()	Derive key using KDF2-SHA-224, combine output.
CRYPTO_KDF2_SHA256_CalcEx()	Derive key using KDF2-SHA-256, combine output.
CRYPTO_KDF2_SHA384_CalcEx()	Derive key using KDF2-SHA-384, combine output.
CRYPTO_KDF2_SHA512_CalcEx()	Derive key using KDF2-SHA-512, combine output.
CRYPTO_KDF2_SHA512_224_CalcEx()	Derive key using KDF2-SHA-512/224, combine output.
CRYPTO_KDF2_SHA512_256_CalcEx()	Derive key using KDF2-SHA-512/256, combine output.
CRYPTO_KDF2_SHA3_224_CalcEx()	Derive key using KDF2-SHA3-224, combine output.
CRYPTO_KDF2_SHA3_256_CalcEx()	Derive key using KDF2-SHA3-256, combine output.
CRYPTO_KDF2_SHA3_384_CalcEx()	Derive key using KDF2-SHA3-384, combine output.
CRYPTO_KDF2_SHA3_512_CalcEx()	Derive key using KDF2-SHA3-512, combine output.
CRYPTO_KDF2_SM3_CalcEx()	Derive key using KDF2-SM3, combine output.
CRYPTO_KDF2_BLAKE2B_CalcEx()	Derive key using KDF2-BLAKE2b, combine output.
CRYPTO_KDF2_BLAKE2S_CalcEx()	Derive key using KDF2-BLAKE2s, combine output.

CRYPTO_KDF2_SHA1_Calc()

Description

Derive key using KDF2-SHA-1.

Prototype

void CRYPTO_KDF2_SHA1_Calc(const U8       * pSeed,
                                 unsigned   SeedLen,
                                 U8       * pOutput,
                                 unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SHA1_CalcEx()

Description

Derive key using KDF2-SHA-1, combine output.

Prototype

void CRYPTO_KDF2_SHA1_CalcEx(const U8              * pSeed,
                                   unsigned          SeedLen,
                                   U8              * pOutput,
                                   unsigned          OutputLen,
                                   CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_SHA224_Calc()

Description

Derive key using KDF2-SHA-224.

Prototype

void CRYPTO_KDF2_SHA224_Calc(const U8       * pSeed,
                                   unsigned   SeedLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SHA224_CalcEx()

Description

Derive key using KDF2-SHA-224, combine output.

Prototype

void CRYPTO_KDF2_SHA224_CalcEx(const U8              * pSeed,
                                     unsigned          SeedLen,
                                     U8              * pOutput,
                                     unsigned          OutputLen,
                                     CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_SHA256_Calc()

Description

Derive key using KDF2-SHA-256.

Prototype

void CRYPTO_KDF2_SHA256_Calc(const U8       * pSeed,
                                   unsigned   SeedLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SHA256_CalcEx()

Description

Derive key using KDF2-SHA-256, combine output.

Prototype

void CRYPTO_KDF2_SHA256_CalcEx(const U8              * pSeed,
                                     unsigned          SeedLen,
                                     U8              * pOutput,
                                     unsigned          OutputLen,
                                     CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_SHA384_Calc()

Description

Derive key using KDF2-SHA-384.

Prototype

void CRYPTO_KDF2_SHA384_Calc(const U8       * pSeed,
                                   unsigned   SeedLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SHA384_CalcEx()

Description

Derive key using KDF2-SHA-384, combine output.

Prototype

void CRYPTO_KDF2_SHA384_CalcEx(const U8              * pSeed,
                                     unsigned          SeedLen,
                                     U8              * pOutput,
                                     unsigned          OutputLen,
                                     CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_SHA512_Calc()

Description

Derive key using KDF2-SHA-512.

Prototype

void CRYPTO_KDF2_SHA512_Calc(const U8       * pSeed,
                                   unsigned   SeedLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SHA512_CalcEx()

Description

Derive key using KDF2-SHA-512, combine output.

Prototype

void CRYPTO_KDF2_SHA512_CalcEx(const U8              * pSeed,
                                     unsigned          SeedLen,
                                     U8              * pOutput,
                                     unsigned          OutputLen,
                                     CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_SHA512_224_Calc()

Description

Derive key using KDF2-SHA-512/224.

Prototype

void CRYPTO_KDF2_SHA512_224_Calc(const U8       * pSeed,
                                       unsigned   SeedLen,
                                       U8       * pOutput,
                                       unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SHA512_224_CalcEx()

Description

Derive key using KDF2-SHA-512/224, combine output.

Prototype

void CRYPTO_KDF2_SHA512_224_CalcEx(const U8              * pSeed,
                                         unsigned          SeedLen,
                                         U8              * pOutput,
                                         unsigned          OutputLen,
                                         CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_SHA512_256_Calc()

Description

Derive key using KDF2-SHA-512/256.

Prototype

void CRYPTO_KDF2_SHA512_256_Calc(const U8       * pSeed,
                                       unsigned   SeedLen,
                                       U8       * pOutput,
                                       unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SHA512_256_CalcEx()

Description

Derive key using KDF2-SHA-512/256, combine output.

Prototype

void CRYPTO_KDF2_SHA512_256_CalcEx(const U8              * pSeed,
                                         unsigned          SeedLen,
                                         U8              * pOutput,
                                         unsigned          OutputLen,
                                         CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_SHA3_224_Calc()

Description

Derive key using KDF2-SHA3-224.

Prototype

void CRYPTO_KDF2_SHA3_224_Calc(const U8       * pSeed,
                                     unsigned   SeedLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SHA3_224_CalcEx()

Description

Derive key using KDF2-SHA3-224, combine output.

Prototype

void CRYPTO_KDF2_SHA3_224_CalcEx(const U8              * pSeed,
                                       unsigned          SeedLen,
                                       U8              * pOutput,
                                       unsigned          OutputLen,
                                       CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_SHA3_256_Calc()

Description

Derive key using KDF2-SHA3-256.

Prototype

void CRYPTO_KDF2_SHA3_256_Calc(const U8       * pSeed,
                                     unsigned   SeedLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SHA3_256_CalcEx()

Description

Derive key using KDF2-SHA3-256, combine output.

Prototype

void CRYPTO_KDF2_SHA3_256_CalcEx(const U8              * pSeed,
                                       unsigned          SeedLen,
                                       U8              * pOutput,
                                       unsigned          OutputLen,
                                       CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_SHA3_384_Calc()

Description

Derive key using KDF2-SHA3-384.

Prototype

void CRYPTO_KDF2_SHA3_384_Calc(const U8       * pSeed,
                                     unsigned   SeedLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SHA3_384_CalcEx()

Description

Derive key using KDF2-SHA3-384, combine output.

Prototype

void CRYPTO_KDF2_SHA3_384_CalcEx(const U8              * pSeed,
                                       unsigned          SeedLen,
                                       U8              * pOutput,
                                       unsigned          OutputLen,
                                       CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_SHA3_512_Calc()

Description

Derive key using KDF2-SHA3-512.

Prototype

void CRYPTO_KDF2_SHA3_512_Calc(const U8       * pSeed,
                                     unsigned   SeedLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SHA3_512_CalcEx()

Description

Derive key using KDF2-SHA3-512, combine output.

Prototype

void CRYPTO_KDF2_SHA3_512_CalcEx(const U8              * pSeed,
                                       unsigned          SeedLen,
                                       U8              * pOutput,
                                       unsigned          OutputLen,
                                       CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_SM3_Calc()

Description

Derive key using KDF2-SM3.

Prototype

void CRYPTO_KDF2_SM3_Calc(const U8       * pSeed,
                                unsigned   SeedLen,
                                U8       * pOutput,
                                unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_SM3_CalcEx()

Description

Derive key using KDF2-SM3, combine output.

Prototype

void CRYPTO_KDF2_SM3_CalcEx(const U8              * pSeed,
                                  unsigned          SeedLen,
                                  U8              * pOutput,
                                  unsigned          OutputLen,
                                  CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_BLAKE2B_Calc()

Description

Derive key using KDF2-BLAKE2b.

Prototype

void CRYPTO_KDF2_BLAKE2B_Calc(const U8       * pSeed,
                                    unsigned   SeedLen,
                                    U8       * pOutput,
                                    unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_BLAKE2B_CalcEx()

Description

Derive key using KDF2-BLAKE2b, combine output.

Prototype

void CRYPTO_KDF2_BLAKE2B_CalcEx(const U8              * pSeed,
                                      unsigned          SeedLen,
                                      U8              * pOutput,
                                      unsigned          OutputLen,
                                      CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

CRYPTO_KDF2_BLAKE2S_Calc()

Description

Derive key using KDF2-BLAKE2s.

Prototype

void CRYPTO_KDF2_BLAKE2S_Calc(const U8       * pSeed,
                                    unsigned   SeedLen,
                                    U8       * pOutput,
                                    unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_KDF2_BLAKE2S_CalcEx()

Description

Derive key using KDF2-BLAKE2s, combine output.

Prototype

void CRYPTO_KDF2_BLAKE2S_CalcEx(const U8              * pSeed,
                                      unsigned          SeedLen,
                                      U8              * pOutput,
                                      unsigned          OutputLen,
                                      CRYPTO_LOGIC_OP   Operation);

Parameters

Parameter	Description
pSeed	Pointer to seed for mask generation.
SeedLen	Octet length of the seed.
pOutput	Pointer to buffer to receive computed mask.
OutputLen	Octet length of the buffer.
Operation	Logical operation combining derived key with output.

Additional information

The output of the key derivation process is combined with the receiving object using the logical operation Operation.

X9.63 KDF

Standards reference

The X9.63 KDF is specified by the following document:

• ANS X9.63 — Public Key Cryptography for the Financial Services Industry: Key Agreement and Key Transport Using Elliptic Curve Cryptography

Type-safe API

Function	Description
Key derivation
CRYPTO_X9v63_KDF_SHA1_Calc()	Derive key using X9.63 KDF-SHA-1.
CRYPTO_X9v63_KDF_SHA224_Calc()	Derive key using X9.63 KDF-SHA-224.
CRYPTO_X9v63_KDF_SHA256_Calc()	Derive key using X9.63 KDF-SHA-256.
CRYPTO_X9v63_KDF_SHA384_Calc()	Derive key using X9.63 KDF-SHA-384.
CRYPTO_X9v63_KDF_SHA512_Calc()	Derive key using X9.63 KDF-SHA-512.
CRYPTO_X9v63_KDF_SHA512_224_Calc()	Derive key using X9.63 KDF-SHA-512/224.
CRYPTO_X9v63_KDF_SHA512_256_Calc()	Derive key using X9.63 KDF-SHA-512/256.
CRYPTO_X9v63_KDF_SM3_Calc()	Derive key using X9.63 KDF-SM3.
CRYPTO_X9v63_KDF_BLAKE2B_Calc()	Derive key using X9.63 KDF-BLAKE2b.
CRYPTO_X9v63_KDF_BLAKE2S_Calc()	Derive key using X9.63 KDF-BLAKE2s.
Key derivation with shared data
CRYPTO_X9v63_KDF_SHA1_CalcEx()	Derive key using X9.63 KDF-SHA-1, with shared data.
CRYPTO_X9v63_KDF_SHA224_CalcEx()	Derive key using X9.63 KDF-SHA-224, with shared data.
CRYPTO_X9v63_KDF_SHA256_CalcEx()	Derive key using X9.63 KDF-SHA-256, with shared data.
CRYPTO_X9v63_KDF_SHA384_CalcEx()	Derive key using X9.63 KDF-SHA-384, with shared data.
CRYPTO_X9v63_KDF_SHA512_CalcEx()	Derive key using X9.63 KDF-SHA-512, with shared data.
CRYPTO_X9v63_KDF_SHA512_224_CalcEx()	Derive key using X9.63 KDF-SHA-512/224, with shared data.
CRYPTO_X9v63_KDF_SHA512_256_CalcEx()	Derive key using X9.63 KDF-SHA-512/256, with shared data.
CRYPTO_X9v63_KDF_SM3_CalcEx()	Derive key using X9.63 KDF-SM3, with shared data.
CRYPTO_X9v63_KDF_BLAKE2B_CalcEx()	Derive key using X9.63 KDF-BLAKE2b, with shared data.
CRYPTO_X9v63_KDF_BLAKE2S_CalcEx()	Derive key using X9.63 KDF-BLAKE2s, with shared data.

CRYPTO_X9v63_KDF_SHA1_Calc()

Description

Derive key using X9.63 KDF-SHA-1.

Prototype

void CRYPTO_X9v63_KDF_SHA1_Calc(const U8       * pSeed,
                                      unsigned   SeedLen,
                                      U8       * pOutput,
                                      unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA1_CalcEx()

Description

Derive key using X9.63 KDF-SHA-1, with shared data.

Prototype

void CRYPTO_X9v63_KDF_SHA1_CalcEx(const U8       * pSeed,
                                        unsigned   SeedLen,
                                  const U8       * pShared,
                                        unsigned   SharedLen,
                                        U8       * pOutput,
                                        unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pShared	Pointer to shared octet string for key derivation.
SharedLen	Octet length of the shared octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA224_Calc()

Description

Derive key using X9.63 KDF-SHA-224.

Prototype

void CRYPTO_X9v63_KDF_SHA224_Calc(const U8       * pSeed,
                                        unsigned   SeedLen,
                                        U8       * pOutput,
                                        unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA224_CalcEx()

Description

Derive key using X9.63 KDF-SHA-224, with shared data.

Prototype

void CRYPTO_X9v63_KDF_SHA224_CalcEx(const U8       * pSeed,
                                          unsigned   SeedLen,
                                    const U8       * pShared,
                                          unsigned   SharedLen,
                                          U8       * pOutput,
                                          unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pShared	Pointer to shared octet string for key derivation.
SharedLen	Octet length of the shared octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA256_Calc()

Description

Derive key using X9.63 KDF-SHA-256.

Prototype

void CRYPTO_X9v63_KDF_SHA256_Calc(const U8       * pSeed,
                                        unsigned   SeedLen,
                                        U8       * pOutput,
                                        unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA256_CalcEx()

Description

Derive key using X9.63 KDF-SHA-256, with shared data.

Prototype

void CRYPTO_X9v63_KDF_SHA256_CalcEx(const U8       * pSeed,
                                          unsigned   SeedLen,
                                    const U8       * pShared,
                                          unsigned   SharedLen,
                                          U8       * pOutput,
                                          unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pShared	Pointer to shared octet string for key derivation.
SharedLen	Octet length of the shared octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA384_Calc()

Description

Derive key using X9.63 KDF-SHA-384.

Prototype

void CRYPTO_X9v63_KDF_SHA384_Calc(const U8       * pSeed,
                                        unsigned   SeedLen,
                                        U8       * pOutput,
                                        unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA384_CalcEx()

Description

Derive key using X9.63 KDF-SHA-384, with shared data.

Prototype

void CRYPTO_X9v63_KDF_SHA384_CalcEx(const U8       * pSeed,
                                          unsigned   SeedLen,
                                    const U8       * pShared,
                                          unsigned   SharedLen,
                                          U8       * pOutput,
                                          unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pShared	Pointer to shared octet string for key derivation.
SharedLen	Octet length of the shared octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA512_Calc()

Description

Derive key using X9.63 KDF-SHA-512.

Prototype

void CRYPTO_X9v63_KDF_SHA512_Calc(const U8       * pSeed,
                                        unsigned   SeedLen,
                                        U8       * pOutput,
                                        unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA512_CalcEx()

Description

Derive key using X9.63 KDF-SHA-512, with shared data.

Prototype

void CRYPTO_X9v63_KDF_SHA512_CalcEx(const U8       * pSeed,
                                          unsigned   SeedLen,
                                    const U8       * pShared,
                                          unsigned   SharedLen,
                                          U8       * pOutput,
                                          unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pShared	Pointer to shared octet string for key derivation.
SharedLen	Octet length of the shared octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA512_224_Calc()

Description

Derive key using X9.63 KDF-SHA-512/224.

Prototype

void CRYPTO_X9v63_KDF_SHA512_224_Calc(const U8       * pSeed,
                                            unsigned   SeedLen,
                                            U8       * pOutput,
                                            unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA512_224_CalcEx()

Description

Derive key using X9.63 KDF-SHA-512/224, with shared data.

Prototype

void CRYPTO_X9v63_KDF_SHA512_224_CalcEx(const U8       * pSeed,
                                              unsigned   SeedLen,
                                        const U8       * pShared,
                                              unsigned   SharedLen,
                                              U8       * pOutput,
                                              unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pShared	Pointer to shared octet string for key derivation.
SharedLen	Octet length of the shared octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA512_256_Calc()

Description

Derive key using X9.63 KDF-SHA-512/256.

Prototype

void CRYPTO_X9v63_KDF_SHA512_256_Calc(const U8       * pSeed,
                                            unsigned   SeedLen,
                                            U8       * pOutput,
                                            unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SHA512_256_CalcEx()

Description

Derive key using X9.63 KDF-SHA-512/256, with shared data.

Prototype

void CRYPTO_X9v63_KDF_SHA512_256_CalcEx(const U8       * pSeed,
                                              unsigned   SeedLen,
                                        const U8       * pShared,
                                              unsigned   SharedLen,
                                              U8       * pOutput,
                                              unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pShared	Pointer to shared octet string for key derivation.
SharedLen	Octet length of the shared octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SM3_Calc()

Description

Derive key using X9.63 KDF-SM3.

Prototype

void CRYPTO_X9v63_KDF_SM3_Calc(const U8       * pSeed,
                                     unsigned   SeedLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_SM3_CalcEx()

Description

Derive key using X9.63 KDF-SM3, with shared data.

Prototype

void CRYPTO_X9v63_KDF_SM3_CalcEx(const U8       * pSeed,
                                       unsigned   SeedLen,
                                 const U8       * pShared,
                                       unsigned   SharedLen,
                                       U8       * pOutput,
                                       unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pShared	Pointer to shared octet string for key derivation.
SharedLen	Octet length of the shared octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_BLAKE2B_Calc()

Description

Derive key using X9.63 KDF-BLAKE2b.

Prototype

void CRYPTO_X9v63_KDF_BLAKE2B_Calc(const U8       * pSeed,
                                         unsigned   SeedLen,
                                         U8       * pOutput,
                                         unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_BLAKE2B_CalcEx()

Description

Derive key using X9.63 KDF-BLAKE2b, with shared data.

Prototype

void CRYPTO_X9v63_KDF_BLAKE2B_CalcEx(const U8       * pSeed,
                                           unsigned   SeedLen,
                                     const U8       * pShared,
                                           unsigned   SharedLen,
                                           U8       * pOutput,
                                           unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pShared	Pointer to shared octet string for key derivation.
SharedLen	Octet length of the shared octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_BLAKE2S_Calc()

Description

Derive key using X9.63 KDF-BLAKE2s.

Prototype

void CRYPTO_X9v63_KDF_BLAKE2S_Calc(const U8       * pSeed,
                                         unsigned   SeedLen,
                                         U8       * pOutput,
                                         unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

CRYPTO_X9v63_KDF_BLAKE2S_CalcEx()

Description

Derive key using X9.63 KDF-BLAKE2s, with shared data.

Prototype

void CRYPTO_X9v63_KDF_BLAKE2S_CalcEx(const U8       * pSeed,
                                           unsigned   SeedLen,
                                     const U8       * pShared,
                                           unsigned   SharedLen,
                                           U8       * pOutput,
                                           unsigned   OutputLen);

Parameters

Parameter	Description
pSeed	Pointer to seed octet string for key derivation.
SeedLen	Octet length of the seed octet string.
pShared	Pointer to shared octet string for key derivation.
SharedLen	Octet length of the shared octet string.
pOutput	Pointer to object that receives the derived key.
OutputLen	Octet length of the derived key.

HKDF

Type-safe API

Function	Description
Calculate derived key
CRYPTO_HKDF_BLAKE2B_Calc()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_BLAKE2S_Calc()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_MD5_Calc()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_RIPEMD160_Calc()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA1_Calc()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA224_Calc()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA256_Calc()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA384_Calc()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA512_Calc()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA512_224_Calc()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA512_256_Calc()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SM3_Calc()	Compute pseudorandom key from keying material.
Extract operation
CRYPTO_HKDF_MD5_Extract()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_BLAKE2B_Extract()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_BLAKE2S_Extract()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_RIPEMD160_Extract()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA1_Extract()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA224_Extract()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA256_Extract()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA384_Extract()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA512_Extract()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA512_224_Extract()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SHA512_256_Extract()	Compute pseudorandom key from keying material.
CRYPTO_HKDF_SM3_Extract()	Compute pseudorandom key from keying material.
Expand operation
CRYPTO_HKDF_BLAKE2B_Expand()	Generate keying material from pseudorandom key.
CRYPTO_HKDF_BLAKE2S_Expand()	Generate keying material from pseudorandom key.
CRYPTO_HKDF_MD5_Expand()	Generate keying material from pseudorandom key.
CRYPTO_HKDF_RIPEMD160_Expand()	Generate keying material from pseudorandom key.
CRYPTO_HKDF_SHA1_Expand()	Generate keying material from pseudorandom key.
CRYPTO_HKDF_SHA224_Expand()	Generate keying material from pseudorandom key.
CRYPTO_HKDF_SHA256_Expand()	Generate keying material from pseudorandom key.
CRYPTO_HKDF_SHA384_Expand()	Generate keying material from pseudorandom key.
CRYPTO_HKDF_SHA512_Expand()	Generate keying material from pseudorandom key.
CRYPTO_HKDF_SHA512_224_Expand()	Generate keying material from pseudorandom key.
CRYPTO_HKDF_SHA512_256_Expand()	Generate keying material from pseudorandom key.
CRYPTO_HKDF_SM3_Expand()	Generate keying material from pseudorandom key.

CRYPTO_HKDF_BLAKE2B_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_BLAKE2B_Calc(const U8       * pInput,
                                    unsigned   InputLen,
                              const U8       * pSalt,
                                    unsigned   SaltLen,
                              const U8       * pInfo,
                                    unsigned   InfoLen,
                                    U8       * pOutput,
                                    unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_BLAKE2B_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_BLAKE2B_Expand(const U8       * pPRK,
                                      unsigned   PRKLen,
                                const U8       * pInfo,
                                      unsigned   InfoLen,
                                      U8       * pOutput,
                                      unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_BLAKE2B_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_BLAKE2B_Extract(const U8       * pInput,
                                       unsigned   InputLen,
                                 const U8       * pSalt,
                                       unsigned   SaltLen,
                                       U8       * pPRK,
                                       unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

CRYPTO_HKDF_BLAKE2S_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_BLAKE2S_Calc(const U8       * pInput,
                                    unsigned   InputLen,
                              const U8       * pSalt,
                                    unsigned   SaltLen,
                              const U8       * pInfo,
                                    unsigned   InfoLen,
                                    U8       * pOutput,
                                    unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_BLAKE2S_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_BLAKE2S_Expand(const U8       * pPRK,
                                      unsigned   PRKLen,
                                const U8       * pInfo,
                                      unsigned   InfoLen,
                                      U8       * pOutput,
                                      unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_BLAKE2S_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_BLAKE2S_Extract(const U8       * pInput,
                                       unsigned   InputLen,
                                 const U8       * pSalt,
                                       unsigned   SaltLen,
                                       U8       * pPRK,
                                       unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

CRYPTO_HKDF_MD5_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_MD5_Calc(const U8       * pInput,
                                unsigned   InputLen,
                          const U8       * pSalt,
                                unsigned   SaltLen,
                          const U8       * pInfo,
                                unsigned   InfoLen,
                                U8       * pOutput,
                                unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_MD5_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_MD5_Expand(const U8       * pPRK,
                                  unsigned   PRKLen,
                            const U8       * pInfo,
                                  unsigned   InfoLen,
                                  U8       * pOutput,
                                  unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_MD5_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_MD5_Extract(const U8       * pInput,
                                   unsigned   InputLen,
                             const U8       * pSalt,
                                   unsigned   SaltLen,
                                   U8       * pPRK,
                                   unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

CRYPTO_HKDF_RIPEMD160_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_RIPEMD160_Calc(const U8       * pInput,
                                      unsigned   InputLen,
                                const U8       * pSalt,
                                      unsigned   SaltLen,
                                const U8       * pInfo,
                                      unsigned   InfoLen,
                                      U8       * pOutput,
                                      unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_RIPEMD160_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_RIPEMD160_Expand(const U8       * pPRK,
                                        unsigned   PRKLen,
                                  const U8       * pInfo,
                                        unsigned   InfoLen,
                                        U8       * pOutput,
                                        unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_RIPEMD160_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_RIPEMD160_Extract(const U8       * pInput,
                                         unsigned   InputLen,
                                   const U8       * pSalt,
                                         unsigned   SaltLen,
                                         U8       * pPRK,
                                         unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

CRYPTO_HKDF_SHA1_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA1_Calc(const U8       * pInput,
                                 unsigned   InputLen,
                           const U8       * pSalt,
                                 unsigned   SaltLen,
                           const U8       * pInfo,
                                 unsigned   InfoLen,
                                 U8       * pOutput,
                                 unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA1_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_SHA1_Expand(const U8       * pPRK,
                                   unsigned   PRKLen,
                             const U8       * pInfo,
                                   unsigned   InfoLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA1_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA1_Extract(const U8       * pInput,
                                    unsigned   InputLen,
                              const U8       * pSalt,
                                    unsigned   SaltLen,
                                    U8       * pPRK,
                                    unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

CRYPTO_HKDF_SHA224_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA224_Calc(const U8       * pInput,
                                   unsigned   InputLen,
                             const U8       * pSalt,
                                   unsigned   SaltLen,
                             const U8       * pInfo,
                                   unsigned   InfoLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA224_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_SHA224_Expand(const U8       * pPRK,
                                     unsigned   PRKLen,
                               const U8       * pInfo,
                                     unsigned   InfoLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA224_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA224_Extract(const U8       * pInput,
                                      unsigned   InputLen,
                                const U8       * pSalt,
                                      unsigned   SaltLen,
                                      U8       * pPRK,
                                      unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

CRYPTO_HKDF_SHA256_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA256_Calc(const U8       * pInput,
                                   unsigned   InputLen,
                             const U8       * pSalt,
                                   unsigned   SaltLen,
                             const U8       * pInfo,
                                   unsigned   InfoLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA256_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_SHA256_Expand(const U8       * pPRK,
                                     unsigned   PRKLen,
                               const U8       * pInfo,
                                     unsigned   InfoLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA256_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA256_Extract(const U8       * pInput,
                                      unsigned   InputLen,
                                const U8       * pSalt,
                                      unsigned   SaltLen,
                                      U8       * pPRK,
                                      unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

CRYPTO_HKDF_SHA384_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA384_Calc(const U8       * pInput,
                                   unsigned   InputLen,
                             const U8       * pSalt,
                                   unsigned   SaltLen,
                             const U8       * pInfo,
                                   unsigned   InfoLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA384_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_SHA384_Expand(const U8       * pPRK,
                                     unsigned   PRKLen,
                               const U8       * pInfo,
                                     unsigned   InfoLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA384_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA384_Extract(const U8       * pInput,
                                      unsigned   InputLen,
                                const U8       * pSalt,
                                      unsigned   SaltLen,
                                      U8       * pPRK,
                                      unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

CRYPTO_HKDF_SHA512_224_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA512_224_Calc(const U8       * pInput,
                                       unsigned   InputLen,
                                 const U8       * pSalt,
                                       unsigned   SaltLen,
                                 const U8       * pInfo,
                                       unsigned   InfoLen,
                                       U8       * pOutput,
                                       unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA512_224_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_SHA512_224_Expand(const U8       * pPRK,
                                         unsigned   PRKLen,
                                   const U8       * pInfo,
                                         unsigned   InfoLen,
                                         U8       * pOutput,
                                         unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA512_224_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA512_224_Extract(const U8       * pInput,
                                          unsigned   InputLen,
                                    const U8       * pSalt,
                                          unsigned   SaltLen,
                                          U8       * pPRK,
                                          unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

CRYPTO_HKDF_SHA512_256_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA512_256_Calc(const U8       * pInput,
                                       unsigned   InputLen,
                                 const U8       * pSalt,
                                       unsigned   SaltLen,
                                 const U8       * pInfo,
                                       unsigned   InfoLen,
                                       U8       * pOutput,
                                       unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA512_256_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_SHA512_256_Expand(const U8       * pPRK,
                                         unsigned   PRKLen,
                                   const U8       * pInfo,
                                         unsigned   InfoLen,
                                         U8       * pOutput,
                                         unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA512_256_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA512_256_Extract(const U8       * pInput,
                                          unsigned   InputLen,
                                    const U8       * pSalt,
                                          unsigned   SaltLen,
                                          U8       * pPRK,
                                          unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

CRYPTO_HKDF_SHA512_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA512_Calc(const U8       * pInput,
                                   unsigned   InputLen,
                             const U8       * pSalt,
                                   unsigned   SaltLen,
                             const U8       * pInfo,
                                   unsigned   InfoLen,
                                   U8       * pOutput,
                                   unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA512_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_SHA512_Expand(const U8       * pPRK,
                                     unsigned   PRKLen,
                               const U8       * pInfo,
                                     unsigned   InfoLen,
                                     U8       * pOutput,
                                     unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SHA512_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SHA512_Extract(const U8       * pInput,
                                      unsigned   InputLen,
                                const U8       * pSalt,
                                      unsigned   SaltLen,
                                      U8       * pPRK,
                                      unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

CRYPTO_HKDF_SM3_Calc()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SM3_Calc(const U8       * pInput,
                                unsigned   InputLen,
                          const U8       * pSalt,
                                unsigned   SaltLen,
                          const U8       * pInfo,
                                unsigned   InfoLen,
                                U8       * pOutput,
                                unsigned   OutputLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of salt.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SM3_Expand()

Description

Generate keying material from pseudorandom key.

Prototype

void CRYPTO_HKDF_SM3_Expand(const U8       * pPRK,
                                  unsigned   PRKLen,
                            const U8       * pInfo,
                                  unsigned   InfoLen,
                                  U8       * pOutput,
                                  unsigned   OutputLen);

Parameters

Parameter	Description
pPRK	Pointer to pseudorandom key (usually the output of the extract step).
PRKLen	Octet length of the pseudorandom key.
pInfo	Pointer to context string.
InfoLen	Octet length of context string.
pOutput	Pointer to object that receives the output keying material.
OutputLen	Octet length of output keying material object.

CRYPTO_HKDF_SM3_Extract()

Description

Compute pseudorandom key from keying material.

Prototype

void CRYPTO_HKDF_SM3_Extract(const U8       * pInput,
                                   unsigned   InputLen,
                             const U8       * pSalt,
                                   unsigned   SaltLen,
                                   U8       * pPRK,
                                   unsigned   PRKLen);

Parameters

Parameter	Description
pInput	Pointer to input keying material.
InputLen	Octet length of keying material.
pSalt	Pointer to salt to use when hashing to avoid dictionary attacks.
SaltLen	Octet length of the salt.
pPRK	Pointer to object that receives the pseudorandom key.
PRKLen	Octet length of the pseudorandom key.

Self-test API

The following table lists the AESKW self-test API functions.

Function	Description
CRYPTO_HKDF_SelfTest()	Run all HKDF test vectors.

CRYPTO_HKDF_SelfTest()

Description

Run all HKDF test vectors.

Prototype

void CRYPTO_HKDF_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

PBKDF2

Standards reference

PBKDF2 is specified by the following document:

• IETC RFC 8018 — PKCS #5: Password-Based Cryptography Specification Version 2.1

Type-safe API

Function	Description
CRYPTO_PBKDF2_HMAC_SHA1_Calc()	Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-1 as the hash function.
CRYPTO_PBKDF2_HMAC_SHA224_Calc()	Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-224 as the hash function.
CRYPTO_PBKDF2_HMAC_SHA256_Calc()	Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-256 as the hash function.
CRYPTO_PBKDF2_HMAC_SHA384_Calc()	Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-384 as the hash function.
CRYPTO_PBKDF2_HMAC_SHA512_Calc()	Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-512 as the hash function.
CRYPTO_PBKDF2_HMAC_SHA512_224_Calc()	Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-512/224 as the hash function.
CRYPTO_PBKDF2_HMAC_SHA512_256_Calc()	Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-512/256 as the hash function.
CRYPTO_PBKDF2_HMAC_SM3_Calc()	Generate a master key in Output[] derived from Password and Salt and the iteration count C using SM3 as the hash function.

CRYPTO_PBKDF2_HMAC_SHA1_Calc()

Description

Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-1 as the hash function.

Prototype

void CRYPTO_PBKDF2_HMAC_SHA1_Calc(const U8       * pPassword,
                                        unsigned   PasswordLen,
                                  const U8       * pSalt,
                                        unsigned   SaltLen,
                                        unsigned   IterationCount,
                                        U8       * pOutput,
                                        unsigned   OutputLen);

Parameters

Parameter	Description
pPassword	Pointer to password octet string.
PasswordLen	Octet length of the password octet string.
pSalt	Pointer to salt octet string (avoiding dictionary attacks).
SaltLen	Octet length of the salt octet string.
IterationCount	Number of hashing iterations to perform.
pOutput	Pointer to object that receives the hashed password.
OutputLen	Octet length of the object that receives the hashed password.

CRYPTO_PBKDF2_HMAC_SHA224_Calc()

Description

Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-224 as the hash function.

Prototype

void CRYPTO_PBKDF2_HMAC_SHA224_Calc(const U8       * pPassword,
                                          unsigned   PasswordLen,
                                    const U8       * pSalt,
                                          unsigned   SaltLen,
                                          unsigned   IterationCount,
                                          U8       * pOutput,
                                          unsigned   OutputLen);

Parameters

Parameter	Description
pPassword	Pointer to password octet string.
PasswordLen	Octet length of the password octet string.
pSalt	Pointer to salt octet string (avoiding dictionary attacks).
SaltLen	Octet length of the salt octet string.
IterationCount	Number of hashing iterations to perform.
pOutput	Pointer to object that receives the hashed password.
OutputLen	Octet length of the object that receives the hashed password.

CRYPTO_PBKDF2_HMAC_SHA256_Calc()

Description

Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-256 as the hash function.

Prototype

void CRYPTO_PBKDF2_HMAC_SHA256_Calc(const U8       * pPassword,
                                          unsigned   PasswordLen,
                                    const U8       * pSalt,
                                          unsigned   SaltLen,
                                          unsigned   IterationCount,
                                          U8       * pOutput,
                                          unsigned   OutputLen);

Parameters

Parameter	Description
pPassword	Pointer to password octet string.
PasswordLen	Octet length of the password octet string.
pSalt	Pointer to salt octet string (avoiding dictionary attacks).
SaltLen	Octet length of the salt octet string.
IterationCount	Number of hashing iterations to perform.
pOutput	Pointer to object that receives the hashed password.
OutputLen	Octet length of the object that receives the hashed password.

CRYPTO_PBKDF2_HMAC_SHA384_Calc()

Description

Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-384 as the hash function.

Prototype

void CRYPTO_PBKDF2_HMAC_SHA384_Calc(const U8       * pPassword,
                                          unsigned   PasswordLen,
                                    const U8       * pSalt,
                                          unsigned   SaltLen,
                                          unsigned   IterationCount,
                                          U8       * pOutput,
                                          unsigned   OutputLen);

Parameters

Parameter	Description
pPassword	Pointer to password octet string.
PasswordLen	Octet length of the password octet string.
pSalt	Pointer to salt octet string (avoiding dictionary attacks).
SaltLen	Octet length of the salt octet string.
IterationCount	Number of hashing iterations to perform.
pOutput	Pointer to object that receives the hashed password.
OutputLen	Octet length of the object that receives the hashed password.

CRYPTO_PBKDF2_HMAC_SHA512_Calc()

Description

Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-512 as the hash function.

Prototype

void CRYPTO_PBKDF2_HMAC_SHA512_Calc(const U8       * pPassword,
                                          unsigned   PasswordLen,
                                    const U8       * pSalt,
                                          unsigned   SaltLen,
                                          unsigned   IterationCount,
                                          U8       * pOutput,
                                          unsigned   OutputLen);

Parameters

Parameter	Description
pPassword	Pointer to password octet string.
PasswordLen	Octet length of the password octet string.
pSalt	Pointer to salt octet string (avoiding dictionary attacks).
SaltLen	Octet length of the salt octet string.
IterationCount	Number of hashing iterations to perform.
pOutput	Pointer to object that receives the hashed password.
OutputLen	Octet length of the object that receives the hashed password.

CRYPTO_PBKDF2_HMAC_SHA512_224_Calc()

Description

Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-512/224 as the hash function.

Prototype

void CRYPTO_PBKDF2_HMAC_SHA512_224_Calc(const U8       * pPassword,
                                              unsigned   PasswordLen,
                                        const U8       * pSalt,
                                              unsigned   SaltLen,
                                              unsigned   IterationCount,
                                              U8       * pOutput,
                                              unsigned   OutputLen);

Parameters

Parameter	Description
pPassword	Pointer to password octet string.
PasswordLen	Octet length of the password octet string.
pSalt	Pointer to salt octet string (avoiding dictionary attacks).
SaltLen	Octet length of the salt octet string.
IterationCount	Number of hashing iterations to perform.
pOutput	Pointer to object that receives the hashed password.
OutputLen	Octet length of the object that receives the hashed password.

CRYPTO_PBKDF2_HMAC_SHA512_256_Calc()

Description

Generate a master key in Output[] derived from Password and Salt and the iteration count C using SHA-512/256 as the hash function.

Prototype

void CRYPTO_PBKDF2_HMAC_SHA512_256_Calc(const U8       * pPassword,
                                              unsigned   PasswordLen,
                                        const U8       * pSalt,
                                              unsigned   SaltLen,
                                              unsigned   IterationCount,
                                              U8       * pOutput,
                                              unsigned   OutputLen);

Parameters

Parameter	Description
pPassword	Pointer to password octet string.
PasswordLen	Octet length of the password octet string.
pSalt	Pointer to salt octet string (avoiding dictionary attacks).
SaltLen	Octet length of the salt octet string.
IterationCount	Number of hashing iterations to perform.
pOutput	Pointer to object that receives the hashed password.
OutputLen	Octet length of the object that receives the hashed password.

CRYPTO_PBKDF2_HMAC_SM3_Calc()

Description

Generate a master key in Output[] derived from Password and Salt and the iteration count C using SM3 as the hash function.

Prototype

void CRYPTO_PBKDF2_HMAC_SM3_Calc(const U8       * pPassword,
                                       unsigned   PasswordLen,
                                 const U8       * pSalt,
                                       unsigned   SaltLen,
                                       unsigned   IterationCount,
                                       U8       * pOutput,
                                       unsigned   OutputLen);

Parameters

Parameter	Description
pPassword	Pointer to password octet string.
PasswordLen	Octet length of the password octet string.
pSalt	Pointer to salt octet string (avoiding dictionary attacks).
SaltLen	Octet length of the salt octet string.
IterationCount	Number of hashing iterations to perform.
pOutput	Pointer to object that receives the hashed password.
OutputLen	Octet length of the object that receives the hashed password.

Self-test API

The following table lists the PBKDF2 self-test API functions.

Function	Description
CRYPTO_PBKDF2_SelfTest()	Run all PBKDF2 test vectors.

CRYPTO_PBKDF2_SelfTest()

Description

Run all PBKDF2 test vectors.

Prototype

void CRYPTO_PBKDF2_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to selftest API.

Extendable-output functions

emCrypt implements the following extendable-output functions:

• SHAKE128 and SHAKE256
• cSHAKE

In addition, the Keccak building block for SHA-3 and SHAKE is implemented.

SHAKE128

Type-safe API

Function	Description
Message functions
CRYPTO_SHAKE128_Calc()	Calculate SHAKE128 output.
Incremental functions
CRYPTO_SHAKE128_Init()	Initialize SHAKE128 context.
CRYPTO_SHAKE128_Add()	Add data to SHAKE128.
CRYPTO_SHAKE128_Final()	Add data to SHAKE128.
CRYPTO_SHAKE128_Kill()	Destroy SHAKE128 context.

CRYPTO_SHAKE128_Add()

Description

Add data to SHAKE128.

Prototype

void CRYPTO_SHAKE128_Add(      CRYPTO_SHAKE_CONTEXT * pSelf,
                         const U8                   * pInput,
                               unsigned               InputLen);

Parameters

Parameter	Description
pSelf	Pointer to SHAKE context.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_SHAKE128_Calc()

Description

Calculate SHAKE128 output.

Prototype

void CRYPTO_SHAKE128_Calc(      U8       * pOutput,
                                unsigned   OutputLen,
                          const U8       * pInput,
                                unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the output.
OutputLen	Octet length of the output string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_SHAKE128_Final()

Description

Add data to SHAKE128.

Prototype

void CRYPTO_SHAKE128_Final(CRYPTO_SHAKE_CONTEXT * pSelf,
                           U8                   * pOutput,
                           unsigned               OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to SHAKE context.
pOutput	Pointer to object that receives the output.
OutputLen	Octet length of the output string.

CRYPTO_SHAKE128_Init()

Description

Initialize SHAKE128 context.

Prototype

void CRYPTO_SHAKE128_Init(CRYPTO_SHAKE_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to SHAKE context.

CRYPTO_SHAKE128_Kill()

Description

Destroy SHAKE128 context.

Prototype

void CRYPTO_SHAKE128_Kill(CRYPTO_SHAKE_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to SHAKE context.

Self-test API

The following table lists the SHAKE self-test API functions.

Function	Description
CRYPTO_SHAKE128_CAVS_SelfTest()	Run CAVS SHAKE128 self-test.

CRYPTO_SHAKE128_CAVS_SelfTest()

Description

Run CAVS SHAKE128 self-test.

Prototype

void CRYPTO_SHAKE128_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

SHAKE256

Type-safe API

Function	Description
Message functions
CRYPTO_SHAKE256_Calc()	Calculate SHAKE256 output.
Incremental functions
CRYPTO_SHAKE256_Init()	Initialize SHAKE256 context.
CRYPTO_SHAKE256_Add()	Add data to SHAKE256.
CRYPTO_SHAKE256_Final()	Add data to SHAKE256.
CRYPTO_SHAKE256_Kill()	Destroy SHAKE256 context.

CRYPTO_SHAKE256_Add()

Description

Add data to SHAKE256.

Prototype

void CRYPTO_SHAKE256_Add(      CRYPTO_SHAKE_CONTEXT * pSelf,
                         const U8                   * pInput,
                               unsigned               InputLen);

Parameters

Parameter	Description
pSelf	Pointer to SHAKE context.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_SHAKE256_Calc()

Description

Calculate SHAKE256 output.

Prototype

void CRYPTO_SHAKE256_Calc(      U8       * pOutput,
                                unsigned   OutputLen,
                          const U8       * pInput,
                                unsigned   InputLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the output.
OutputLen	Octet length of the output string.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_SHAKE256_Final()

Description

Add data to SHAKE256.

Prototype

void CRYPTO_SHAKE256_Final(CRYPTO_SHAKE_CONTEXT * pSelf,
                           U8                   * pOutput,
                           unsigned               OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to SHAKE context.
pOutput	Pointer to object that receives the output.
OutputLen	Octet length of the output string.

CRYPTO_SHAKE256_Init()

Description

Initialize SHAKE256 context.

Prototype

void CRYPTO_SHAKE256_Init(CRYPTO_SHAKE_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to SHAKE context.

CRYPTO_SHAKE256_Kill()

Description

Destroy SHAKE256 context.

Prototype

void CRYPTO_SHAKE256_Kill(CRYPTO_SHAKE_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to SHAKE context.

Self-test API

The following table lists the SHAKE self-test API functions.

Function	Description
CRYPTO_SHAKE256_CAVS_SelfTest()	Run CAVS SHAKE256 self-test.

CRYPTO_SHAKE256_CAVS_SelfTest()

Description

Run CAVS SHAKE256 self-test.

Prototype

void CRYPTO_SHAKE256_CAVS_SelfTest(const CRYPTO_SELFTEST_API * pAPI);

Parameters

Parameter	Description
pAPI	Pointer to self-test API.

cSHAKE

Type-safe API

Function	Description
Message functions
CRYPTO_CSHAKE128_Calc()	Calculate cSHAKE128 output.
CRYPTO_CSHAKE256_Calc()	Calculate cSHAKE256 output.
Incremental functions
CRYPTO_CSHAKE_Init()	Initialize cSHAKE.
CRYPTO_CSHAKE_Add()	Add data (absorb).
CRYPTO_CSHAKE_Get()	Get data (squeeze).
CRYPTO_CSHAKE_Kill()	Clear cSHAKE context.
Building blocks
CRYPTO_CSHAKE_LeftEncode()	Encode integer, left formatting.
CRYPTO_CSHAKE_RightEncode()	Encode integer, right formatting.
CRYPTO_CSHAKE_EncodeStr()	Encode octet string.
CRYPTO_CSHAKE_BlockPad()	Add zeros to block boundary.

CRYPTO_CSHAKE128_Calc()

Description

Calculate cSHAKE128 output.

Prototype

void CRYPTO_CSHAKE128_Calc(      U8       * pOutput,
                                 unsigned   OutputLen,
                           const U8       * pInput,
                                 unsigned   InputLen,
                           const U8       * pCust,
                                 unsigned   CustLen,
                           const U8       * pFunc,
                                 unsigned   FuncLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the output.
OutputLen	Octet length of the output string (L/8).
pInput	Pointer to input octet string (X).
InputLen	Octet length of the input octet string.
pCust	Pointer to customization string (S).
CustLen	Octet length of the customization string.
pFunc	Pointer to NIST-allocated function name (N).
FuncLen	Octet length of the NIST-allocated function string.

CRYPTO_CSHAKE256_Calc()

Description

Calculate cSHAKE256 output.

Prototype

void CRYPTO_CSHAKE256_Calc(      U8       * pOutput,
                                 unsigned   OutputLen,
                           const U8       * pInput,
                                 unsigned   InputLen,
                           const U8       * pCust,
                                 unsigned   CustLen,
                           const U8       * pFunc,
                                 unsigned   FuncLen);

Parameters

Parameter	Description
pOutput	Pointer to object that receives the output.
OutputLen	Octet length of the output string (L/8).
pInput	Pointer to input octet string (X).
InputLen	Octet length of the input octet string.
pCust	Pointer to customization string (S).
CustLen	Octet length of the customization string.
pFunc	Pointer to NIST-allocated function name (N).
FuncLen	Octet length of the NIST-allocated function string.

CRYPTO_CSHAKE_Init()

Description

Initialize cSHAKE.

Prototype

void CRYPTO_CSHAKE_Init(      CRYPTO_CSHAKE_CONTEXT * pSelf,
                        const U8                    * pCust,
                              unsigned                CustLen,
                        const U8                    * pFunc,
                              unsigned                FuncLen,
                              unsigned                Security);

Parameters

Parameter	Description
pSelf	Pointer to cSHAKE context.
pCust	Pointer to customization string (S).
CustLen	Octet length of the customization string.
pFunc	Pointer to NIST-allocated function name (N).
FuncLen	Octet length of the NIST-allocated function string.
Security	Security strength in bits.

CRYPTO_CSHAKE_Add()

Description

Add data (absorb).

Prototype

void CRYPTO_CSHAKE_Add(      CRYPTO_CSHAKE_CONTEXT * pSelf,
                       const U8                    * pInput,
                             unsigned                InputLen);

Parameters

Parameter	Description
pSelf	Pointer to cSHAKE context.
pInput	Pointer to input octet string.
InputLen	Octet length of the input octet string.

CRYPTO_CSHAKE_LeftEncode()

Description

Encode integer, left formatting.

Prototype

void CRYPTO_CSHAKE_LeftEncode(CRYPTO_CSHAKE_CONTEXT * pSelf,
                              U32                     N);

Parameters

Parameter	Description
pSelf	Pointer to Keccak context.
N	Integer to encode.

CRYPTO_CSHAKE_RightEncode()

Description

Encode integer, right formatting.

Prototype

void CRYPTO_CSHAKE_RightEncode(CRYPTO_CSHAKE_CONTEXT * pSelf,
                               U32                     N);

Parameters

Parameter	Description
pSelf	Pointer to Keccak context.
N	Integer to encode.

CRYPTO_CSHAKE_EncodeStr()

Description

Encode octet string.

Prototype

void CRYPTO_CSHAKE_EncodeStr(      CRYPTO_CSHAKE_CONTEXT * pSelf,
                             const U8                    * pStr,
                                   unsigned                StrLen);

Parameters

Parameter	Description
pSelf	Pointer to Keccak context.
pStr	Pointer to octet string to encode.
StrLen	Octet length of the string to encode.

CRYPTO_CSHAKE_BlockPad()

Description

Add zeros to block boundary.

Prototype

void CRYPTO_CSHAKE_BlockPad(CRYPTO_CSHAKE_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cSHAKE context.

CRYPTO_CSHAKE_Get()

Description

Get data (squeeze).

Prototype

void CRYPTO_CSHAKE_Get(CRYPTO_CSHAKE_CONTEXT * pSelf,
                       U8                    * pOutput,
                       unsigned                OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to cSHAKE context.
pOutput	Pointer to object that receives the output.
OutputLen	Octet length of the output string.

CRYPTO_CSHAKE_Kill()

Description

Clear cSHAKE context.

Prototype

void CRYPTO_CSHAKE_Kill(CRYPTO_CSHAKE_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to cSHAKE context.

Keccak

Keccak is the building block used for the SHAKE and cSHAKE extendable output functions and the SHA-3 family of hash functions.

Type-safe API

Function	Description
Message functions
CRYPTO_KECCAK_Init()	Initialize Keccak context.
CRYPTO_KECCAK_Add()	Add data to state (absorb).
CRYPTO_KECCAK_AddPadding()	Add final padding.
CRYPTO_KECCAK_Get()	Get output (squeeze).
CRYPTO_KECCAK_Kill()	Destroy a Keccak context.

CRYPTO_KECCAK_Init()

Description

Initialize Keccak context.

Prototype

void CRYPTO_KECCAK_Init(CRYPTO_KECCAK_CONTEXT * pSelf,
                        unsigned                Capacity);

Parameters

Parameter	Description
pSelf	Pointer to Keccak context.
Capacity	Keccak capacity.

CRYPTO_KECCAK_Add()

Description

Add data to state (absorb).

Prototype

void CRYPTO_KECCAK_Add(      CRYPTO_KECCAK_CONTEXT * pSelf,
                       const U8                    * pInput,
                             unsigned                InputLen);

Parameters

Parameter	Description
pSelf	Pointer to Keccak context.
pInput	Pointer to input data to absorb.
InputLen	Octet length of the input data.

CRYPTO_KECCAK_AddPadding()

Description

Add final padding.

Prototype

void CRYPTO_KECCAK_AddPadding(CRYPTO_KECCAK_CONTEXT * pSelf,
                              U8                      Padding);

Parameters

Parameter	Description
pSelf	Pointer to Keccak context.
Padding	Padding to add.

CRYPTO_KECCAK_Get()

Description

Get output (squeeze).

Prototype

void CRYPTO_KECCAK_Get(CRYPTO_KECCAK_CONTEXT * pSelf,
                       U8                    * pOutput,
                       unsigned                OutputLen);

Parameters

Parameter	Description
pSelf	Pointer to Keccak context.
pOutput	Pointer to object that receives the squeezed data.
OutputLen	Octet length of the receiving object.

CRYPTO_KECCAK_Kill()

Description

Destroy a Keccak context.

Prototype

void CRYPTO_KECCAK_Kill(CRYPTO_KECCAK_CONTEXT * pSelf);

Parameters

Parameter	Description
pSelf	Pointer to Keccak context.

Asymmetric encryption (public key)

RSA

Introduction

A RSA key pair consists of a public key (which can be used for encryption) and a private key (which can be used for decryption).

Public RSA key

The public key has to be provided as object of type CRYPTO_RSA_PUBLIC_KEY to the API functions. It consists of two components:

• The modulus.
• The public exponent.

Both components are stored as multi precision integers in the CRYPTO_RSA_PUBLIC_KEY object. In most cases the public key is not available as object of this type in the application. Therefore the application has to load the public key into a CRYPTO_RSA_PUBLIC_KEY object before it can be used by cryptographic functions. This can be done using the multi precision integer function described in Format conversion. Depending of the format the public key is available, an appropriate conversion function can be chosen.

Example

//
// Public RSA key given as octet string in big endian byte order.
//
const U8 PublicExponent[] = { 0x01, 0x00, 0x01 };
const U8 Modulus[] = { 0x8a, 0x8f, 0xa3, 0x9f, 0x9d, 0x71, ..., 0x29 };
//
// Public key object.
// 
CRYPTO_RSA_PUBLIC_KEY  PublicKey;
//
// Load public key.
//
CRYPTO_RSA_InitPublicKey(&PublicKey, &MemContext);
if (CRYPTO_MPI_LoadBytes(&PublicKey.N, Modulus, sizeof(Modulus)) < 0 ||
    CRYPTO_MPI_LoadBytes(&PublicKey.E, PublicExponent, sizeof(PublicExponent)) < 0) {
  // error: Not enough memory 
}
//
// Public key can be used now.
//
r = CRYPTO_RSA_Encrypt(&PublicKey, pResult, ResultLen, 
                                   pClearData, ClearDataLen, &MemContext);

For an explanation of the memory context MemContext refer to Dynamic memory usage.

Private RSA key

The private key has to be provided as object of type CRYPTO_RSA_PRIVATE_KEY to the API functions. It consists of the following components:

• Modulus.
• Private exponent (D).
• Prime factor P.
• Prime factor Q.
• First exponent for CRT, dP := D mod (P-1)
• Second exponent for CRT, dQ := D mod (Q-1)
• Coefficient for CRT, U := Q^-1 mod P

Not all components are necessary for a private key operation. They are stored as multi precision integers in the CRYPTO_RSA_PRIVATE_KEY object. In most cases the private key is not available as object of this type in the application. Therefore the application has to load the private key into a CRYPTO_RSA_PRIVATE_KEY object before it can be used by cryptographic functions. This can be done using the multi precision integer function described in Format conversion. Depending of the format the private key is available, an appropriate conversion function can be chosen.

Example

//
// Private RSA key given as octet string in big endian byte order.
//
const U8 P[] = { 0xbb, 0x74, 0xf6, 0x08, 0x35, 0x5a, 0x87, ..., 0x77 };
const U8 Q[] = { 0xbd, 0x39, 0xc0, 0x79, 0x9d, 0x9f, 0xa6, ..., 0x5F };
const U8 dP[] = { 0x22, 0xf2, 0x89, 0x33, 0xba, 0x8e, 0xa8, ..., 0xdd };
const U8 dQ[] = { 0x5f, 0x7d, 0xa1, 0x2d, 0x61, 0x93, 0xa9, ..., 0x18 };
const U8 U[] = { 0x2c, 0x13, 0x24, 0x9a, 0xef, 0x34, 0xfd, ..., 0x1f };
//
// Private key object.
// 
CRYPTO_RSA_PRIVATE_KEY  PrivateKey;
//
// Load private key.
//
CRYPTO_RSA_InitPrivateKey(&PrivateKey, &MemContext);
if (CRYPTO_MPI_LoadBytes(&PrivateKey.P, P, sizeof(P)) < 0 ||
    CRYPTO_MPI_LoadBytes(&PrivateKey.Q, Q, sizeof(Q)) < 0 ||
    CRYPTO_MPI_LoadBytes(&PrivateKey.DP, dP, sizeof(dP)) < 0 ||
    CRYPTO_MPI_LoadBytes(&PrivateKey.DQ, dQ, sizeof(dQ)) < 0 ||
    CRYPTO_MPI_LoadBytes(&PrivateKey.QInv, U, sizeof(U)) < 0) {
  // error: Not enough memory 
}
//
// Private key can be used now.
//
r = CRYPTO_RSA_Decrypt(&PrivateKey, pResult, ResultLen, 
                                    pCipherData, CipherDataLen, &MemContext);

For an explanation of the memory context MemContext refer to Dynamic memory usage.

Data types

Type	Description
CRYPTO_RSA_PRIVATE_KEY	RSA private key data.
CRYPTO_RSA_PUBLIC_KEY	RSA public key data.

CRYPTO_RSA_PRIVATE_KEY

Description

RSA private key data.

Type definition

typedef struct {
  CRYPTO_MPI  D;
  CRYPTO_MPI  P;
  CRYPTO_MPI  Q;
  CRYPTO_MPI  DP;
  CRYPTO_MPI  DQ;
  CRYPTO_MPI  QInv;
  CRYPTO_MPI  N;
  CRYPTO_MPI  E;
} CRYPTO_RSA_PRIVATE_KEY;

Structure members

Member	Description
D	Decryption exponent (non-CRT form).
P	Factor p of the public modulus.
Q	Factor q of the public modulus.
DP	d mod (p-1)
DQ	d mod (q-1)
QInv	q^(-1) mod p, i.e. ModInv(q, p)
N	Public modulus (non-CRT form).
E	Encryption exponent.

CRYPTO_RSA_PUBLIC_KEY

Description

RSA public key data.

Type definition

typedef struct {
  CRYPTO_MPI  N;
  CRYPTO_MPI  E;
} CRYPTO_RSA_PUBLIC_KEY;

Structure members

Member	Description
N	Public modulus, pq
E	Public encryption exponent

Management functions

Function	Description
CRYPTO_RSA_InitPublicKey()	Initialize RSA public key object before use.
CRYPTO_RSA_InitPrivateKey()	Initialize RSA private key object before use.
CRYPTO_RSA_KillPublicKey()	Zero all data relating to the public key and reclaim storage.
CRYPTO_RSA_KillPrivateKey()	Zero all data relating to the private key and reclaim storage.

CRYPTO_RSA_InitPrivateKey()

Description

Initialize RSA private key object before use. The function creates an empty private key object.

Prototype

void CRYPTO_RSA_InitPrivateKey(CRYPTO_RSA_PRIVATE_KEY * pSelf,
                               CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	P.rivate key to initialize.
pMem	Allocator to use for expanding components of a private key.

CRYPTO_RSA_InitPublicKey()

Description

Initialize RSA public key object before use. The function creates an empty private key object.

Prototype

void CRYPTO_RSA_InitPublicKey(CRYPTO_RSA_PUBLIC_KEY * pSelf,
                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key to initialize.
pMem	Allocator to use for expanding components of a public key.

CRYPTO_RSA_KillPrivateKey()

Description

Zero all data relating to the private key and reclaim storage.

Prototype

void CRYPTO_RSA_KillPrivateKey(CRYPTO_RSA_PRIVATE_KEY * pSelf);

Parameters

Parameter	Description
pSelf	Private key to burn, or NULL.

CRYPTO_RSA_KillPublicKey()

Description

Zero all data relating to the public key and reclaim storage.

Prototype

void CRYPTO_RSA_KillPublicKey(CRYPTO_RSA_PUBLIC_KEY * pSelf);

Parameters

Parameter	Description
pSelf	Public key to burn, or NULL.

Encryption functions

Function	Description
CRYPTO_RSA_EncryptMPIToMPI()	Encrypts a plaintext MPI to a ciphertext MPI using a public key.
CRYPTO_RSA_Encrypt()	Encrypts the plaintext to the ciphertext using a public key.
CRYPTO_RSA_EncryptMPI()	Encrypts the text using a public key.

CRYPTO_RSA_Encrypt()

Description

Encrypts the plaintext to the ciphertext using a public key.

Prototype

int CRYPTO_RSA_Encrypt(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                             U8                    * pOutput,
                             unsigned                OutputLen,
                       const U8                    * pInput,
                             unsigned                InputLen,
                             CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Pointer to public key for encryption.
pOutput	Pointer to object that receives the ciphered message.
OutputLen	Octet length of the receiving object.
pInput	Pointer to octet string containing the plaintext message.
InputLen	Octet length of the plaintext message.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
≥ 0	Success.

CRYPTO_RSA_EncryptMPI()

Description

Encrypts the text using a public key. CRYPTO_RSA_Encrypt() assumes that original plaintext is less than the modulus.

Prototype

int CRYPTO_RSA_EncryptMPI(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                CRYPTO_MPI            * pText,
                                CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key to encrypt with.
pText	Plaintext MPI on entry, ciphered MPI on return.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
≥ 0	Success.

CRYPTO_RSA_EncryptMPIToMPI()

Description

Encrypts a plaintext MPI to a ciphertext MPI using a public key. CRYPTO_RSA_EncryptMPI() assumes that plaintext is less than the modulus.

Prototype

int CRYPTO_RSA_EncryptMPIToMPI(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                     CRYPTO_MPI            * pOutput,
                               const CRYPTO_MPI            * pInput,
                                     CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key to encrypt with.
pOutput	Ciphered MPI.
pInput	Plaintext MPI.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
≥ 0	Success.

Decryption functions

Function	Description
CRYPTO_RSA_DecryptMPIToMPI()	Decrypts a ciphertext MPI to a plaintext MPI using a private key.
CRYPTO_RSA_DecryptMPI()	Decrypts the ciphertext to the plaintext using a private key.
CRYPTO_RSA_Decrypt()	Decrypts a ciphertext message to plaintext message using a private key.
CRYPTO_RSA_DecryptMPINonCRT()	Decrypts the ciphertext to the plaintext using a private key and the standard decryption exponent (rather than CRT form).

CRYPTO_RSA_Decrypt()

Description

Decrypts a ciphertext message to plaintext message using a private key.

Prototype

int CRYPTO_RSA_Decrypt(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                             U8                     * pOutput,
                             unsigned                 OutputLen,
                       const U8                     * pInput,
                             unsigned                 InputLen,
                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Pointer to private key for decryption.
pOutput	Pointer to object that receives the decrypted message.
OutputLen	Octet length of the object that receives the decrypted message.
pInput	Pointer to octet string that contains the ciphered message.
InputLen	Octet length of the ciphered message.
pMem	Allocator to use for temporary storage.

Return value

≥ 0	Success.
< 0	Processing error.

CRYPTO_RSA_DecryptMPI()

Description

Decrypts the ciphertext to the plaintext using a private key.

Prototype

int CRYPTO_RSA_DecryptMPI(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                CRYPTO_MPI             * pText,
                                CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key to decrypt with.
pText	Ciphered MPI on entry, plaintext MPI on return.
pMem	Allocator to use for temporary storage.

Return value

≥ 0	Success.
< 0	Processing error.

CRYPTO_RSA_DecryptMPINonCRT()

Description

Decrypts the ciphertext to the plaintext using a private key and the standard decryption exponent (rather than CRT form).

Prototype

int CRYPTO_RSA_DecryptMPINonCRT(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                      CRYPTO_MPI             * pText,
                                      CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key.
pText	Data to be decrypted (to itself).
pMem	Allocator to use for temporary storage.

Return value

≥ 0	Success.
< 0	Processing error.

CRYPTO_RSA_DecryptMPIToMPI()

Description

Decrypts a ciphertext MPI to a plaintext MPI using a private key.

Prototype

int CRYPTO_RSA_DecryptMPIToMPI(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                     CRYPTO_MPI             * pOutput,
                               const CRYPTO_MPI             * pInput,
                                     CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Public key to encrypt with.
pOutput	Decrypted MPI (aka plaintext).
pInput	Ciphered MPI (aka ciphertext).
pMem	Allocator to use for temporary storage.

Return value

≥ 0	Success.
< 0	Processing error.

Utility functions

Function	Description
CRYPTO_RSA_CalcDecryptExponent()	Given two primes in the private key and an exponent in the public key, compute the decryption exponent and the CRT form of the private key.
CRYPTO_RSA_ConstructKeys()	initialize the private and public key structures given two primes and a public exponent.
CRYPTO_RSA_RecoverModulus()	Computes the modulus pq into pModulus from the modulus factors P and Q held in the private key.
CRYPTO_RSA_ModulusBits()	Computes the number of modulus bits from the modulus factors P and Q held in the private key.
CRYPTO_RSA_ModulusBytes()	Computes the number of modulus bytes from the modulus factors P and Q held in the private key.
CRYPTO_RSA_ModulusBytes_ASN1()	Inquire number of bytes to encode the modulus as an ASN.1 integer.
CRYPTO_RSA_IsConsistentPair()	Predicate which determines whether the parameters held in the private and public keys of an RSA key pair are consistent.

CRYPTO_RSA_CalcDecryptExponent()

Description

Given two primes in the private key and an exponent in the public key, compute the decryption exponent and the CRT form of the private key.

Prototype

int CRYPTO_RSA_CalcDecryptExponent(      CRYPTO_RSA_PRIVATE_KEY * pPrivateKey,
                                   const CRYPTO_RSA_PUBLIC_KEY  * pPublicKey,
                                         CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pPrivateKey	Pointer to object that receives the private key.
pPublicKey	Pointer to RSA public key.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
≥ 0	Success.

CRYPTO_RSA_ConstructKeys()

Description

initialize the private and public key structures given two primes and a public exponent. This function does not check that the parameters make a valid key pair, you can use CRYPTO_RSA_IsConsistentPair() for that.

Prototype

int CRYPTO_RSA_ConstructKeys(      CRYPTO_RSA_PRIVATE_KEY * pPrivateKey,
                                   CRYPTO_RSA_PUBLIC_KEY  * pPublicKey,
                                   CRYPTO_MPI             * pP,
                                   CRYPTO_MPI             * pQ,
                             const CRYPTO_MPI             * pExponent,
                                   CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pPrivateKey	Private key to construct.
pPublicKey	Public key to construct.
pP	First prime factor of the modulus.
pQ	Second prime factor of the modulus.
pExponent	Public encryption exponent.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
≥ 0	Success.

CRYPTO_RSA_IsConsistentPair()

Description

Predicate which determines whether the parameters held in the private and public keys of an RSA key pair are consistent.

Prototype

int CRYPTO_RSA_IsConsistentPair(const CRYPTO_RSA_PUBLIC_KEY  * pPublicKey,
                                const CRYPTO_RSA_PRIVATE_KEY * pPrivateKey,
                                      CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pPublicKey	Public key to validate.
pPrivateKey	Private key to validate.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
= 0	Processing success, but keys are not consistent.
> 0	Processing success, keys are consistent.

CRYPTO_RSA_ModulusBits()

Description

Computes the number of modulus bits from the modulus factors P and Q held in the private key.

Prototype

int CRYPTO_RSA_ModulusBits(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                 CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key.
pMem	Allocator to use for temporary storage.

Return value

≥ 0	The number of bits in the modulus.
< 0	Processing error.

CRYPTO_RSA_ModulusBytes()

Description

Computes the number of modulus bytes from the modulus factors P and Q held in the private key.

Prototype

int CRYPTO_RSA_ModulusBytes(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                  CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
≥ 0	The number of bytes in the modulus.

Additional information

This function returns the minimum number of bytes required to encode the modulus and considers the modulus unsigned. Therefore, the most significant byte of the encoded form is allowed to have its most significant bit set. Should you need to compute the number of bytes to encoded a non-negative ASN.1 modulus, use CRYPTO_RSA_ModulusBytesN().

CRYPTO_RSA_ModulusBytes_ASN1()

Description

Inquire number of bytes to encode the modulus as an ASN.1 integer.

Prototype

int CRYPTO_RSA_ModulusBytes_ASN1(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
≥ 0	The number of bytes in the modulus.

Additional information

This function returns the minimum number of bytes required to encode the modulus is ASN.1 form where the most significant byte of the encoded form has its most significant bit set to zero.

The number of modulus bits is computed from the modulus factors P and Q held in the private key.

CRYPTO_RSA_RecoverModulus()

Description

Computes the modulus pq into pModulus from the modulus factors P and Q held in the private key.

Prototype

int CRYPTO_RSA_RecoverModulus(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                    CRYPTO_MPI             * pModulus,
                                    CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key.
pModulus	Modulus calculated from private key.
pMem	Allocator to use for temporary storage.

Return value

≥ 0	Success.
< 0	Processing error.

Digital signatures

RSA

Introduction

A RSA key pair consists of a private key (which can be used to create signatures) and a public key (which can be used to verify signatures).

Public RSA key

The public key has to be provided as object of type CRYPTO_RSA_PUBLIC_KEY to the API functions. It consists of two components:

• The modulus.
• The public exponent.

Both components are stored as multi precision integers in the CRYPTO_RSA_PUBLIC_KEY object. In most cases the public key is not available as object of this type in the application. Therefore the application has to load the public key into a CRYPTO_RSA_PUBLIC_KEY object before it can be used by cryptographic functions. This can be done using the multi precision integer function described in Format conversion. Depending of the format the public key is available, an appropriate conversion function can be chosen.

Example

//
// Public RSA key given as octet string in big endian byte order.
//
const U8 PublicExponent[] = { 0x01, 0x00, 0x01 };
const U8 Modulus[] = { 0x8a, 0x8f, 0xa3, 0x9f, 0x9d, 0x71, ..., 0x29 };
//
// Public key object.
// 
CRYPTO_RSA_PUBLIC_KEY  PublicKey;
//
// Load public key.
//
CRYPTO_RSA_InitPublicKey(&PublicKey, &MemContext);
if (CRYPTO_MPI_LoadBytes(&PublicKey.N, Modulus, sizeof(Modulus)) < 0 ||
    CRYPTO_MPI_LoadBytes(&PublicKey.E, PublicExponent, sizeof(PublicExponent)) < 0) {
  // error: Not enough memory 
}
//
// Public key can be used now.
//
r = CRYPTO_RSASSA_PKCS1_SHA1_Verify(&PublicKey, pMessage, MessageLen, NULL, 0, 
                                    pSignature, SignatureLen, &MemContext);

For an explanation of the memory context MemContext refer to Dynamic memory usage.

Private RSA key

The private key has to be provided as object of type CRYPTO_RSA_PRIVATE_KEY to the API functions. It consists of the following components:

• Modulus.
• Private exponent (D).
• Prime factor P.
• Prime factor Q.
• First exponent for CRT, dP := D mod (P-1)
• Second exponent for CRT, dQ := D mod (Q-1)
• Coefficient for CRT, U := Q^-1 mod P

Not all components are necessary for a private key operation. They are stored as multi precision integers in the CRYPTO_RSA_PRIVATE_KEY object. In most cases the private key is not available as object of this type in the application. Therefore the application has to load the private key into a CRYPTO_RSA_PRIVATE_KEY object before it can be used by cryptographic functions. This can be done using the multi precision integer function described in Format conversion. Depending of the format the private key is available, an appropriate conversion function can be chosen.

Example

//
// Private RSA key given as octet string in big endian byte order.
//
const U8 P[] = { 0xbb, 0x74, 0xf6, 0x08, 0x35, 0x5a, 0x87, ..., 0x77 };
const U8 Q[] = { 0xbd, 0x39, 0xc0, 0x79, 0x9d, 0x9f, 0xa6, ..., 0x5F };
const U8 dP[] = { 0x22, 0xf2, 0x89, 0x33, 0xba, 0x8e, 0xa8, ..., 0xdd };
const U8 dQ[] = { 0x5f, 0x7d, 0xa1, 0x2d, 0x61, 0x93, 0xa9, ..., 0x18 };
const U8 U[] = { 0x2c, 0x13, 0x24, 0x9a, 0xef, 0x34, 0xfd, ..., 0x1f };
//
// Private key object.
// 
CRYPTO_RSA_PRIVATE_KEY  PrivateKey;
//
// Load private key.
//
CRYPTO_RSA_InitPrivateKey(&PrivateKey, &MemContext);
if (CRYPTO_MPI_LoadBytes(&PrivateKey.P, P, sizeof(P)) < 0 ||
    CRYPTO_MPI_LoadBytes(&PrivateKey.Q, Q, sizeof(Q)) < 0 ||
    CRYPTO_MPI_LoadBytes(&PrivateKey.DP, dP, sizeof(dP)) < 0 ||
    CRYPTO_MPI_LoadBytes(&PrivateKey.DQ, dQ, sizeof(dQ)) < 0 ||
    CRYPTO_MPI_LoadBytes(&PrivateKey.QInv, U, sizeof(U)) < 0) {
  // error: Not enough memory 
}
//
// Private key can be used now.
//
r = CRYPTO_RSASSA_PKCS1_SHA1_Sign(&PrivateKey, pMessage, MessageLen, NULL, 0, 
                                  pSignature, SignatureLen, &MemContext);

For an explanation of the memory context MemContext refer to Dynamic memory usage.

Key generation

The following table lists the RSA PKCS#1 type-safe key generation functions.

Function	Description
CRYPTO_RSA_P1363_GenKeys()	Generate an RSA key pair into the private and public key structures.
CRYPTO_RSA_FIPS186_GenKeys()	Generate a public and private key pair.
CRYPTO_RSA_FIPS186_GenPrime()	Generate a Shawe-Taylor provable prime of arbitrary size as per FIPS 186-4 section C.10 with N1 = 1 and N2 = 2.
CRYPTO_RSA_FIPS186_GenPrimePair()	Generate a pair of provable prime of arbitrary size as as per FIPS 186-4 section B.3.2, “Generation of Random Primes that are Provably Prime”.
CRYPTO_RSA_FIPS186_ValidateParaSize()	Validate that the modulus size L is acceptable by the FIPS 186-4 standard.

CRYPTO_RSA_P1363_GenKeys()

Description

Generate an RSA key pair into the private and public key structures. The generated modulus is ModulusBits in size. If you call CRYPTO_RSA_GenerateKeys() with an exponent that is null or zero, CRYPTO_RSA_GenerateKeys() will choose an appropriate, small public exponent for you. If you call CRYPTO_RSA_GenerateKeys() with a chosen (fixed) public exponent, that exponent is assigned to the public key pair.

Prototype

int CRYPTO_RSA_P1363_GenKeys(      CRYPTO_RSA_PRIVATE_KEY * pPrivateKey,
                                   CRYPTO_RSA_PUBLIC_KEY  * pPublicKey,
                                   unsigned                 ModulusBits,
                             const CRYPTO_MPI             * pExponent,
                                   CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pPrivateKey	Generated private key.
pPublicKey	Generated public key.
ModulusBits	Size of the public modulus, in bits.
pExponent	Public encryption exponent.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error generating keys.
≥ 0	Key generation successful.

CRYPTO_RSA_FIPS186_GenKeys()

Description

Generate a public and private key pair.

Prototype

int CRYPTO_RSA_FIPS186_GenKeys(      CRYPTO_RSA_PRIVATE_KEY      * pPrivateKey,
                                     CRYPTO_RSA_PUBLIC_KEY       * pPublicKey,
                                     U8                          * pSeed,
                                     unsigned                      SeedLen,
                                     unsigned                      ModulusBits,
                               const CRYPTO_MPI                  * pExponent,
                               const CRYPTO_FIPS186_PRIMEGEN_API * pPrimeAPI,
                                     CRYPTO_MEM_CONTEXT          * pMem);

Parameters

Parameter	Description
pPrivateKey	Generated private key.
pPublicKey	Generated public key.
pSeed	Initial seed, zeroed upon return.
SeedLen	Number of bytes in the seed array.
ModulusBits	Size of the public modulus, in bits.
pExponent	Public encryption exponent.
pPrimeAPI	Pointer to prime generation API.
pMem	Allocator to use for temporary storage.

Return value

≤ 0	Failed to generate a key pair.
> 0	Successful generation of a proven prime key pair.

CRYPTO_RSA_FIPS186_GenPrime()

Description

Generate a Shawe-Taylor provable prime of arbitrary size as per FIPS 186-4 section C.10 with N1 = 1 and N2 = 2.

Prototype

int CRYPTO_RSA_FIPS186_GenPrime(      CRYPTO_MPI                  * pPrime,
                                      unsigned                      PrimeLen,
                                      U8                          * pSeed,
                                      unsigned                      SeedLen,
                                const CRYPTO_MPI                  * pE,
                                const CRYPTO_FIPS186_PRIMEGEN_API * pPrimeAPI,
                                      CRYPTO_MEM_CONTEXT          * pMem);

Parameters

Parameter	Description
pPrime	Pointer to MPI that receives the generated prime.
PrimeLen	Number of bits in the generated prime.
pSeed	Initial seed, updated upon return for subsequent calls to generate additional random numbers with updated seed.
SeedLen	Octet length of the seed.
pE	Public exponent that must be coprime to the generated prime, minus one.
pPrimeAPI	Pointer to prime generation API.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
= 0	Processing successful but no prime generated.
> 0	Processing successful with prime generated.

CRYPTO_RSA_FIPS186_GenPrimePair()

Description

Generate a pair of provable prime of arbitrary size as as per FIPS 186-4 section B.3.2, “Generation of Random Primes that are Provably Prime”.

Prototype

int CRYPTO_RSA_FIPS186_GenPrimePair(      CRYPTO_MPI                  * pP,
                                          CRYPTO_MPI                  * pQ,
                                          U8                          * pSeed,
                                          unsigned                      SeedLen,
                                          unsigned                      ModulusLen,
                                    const CRYPTO_MPI                  * pE,
                                    const CRYPTO_FIPS186_PRIMEGEN_API * pPrimeAPI,
                                          CRYPTO_MEM_CONTEXT          * pMem);

Parameters

Parameter	Description
pP	Generated prime #1, P.
pQ	Generated prime #2, Q.
pSeed	Initial seed, zeroed upon return.
SeedLen	Octet length of the seed.
ModulusLen	Number of bits in product of the primes P and Q, i.e. the size of a public modulus in bits.
pE	Public exponent that must be coprime to P-1 and Q-1.
pPrimeAPI	Pointer to prime generation API.
pMem	Allocator to use for temporary storage.

Return value

< 0	Failure to generate a prime pair
≥ 0	Successful generation of a proven prime pair.

CRYPTO_RSA_FIPS186_ValidateParaSize()

Description

Validate that the modulus size L is acceptable by the FIPS 186-4 standard.

Prototype

int CRYPTO_RSA_FIPS186_ValidateParaSize(unsigned L);

Parameters

Parameter	Description
L	Length of modulus to validate, in bits.

Return value

= 0	Parameters are not acceptable.
≠ 0	Parameters are valid.

RSASSA-PKCS1 message sign and verify

The following table lists the RSASSA-PKCS#1 type-safe message sign and verify API functions.

Function	Description
Sign message
CRYPTO_RSASSA_PKCS1_SHA1_Sign()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA224_Sign()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA256_Sign()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA384_Sign()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_Sign()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_224_Sign()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_256_Sign()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_224_Sign()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_256_Sign()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_384_Sign()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_512_Sign()	Sign hashed message according to PKCS#1 version 1.5.
Verifiy message
CRYPTO_RSASSA_PKCS1_SHA1_Verify()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA224_Verify()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA256_Verify()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA384_Verify()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_Verify()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_224_Verify()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_256_Verify()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_224_Verify()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_256_Verify()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_384_Verify()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_512_Verify()	Sign hashed message according to PKCS#1 version 1.5.

CRYPTO_RSASSA_PKCS1_SHA1_Sign()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA1_Sign(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                  const U8                     * pMessage,
                                        unsigned                 MessageLen,
                                  const U8                     * pSalt,
                                        unsigned                 SaltLen,
                                        U8                     * pSignature,
                                        unsigned                 SignatureLen,
                                        CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessage	Message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA1 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA1_Verify()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA1_Verify(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                    const U8                    * pMessage,
                                          unsigned                MessageLen,
                                          U8                    * pSalt,
                                          unsigned                SaltLen,
                                    const U8                    * pSignature,
                                          unsigned                SignatureLen,
                                          CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessage	Message to verify.
MessageLen	Size of message in bytes.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA1 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA224_Sign()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA224_Sign(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                    const U8                     * pMessage,
                                          unsigned                 MessageLen,
                                    const U8                     * pSalt,
                                          unsigned                 SaltLen,
                                          U8                     * pSignature,
                                          unsigned                 SignatureLen,
                                          CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessage	Message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA224 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA224_Verify()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA224_Verify(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                      const U8                    * pMessage,
                                            unsigned                MessageLen,
                                            U8                    * pSalt,
                                            unsigned                SaltLen,
                                      const U8                    * pSignature,
                                            unsigned                SignatureLen,
                                            CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessage	Message to verify.
MessageLen	Size of message in bytes.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA224 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA256_Sign()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA256_Sign(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                    const U8                     * pMessage,
                                          unsigned                 MessageLen,
                                    const U8                     * pSalt,
                                          unsigned                 SaltLen,
                                          U8                     * pSignature,
                                          unsigned                 SignatureLen,
                                          CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessage	Message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA256 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA256_Verify()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA256_Verify(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                      const U8                    * pMessage,
                                            unsigned                MessageLen,
                                            U8                    * pSalt,
                                            unsigned                SaltLen,
                                      const U8                    * pSignature,
                                            unsigned                SignatureLen,
                                            CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessage	Message to verify.
MessageLen	Size of message in bytes.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA256 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA384_Sign()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA384_Sign(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                    const U8                     * pMessage,
                                          unsigned                 MessageLen,
                                    const U8                     * pSalt,
                                          unsigned                 SaltLen,
                                          U8                     * pSignature,
                                          unsigned                 SignatureLen,
                                          CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessage	Message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA384 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA384_Verify()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA384_Verify(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                      const U8                    * pMessage,
                                            unsigned                MessageLen,
                                            U8                    * pSalt,
                                            unsigned                SaltLen,
                                      const U8                    * pSignature,
                                            unsigned                SignatureLen,
                                            CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessage	Message to verify.
MessageLen	Size of message in bytes.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA384 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA512_224_Sign()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_224_Sign
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessage,
                                             unsigned                 MessageLen,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessage	Message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA512_224 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA512_224_Verify()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_224_Verify
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessage,
                                              unsigned                MessageLen,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessage	Message to verify.
MessageLen	Size of message in bytes.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA512_224 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA512_256_Sign()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_256_Sign
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessage,
                                             unsigned                 MessageLen,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessage	Message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA512_256 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA512_256_Verify()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_256_Verify
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessage,
                                              unsigned                MessageLen,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessage	Message to verify.
MessageLen	Size of message in bytes.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA512_256 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA512_Sign()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_Sign(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                    const U8                     * pMessage,
                                          unsigned                 MessageLen,
                                    const U8                     * pSalt,
                                          unsigned                 SaltLen,
                                          U8                     * pSignature,
                                          unsigned                 SignatureLen,
                                          CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessage	Message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA512 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA512_Verify()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_Verify(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                      const U8                    * pMessage,
                                            unsigned                MessageLen,
                                            U8                    * pSalt,
                                            unsigned                SaltLen,
                                      const U8                    * pSignature,
                                            unsigned                SignatureLen,
                                            CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessage	Message to verify.
MessageLen	Size of message in bytes.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA512 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA3_224_Sign()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_224_Sign(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                      const U8                     * pMessage,
                                            unsigned                 MessageLen,
                                      const U8                     * pSalt,
                                            unsigned                 SaltLen,
                                            U8                     * pSignature,
                                            unsigned                 SignatureLen,
                                            CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessage	Message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA3_224 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA3_224_Verify()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_224_Verify(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessage,
                                              unsigned                MessageLen,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessage	Message to verify.
MessageLen	Size of message in bytes.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA3_224 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA3_256_Sign()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_256_Sign(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                      const U8                     * pMessage,
                                            unsigned                 MessageLen,
                                      const U8                     * pSalt,
                                            unsigned                 SaltLen,
                                            U8                     * pSignature,
                                            unsigned                 SignatureLen,
                                            CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessage	Message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA3_256 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA3_256_Verify()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_256_Verify(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessage,
                                              unsigned                MessageLen,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessage	Message to verify.
MessageLen	Size of message in bytes.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA3_256 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA3_384_Sign()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_384_Sign(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                      const U8                     * pMessage,
                                            unsigned                 MessageLen,
                                      const U8                     * pSalt,
                                            unsigned                 SaltLen,
                                            U8                     * pSignature,
                                            unsigned                 SignatureLen,
                                            CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessage	Message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA3_384 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA3_384_Verify()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_384_Verify(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessage,
                                              unsigned                MessageLen,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessage	Message to verify.
MessageLen	Size of message in bytes.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA3_384 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA3_512_Sign()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_512_Sign(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                      const U8                     * pMessage,
                                            unsigned                 MessageLen,
                                      const U8                     * pSalt,
                                            unsigned                 SaltLen,
                                            U8                     * pSignature,
                                            unsigned                 SignatureLen,
                                            CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessage	Message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA3_512 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA3_512_Verify()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_512_Verify(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessage,
                                              unsigned                MessageLen,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessage	Message to verify.
MessageLen	Size of message in bytes.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA3_512 as the hash function.

RSASSA-PKCS1 digest sign and verify

The following table lists the RSASSA-PKCS#1 type-safe digest sign and verify API functions.

Function	Description
Sign digest
CRYPTO_RSASSA_PKCS1_SHA1_SignDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA224_SignDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA256_SignDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA384_SignDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_SignDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_224_SignDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_256_SignDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_224_SignDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_256_SignDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_384_SignDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_512_SignDigest()	Sign hashed message according to PKCS#1 version 1.5.
Verifiy digest
CRYPTO_RSASSA_PKCS1_SHA1_VerifyDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA224_VerifyDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA256_VerifyDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA384_VerifyDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_VerifyDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_224_VerifyDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA512_256_VerifyDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_224_VerifyDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_256_VerifyDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_384_VerifyDigest()	Sign hashed message according to PKCS#1 version 1.5.
CRYPTO_RSASSA_PKCS1_SHA3_512_VerifyDigest()	Sign hashed message according to PKCS#1 version 1.5.
Low-level functions
CRYPTO_RSASSA_PKCS1_SignDigest()	Sign data using RSASSA-PKCS1-v1_5.
CRYPTO_RSA_PKCS1_Unwrap()	Decrypt a signature according to PKCS#1 version 1.5.

CRYPTO_RSASSA_PKCS1_SHA1_SignDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA1_SignDigest
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessageHash,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessageHash	Digest to sign.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA1 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA1_VerifyDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA1_VerifyDigest
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessageHash,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessageHash	Digest to verify.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA1 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA224_SignDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA224_SignDigest
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessageHash,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessageHash	Digest to sign.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA224 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA224_VerifyDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA224_VerifyDigest
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessageHash,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessageHash	Digest to verify.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA224 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA256_SignDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA256_SignDigest
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessageHash,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessageHash	Digest to sign.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA256 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA256_VerifyDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA256_VerifyDigest
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessageHash,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessageHash	Digest to verify.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA256 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA384_SignDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA384_SignDigest
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessageHash,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessageHash	Digest to sign.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA384 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA384_VerifyDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA384_VerifyDigest
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessageHash,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessageHash	Digest to verify.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA384 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA512_224_SignDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_224_SignDigest
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessageHash,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessageHash	Digest to sign.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA512_224 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA512_224_VerifyDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_224_VerifyDigest
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessageHash,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessageHash	Digest to verify.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA512_224 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA512_256_SignDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_256_SignDigest
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessageHash,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessageHash	Digest to sign.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA512_256 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA512_256_VerifyDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_256_VerifyDigest
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessageHash,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessageHash	Digest to verify.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA512_256 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA512_SignDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_SignDigest
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessageHash,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessageHash	Digest to sign.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA512 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA512_VerifyDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA512_VerifyDigest
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessageHash,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessageHash	Digest to verify.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA512 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA3_224_SignDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_224_SignDigest
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessageHash,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessageHash	Digest to sign.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA3_224 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA3_224_VerifyDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_224_VerifyDigest
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessageHash,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessageHash	Digest to verify.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA3_224 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA3_256_SignDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_256_SignDigest
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessageHash,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessageHash	Digest to sign.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA3_256 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA3_256_VerifyDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_256_VerifyDigest
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessageHash,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessageHash	Digest to verify.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA3_256 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA3_384_SignDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_384_SignDigest
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessageHash,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessageHash	Digest to sign.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA3_384 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA3_384_VerifyDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_384_VerifyDigest
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessageHash,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessageHash	Digest to verify.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA3_384 as the hash function.

CRYPTO_RSASSA_PKCS1_SHA3_512_SignDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_512_SignDigest
                                      (const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                       const U8                     * pMessageHash,
                                       const U8                     * pSalt,
                                             unsigned                 SaltLen,
                                             U8                     * pSignature,
                                             unsigned                 SignatureLen,
                                             CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key for encryption.
pMessageHash	Digest to sign.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but signature failure (signature buffer too small, salt given).
> 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-SIGN using EMSA-PKCS1-v1_5-ENCODE according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to *pInput and the ciphertext C is equivalent to *pOutput.

This implementation uses SHA3_512 as the hash function.

For reference, see PKCS #1 v2.2 section 9.2, EMCSA_PKCS1-v1_5.

CRYPTO_RSASSA_PKCS1_SHA3_512_VerifyDigest()

Description

Sign hashed message according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSASSA_PKCS1_SHA3_512_VerifyDigest
                                       (const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                                        const U8                    * pMessageHash,
                                              U8                    * pSalt,
                                              unsigned                SaltLen,
                                        const U8                    * pSignature,
                                              unsigned                SignatureLen,
                                              CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for verification.
pMessageHash	Digest to verify.
pSalt	Recovered salt. If pSalt is null, the salt is not recovered, but SaltLen must still be given.
SaltLen	Size of salt octet string in bytes.
pSignature	Signature of message.
SignatureLen	Size of signature buffer in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Error status indication.
= 0	Processing complete but verification failure.
> 0	Signature verified successfully.

Additional information

The RSASSA-PKCS1-v1_5 signature scheme does not provide the capability to add and recover a salt from the signature. Therefore, this function zeros the salt octet string. This decision is taken such that this function prototype exactly matches the corresponding prototype for the RSASSA-PSS signature scheme and they can, therefore, be used somewhat interchangeably in source code.

This implementation uses SHA3_512 as the hash function.

CRYPTO_RSASSA_PKCS1_SignDigest()

Description

Sign data using RSASSA-PKCS1-v1_5.

Prototype

int CRYPTO_RSASSA_PKCS1_SignDigest(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                   const U8                     * pDigest,
                                         unsigned                 DigestLen,
                                         U8                     * pSignature,
                                         unsigned                 SignatureLen,
                                         CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Pointer to private key for signing.
pDigest	Pointer to digest to sign, typically a DigestInfo octet string.
DigestLen	Octet length of digest octet string.
pSignature	Pointer to object that receives the signed digest.
SignatureLen	Octet length of the signed digest object.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
≥ 0	Encryption successful, number of bytes in encrypted message.

Additional information

This is an implementation of RSASSA-PKCS1-V1_5-Sign using EMSA-PKCS1-v1_5-Encode according to PKCS #1 and RFC 2437. In this instance, M of RFC 2437 is equivalent to pInput[] and the ciphertext C is equivalent to pOutput[].

CRYPTO_RSA_PKCS1_Unwrap()

Description

Decrypt a signature according to PKCS#1 version 1.5.

Prototype

int CRYPTO_RSA_PKCS1_Unwrap(const CRYPTO_RSA_PUBLIC_KEY * pSelf,
                            const U8                    * pInput,
                                  unsigned                InputLen,
                                  U8                    * pOutput,
                                  unsigned                OutputLen,
                                  CRYPTO_MEM_CONTEXT    * pMem);

Parameters

Parameter	Description
pSelf	Public key for decryption.
pInput	Message to decrypt.
InputLen	Octet length of message to decrypt.
pOutput	Decrypted message buffer.
OutputLen	Octet length of decrypted message buffer.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
≥ 0	Decryption successful, number of bytes in decrypted message.

RSASSA-PSS message sign and verify

The following table lists the RSASSA-PSS type-safe message sign and verify API functions.

Function	Description
Sign message
CRYPTO_RSASSA_PSS_SHA1_Sign()	Signs a message with a private key using the RSASSA-PSS-Sign algorithm.
CRYPTO_RSASSA_PSS_SHA224_Sign()	Signs a message with a private key using the RSASSA-PSS-Sign algorithm.
CRYPTO_RSASSA_PSS_SHA256_Sign()	Signs a message with a private key using the RSASSA-PSS-Sign algorithm.
CRYPTO_RSASSA_PSS_SHA384_Sign()	Signs a message with a private key using the RSASSA-PSS-Sign algorithm.
CRYPTO_RSASSA_PSS_SHA512_Sign()	Signs a message with a private key using the RSASSA-PSS-Sign algorithm.
CRYPTO_RSASSA_PSS_SHA512_224_Sign()	Signs a message with a private key using the RSASSA-PSS-Sign algorithm.
CRYPTO_RSASSA_PSS_SHA512_256_Sign()	Signs a message with a private key using the RSASSA-PSS-Sign algorithm.
CRYPTO_RSASSA_PSS_SHA3_224_Sign()	Signs a message with a private key using the RSASSA-PSS-Sign algorithm.
CRYPTO_RSASSA_PSS_SHA3_256_Sign()	Signs a message with a private key using the RSASSA-PSS-Sign algorithm.
CRYPTO_RSASSA_PSS_SHA3_384_Sign()	Signs a message with a private key using the RSASSA-PSS-Sign algorithm.
CRYPTO_RSASSA_PSS_SHA3_512_Sign()	Signs a message with a private key using the RSASSA-PSS-Sign algorithm.
Verify message
CRYPTO_RSASSA_PSS_SHA1_Verify()	Verify a message using a public key and the RSASSA-PSS-Verify algorithm.
CRYPTO_RSASSA_PSS_SHA224_Verify()	Verify a message using a public key and the RSASSA-PSS-Verify algorithm.
CRYPTO_RSASSA_PSS_SHA256_Verify()	Verify a message using a public key and the RSASSA-PSS-Verify algorithm.
CRYPTO_RSASSA_PSS_SHA384_Verify()	Verify a message using a public key and the RSASSA-PSS-Verify algorithm.
CRYPTO_RSASSA_PSS_SHA512_Verify()	Verify a message using a public key and the RSASSA-PSS-Verify algorithm.
CRYPTO_RSASSA_PSS_SHA512_224_Verify()	Verify a message using a public key and the RSASSA-PSS-Verify algorithm.
CRYPTO_RSASSA_PSS_SHA512_256_Verify()	Verify a message using a public key and the RSASSA-PSS-Verify algorithm.
CRYPTO_RSASSA_PSS_SHA3_224_Verify()	Verify a message using a public key and the RSASSA-PSS-Verify algorithm.
CRYPTO_RSASSA_PSS_SHA3_256_Verify()	Verify a message using a public key and the RSASSA-PSS-Verify algorithm.
CRYPTO_RSASSA_PSS_SHA3_384_Verify()	Verify a message using a public key and the RSASSA-PSS-Verify algorithm.
CRYPTO_RSASSA_PSS_SHA3_512_Verify()	Verify a message using a public key and the RSASSA-PSS-Verify algorithm.

CRYPTO_RSASSA_PSS_SHA1_Sign()

Description

Signs a message with a private key using the RSASSA-PSS-Sign algorithm.

Prototype

int CRYPTO_RSASSA_PSS_SHA1_Sign(const CRYPTO_RSA_PRIVATE_KEY * pSelf,
                                const U8                     * pMessage,
                                      unsigned                 MessageLen,
                                const U8                     * pSalt,
                                      unsigned                 SaltLen,
                                      U8                     * pSignature,
                                      unsigned                 SignatureLen,
                                      CRYPTO_MEM_CONTEXT     * pMem);

Parameters

Parameter	Description
pSelf	Private key to sign the message with.
pMessage	Pointer to message to sign.
MessageLen	Size of message to sign in bytes.
pSalt	Salt value to embed.
SaltLen	Size of salt in bytes.
pSignature	Generated signature.
SignatureLen	Size of signature in bytes.
pMem	Allocator to use for temporary storage.

Return value

< 0	Processing error.
= 0	Processing complete but signature failure (signature buffer too small).
> 0	Nonzero indicates the number of bytes written to the the signature buffer that constitute the signature.

CRYPTO_RSASSA_PSS_SHA1_Verify()

Description

Verify a message using a public key and the RSASSA-PSS-Verify algorithm.

Prototype

int CRYPTO_