Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adding Qseed documentation #75

Merged
merged 1 commit into from
Mar 1, 2024
Merged

Adding Qseed documentation #75

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/eaas/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ This service requires an access token. Follow the steps in [Getting Started]({{<

### Related Tools and Services
1. [RNG Tools]({{< ref "/eaas/rngd" >}}): Integrating Qrypt's Quantum Entropy service as a random source for system devices.
2. [Seed PKCS#11 HSMs]({{< ref "/eaas/pkcs11" >}}): Integrating Qrypt's Quantum Entropy service as a random source for PKCS#11 HSMs.
2. [Qseed]({{< ref "/eaas/pkcs11" >}}): Integrating Qrypt's Quantum Entropy service as a random source for PKCS#11 HSMs.

---

Expand Down
95 changes: 20 additions & 75 deletions content/eaas/pkcs11/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,102 +1,47 @@
+++
title = "Seed PKCS#11 HSMs"
title = "Qseed"
weight = 40
+++

This page covers the instructions to use Qrypt's quantum entropy to seed PKCS#11 HSMs (Hardware Security Modules).
This page covers the [Qseed](https://github.com/QryptInc/qseed) application architecture that downloads quantum entropy from Qrypt's entropy service and injects it into a PKCS#11 compliant HSM (Hardware Security Modules) as seed random.

This service requires an access token. Follow the steps in [Getting Started]({{< ref "/getting_started" >}}) to obtain an access token.

## Technology Value
Many of the available HSMs use non-quantum entropy sources. Fortunately, the PKCS#11 Cryptoki interface provides a C_SeedRandom function to inject entropy into a PKCS#11 compliant HSM. Developers can inject Qrypt's quantum entropy into the HSM using the C_SeedRandom function. As a result, HSM keys can be pseudorandomly generated from quantum entropy.
Many of the available HSMs use non-quantum entropy sources. Fortunately, the PKCS#11 Cryptoki interface provides a C_SeedRandom function to inject entropy into a PKCS#11 compliant HSM. Developers can inject Qrypt's quantum entropy into a HSM using the C_SeedRandom function. As a result, HSM keys can be pseudorandomly generated from quantum entropy.

## Overview
{{< figure src="images/diagram.png" >}}
{{< figure src="images/inject-seedrandom.png" >}}

There are four components to the architecture diagram above.
1. **HSM**: Cryptographic hardware or software device that implements the PKCS#11 interface.
2. **Client Application**: Self implemented or Qrypt provided service that periodically retrieves entropy from an external source and injects it into an HSM.
3. **Qrypt Services**: Qrypt's Entropy service that can provide quantum entropy via a REST API.
4. **Cryptoki Library**: A library that the HSM vendor provides that implements the PKCS#11 interface for their device.
1. **Qrypt Services**: Qrypt's entropy service that can provide quantum entropy via a REST API.
2. **Qseed Application**: Application that periodically retrieves entropy from Qrypt's entropy service and injects it into an HSM via a PKCS#11 Cryptoki interface (C_SeedRandom).
3. **Cryptoki Library**: A library that the HSM vendor provides that implements the PKCS#11 Cryptoki interface for their device.
4. **HSM**: Cryptographic hardware or software device.

### Integration Steps
## Installing Qseed Application

* Install HSM Vendor provided Cryptoki library in runtime environment's path
* Configure Client Application with a Qrypt EaaS API token to pull entropy
* Configure Client Application to authenticate with HSM per vendor instructions
* Configure Client Application to reseed as required
The Qseed application and steps to install it can be found [here](https://github.com/QryptInc/qseed).

## Building Client Application
## Qseed FAQs

The following steps are a guide to develop your own client application that can inject Qrypt's quantum entropy into a PKCS#11 compliant HSM.
**How do I inject entropy into multiple HSM partitions?**

### Step 1: Setup PKCS#11 HSM
The Qseed application can only inject entropy into a single partition. In order to seed multiple partitions, you will need to start multiple instances of the Qseed application.

Follow the setup guide provided by your HSM vendor.
**What is the recommended amount of entropy to inject into the HSM?**

First, create a PKCS#11 token with a PIN for a slot. The slot number and PIN will be needed for the next step.
The Qseed application injects 48 bytes by default. This is recommended for Thales Network Luna 7 HSMs.

### Step 2: Update your client application to open and login to a PKCS#11 session
**Why is more entropy downloaded than injected?**

Sample code in C++ is shown below.
Qrypt's entropy service supports entropy download at the granularity of KiBs. Extra downloaded entropy is discarded by the Qseed application.

```c++
CK_SESSION_HANDLE open_session(CK_SLOT_ID slot_id) {
CK_SESSION_HANDLE session;
CK_RV rv = C_OpenSession(slot_id, CKF_SERIAL_SESSION, NULL, NULL, &session);
if (rv != CKR_OK) {
std::string error_msg = "C_OpenSession error: " + std::to_string(rv) + "\n";
throw std::runtime_error(error_msg);
}
return session;
}
**How do I authenticate with the HSM partition using the Security Officer (SO) PIN?**

void login_session(CK_SESSION_HANDLE session, CK_UTF8CHAR_PTR pin) {
CK_RV rv = C_Login(session, CKU_USER, pin, strlen((char*)pin));
if (rv != CKR_OK) {
std::string error_msg = "C_Login error: " + std::to_string(rv) + "\n";
throw std::runtime_error(error_msg);
}
}
```
The Qseed application only support Crypto User PINs. You will need to create a Crypto User PIN for the Qseed application.

### Step 3: Update your client application to download Qrypt's quantum entropy
A REST API can be called for entropy download. More information about the REST API can be found in the [Submit a request for entropy]({{< ref "/eaas#submit-a-request-for-entropy" >}}) section under 'Quantum Entropy'. You will need a library that can perform HTTPS requests.

C++ sample code using libcurl is provided in the [Quickstart](https://github.com/QryptInc/qrypt-security-quickstarts-cpp/blob/main/src/eaas.cpp). We recommend using environment variables to pass the Qrypt Token into the application.

Requests to the entropy API can only be performed in units of KiB. As a result, there may be random usage inefficiencies. Developers can choose to implement their own buffer management locally for better random utilization.

### Step 4: Update your client application to call C_SeedRandom

Sample code in C++ is shown below.

```c++
void set_seed_random(CK_SESSION_HANDLE session, CK_BYTE_PTR seed_random) {

// Call Cryptoki interface to seed random
CK_RV rv = C_SeedRandom(session, seed_random, sizeof(seed_random));
if (rv != CKR_OK) {
std::string error_msg = "C_SeedRandom error: " + std::to_string(rv) + "\n";
throw std::runtime_error(error_msg);
}

}
```

### Step 5: Update your client application to close the PKCS#11 session

Sample code in C++ is shown below.

```c++
void close_session(CK_SESSION_HANDLE session) {
C_Logout(session);
C_CloseSession(session);
}
```

### References
## References

More information about the PKCS#11 Cryptoki interface can be found at [Oasis PKCS#11 Specification](https://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html).

Click [here](https://github.com/QryptInc/qseed) for a complete working example client application.
Binary file modified content/eaas/pkcs11/images/inject-seedrandom.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 8 additions & 8 deletions docs/404.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@
<title>404 Page not found</title>


<link href="./css/nucleus.css?1706292135" rel="stylesheet">
<link href="./css/fontawesome-all.min.css?1706292135" rel="stylesheet">
<link href="./css/hybrid.css?1706292135" rel="stylesheet">
<link href="./css/featherlight.min.css?1706292135" rel="stylesheet">
<link href="./css/perfect-scrollbar.min.css?1706292135" rel="stylesheet">
<link href="./css/theme.css?1706292135" rel="stylesheet">
<link href="./css/hugo-theme.css?1706292135" rel="stylesheet">
<link href="./css/nucleus.css?1709322073" rel="stylesheet">
<link href="./css/fontawesome-all.min.css?1709322073" rel="stylesheet">
<link href="./css/hybrid.css?1709322073" rel="stylesheet">
<link href="./css/featherlight.min.css?1709322073" rel="stylesheet">
<link href="./css/perfect-scrollbar.min.css?1709322073" rel="stylesheet">
<link href="./css/theme.css?1709322073" rel="stylesheet">
<link href="./css/hugo-theme.css?1709322073" rel="stylesheet">

<link href="./css/theme-mine.css?1706292135" rel="stylesheet">
<link href="./css/theme-mine.css?1709322073" rel="stylesheet">

<style>
:root #header + #content > #left > #rlblock_left {
Expand Down
54 changes: 27 additions & 27 deletions docs/categories/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,22 +12,22 @@
<title>Categories :: Qrypt</title>


<link href="../css/nucleus.css?1706292135" rel="stylesheet">
<link href="../css/fontawesome-all.min.css?1706292135" rel="stylesheet">
<link href="../css/hybrid.css?1706292135" rel="stylesheet">
<link href="../css/featherlight.min.css?1706292135" rel="stylesheet">
<link href="../css/perfect-scrollbar.min.css?1706292135" rel="stylesheet">
<link href="../css/auto-complete.css?1706292135" rel="stylesheet">
<link href="../css/atom-one-dark-reasonable.css?1706292135" rel="stylesheet">
<link href="../css/theme.css?1706292135" rel="stylesheet">
<link href="../css/tabs.css?1706292135" rel="stylesheet">
<link href="../css/hugo-theme.css?1706292135" rel="stylesheet">
<link href="../css/nucleus.css?1709322073" rel="stylesheet">
<link href="../css/fontawesome-all.min.css?1709322073" rel="stylesheet">
<link href="../css/hybrid.css?1709322073" rel="stylesheet">
<link href="../css/featherlight.min.css?1709322073" rel="stylesheet">
<link href="../css/perfect-scrollbar.min.css?1709322073" rel="stylesheet">
<link href="../css/auto-complete.css?1709322073" rel="stylesheet">
<link href="../css/atom-one-dark-reasonable.css?1709322073" rel="stylesheet">
<link href="../css/theme.css?1709322073" rel="stylesheet">
<link href="../css/tabs.css?1709322073" rel="stylesheet">
<link href="../css/hugo-theme.css?1709322073" rel="stylesheet">

<link href="../css/theme-mine.css?1706292135" rel="stylesheet">
<link href="../css/theme-mine.css?1709322073" rel="stylesheet">



<script src="../js/jquery-3.3.1.min.js?1706292135"></script>
<script src="../js/jquery-3.3.1.min.js?1709322073"></script>


</head>
Expand All @@ -49,14 +49,14 @@

</div>

<script type="text/javascript" src="../js/lunr.min.js?1706292135"></script>
<script type="text/javascript" src="../js/auto-complete.js?1706292135"></script>
<script type="text/javascript" src="../js/lunr.min.js?1709322073"></script>
<script type="text/javascript" src="../js/auto-complete.js?1709322073"></script>
<script type="text/javascript">

var baseurl = "https:\/\/QryptInc.github.io";

</script>
<script type="text/javascript" src="../js/search.js?1706292135"></script>
<script type="text/javascript" src="../js/search.js?1709322073"></script>

</div>

Expand Down Expand Up @@ -129,15 +129,15 @@

<li
data-nav-id="/eaas/pkcs11/"
title="Seed PKCS#11 HSMs"
title="Qseed"
class="dd-item



"
>
<a href="../eaas/pkcs11/">
Seed PKCS#11 HSMs
Qseed
</a>

</li>
Expand Down Expand Up @@ -784,19 +784,19 @@ <h1>
<div style="left: -1000px; overflow: scroll; position: absolute; top: -1000px; border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;">
<div style="border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;"></div>
</div>
<script src="../js/clipboard.min.js?1706292135"></script>
<script src="../js/perfect-scrollbar.min.js?1706292135"></script>
<script src="../js/perfect-scrollbar.jquery.min.js?1706292135"></script>
<script src="../js/jquery.sticky.js?1706292135"></script>
<script src="../js/featherlight.min.js?1706292135"></script>
<script src="../js/highlight.pack.js?1706292135"></script>
<script src="../js/clipboard.min.js?1709322073"></script>
<script src="../js/perfect-scrollbar.min.js?1709322073"></script>
<script src="../js/perfect-scrollbar.jquery.min.js?1709322073"></script>
<script src="../js/jquery.sticky.js?1709322073"></script>
<script src="../js/featherlight.min.js?1709322073"></script>
<script src="../js/highlight.pack.js?1709322073"></script>
<script>hljs.initHighlightingOnLoad();</script>
<script src="../js/modernizr.custom-3.6.0.js?1706292135"></script>
<script src="../js/learn.js?1706292135"></script>
<script src="../js/hugo-learn.js?1706292135"></script>
<script src="../js/modernizr.custom-3.6.0.js?1709322073"></script>
<script src="../js/learn.js?1709322073"></script>
<script src="../js/hugo-learn.js?1709322073"></script>


<script src="../mermaid/mermaid.js?1706292135"></script>
<script src="../mermaid/mermaid.js?1709322073"></script>

<script>
mermaid.initialize({ startOnLoad: true });
Expand Down
54 changes: 27 additions & 27 deletions docs/concepts/entropy-projection/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,22 +12,22 @@
<title>Key Entropy Size :: Qrypt</title>


<link href="../../css/nucleus.css?1706292135" rel="stylesheet">
<link href="../../css/fontawesome-all.min.css?1706292135" rel="stylesheet">
<link href="../../css/hybrid.css?1706292135" rel="stylesheet">
<link href="../../css/featherlight.min.css?1706292135" rel="stylesheet">
<link href="../../css/perfect-scrollbar.min.css?1706292135" rel="stylesheet">
<link href="../../css/auto-complete.css?1706292135" rel="stylesheet">
<link href="../../css/atom-one-dark-reasonable.css?1706292135" rel="stylesheet">
<link href="../../css/theme.css?1706292135" rel="stylesheet">
<link href="../../css/tabs.css?1706292135" rel="stylesheet">
<link href="../../css/hugo-theme.css?1706292135" rel="stylesheet">
<link href="../../css/nucleus.css?1709322073" rel="stylesheet">
<link href="../../css/fontawesome-all.min.css?1709322073" rel="stylesheet">
<link href="../../css/hybrid.css?1709322073" rel="stylesheet">
<link href="../../css/featherlight.min.css?1709322073" rel="stylesheet">
<link href="../../css/perfect-scrollbar.min.css?1709322073" rel="stylesheet">
<link href="../../css/auto-complete.css?1709322073" rel="stylesheet">
<link href="../../css/atom-one-dark-reasonable.css?1709322073" rel="stylesheet">
<link href="../../css/theme.css?1709322073" rel="stylesheet">
<link href="../../css/tabs.css?1709322073" rel="stylesheet">
<link href="../../css/hugo-theme.css?1709322073" rel="stylesheet">

<link href="../../css/theme-mine.css?1706292135" rel="stylesheet">
<link href="../../css/theme-mine.css?1709322073" rel="stylesheet">



<script src="../../js/jquery-3.3.1.min.js?1706292135"></script>
<script src="../../js/jquery-3.3.1.min.js?1709322073"></script>


</head>
Expand All @@ -49,14 +49,14 @@

</div>

<script type="text/javascript" src="../../js/lunr.min.js?1706292135"></script>
<script type="text/javascript" src="../../js/auto-complete.js?1706292135"></script>
<script type="text/javascript" src="../../js/lunr.min.js?1709322073"></script>
<script type="text/javascript" src="../../js/auto-complete.js?1709322073"></script>
<script type="text/javascript">

var baseurl = "https:\/\/QryptInc.github.io";

</script>
<script type="text/javascript" src="../../js/search.js?1706292135"></script>
<script type="text/javascript" src="../../js/search.js?1709322073"></script>

</div>

Expand Down Expand Up @@ -129,15 +129,15 @@

<li
data-nav-id="/eaas/pkcs11/"
title="Seed PKCS#11 HSMs"
title="Qseed"
class="dd-item



"
>
<a href="../../eaas/pkcs11/">
Seed PKCS#11 HSMs
Qseed
</a>

</li>
Expand Down Expand Up @@ -913,19 +913,19 @@ <h2 id="formula">Formula</h2>
<div style="left: -1000px; overflow: scroll; position: absolute; top: -1000px; border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;">
<div style="border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;"></div>
</div>
<script src="../../js/clipboard.min.js?1706292135"></script>
<script src="../../js/perfect-scrollbar.min.js?1706292135"></script>
<script src="../../js/perfect-scrollbar.jquery.min.js?1706292135"></script>
<script src="../../js/jquery.sticky.js?1706292135"></script>
<script src="../../js/featherlight.min.js?1706292135"></script>
<script src="../../js/highlight.pack.js?1706292135"></script>
<script src="../../js/clipboard.min.js?1709322073"></script>
<script src="../../js/perfect-scrollbar.min.js?1709322073"></script>
<script src="../../js/perfect-scrollbar.jquery.min.js?1709322073"></script>
<script src="../../js/jquery.sticky.js?1709322073"></script>
<script src="../../js/featherlight.min.js?1709322073"></script>
<script src="../../js/highlight.pack.js?1709322073"></script>
<script>hljs.initHighlightingOnLoad();</script>
<script src="../../js/modernizr.custom-3.6.0.js?1706292135"></script>
<script src="../../js/learn.js?1706292135"></script>
<script src="../../js/hugo-learn.js?1706292135"></script>
<script src="../../js/modernizr.custom-3.6.0.js?1709322073"></script>
<script src="../../js/learn.js?1709322073"></script>
<script src="../../js/hugo-learn.js?1709322073"></script>


<script src="../../mermaid/mermaid.js?1706292135"></script>
<script src="../../mermaid/mermaid.js?1709322073"></script>

<script>
mermaid.initialize({ startOnLoad: true });
Expand Down
Loading
Loading