@perfood/capacitor-crypto-api

This is a capacitor plugin that provides a simple API to generate key-pairs in the Secure Enclave (iOS) or StrongBox/TEE (Android) and use them to sign and verify data.

Limitations of the Secure Enclave (iOS)

"Works only with NIST P-256 elliptic curve keys. These keys can only be used for creating and verifying cryptographic signatures, or for elliptic curve Diffie-Hellman key exchange (and by extension, symmetric encryption)." - Apple Developer Documentation

Since the Secure Enclave only supports the NIST P-256 elliptic curve, only ECDSA is supported. ECDH is not supported, but may be supported in the future. PRs are welcome.

Format of the signature

Secure Enclave (iOS) and StrongBox/TEE (Android) return the signature in ASN.1 DER format. The WebCrypto API returns the signature in raw (IEEE P1363) format.

This plugin has the functions derToP1363 and p1363ToDer to convert the signature from ASN.1 DER to raw (IEEE P1363) format and vice versa.

For development

The plugin also uses the WebCrypto API to generate key-pairs in the browser and use them to sign and verify data. The key-pairs are stored in the browser's local storage.

WebCrypto API is only available in secure contexts (https)

Use Case

This can be used to realize a 2-factor-authentication mechanism, where the private-key is stored in the Secure Enclave (iOS) or StrongBox/TEE (Android) and the public-key is stored on the server.

The server creates a challenge and sends it to the client. The client signs the challenge with the private-key and sends the signed data back to the server.

The server can then verify the signature of the data with the public-key and be sure that the data was signed by the private-key.

There is an example in the example directory.

Install

npm install @perfood/capacitor-crypto-api
npx cap sync

API

• list()
• generateKey(...)
• loadKey(...)
• deleteKey(...)
• sign(...)
• verify(...)
• Interfaces

list()

list() => Promise<ListResponse>

Returns all key-pair tags that are available in the Secure Enclave (iOS) or StrongBox/TEE (Android).

Returns: Promise<ListResponse>

generateKey(...)

generateKey(options: GenerateKeyOptions) => Promise<GenerateKeyResponse>

Generates a key-pair in the Secure Enclave (iOS) or StrongBox/TEE (Android), tags it for alter referencing and returns the public-key only, since the private-key is protected and can't be extracted.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | GenerateKeyOptions |

Returns: Promise<GenerateKeyResponse>

Since: 1.0.0

loadKey(...)

loadKey(options: LoadKeyOptions) => Promise<LoadKeyResponse>

Loads the public-key from the Secure Enclave (iOS) or StrongBox/TEE (Android).

| Param | Type | | ------------- | --------------------------------------------------------- | | options | LoadKeyOptions |

Returns: Promise<LoadKeyResponse>

Since: 1.0.0

deleteKey(...)

deleteKey(options: DeleteKeyOptions) => Promise<void>

Deletes the key-pair from the Secure Enclave (iOS) or StrongBox/TEE (Android).

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | DeleteKeyOptions |

Since: 1.0.0

sign(...)

sign(options: SignOptions) => Promise<SignResponse>

Signs the data in the Secure Enclave (iOS) or StrongBox/TEE (Android). Uses the private-key associated with the tag.

Only ECDSA is supported.

| Param | Type | | ------------- | --------------------------------------------------- | | options | SignOptions |

Returns: Promise<SignResponse>

Since: 1.0.0

verify(...)

verify(options: VerifyOptions) => Promise<VerifyResponse>

Verifies the signature of the data with the foreign public-key.

Only ECDSA is supported.

| Param | Type | | ------------- | ------------------------------------------------------- | | options | VerifyOptions |

Returns: Promise<VerifyResponse>

Since: 1.0.0

Interfaces

ListResponse

| Prop | Type | Description | | ---------- | --------------------- | ------------------ | | list | string[] | The key-pair tags. |

GenerateKeyResponse

| Prop | Type | Description | | --------------- | ------------------- | -------------------------------- | | publicKey | string | The public-key in base64 format. |

GenerateKeyOptions

| Prop | Type | Description | | --------- | ------------------- | ----------------- | | tag | string | The key-pair tag. |

LoadKeyResponse

| Prop | Type | Description | | --------------- | ------------------- | -------------------------------- | | publicKey | string | The public-key in base64 format. |

LoadKeyOptions

| Prop | Type | Description | | --------- | ------------------- | ----------------- | | tag | string | The key-pair tag. |

DeleteKeyOptions

| Prop | Type | Description | | --------- | ------------------- | ----------------- | | tag | string | The key-pair tag. |

SignResponse

| Prop | Type | Description | | --------------- | ------------------- | ------------------------------- | | signature | string | The signature in base64 format. |

SignOptions

| Prop | Type | Description | | ---------- | ------------------- | ----------------- | | tag | string | The key-pair tag. | | data | string | The data to sign. |

VerifyResponse

| Prop | Type | Description | | -------------- | -------------------- | ---------------------------------- | | verified | boolean | Whether the signature is verified. |

VerifyOptions

| Prop | Type | Description | | ---------------------- | ------------------- | ---------------------------------------- | | foreignPublicKey | string | The foreign public-key in base64 format. | | data | string | The signed data. | | signature | string | The signature in base64 format. |