mirrors/certd
1
0
Fork 0
mirror of https://github.com/certd/certd.git synced 2025-11-25 09:10:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

build: publish

Browse Source
This commit is contained in:
xiaojunnuo
2024-11-14 00:20:17 +08:00
parent 48bc7a45a9
commit 111a0823e9
12 changed files with 199 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
packages/core/acme-client/docs/crypto.md
View File

@@ -6,6 +6,38 @@
</dd>
</dl>
## Constants
<dl>
<dt><a href="#createPrivateEcdsaKey">createPrivateEcdsaKey</a> ⇒ <code>Promise.&lt;buffer&gt;</code></dt>
<dd><p>Generate a private ECDSA key</p>
</dd>
<dt><a href="#getPublicKey">getPublicKey</a> ⇒ <code>buffer</code></dt>
<dd><p>Get a public key derived from a RSA or ECDSA key</p>
</dd>
<dt><a href="#getPemBodyAsB64u">getPemBodyAsB64u</a> ⇒ <code>string</code></dt>
<dd><p>Parse body of PEM encoded object and return a Base64URL string
If multiple objects are chained, the first body will be returned</p>
</dd>
<dt><a href="#readCsrDomains">readCsrDomains</a> ⇒ <code>object</code></dt>
<dd><p>Read domains from a Certificate Signing Request</p>
</dd>
<dt><a href="#readCertificateInfo">readCertificateInfo</a> ⇒ <code>object</code></dt>
<dd><p>Read information from a certificate
If multiple certificates are chained, the first will be read</p>
</dd>
<dt><a href="#createCsr">createCsr</a> ⇒ <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code></dt>
<dd><p>Create a Certificate Signing Request</p>
</dd>
<dt><a href="#createAlpnCertificate">createAlpnCertificate</a> ⇒ <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code></dt>
<dd><p>Create a self-signed ALPN certificate for TLS-ALPN-01 challenges</p>
<p><a href="https://datatracker.ietf.org/doc/html/rfc8737">https://datatracker.ietf.org/doc/html/rfc8737</a></p>
</dd>
<dt><a href="#isAlpnCertificateAuthorizationValid">isAlpnCertificateAuthorizationValid</a> ⇒ <code>boolean</code></dt>
<dd><p>Validate that a ALPN certificate contains the expected key authorization</p>
</dd>
</dl>
## Functions
<dl>
@@ -15,12 +47,6 @@
<dt><a href="#createPrivateKey">createPrivateKey()</a></dt>
<dd><p>Alias of <code>createPrivateRsaKey()</code></p>
</dd>
<dt><a href="#createPrivateEcdsaKey">createPrivateEcdsaKey([namedCurve])</a> ⇒ <code>Promise.&lt;buffer&gt;</code></dt>
<dd><p>Generate a private ECDSA key</p>
</dd>
<dt><a href="#getPublicKey">getPublicKey(keyPem)</a> ⇒ <code>buffer</code></dt>
<dd><p>Get a public key derived from a RSA or ECDSA key</p>
</dd>
<dt><a href="#getJwk">getJwk(keyPem)</a> ⇒ <code>object</code></dt>
<dd><p>Get a JSON Web Key derived from a RSA or ECDSA key</p>
<p><a href="https://datatracker.ietf.org/doc/html/rfc7517">https://datatracker.ietf.org/doc/html/rfc7517</a></p>
@@ -28,27 +54,6 @@
<dt><a href="#splitPemChain">splitPemChain(chainPem)</a> ⇒ <code>Array.&lt;string&gt;</code></dt>
<dd><p>Split chain of PEM encoded objects from string into array</p>
</dd>
<dt><a href="#getPemBodyAsB64u">getPemBodyAsB64u(pem)</a> ⇒ <code>string</code></dt>
<dd><p>Parse body of PEM encoded object and return a Base64URL string
If multiple objects are chained, the first body will be returned</p>
</dd>
<dt><a href="#readCsrDomains">readCsrDomains(csrPem)</a> ⇒ <code>object</code></dt>
<dd><p>Read domains from a Certificate Signing Request</p>
</dd>
<dt><a href="#readCertificateInfo">readCertificateInfo(certPem)</a> ⇒ <code>object</code></dt>
<dd><p>Read information from a certificate
If multiple certificates are chained, the first will be read</p>
</dd>
<dt><a href="#createCsr">createCsr(data, [keyPem])</a> ⇒ <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code></dt>
<dd><p>Create a Certificate Signing Request</p>
</dd>
<dt><a href="#createAlpnCertificate">createAlpnCertificate(authz, keyAuthorization, [keyPem])</a> ⇒ <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code></dt>
<dd><p>Create a self-signed ALPN certificate for TLS-ALPN-01 challenges</p>
<p><a href="https://datatracker.ietf.org/doc/html/rfc8737">https://datatracker.ietf.org/doc/html/rfc8737</a></p>
</dd>
<dt><a href="#isAlpnCertificateAuthorizationValid">isAlpnCertificateAuthorizationValid(certPem, keyAuthorization)</a> ⇒ <code>boolean</code></dt>
<dd><p>Validate that a ALPN certificate contains the expected key authorization</p>
</dd>
</dl>
<a name="crypto"></a>
@@ -57,40 +62,12 @@ If multiple certificates are chained, the first will be read</p>
Native Node.js crypto interface
**Kind**: global namespace
<a name="createPrivateRsaKey"></a>
## createPrivateRsaKey([modulusLength]) ⇒ <code>Promise.&lt;buffer&gt;</code>
Generate a private RSA key
**Kind**: global function
**Returns**: <code>Promise.&lt;buffer&gt;</code> - PEM encoded private RSA key
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [modulusLength] | <code>number</code> | <code>2048</code> | Size of the keys modulus in bits, default: `2048` |
**Example**
Generate private RSA key
```js
const privateKey = await acme.crypto.createPrivateRsaKey();
```
**Example**
Private RSA key with modulus size 4096
```js
const privateKey = await acme.crypto.createPrivateRsaKey(4096);
```
<a name="createPrivateKey"></a>
## createPrivateKey()
Alias of `createPrivateRsaKey()`
**Kind**: global function
<a name="createPrivateEcdsaKey"></a>
## createPrivateEcdsaKey([namedCurve]) ⇒ <code>Promise.&lt;buffer&gt;</code>
## createPrivateEcdsaKey ⇒ <code>Promise.&lt;buffer&gt;</code>
Generate a private ECDSA key
**Kind**: global function
**Kind**: global constant
**Returns**: <code>Promise.&lt;buffer&gt;</code> - PEM encoded private ECDSA key
| Param | Type | Description |
@@ -109,10 +86,10 @@ const privateKey = await acme.crypto.createPrivateEcdsaKey('P-384');
```
<a name="getPublicKey"></a>
## getPublicKey(keyPem) ⇒ <code>buffer</code>
## getPublicKey ⇒ <code>buffer</code>
Get a public key derived from a RSA or ECDSA key
**Kind**: global function
**Kind**: global constant
**Returns**: <code>buffer</code> - PEM encoded public key
| Param | Type | Description |
@@ -124,44 +101,13 @@ Get public key
```js
const publicKey = acme.crypto.getPublicKey(privateKey);
```
<a name="getJwk"></a>
## getJwk(keyPem) ⇒ <code>object</code>
Get a JSON Web Key derived from a RSA or ECDSA key
https://datatracker.ietf.org/doc/html/rfc7517
**Kind**: global function
**Returns**: <code>object</code> - JSON Web Key
| Param | Type | Description |
| --- | --- | --- |
| keyPem | <code>buffer</code> \| <code>string</code> | PEM encoded private or public key |
**Example**
Get JWK
```js
const jwk = acme.crypto.getJwk(privateKey);
```
<a name="splitPemChain"></a>
## splitPemChain(chainPem) ⇒ <code>Array.&lt;string&gt;</code>
Split chain of PEM encoded objects from string into array
**Kind**: global function
**Returns**: <code>Array.&lt;string&gt;</code> - Array of PEM objects including headers
| Param | Type | Description |
| --- | --- | --- |
| chainPem | <code>buffer</code> \| <code>string</code> | PEM encoded object chain |
<a name="getPemBodyAsB64u"></a>
## getPemBodyAsB64u(pem) ⇒ <code>string</code>
## getPemBodyAsB64u ⇒ <code>string</code>
Parse body of PEM encoded object and return a Base64URL string
If multiple objects are chained, the first body will be returned
**Kind**: global function
**Kind**: global constant
**Returns**: <code>string</code> - Base64URL-encoded body
| Param | Type | Description |
@@ -170,10 +116,10 @@ If multiple objects are chained, the first body will be returned
<a name="readCsrDomains"></a>
## readCsrDomains(csrPem) ⇒ <code>object</code>
## readCsrDomains ⇒ <code>object</code>
Read domains from a Certificate Signing Request
**Kind**: global function
**Kind**: global constant
**Returns**: <code>object</code> - {commonName, altNames}
| Param | Type | Description |
@@ -190,11 +136,11 @@ console.log(`Alt names: ${altNames.join(', ')}`);
```
<a name="readCertificateInfo"></a>
## readCertificateInfo(certPem) ⇒ <code>object</code>
## readCertificateInfo ⇒ <code>object</code>
Read information from a certificate
If multiple certificates are chained, the first will be read
**Kind**: global function
**Kind**: global constant
**Returns**: <code>object</code> - Certificate info
| Param | Type | Description |
@@ -215,10 +161,10 @@ console.log(`Alt names: ${altNames.join(', ')}`);
```
<a name="createCsr"></a>
## createCsr(data, [keyPem]) ⇒ <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code>
## createCsr ⇒ <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code>
Create a Certificate Signing Request
**Kind**: global function
**Kind**: global constant
**Returns**: <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code> - [privateKey, certificateSigningRequest]
| Param | Type | Description |
@@ -276,12 +222,12 @@ const [, certificateRequest] = await acme.crypto.createCsr({
```
<a name="createAlpnCertificate"></a>
## createAlpnCertificate(authz, keyAuthorization, [keyPem]) ⇒ <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code>
## createAlpnCertificate ⇒ <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code>
Create a self-signed ALPN certificate for TLS-ALPN-01 challenges
https://datatracker.ietf.org/doc/html/rfc8737
**Kind**: global function
**Kind**: global constant
**Returns**: <code>Promise.&lt;Array.&lt;buffer&gt;&gt;</code> - [privateKey, certificate]
| Param | Type | Description |
@@ -303,10 +249,10 @@ const [, alpnCertificate] = await acme.crypto.createAlpnCertificate(authz, keyAu
```
<a name="isAlpnCertificateAuthorizationValid"></a>
## isAlpnCertificateAuthorizationValid(certPem, keyAuthorization) ⇒ <code>boolean</code>
## isAlpnCertificateAuthorizationValid ⇒ <code>boolean</code>
Validate that a ALPN certificate contains the expected key authorization
**Kind**: global function
**Kind**: global constant
**Returns**: <code>boolean</code> - True when valid
| Param | Type | Description |
@@ -314,3 +260,62 @@ Validate that a ALPN certificate contains the expected key authorization
| certPem | <code>buffer</code> \| <code>string</code> | PEM encoded certificate |
| keyAuthorization | <code>string</code> | Expected challenge key authorization |
<a name="createPrivateRsaKey"></a>
## createPrivateRsaKey([modulusLength]) ⇒ <code>Promise.&lt;buffer&gt;</code>
Generate a private RSA key
**Kind**: global function
**Returns**: <code>Promise.&lt;buffer&gt;</code> - PEM encoded private RSA key
| Param | Type | Description |
| --- | --- | --- |
| [modulusLength] | <code>number</code> | Size of the keys modulus in bits, default: `2048` |
**Example**
Generate private RSA key
```js
const privateKey = await acme.crypto.createPrivateRsaKey();
```
**Example**
Private RSA key with modulus size 4096
```js
const privateKey = await acme.crypto.createPrivateRsaKey(4096);
```
<a name="createPrivateKey"></a>
## createPrivateKey()
Alias of `createPrivateRsaKey()`
**Kind**: global function
<a name="getJwk"></a>
## getJwk(keyPem) ⇒ <code>object</code>
Get a JSON Web Key derived from a RSA or ECDSA key
https://datatracker.ietf.org/doc/html/rfc7517
**Kind**: global function
**Returns**: <code>object</code> - JSON Web Key
| Param | Type | Description |
| --- | --- | --- |
| keyPem | <code>buffer</code> \| <code>string</code> | PEM encoded private or public key |
**Example**
Get JWK
```js
const jwk = acme.crypto.getJwk(privateKey);
```
<a name="splitPemChain"></a>
## splitPemChain(chainPem) ⇒ <code>Array.&lt;string&gt;</code>
Split chain of PEM encoded objects from string into array
**Kind**: global function
**Returns**: <code>Array.&lt;string&gt;</code> - Array of PEM objects including headers
| Param | Type | Description |
| --- | --- | --- |
| chainPem | <code>buffer</code> \| <code>string</code> | PEM encoded object chain |