@perfood/capacitor-crypto-api

@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.