With Core Secret split a secret in multiples shares and require the possession of a subset of these shares in order to reassemble the secret.
Each secret is divided in a given number of shares along with a fixed threshold value requiring the possession of a minimal number of shares in order to recover the secret value. Concretely one person may share and distribute a secret with several peers, each one of these peers will later be able to recover the initial secret by using its own share and by requesting additional shares to other peers until reaching the required threshold for successfully recovering the secret. Core Secret implements the Shamir's secret sharing scheme.
The first step before sharing a secret or being able to receive a secret share is to authenticate its trusted peers. It is a necessary step because the exchanges leading to the share of a secret will only be authorized with authenticated peers. A peer's public key must be imported in order to consider this peer as authenticated. Conversely, a device will also be required to make peers import its own public key before sharing a secret with them. In Core Secret a public key is represented as a QR code and must be scanned by a peer if it wants to import it. The following example shows Alice importing John's public key.
Core Secret implements two main features. The first one enables sharing secrets of limited sizes with peers by using Bluetooth Low Energy; whereas the second one will be useful to create and share larger secrets using asynchronous methods.
Secret sharing with Bluetooth 4.0
The purpose of this feature is to share secrets with different peers. For instance the sharer also called the initiator may choose to share a secret file or a secret note with peers selected among his list of trusted authenticated peers.
In this case all communications between the initiator and its peers use Bluetooth 4.0 (see the FAQ to see the list of current Bluetooth 4.0 compatibles devices). Bluetooth 4.0 being not a technology intended for transferring large quantity of data the tranferts are then limited in this mode. The limit size is currently arbitrarily fixed to 100 kB (note that this limitation might change as the implementations improve and observed throughputs increase).
These are the currently implemented pre-defined secrets templates:
- File (whose size is limited to 100 kB)
- Encryption key (see next sections for more details)
Remark on shares labels:
During the previous secret sharing, the option Include labels was enabled. This option sends unencrypted (in the clear) with each secret share a list of all public keys labels of the peers with whom the secret is shared. These informations can be useful at recovery to know which peer has a share of the secret to recover. However if it appears that these labels disclose too much sensitive informations it is possible by disabling this option to not send any label.
Once secret sharing's done, not only each peer owns a share of the secret key used to encrypt the secret but it also has a share of the ciphertext. That is after the secret message is encrypted with the secret key its result is also divided in shares and each peer is assigned one share of the ciphertext. Therefore at any given time any peer only have one share of the secret and one share of the ciphertext stored in its device, none of them store the full ciphertext on its system. Anytime a peer wants to recover the plaintext message it has to gather secret shares and ciphertext shares, knowing that this number of shares is determined by the threshold value fixed before the secret was shared. Because requests for gathering shares from peers are also made in Bluetooth 4.0, only peers at proximity can be queried.
If the threshold value is not reached the secret can not be recovered. If one or more peers delete their shares the secret may become definitively unrecoverable and is lost. A share is automatically obtained from a peer if the peer requesting it is authenticated (by its public key) on this peer and if it provides a valid proof that it also holds a valid share of the secret itself. This procedure doesn't require any further authorization step from the peer. After the initial sharing the initiator like any of its peers only keeps a share of the secret and therefore will also need to query for shares when it seeks to recover the secret. Once recovered a secret is available as long as the application remains active (i.e. device not locked or in sleep mode, application not in background) and as long as the current menu is not popped/exited.
Added to the threshold secret sharing introduced before it is also possible to add another layer of security by adding a password for protecting the secret. With this additional protection when a device successfully recovers a secret and decrypts its ciphertext a password is then asked to fully decrypt the secret. Therefore in this setting the initial plaintext is encrypted two times, one time with the shared secret and then a second time with a secret key directly derived from the user provided password.
Once secret shares are distributed the original secret message can not be edited anymore and new peers can not be added to the list of peers for this secret. Nevertheless it is possible to modify the original secret or share it with new peers simply by resharing a copy of the secret. Core Secret provides an easy way to reshare any given secret, it just requires to first recover the secret then to choose the reshare option in the proposed list of actions:
This resharing functionality can be useful for saving a secret by assigning it to new devices.
A secret share is intimately tied with the device on which it was created or first received, therefore it is not possible to restore the same secret share on a different device after the restoration of a backup, i.e. it is not possible to backup Core Secret from a device through iTunes and then restore it on a new device and keep the old secret shares. However, it is possible to successfully restore a Core Secret's backup (all Core Secret application data, including all secret shares) on the same device it was originally backed-up from. The reason is simply for preventing multiple instances of secret shares running on different devices. The most common method for overcoming this limitation is simply by resharing the secret before switching to another device.
Pasteboard & temporary files
It is often possible and convenient to copy a recovered secret data in the pasteboard buffer. While iOS doesn't provide a foolproof system-wide mechanism to delete this buffer, Core Secret tries to minimize the duration a secret is held in this buffer by deleting it while in background few minutes after Core Secret has been backgrounded. Note that if Core Secret is killed it may not have had the time to wipe out this buffer, in this case just be sure to restart Core Secret.
Likewise in several occassions temporary files are either generated or copied to Core Secret, for instance when a file is copied to Core Secret through iTunes or when a file is opened with Core Secret from another iOS app. In these cases as soon as this file is encrypted by Core Secret its plaintext representation is deleted from Core Secret, also anytime Core Secret is exited (when the home button is pressed) all temporary files are deleted. Maybe the unattended side effect will be to lose a plaintext file you still haven't encrypted; in this case just re-open it with Core Secret and don't wait for encrypting it.
Shared encryption key
Create a shared encryption key
The second most important feature of Core Secret is directly a by-product of the previous Bluetooth sharing functionality, in fact it is a particular case of this feature. In effect, like it's possible to share a file or a secret note this functionality enables the sharing of an encryption key.
Adding encrypted items
Shared encryption keys provide several benefits among them are that once recovered an encryption key can be used to encrypt one or more new secret items, and these items will have fewer restrictions than in the Bluetooth sharing mode. Indeed there is no size limitation in this mode and also ciphertexts are transmitted in full and stored in full on a device.
For instance an encryption key might be used to encrypt a set of photos.
At the difference of the Bluetooth sharing mode a same encryption key can be used to encrypt more than one item which will provide more flexibility to asynchronously share encrypted elements with other peers. Moreover, as soon as an encryption key is recovered it can be used without limit to decrypt any data that was previously encrypted with this key. Of course if the secret share corresponding to an encryption key is deleted from Core Secret all the items encrypted with this key will become unavailable and will therefore be automatically deleted by the application.
In this mode it is possible to create new secrets from the following pre-defined templates:
- File (a file's size is not limited anymore but in practice its maximum size will depend on the quantity of memory available on the system, usually it will work with 50 MB files unless a password is used which in this case will constrain the memory a lot more and will require smaller files)
- Photo or video
The encryption key being shared with one or more peers it is possible to send an element encrypted with this key to one of these peers and these peers will be able to decrypt it from their shares of the initial secret (once recovered). By extending the previous example it is possible to send an encrypted copy of one of the photos to another peer by using Airdrop (see the FAQ to see the list of current Airdrop compatibles devices).
With this method it is possible to encrypt and share items of bigger sizes. It is currently possible to send such ciphertexts to a remote peer through Airdrop or by Mail.
QR code sharing
When the size of an encrypted item is really small, that is when its plaintext was around at most 256 bytes, it is possible to share it with a peer by using a QR code representation of the encrypted data and making it scan by the peer. This method is different but the result is the same than with previous Mail and Airdrop methods.
For instance an encryption key can be used to encrypt Contact informations and if the corresponding data is short enough a QR code will automatically be generated and may be shared.
QR code scanning
The Scan QR code functionality available from the main menu can be used to either scan a public key (from a peer) or an encrypted shared item. Core Secret also provides a shortcut to access this functionality simply by shaking the device from the main menu.
Duplicating a secret
An encrypted item may also be encrypted with a new encryption key different from the original key used to encrypt this item. This functionality may be used in order to reshare a secret item with a new peer, one that had no share from the original encryption key.
Managing Bluetooth 4.0 services
In the settings, Bluetooth 4.0 services can be disabled which means that no peer will be able to connect to this device to request any secret share stored on this device. This functionality might be useful for improving the battery life when Core secret is not needed or to further improve the security. Indeed, it is possible to think of a use case where a secret would be shared between multiple peers, where every shares would be required to recover the original secret and in which a device would disable this option as well as its Wifi and mobile network. Therefore in this case only that device would be able to complete the recovery of the secret. Indeed, any other device attempting the recovery would always fail to recover the last mandatory share held by that device.
Confirm secret sharing
By default a peer automatically accepts any new secret share received from authenticated peers (peers with authorized public keys). However when enabled the second option presented in the settings of Core Secret prevents this behavior. In this case new secret shares received by the device will be required to be explicitly accepted by the user (see screenshot below). Moreover, when the application is not active any new secret share received is automatically refused and discarded.
Core Secret's crypto source code is available on github in this repository.
Details of cryptographic primitives used:
- The crypto library used for performing secret-key cryptography and public-key cryptography is NaCl, more precisely Core Secret uses the libsodium port of NaCl.
- All public keys used are keys on the elliptic curve Curve25519.
- Public-key encryptions use the
crypto_box_curve25519xsalsa20poly1305primitive as specified in NaCl.
- Secret-key encryptions use the
crypto_secretbox_xsalsa20poly1305primitive as specified in NaCl. These cryptosystems use Salsa20 and Poly1305 respectively for encryption and as MAC.
- The secret sharing scheme implemented is the Shamir's threshold secret sharing scheme.
- The Schnorr identification scheme on elliptic curve Ed25519 is used to implement proofs-of-knowledge. Its related Schnorr signature scheme is also used for providing proofs-of-possessions.
- Password based key derivations use scrypt with the following parameters:
r=8, p=1, N=32768 or N=65536.
- The CSPRNG used to generate keys and IVs is the one provided in the iOS framework which is expected to directly read random bytes from
- The digest function
SHA256and its related
HMAC-SHA256used in Core Secret come from the CommonCrypto framework from iOS's SDK.
Third parties applications may interact with Core Secret by using Core Secret to encrypt or decrypt messages using secret keys provided and managed by Core Secret. A client application only needs to follow the request scheme presented in the following sections. See this example application for a concrete implementation.
Core Secret implements the inter-applications protocol as specified by x-callback-url. In particular, Core Secret internally uses the InterAppCommunication library to handle external requests and return responses requests.
Core Secret's URL scheme is
coresecret://, encryption and decryption actions are respectively
Expected request parameters:
description(string, optional): secret's public description.
plaintext(string, required): message to encrypt.
plaintextwill be encrypted with an encryption key selected by the user at Core Secret's launch.
filename(string, optional): filename if
plaintextis the content of a file. In this case file's content must be Base 64 encoded before assigning it to its
store(bool, optional, default value: 0): 1 if the encrypted result must be store in Core Secret; 0 otherwise.
addPassword(bool, optional, default value: 0): 1 if a password must be provided; 0 otherwise.
scryptN(int, optional): value of parameter N used by scrypt, only expected if
addPasswordis also provided as request parameter. Its value must be greater or equal to
32768. If this parameter is not provided a choice will be interactively presented to the user when the password is asked.
coresecret://x-callback-url/encrypt?&plaintext=<message to encrypt>&description=Example&x-source=CSClient&x-cancel=csclient%3A%2F%2Fx-callback-url%2FIACRequestResponse%3F%26IACRequestID%3D818A521F-A6F2-4183-9116-216F190385E0%26IACResponseType%3D2%26&x-error=csclient%3A%2F%2Fx-callback-url%2FIACRequestResponse%3F%26IACRequestID%3D818A521F-A6F2-4183-9116-216F190385E0%26IACResponseType%3D1%26&x-success=csclient%3A%2F%2Fx-callback-url
Expected response request parameters:
encryptedData(base64 string, required): encrypted data corresponding to the encryption of
plaintext. This parameter is missing if an error was encountered while handling the encrypt request.
Example of response request returned by Core Secret.
csclient://x-callback-url/IACRequestResponse?&IACRequestID=818A521F-A6F2-4183-9116-216F190385E0&IACResponseType=0&encryptedData=<encrypted base 64 message>
Expected request parameters:
encryptedData(base64 string, required): message to decrypt. The encryption key will automatically be selected by Core Secret when it is launched and the user will need to confirm it before performing the decrypt operation.
store(bool, optional, default value: 0): 1 if the decrypted message must be stored in Core Secret; 0 otherwise.
coresecret://x-callback-url/decrypt?&encryptedData=<encrypted base 64 message>&x-source=CSClient&x-cancel=csclient%3A%2F%2Fx-callback-url%2FIACRequestResponse%3F%26IACRequestID%3D93C69763-5F10-409B-AD35-ADC4310ED3E6%26IACResponseType%3D2%26&x-error=csclient%3A%2F%2Fx-callback-url%2FIACRequestResponse%3F%26IACRequestID%3D93C69763-5F10-409B-AD35-ADC4310ED3E6%26IACResponseType%3D1%26&x-success=csclient%3A%2F%2Fx-callback-url%2FIACRequestResponse%3F%26IACRequestID%3D93C69763-5F10-409B-AD35-ADC4310ED3E6%26IACResponseType%3D0%26
Expected response request parameters:
description(string, optional): public description of the secret
plaintext(string, required): decrypted message.
plaintextis Base 64 encoded if its data originate from a file (see next parameter). This parameter is missing if an error was encountered while decrypting the data.
filename(string, optional): filename corresponding to file's content
plaintext. In this case
plaintextis Base 64 encoded and must be handled as file's content.
Example of response request returned by Core Secret.