Post-quantum Mode vs Hybrid Mode

Key Protect supports two modes that protect your keys during a TLS connection: post-quantum Mode and Hybrid mode.

• Hybrid Mode: Hybrid mode uses a combination of a post-quantum algorithm and classic key exchange algorithms to protect your data while in transit. When you make a request using this mode, the classic elliptic algorithm and the post-quantum algorithm will be used in a key exchange mechanism to cryptographically protect your data as it makes its way to the Key Protect service.

  Hybrid mode supports the hybrid Kyber algorithm with the following parameter sets (key sizes):

  • p256_kyber512: combines kyber512 with ECDH using p_256 curve. It provides L1 security.
  • p384_kyber768: combines kyber768 with ECDH using p_384 curve. It provides L3 security.
  • p521_kyber1024: combines kyber1024 with ECDH using p_521 curve. It provides L5 security.

The hybrid algorithm is used based on guidance from the post-quantum project community. For more information about the algorithm and its associated key sizes, see Prototyping post-quantum and hybrid key exchange and authentication in TLS and SSH.

• Post-quantum Mode: Post-quantum mode uses a post-quantum algorithm to protect your data while in transit. When you make a request using this mode, the post-quantum algorithm is used in a key exchange mechanism to cryptographically protect your data as it makes its way to the Key Protect service.

  Post-quantum mode supports the Kyber algorithm with the following parameter sets (key sizes):

  • kyber512
  • kyber768
  • kyber1024

The Kyber algorithm is used based on recommendation from IBM Cloud. To find out more about the algorithm and its associated key sizes, see CRYSTALS-Kyber.

Post-quantum Enabled Endpoints

IBM® Key Protect for IBM Cloud® has post-quantum enabled endpoints for 2 regions; US-South and EU-GB. See the following table to determine which post-quantum enabled endpoints to use when sending requests to the IBM® Key Protect for IBM Cloud® service.

The classic Key Protect service endpoints are not post-quantum enabled.

Prerequisites

Before setting up your application to work with the SDK, follow these steps:

1. Download the Open post-quantum Software Stack (OQSSA) script. This script builds and install all necessary dependencies ( liboqs, openssl, and libcurl) into your HOME directory folder ( $HOME/opt/oqssa/).

2. Make sure dependent packages required for building OQSSA are installed. You need sudo permissions in order to install the dependency packages.

   • Debian (Ubuntu) dependencies: libtool automake autoconf cmake (3.5 or above) make openssl libssl-dev build-essential git wget golang (1.14 or above) patch perl diffutils

   If you are using a Debian distribution, copy the following code snippet to a file and execute it to verify that all necessary packages have been installed:

   echo "Starting prerequisites verification"
   CMAKE_VER_REQUIRED="3.*"
   packages="libtool automake autoconf cmake make openssl libssl-dev git wget build-essential golang patch perl diffutils"
   for REQUIRED_PKG in $packages
   do
       PKG_STATUS=$(dpkg-query -W --showformat='${Version},${Status}\n' $REQUIRED_PKG|grep "install ok installed")
       if [ "" = "$PKG_STATUS" ]
       then
         echo "$REQUIRED_PKG is NOT installed"
         #sudo apt-get -y install $REQUIRED_PKG
       else
         PKG_VER=$(echo $PKG_STATUS| cut -d',' -f 1)
         if [ "cmake" == $REQUIRED_PKG ]  && ! [[ $PKG_VER =~ $CMAKE_VER_REQUIRED ]]
         then
           echo "$REQUIRED_PKG Version is: $PKG_VER. OQSSA requires cmake 3.5 and above."
         fi
       fi
   done
   echo "Prerequisites verification completed"
   

   • RHEL (Centos/Fedora) dependencies: libtool automake autoconf cmake (3.5 or above) make openssl ncurses-devel gcc-c++ glibc-locale-source glibc-langpack-enopenssl-devel git wget golang (1.14 or above) patch perl diffutils 'Developement Tools'

   If you are using a RHEL distribution, copy the following code snippet to a file and execute it to verify that all necessary packages have been installed:

   echo "Starting prerequisites verification"
   CMAKE_VER_REQUIRED="3.*"
   packages="git libtool automake autoconf cmake make openssl  ncurses-devel gcc-c++ openssl-devel wget glibc-locale-source glibc-langpack-en sudo golang patch perl diffutils"
   for REQUIRED_PKG in $packages
   do
       PKG_STATUS=$(rpm -q --qf '%{VERSION},%{INSTALLTIME}\n' $REQUIRED_PKG)
       if [[ "$PKG_STATUS" == *"not installed"* ]];
       then
       echo "$REQUIRED_PKG is NOT installed"
       #sudo yum -y install $REQUIRED_PKG
       else
         PKG_VER=$(echo $PKG_STATUS| cut -d',' -f 1)
         if [ "cmake" == $REQUIRED_PKG ]  && ! [[ $PKG_VER =~ $CMAKE_VER_REQUIRED ]]
         then
           echo "$REQUIRED_PKG Version is: $PKG_VER. OQSSA requires cmake 3.5 and above."
         fi
       fi
   done
   PKG_STATUS=$(yum grouplist Dev* |grep "Development Tools")
   if [ "" = "$PKG_STATUS" ]
   then
       echo "Developement Tools is NOT installed"
   fi
   echo "Prerequisites verification completed"
   

