# Cryptographic mechanisms
Here you will find a brief definition of the cryptographic mechanisms used by Seald.
Their implementation used in Seald is SSCrypto
(opens new window).
# Randomness generation
Depending on the target environment, different random generators are used:
- Node.js: the
crypto.randomBytes
(opens new window) function provided by thecrypto
module; - Browser: if SubtleCrypto (opens new window) is available
window.crypto.getRandomValues
is used. For very old browsers (Chrome <37, Edge<12, IE<11, Firefox<34, Opera<24, Safari<7) a pure JavaScript implementation is provided by node-forge (opens new window), this is a modified version of Fortuna whose seed is derived from the date and browser usage parameters (mouse movements, etc.) - React-native: the
react-native-get-random-values
(opens new window) module provides a secure seed for the Fortuna-based PRNG of node-forge (opens new window).
# Asymmetric key pair generator
The keys used are of type RSA (see RFC 8017 (opens new window)).
Depending on the target environment, different asymmetric key pair generators are used:
- Node.js: the
crypto.generateKeyPair
(opens new window) function provided by thecrypto
module; - Browser: if SubtleCrypto (opens new window) is available
window.crypto.subtle.generateKey
is used. For very old browsers (Chrome <37, Edge<79, IE, Firefox<34, Opera<24, Safari<7) a pure JavaScript implementation is provided by node-forge (opens new window), this is a version ofPRIMEINC
. - React-native: the
react-native-rsa-native
(opens new window) module which uses the SpongyCastle (opens new window) generator in version 1.56 on Android and that of the standard library (opens new window) on iOS.
# Symmetric encryption
To encrypt symmetrically, two algorithms are used to ensure both confidentiality and integrity: an encryption scheme that provides confidentiality only, and a MAC to ensure integrity.
# Sizing
Two symmetric keys are used
- a 256-bit encryption key noted
encryptionKey
; - a 256-bit key for the MAC, noted
authenticationKey
.
Their concatenation in this order is noted messageKey
.
# Lifetime
Keys are used for an indefinite period of time for the data they protect.
# Encryption
Symmetric encryption of clearText
with a messageKey
(concatenation of encryptionKey
and authenticationKey
) to obtain cipheredMessage
is done as follows
- generation of a random initialization vector denoted
iv
of 128 bits; - encryption:
- algorithm:
AES-256-CBC
(see FIPS 197 (opens new window) and NIST Special Publication 800-38A §6.2 (opens new window)); - initialization vector:
iv
; - key:
encryptionKey
; - argument:
clearText
; - result:
cipherText
;
- algorithm:
- MAC:
- algorithm:
HMAC-SHA-256
(see RFC 6234 §8.3 (opens new window)); - argument (
message_array
in RFC 6234): the concatenation ofiv
andcipherText
; - key (
key
in RFC 6234):authenticationKey
; - result:
hmac
;
- algorithm:
- return:
cipheredMessage
which is the concatenation ofiv
,cipherText
, andhmac
.
# Decryption
Symmetric decryption of cipheredMessage
(concatenation of iv
, cipherText
, and hmac
) with a messageKey
(concatenation of encryptionKey
and authenticationKey
) to obtain clearText
is done as follows:
- MAC:
- algorithm:
HMAC-SHA-256
(see RFC 6234 §8.3 (opens new window)); - argument (
message_array
in RFC 6234): the concatenation ofiv
andcipherText
; - key (
key
in RFC 6234):authenticationKey
; - result:
hmac
;
- algorithm:
- comparison of
hmac
withhmac2
, if equal continue; - decryption:
- algorithm:
AES-256-CBC
(see FIPS 197 (opens new window) and NIST Special Publication 800-38A §6.2 (opens new window)); - initialization vector:
iv
; - argument:
cipherText
; - key:
encryptionKey
; - result:
clearText
;
- algorithm:
- return
clearText
.
# Envelope
When using the SDK, cipheredMessage
is put in an envelope format:
# Implementation
The implementation used depends on the target environment;
- Node.js: the
crypto.createCipheriv
(opens new window) function for AES andcrypto.createHmac
(opens new window) for HMAC provided by thecrypto
module; - Browser: if SubtleCrypto (opens new window) is available,
window.crypto.subtle.encrypt
is used for AES andwindow.crypto.subtle.sign
is used for HMAC. For very old browsers (Chrome <37, Edge<79, IE, Firefox<34, Opera<24, Safari<7) a pure JavaScript implementation is provided by node-forge (opens new window). - React-native: a pure JavaScript implementation is provided by node-forge (opens new window).
# Asymmetric cryptography
The keys used are of type RSA (see RFC 8017 (opens new window)).
One pair of keys is reserved for encryption operations, another for signature operations.
# Sizing
The keys are generated with a modulus n
of 4096 bits and a public exponent e
of 65537.
# Lifetime
These keys are generated for a duration not exceeding 157680000 seconds (5 years), with a default lifetime of 94608000 seconds (3 years).
# Asymmetric encryption
The asymmetric encryption of a clearText
with a public key (n,e)
given to obtain cipheredMessage
is performed as follows
- computing a checksum of type
CRC32
(see POSIX.1-2017 §chksum (opens new window)) onclearText
to givecrc32
of length 32 bits; - encryption:
RSAES-OAEP
algorithm (see RFC 8017 §7.1.1 (opens new window)) with the following parameters:SHA1
as the hash functionMGF1-SHA1
(see RFC 8017 §B.2.1 (opens new window)) as the mask generation function- the
L
label left empty
- argument (noted
M
in RFC 8017 §7.1.1 (opens new window)): concatenation ofcrc32
andcleartext
- key used (noted
(n,e)
in RFC 8017 §7.1.1 (opens new window)): public key of the recipient - result `cipheredMessage
- return:
cipheredMessage
TIP
The use of SHA-1
as a hash function in RSAES-OAEP
is robust and compliant with RGS v2.0 (see §B1.2.2.2) (opens new window), even considering that collisions are possible. For more information, see What Hashes Make RSA-OAEP Secure? (opens new window).
# Asymmetric decryption
Asymmetric decryption of a cipheredMessage
with a private key denoted K
given to obtain clearText
is performed as follows:
- decryption:
RSAES-OAEP
algorithm (see RFC 8017 §7.1.2 (opens new window)) with the following parameters:SHA1
as the hash function;MGF1-SHA1
(see RFC 8017 §B.2.1 (opens new window)) as mask generation function;- the
L
label left empty;
- argument (noted
C
in RFC 8017 §7.1.2 (opens new window)): concatenation ofcrc32
andcleartext
; - key used (noted
K
in RFC 8017 §7.1.2 (opens new window)): private key of the recipient; - result
decipheredMessage
;
- decompose
decipheredMessage
intocrc32
andclearText
; - compute a checksum of type
CRC32
(see POSIX.1-2017 §chksum (opens new window)) onclearText
to givecrc32-2
of length 32 bits; - compare
crc32
andcrc32-2
, if equal continue; - return:
clearText
.
# Signature
The production of a signature
signature of a textToSign
using a private key denoted K
is performed as follows:
- signature:
RSASSA-PSS
algorithm (see RFC 8017 §8.1.1 (opens new window)), using in the first step theEMSA-PSS
encoding (see RFC 8017 §9.1.1 (opens new window)) with the following parameters:SHA256
as the hash function;- MGF1
(see [RFC 8017 §B.2.1](https://tools.ietf.org/html/rfc8017)) with
SHA256` as the hash function; sLen
: the maximum length worth 478 bytes given the chosen hash function and the length of the chosen key module;
- argument (noted
M
in RFC 8017 §8.1.1 (opens new window)):textToSign
; - key used (noted
K
in RFC 8017 §8.1.1 (opens new window)): Private key of the signer; - result:
signature
;
- return:
signature
.
# Signature verification
Verification of a signature
signature of a textToSign
using a public key denoted (n,e)
associated with the private key K
used to sign is performed as follows:
- signature verification:
RSASSA-PSS
algorithm (see RFC 8017 §8.1.1 (opens new window)), using in the first step theEMSA-PSS
encoding (see RFC 8017 §9.1.1 (opens new window)) with the following parameters:SHA256
as the hash function;MGF1
(see RFC 8017 §B.2.1 (opens new window)) withSHA256
as the hash function;sLen
: the maximum length worth 478 bytes given the chosen hash function and the length chosen for the key module;
- arguments:
- message (noted
M
in RFC 8017 §8.1.2 (opens new window)):textToSign
; - signature (noted
S
in RFC 8017 §8.1.2 (opens new window)):signature
;
- message (noted
- key used (noted
(n,e)
in RFC 8017 §8.1.2 (opens new window)): signer's public key; - result: boolean
signatureIsValid
indicating if the signature is valid for the message;
- return:
signatureIsValid
.
# Implementation
The implementation used depends on the target environment;
- Node.js: the functions
crypto.privateDecrypt
(opens new window),crypto.publicEncrypt
(opens new window),crypto.sign
(opens new window) andcrypto.verify
(opens new window) provided by thecrypto
module; - Browser: if SubtleCrypto (opens new window) is available,
window.crypto.subtle.encrypt
,window.crypto.subtle.decrypt
,window.crypto.subtle.sign
andwindow.crypto.subtle.verify
are used. For very old browsers (Chrome <37, Edge<79, IE, Firefox<34, Opera<24, Safari<7) a pure JavaScript implementation is provided by node-forge (opens new window). - React-native: a pure JavaScript implementation is provided by node-forge (opens new window).
# Key derivation
Deriving a key from a passphrase
and a salt
to obtain key
is done as follows
- derivation:
- algorithm:
SCrypt
(opens new window), with the following parameters:N
: 16384;r
: 8;p
: 1;- output size: 64 bytes;
- arguments:
passphrase
andsalt
given; - result:
key
;
- algorithm:
- return:
key
.
# Implementation
The implementation used depends on the target environment;
- Node.js: the function
crypto.scrypt
(opens new window) provided by thecrypto
module is used; - Browser: the module
scrypt-js
(opens new window) is used. - React-native: the module
@seald-io/react-native-scrypt
(opens new window) is used, which itself uses libscrypt (opens new window).
← Definitions Protocols →