Skip to content

Commit

Permalink
chore: update documentation to reflect the latest functionality and UI
Browse files Browse the repository at this point in the history
  • Loading branch information
@azasypkin
azasypkin committed Dec 17, 2023
1 parent 10eaf68 commit 772c2ce
Show file tree
Hide file tree
Showing 10 changed files with 215 additions and 95 deletions.
4 changes: 2 additions & 2 deletions blog/2023-08-01-q3-2023-iteration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,15 @@ In [**one of my previous posts**](https://secutils.dev/docs/blog/alpha2-release)

**Tracking issue: [#secutils/8](https://github.com/secutils-dev/secutils/issues/8)**

The **["Digital Certificates → Self-signed certificates"](https://secutils.dev/docs/guides/digital_certificates)** utility currently allows users to create a template for self-signed certificates, with options to tune parameters such as encryption algorithm, signature algorithm, key usage, and more. However, for the initial release, I limited the number of configurable certificate parameters, providing reasonable defaults for the rest. But there are more subtle aspects of digital certificates that users might want to control.
The **["Digital Certificates → Certificate templates"](https://secutils.dev/docs/guides/digital_certificates)** utility currently allows users to create a template for self-signed certificates, with options to tune parameters such as encryption algorithm, signature algorithm, key usage, and more. However, for the initial release, I limited the number of configurable certificate parameters, providing reasonable defaults for the rest. But there are more subtle aspects of digital certificates that users might want to control.

During this iteration, my focus will be on making a few more parameters configurable: key size (RSA, DSA) and curve name (EC). I'm trying to be careful in exposing only necessary parameters to avoid making the UI overly complex.

## Scheduled web page resources checks

**Tracking issue: [#secutils/20](https://github.com/secutils-dev/secutils/issues/20)**

In the previous iteration, I introduced the [**“Web Scraping → Resources Trackers”**](https://secutils.dev/docs/guides/web_scraping/resources) utility, but currently, you need to manually trigger the re-fetching of resources to detect changes since the last check. This behavior defeats the purpose of a monitoring-like utility and is meant to be a temporary stop-gap solution for early adopters who are eager to start tracking changes in web page resources and can tolerate the inconveniences of the early implementation.
In the previous iteration, I introduced the [**“Web Scraping → Resources trackers”**](https://secutils.dev/docs/guides/web_scraping/resources) utility, but currently, you need to manually trigger the re-fetching of resources to detect changes since the last check. This behavior defeats the purpose of a monitoring-like utility and is meant to be a temporary stop-gap solution for early adopters who are eager to start tracking changes in web page resources and can tolerate the inconveniences of the early implementation.

During this iteration, my focus is on adding support for automatic scheduled resources checks and basic email alerts if any changes are detected. This work is already in progress, and I'm planning to write a dedicated blog post covering the implementation details later this month.

Expand Down
4 changes: 2 additions & 2 deletions blog/2023-08-08-scheduler-component.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ tags: [thoughts, overview, technology]
---
Hello!

As you might have learned from the [**"A Plan for the Q3 2023 Iteration"**](https://secutils.dev/docs/blog/q3-2023-iteration) post, my focus for this iteration is on adding support for automatic scheduled resource checks for the [**"Web Scraping → Resources Trackers"**](https://secutils.dev/docs/guides/web_scraping/resources) utility in [**Secutils.dev**](https://secutils.dev). This work is already in progress, and in this post, I'd like to share more details about how I'm designing the scheduler for Secutils.dev. If you're building a scheduler for your application, hopefully, you can learn a useful thing or two.
As you might have learned from the [**"A Plan for the Q3 2023 Iteration"**](https://secutils.dev/docs/blog/q3-2023-iteration) post, my focus for this iteration is on adding support for automatic scheduled resource checks for the [**"Web Scraping → Resources trackers"**](https://secutils.dev/docs/guides/web_scraping/resources) utility in [**Secutils.dev**](https://secutils.dev). This work is already in progress, and in this post, I'd like to share more details about how I'm designing the scheduler for Secutils.dev. If you're building a scheduler for your application, hopefully, you can learn a useful thing or two.

<!--truncate-->

Expand Down Expand Up @@ -55,7 +55,7 @@ Here are a few diagrams from the project repository that explain how it works:
**Job activity**
![Job activity](https://secutils.dev/docs/img/blog/2023-08-08_scheduler_component_job_activity.png)

Tokio cron scheduler ticked all the boxes for me! Its architecture is simple, and if I need to tweak it, I can do it without much trouble. Right now, I've already added an SQLite storage provider and started hooking up the scheduler with the [**"Web Scraping → Resources Trackers"**](https://secutils.dev/docs/guides/web_scraping/resources) utility. Everything is going smoothly, and I hope to finish up the scheduled resources checks functionality in the next few weeks.
Tokio cron scheduler ticked all the boxes for me! Its architecture is simple, and if I need to tweak it, I can do it without much trouble. Right now, I've already added an SQLite storage provider and started hooking up the scheduler with the [**"Web Scraping → Resources trackers"**](https://secutils.dev/docs/guides/web_scraping/resources) utility. Everything is going smoothly, and I hope to finish up the scheduled resources checks functionality in the next few weeks.

That wraps up today's post, thanks for taking the time to read it!

Expand Down
118 changes: 73 additions & 45 deletions docs/guides/digital_certificates.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ On this page, you can find guides on creating digital certificate templates with

In this guide you'll create a template for generating a private key and self-signed certificate for a Node.js HTTPS server:

1. Navigate to [Digital Certificates → Self-signed certificates](https://secutils.dev/ws/certificates__self_signed_certificates) and click **Create certificate template** button
1. Navigate to [Digital Certificates → Certificate templates](https://secutils.dev/ws/certificates__certificate_templates) and click **Create certificate template** button
2. Configure a new certificate template with the following values:

<table class="su-table">
Expand Down Expand Up @@ -175,7 +175,7 @@ Watch the video demo below to see all the steps mentioned earlier in action:

In this guide, you will generate a private key in PKCS#8 format and then export it to a JSON Web Key (JWK) using a custom responder and the browser's built-in Web Crypto API:

1. Navigate to [Digital Certificates → Self-signed certificates](https://secutils.dev/ws/certificates__self_signed_certificates) and click **Create certificate template** button
1. Navigate to [Digital Certificates → Certificate templates](https://secutils.dev/ws/certificates__certificate_templates) and click **Create certificate template** button
2. Configure a new certificate template with the following values:

<table class="su-table">
Expand Down Expand Up @@ -225,18 +225,43 @@ End Entity

3. Click on the **Save** button to save the certificate template
4. Once the template is set up, it will appear in the templates grid
5. Now, navigate to [Webhooks → Responders](https://secutils.dev/ws/webhooks__responders) and click **Create responder** button
6. Configure a new responder with the following values:
5. Click on the template's **Generate** button and use the following values for generation:

<table class="su-table">
<tbody>
<tr>
<td><b>Format</b></td>
<td>
```
PKCS#8 (private key only)
```
</td>
</tr>
</tbody>
</table>

6. Click on the **Generate** button to generate and download the private key as `jwk.p8`
7. Now, navigate to [Webhooks → Responders](https://secutils.dev/ws/webhooks__responders) and click **Create responder** button
8. Configure a new responder with the following values:

<table class="su-table">
<tbody>
<tr>
<td><b>Name</b></td>
<td>
```
subtle-crypto
Subtle Crypto
```
</td>
</tr>
<tr>
<td><b>Path</b></td>
<td>
```
/subtle-crypto
```
</td></tr>
</td>
</tr>
<tr>
<td><b>Method</b></td>
<td>
Expand Down Expand Up @@ -264,55 +289,58 @@ Content-Type: text/html; charset=utf-8
<head>
<title>Subtle Crypto</title>
<style>
h1 { text-align: center }
.center { text-align: center }
pre {
outline: 1px solid #ccc;
padding: 5px;
margin: auto;
margin: 1em auto;
width: 30%;
overflow: hidden;
text-overflow: ellipsis;
}
</style>
<script type="text/javascript">
(async function main() {
// Call certificate/key pair "Generate" API.
const response = await fetch("/api/utils/action", {
method: "POST",
credentials: "same-origin",
headers: {"Content-Type": "application/json"},
body: JSON.stringify({
action: {
type: "certificates",
value: {
type: "generateSelfSignedCertificate",
value: { templateName: "jwk", format: "pkcs8" }
}
}
})
});
document.addEventListener("DOMContentLoaded", async function main() {
document.getElementById("p8_upload").addEventListener("change", (e) => {
if (e.target.files.length === 0) {
return;
}
const reader = new FileReader();
reader.onload = async () => {
// Import generated PKCS#8 key as SubtleCrypto's CryptoKey.
const cryptoKey = await window.crypto.subtle.importKey(
"pkcs8",
new Uint8Array(reader.result),
{ name: "ECDSA", namedCurve: "P-384" },
true,
["sign"]
)
// Import generated PKCS#8 key as SubtleCrypto's CryptoKey.
const cryptoKey = await window.crypto.subtle.importKey(
"pkcs8",
new Uint8Array((await response.json()).value.value.certificate),
{ name: "ECDSA", namedCurve: "P-384" },
true,
["sign"]
)
// Export CryptoKey as JWK and render it.
document.getElementById("jwk").textContent = JSON.stringify(
await window.crypto.subtle.exportKey('jwk', cryptoKey),
null,
2
);
})();
// Export CryptoKey as JWK and render it.
document.getElementById("jwk").textContent = JSON.stringify(
await window.crypto.subtle.exportKey('jwk', cryptoKey),
null,
2
);
};
reader.readAsArrayBuffer(e.target.files[0]);
});
});
</script>
</head>
<body>
<h1>PKCS#8 ➡ JSON Web Key (JWK)</h1>
<pre id="jwk">Loading...</pre>
<h1 class="center">PKCS#8 ➡ JSON Web Key (JWK)</h1>
<div class="center">
<label for="p8_upload">Choose PKCS#8 key (*.p8)</label>
<input
type="file"
id="p8_upload"
name="p8_upload"
accept=".p8" />
<br />
</div>
<pre id="jwk">No PKCS#8 key is loaded yet...</pre>
</body>
</html>
```
Expand All @@ -321,9 +349,9 @@ Content-Type: text/html; charset=utf-8
</tbody>
</table>

7. Click on the **Save** button to save the responder
8. Once the responder is set up, it will appear in the responders grid along with its unique URL
9. Click on the responder's URL and observe that it renders a JSON Web Key (JWK) derived from your ECDSA key template
9. Click on the **Save** button to save the responder
10. Once the responder is set up, it will appear in the responders grid along with its unique URL
11. Click on the responder's URL, upload the `jwk.p8` file downloaded at the step 6, and observe that it renders a JSON Web Key (JWK) derived from your ECDSA key

Watch the video demo below to see all the steps mentioned earlier in action:

Expand Down
Loading

0 comments on commit 772c2ce

Please sign in to comment.