3. Once prerequisite packages are installed and verified, execute script to build and install OQSSA:

   bash build-oqssa.sh
   

4. Run the following command to set the quantum library path:

   export LD_LIBRARY_PATH=$HOME/opt/oqssa/lib:$LD_LIBRARY_PATH
   

Configuring the Key Protect SDK with your application

Once you have the prerequisites installed, follow these steps to configure the Key Protect SDK with your application:

1. Navigate to the folder where the go client resides by running the following command:

       cd $HOME/keyprotect-go-client
   

2. Set the Kyber algorithm in the initialization of the Key Protect client in your application code. If you do not specify an algorithm, your application will default to using the p384_kyber768 algorithm. Use the following code as an example of algorithm configuration:

   qscConfig := kp.ClientQSCConfig{
       AlgorithmID: kp.KP_QSC_ALGO_p384_KYBER768,
   }
   

3. Compile the Key Protect SDK by running the following command:

   LD_LIBRARY_PATH=$HOME/opt/oqssa/lib PKG_CONFIG_PATH=$HOME/opt/oqssa/lib/pkgconfig go build –-tags quantum
   

Prerequisites

Before making a curl request to a Key Protect post-quantum enabled endpoint, follow these steps:

1. Download the Open post-quantum Software Stack (OQSSA) script. This script will build and install all necessary dependencies ( liboqs, openssl, and libcurl) into your HOME directory folder ( $HOME/opt/oqssa/).

2. Make sure dependent packages required for building OQSSA are installed. You need sudo permissions in order to install the dependency packages.

   • Debian (Ubuntu) dependencies: libtool automake autoconf cmake (3.5 or above) make openssl libssl-dev build-essential git wget golang (1.14 or above) patch perl diffutils

   If you are using a Debian distribution, copy the following code snippet to a file and execute it to verify that all necessary packages have been installed:

   echo "Starting prerequisites verification"
   CMAKE_VER_REQUIRED="3.*"
   packages="libtool automake autoconf cmake make openssl libssl-dev git wget build-essential golang patch perl diffutils"
   for REQUIRED_PKG in $packages
   do
       PKG_STATUS=$(dpkg-query -W --showformat='${Version},${Status}\n' $REQUIRED_PKG|grep "install ok installed")
       if [ "" = "$PKG_STATUS" ]
       then
         echo "$REQUIRED_PKG is NOT installed"
         #sudo apt-get -y install $REQUIRED_PKG
       else
         PKG_VER=$(echo $PKG_STATUS| cut -d',' -f 1)
         if [ "cmake" == $REQUIRED_PKG ]  && ! [[ $PKG_VER =~ $CMAKE_VER_REQUIRED ]]
         then
           echo "$REQUIRED_PKG Version is: $PKG_VER. OQSSA requires cmake 3.5 and above."
         fi
       fi
   done
   echo "Prerequisites verification completed"
   

   • RHEL (Centos/Fedora) dependencies: libtool automake autoconf cmake (3.5 or above) make openssl ncurses-devel gcc-c++ glibc-locale-source glibc-langpack-enopenssl-devel git wget golang (1.14 or above) patch perl diffutils 'Developement Tools''

   If you are using a RHEL distribution, copy the following code snippet to a file and execute it to verify that all necessary packages have been installed:

   echo "Starting prerequisites verification"
   CMAKE_VER_REQUIRED="3.*"
   packages="git libtool automake autoconf cmake make openssl  ncurses-devel gcc-c++ openssl-devel wget glibc-locale-source glibc-langpack-en sudo golang patch perl diffutils"
   for REQUIRED_PKG in $packages
   do
       PKG_STATUS=$(rpm -q --qf '%{VERSION},%{INSTALLTIME}\n' $REQUIRED_PKG)
       if [[ "$PKG_STATUS" == *"not installed"* ]];
       then
       echo "$REQUIRED_PKG is NOT installed"
       #sudo yum -y install $REQUIRED_PKG
       else
         PKG_VER=$(echo $PKG_STATUS| cut -d',' -f 1)
         if [ "cmake" == $REQUIRED_PKG ]  && ! [[ $PKG_VER =~ $CMAKE_VER_REQUIRED ]]
         then
           echo "$REQUIRED_PKG Version is: $PKG_VER. OQSSA requires cmake 3.5 and above."
         fi
       fi
   done
   PKG_STATUS=$(yum grouplist Dev* |grep "Development Tools")
   if [ "" = "$PKG_STATUS" ]
   then
       echo "Developement Tools is NOT installed"
   fi
   echo "Prerequisites verification completed"
   

3. Once prerequisite packages are installed and verified, execute the script to build and install OQSSA:

   bash build-oqssa.sh
   

Making a CURL request to a post-quantum enabled endpoint

When making a call to the the a post-quantum enabled endpoint via curl request, you must be specific to ensure that the request successfully goes through. The following table contains a list of flags that are required when making a post-quantum curl request.

You can use the following example request to retrieve a list of keys for your Key Protect instance via a post-quantum enabled endpoint.

$ curl --tlsv1.3 --curves <qsc_algorithm> -X GET \
    "https://qsc.<region>.kms.cloud.ibm.com/api/v2/keys" \
    -H "accept: application/vnd.ibm.kms.key+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Replace the variables in your request according to the following table.