Intel(R) Integrated Performance Primitives Cryptography 2021.12.0

Author: ipl_ci

BUILD.md

@@ -35,6 +35,7 @@
 - GCC 11.4
 - Clang 9.0
 - Clang 12.0
+- Clang 16.0
 - GNU binutils 2.32
 ### Windows* OS
 - [Common tools](#common-tools)

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 This is a list of notable changes to Intel(R) IPP Cryptography, in reverse chronological order.
 
+## Intel(R) IPP Cryptography 2021.12
+- Added single-buffer implementation of Leighton-Micali Hash-Based Signatures(LMS) algorithm, verification part.
+- Added support of Clang 16.0 compiler for Linux.
+- Added examples of AES-GCM Encryption/Decryption usage.
+- AES-GCM algorithm with Intel® Advanced Vector Extensions 2 (Intel® AVX2) vector extensions of Intel® AES New Instructions (Intel® AES-NI) was optimized.
+
 ## Intel(R) IPP Cryptography 2021.11
 - Minimal supported BoringSSL version was increased to [45cf810d](https://github.com/google/boringssl/archive/45cf810dbdbd767f09f8cb0b0fcccd342c39041f.tar.gz) tag.
 

LICENSE

@@ -173,62 +173,4 @@
       incurred by, or claims asserted against, such Contributor by reason
       of your accepting any such warranty or additional liability.
 
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "{}"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright {yyyy} {name of copyright owner}
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
-
-   CMake
-   ------------------------------
-   CMake - Cross Platform Makefile Generator
-   Copyright 2000-2021 Kitware, Inc. and Contributors
-   All rights reserved.
-
-   Redistribution and use in source and binary forms, with or without
-   modification, are permitted provided that the following conditions
-   are met:
-
-   * Redistributions of source code must retain the above copyright
-     notice, this list of conditions and the following disclaimer.
-
-   * Redistributions in binary form must reproduce the above copyright
-     notice, this list of conditions and the following disclaimer in the
-     documentation and/or other materials provided with the distribution.
-
-   * Neither the name of Kitware, Inc. nor the names of Contributors
-     may be used to endorse or promote products derived from this
-     software without specific prior written permission.
-
-   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-   HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+END OF TERMS AND CONDITIONS

README.md

@@ -26,6 +26,7 @@ The library provides a comprehensive set of routines commonly used for cryptogra
 - Finite Field Arithmetic Functions
 - Big Number Integer Arithmetic Functions
 - PRNG/TRNG and Prime Numbers Generation
+- Hash-based signature algorithms
 
 ## Reasons to Use Intel IPP Cryptography
 - Security (constant-time execution for secret processing functions)

README_FIPS.md

@@ -25,7 +25,7 @@ In general, software may be certified at up to level 2.
 
 Intel® Integrated Performance Primitives Cryptography (Intel(R) IPP Cryptography)
 provides building blocks of FIPS-mode API (such as self-tests, FIPS-approved
-functionality status query) which can help the end users to fullfill FIPS level 1 requirements.
+functionality status query) which can help the end users to fulfill FIPS level 1 requirements.
 Please, refer to [Covered Algorithms](#covered-algorithms) section for the full
 list of FIPS-Approved API which are covered with the selftests.
 
@@ -41,7 +41,7 @@ Intel(R) IPP Cryptography may be built in FIPS-mode with IPPCP_FIPS_MODE=on
 configuration for ippcp and MBX_FIPS_MODE=on for crypto_MB (see details in [Build section](#build)).
 
 Application, which uses Intel(R) IPP Cryptography may be **FIPS-Certified** by
-matching FIPS 140 requirement and obtaining NIST sertificate or also be **FIPS-Compliant** for their own customers.
+matching FIPS 140 requirement and obtaining NIST certificate or also be **FIPS-Compliant** for their own customers.
 
 Please, refer to [Level 1 Specific Requirements](#level-1-specific-requirements)
 for the detailed description of what is done on Intel(R) IPP Cryptography-side
@@ -59,7 +59,7 @@ and what should be done by a more high-level application.
 | 6 | Run pairwise consistency selftest for newly generated RSA/ECC keypair | Intel(R) IPP Cryptography provides [fips_selftest_ippcp<algorithm name> API](#covered-algorithms) to run selftests |
 | 7 | Module to guarantee uniqueness of GSM key + IV | **User's application effort required** |
 | 8 | Module to guarantee XTS key1 != key2 | Intel(R) IPP Cryptography-side check |
-| 9 | (non-production) Extract raw noise source output samples of RBG for quality analysis | DBRNG is currenty out of the cryptography boundary |
+| 9 | (non-production) Extract raw noise source output samples of RBG for quality analysis | DBRNG is currently out of the cryptography boundary |
 | 10| (non-production) Run crypto algorithm testing with NIST-generated vectors | Done offline by Intel(R) IPP Cryptography for the [covered algorithms](#covered-algorithms) |
 
 For the implementation details about the steps in [Level 1 Specific Requirements](#level-1-specific-requirements)
@@ -107,7 +107,7 @@ Configuration example for ippcp with Intel® C++ Compiler:
 
 `CC=icc CXX=icpc cmake CMakeLists.txt -B_build -DARCH=intel64 -DIPPCP_FIPS_MODE:BOOL=on[-DIPPCP_SELFTEST_USE_MALLOC:BOOL=on]`
 
-> Note: selftests with intenal memory allocation uses malloc, which introduces
+> Note: selftests with internal memory allocation uses malloc, which introduces
 a c runtime dependency.
 To avoid the dependency, use IPPCP_SELFTEST_USE_MALLOC:BOOL=off or do not specify
 it as this as the default. In this case, all self-tests will require external memory allocation.
@@ -186,7 +186,7 @@ mbx_nistp256_ecdh_mb8(sharedBA, prvB, pubAx, pubAy, pubAz_curr, 0);
 #### Intel(R) IPP Cryptography
 
 Each API from the list is covered with the selftest fips_selftest_ipps<API_name>
-availible in Intel(R) IPP Cryptography build in FIPS mode.
+available in Intel(R) IPP Cryptography build in FIPS mode.
 
 ##### AES
 

data/images/README_FIPS-pictures-0-ippcp_architecture.png

@@ -20,9 +20,12 @@
 
 # List of examples for targets generation
 set(IPPCP_EXAMPLES
-  # AES examples
+  # AES-CTR examples
   aes/aes-256-ctr-encryption.cpp
   aes/aes-256-ctr-decryption.cpp
+  # AES-GCM examples
+  aes/aes-128-gcm-encryption.cpp
+  aes/aes-128-gcm-decryption.cpp
   # DSA
   dsa/dsa-dlp-sha-1-verification.cpp
   dsa/dsa-dlp-sha-256-verification.cpp

examples/CMakeLists.txt

@@ -0,0 +1,172 @@
+/*************************************************************************
+* Copyright (C) 2024 Intel Corporation
+*
+* Licensed under the Apache License,  Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* 	http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law  or agreed  to  in  writing,  software
+* distributed under  the License  is  distributed  on  an  "AS IS"  BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the  specific  language  governing  permissions  and
+* limitations under the License.
+*************************************************************************/
+
+/*!
+  *
+  *  \file
+  *
+  *  \brief AES Galois Counter mode of operation (GCM) example
+  *
+  *  This example demonstrates usage of AES block cipher with 128-bit key
+  *  run with GCM mode of operation. Decryption scheme.
+  *
+  *  The GCM mode of operation is implemented according to the
+  *  "NIST Special Publication 800-38D: Recommendation for Block Cipher Modes of
+  *  Operation: Galois/Counter Mode (GCM) and GMAC" document:
+  *
+  *  https://csrc.nist.gov/pubs/sp/800/38/d/final
+  *
+  */
+
+#include <cstring>
+
+#include "ippcp.h"
+#include "examples_common.h"
+
+/*! Key size in bytes */
+static const int KEY_SIZE = 16;
+
+/*! Message size in bytes */
+static const int MSG_LEN = 60;
+
+/*! Initialization vector size in bytes */
+static const int IV_LEN = 12;
+
+/*! Tag size in bytes */
+static const int TAG_LEN = 16;
+
+/*! Additional authenticated data size in bytes */
+static const int AAD_LEN = 20;
+
+/*! 128-bit secret key */
+static Ipp8u key128[KEY_SIZE] = {
+    0xfe,0xff,0xe9,0x92,0x86,0x65,0x73,0x1c,
+    0x6d,0x6a,0x8f,0x94,0x67,0x30,0x83,0x08
+};
+
+/*! Initialization vector */
+static const Ipp8u iv[IV_LEN] = {
+    0xca,0xfe,0xba,0xbe,0xfa,0xce,0xdb,0xad,
+    0xde,0xca,0xf8,0x88
+};
+
+/*! Plain text */
+static Ipp8u plainText[MSG_LEN] = {
+    0xd9,0x31,0x32,0x25,0xf8,0x84,0x06,0xe5,
+    0xa5,0x59,0x09,0xc5,0xaf,0xf5,0x26,0x9a,
+    0x86,0xa7,0xa9,0x53,0x15,0x34,0xf7,0xda,
+    0x2e,0x4c,0x30,0x3d,0x8a,0x31,0x8a,0x72,
+    0x1c,0x3c,0x0c,0x95,0x95,0x68,0x09,0x53,
+    0x2f,0xcf,0x0e,0x24,0x49,0xa6,0xb5,0x25,
+    0xb1,0x6a,0xed,0xf5,0xaa,0x0d,0xe6,0x57,
+    0xba,0x63,0x7b,0x39
+};
+
+/*! Cipher text */
+static Ipp8u cipherText[MSG_LEN] = {
+    0x42,0x83,0x1e,0xc2,0x21,0x77,0x74,0x24,
+    0x4b,0x72,0x21,0xb7,0x84,0xd0,0xd4,0x9c,
+    0xe3,0xaa,0x21,0x2f,0x2c,0x02,0xa4,0xe0,
+    0x35,0xc1,0x7e,0x23,0x29,0xac,0xa1,0x2e,
+    0x21,0xd5,0x14,0xb2,0x54,0x66,0x93,0x1c,
+    0x7d,0x8f,0x6a,0x5a,0xac,0x84,0xaa,0x05,
+    0x1b,0xa3,0x0b,0x39,0x6a,0x0a,0xac,0x97,
+    0x3d,0x58,0xe0,0x91
+};
+
+/*! Tag */
+static const Ipp8u tag[TAG_LEN] = {
+    0x5b,0xc9,0x4f,0xbc,0x32,0x21,0xa5,0xdb,
+    0x94,0xfa,0xe9,0x5a,0xe7,0x12,0x1a,0x47
+};
+
+/*! Additional authenticated data */
+static const Ipp8u aad[AAD_LEN] = {
+    0xfe,0xed,0xfa,0xce,0xde,0xad,0xbe,0xef,
+    0xfe,0xed,0xfa,0xce,0xde,0xad,0xbe,0xef,
+    0xab,0xad,0xda,0xd2
+};
+
+/*! Main function  */
+int main(void)
+{
+    /* Size of AES-GCM context structure. It will be set up in ippsAES_GCMGetSize(). */
+    int AESGCMSize = 0;
+
+    /* Output plain text */
+    Ipp8u pOutPlainText[MSG_LEN] = {};
+    /* Output tag */
+    Ipp8u pOutTag[TAG_LEN]        = {};
+
+    /* Pointer to AES-GCM context structure */
+    IppsAES_GCMState* pAESGCMState = 0;
+
+    /* Internal function status */
+    IppStatus status = ippStsNoErr;
+
+    do {
+        /* 1. Get size needed for AES-GCM context structure */
+        status = ippsAES_GCMGetSize(&AESGCMSize);
+        if (!checkStatus("ippsAES_GCMGetSize", ippStsNoErr, status))
+            return status;
+
+        /* 2. Allocate memory for AES-GCM context structure */
+        pAESGCMState = (IppsAES_GCMState*)(new Ipp8u[AESGCMSize]);
+        if (NULL == pAESGCMState) {
+            printf("ERROR: Cannot allocate memory (%d bytes) for AES-GCM state\n", AESGCMSize);
+            return -1;
+        }
+
+        /* 3. Initialize AES-GCM context */
+        status = ippsAES_GCMInit(key128, KEY_SIZE, pAESGCMState, AESGCMSize);
+        if (!checkStatus("ippsAES_GCMInit", ippStsNoErr, status))
+            break;
+
+        /* 4. Decryption setup */
+        status = ippsAES_GCMStart(iv, IV_LEN, aad, AAD_LEN, pAESGCMState);
+        if (!checkStatus("ippsAES_GCMStart", ippStsNoErr, status))
+            break;
+
+        /* 5.Decryption */
+        status = ippsAES_GCMDecrypt(cipherText, pOutPlainText, MSG_LEN, pAESGCMState);
+        if (!checkStatus("ippsAES_GCMDecrypt", ippStsNoErr, status))
+            break;
+
+        /* 6. Get tag */
+        status = ippsAES_GCMGetTag(pOutTag, TAG_LEN, pAESGCMState);
+        if (!checkStatus("ippsAES_GCMGetTag", ippStsNoErr, status))
+            break;
+
+        /* Compare output to known answer */
+        if (0 != memcmp(pOutTag, tag, TAG_LEN)) {
+            printf("ERROR: Output tag and reference tag do not match\n");
+            break;
+        }
+        if (0 != memcmp(pOutPlainText, plainText, MSG_LEN)) {
+            printf("ERROR: Decrypted and plain text do not match\n");
+            break;
+        }
+    } while (0);
+
+    /* 7. Remove secret and release resources */
+    ippsAES_GCMReset(pAESGCMState);
+    if (pAESGCMState) 
+        delete [] (Ipp8u*)pAESGCMState;
+
+    PRINT_EXAMPLE_STATUS("ippsAES_GCMDecrypt", "AES-GCM 128 Decryption", !status)
+
+    return status;
+}