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.

Principle

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.

Peers authentication

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.

This table presents Alice's public key and list all Alice's authenticated peers (none so far).

A QR code representing John's public key is scanned by Alice and added to her list of authenticated peers.

John's key is now listed as an authenticated peer.

Alice's public key. A peer may authenticate Alice simply by scanning and importing this public key.

Various representations of Alice'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.

A Note is selected as secret type. The description field represents an optional public description used as metadata for the secret if provided. As it is not encrypted this description must not contain sensitive informations. The description is transmitted with the secret when the share is sent to a peer.

The secret note is edited.

Share menu. The threshold value represents the number of shares that must be collected before a secret can be recovered. Shares labels are the names of peers public keys used to encrypt distributed shares, this metadata is also not encrypted. Listed peers are currently Bluetooth 4.0 connected peers running Core Secret. A closed lock icon means peer's public key is authenticated.

Peers with which the secret must be shared are selected (in this case only John). Sharing immediately starts when Share is taped. Shares are then sent to all selected peers. If a peer encounters an error it is possible to resend its share by re-taping the same button.

Sharing finished.

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:

  • Note
  • File (whose size is limited to 100 kB)
  • Password
  • Contact
  • 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.

Before attempting to recover a secret it is possible to view some metadata of the secret. In particular if the option Include labels was enabled during secret sharing then labels should be available and displayed.

Secret recovering

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.

Automatic recovering of the secret. When a secret is selected for recovering, Alice's device automatically scans for peers at proximity possessing a share of the secret, then automatically connects to them and ask for their shares.

Secret message's view once the secret's recovered and the note decrypted.

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.

Password protection

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.

Add password's option is enabled. The choice between two N values is presented. This value is provided as input to the underlying password key derivation algorithm used (see crypto section for more details). In short, more this value is large more the password key derivation process is resource intensive which therefore usually adds stronger security. Of course as side effect, a larger value will require more time in order to derive its key.

A password is typed.

Secret resharing

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:

Tap Reshare to reencrypt a copy of this secret to new peers. Warning all others options presented in this menu are unencrypted alternative ways of sharing this secret, i.e. in these cases the secret is simply sent as plaintext.

This resharing functionality can be useful for saving a secret by assigning it to new devices.

Restoring secrets

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.

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.

Create a shared encryption key that will later be used to encrypt photos.

The icons displayed in this table are different for secret shares whose the underlying secret is an encryption key than for the others types of secrets. In this case Photos will be a kind of container for encrypted photos, whereas Note example is just an immutable secret note.

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.

When the encryption key Photos is recovered a table with a list of all items encrypted with this key is presented to the user. As expected, in this case the table is currently empty.

Metadata for a new photo.

A new picture is taken and validated.

This photo is encrypted with the encryption key Photos and therefore becomes visible in the list of encrypted items associated with this key. It is then possible to decrypt this photo and view it or to access its informations.

A second photo was taken.

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:

  • Note
  • 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)
  • Password
  • Contact
  • Photo or video

Airdrop sharing

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

Tap Share encrypted to send Photo 1 encrypted to another peer reachable by Wifi or Bluetooth 2.0. Of course the remote peer will need to possess a share of the initial secret to be able to decrypt this photo and to import it.

Peer's selection.

The peer receives the Airdrop request and chooses to accept it. The encrypted message is automatically opened with Core Secret.

Core Secret automatically pre-selects the corresponding encryption key shared with the sender and used to encrypt Photo 1 and ask the user to confirm this key in order to start recovering the encryption key and then decrypt the photo.

The encryption key is recovered, Photo 1 is decrypted and imported. The blue font color used to display its name is used to signal this is a newly imported item.

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.

Secret contact informations. This contact was encrypted with a shared encryption key.

In the detailed informations associated with this contact element a QR code section is automatically included. This QR code represents the encrypted data for the secret contact Alice. This QR code can be scanned and decrypted by a peer sharing the same encryption key.

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.

Directly scan a QR code.

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.

By taping Encrypt Photo 1 currently encrypted with the encryption key Photos is duplicated and assigned to another encryption key.

The target encryption key is selected among all encryption keys currently available in Core secret on the device. Photos copy is selected and Photo 1 is encrypted with this 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.

Settings of Core Secret.

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.

A share request requiring to be explicitly accepted.

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_curve25519xsalsa20poly1305 primitive as specified in NaCl.
  • Secret-key encryptions use the crypto_secretbox_xsalsa20poly1305 primitive 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 /dev/random.
  • The digest function SHA256 and its related HMAC-SHA256 used 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.

URL scheme

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 encrypt and decrypt.

Encryption request

Expected request parameters:

  • description (string, optional): secret's public description.
  • plaintext (string, required): message to encrypt. plaintext will be encrypted with an encryption key selected by the user at Core Secret's launch.
  • filename (string, optional): filename if plaintext is the content of a file. In this case file's content must be Base 64 encoded before assigning it to its plaintext parameter.
  • 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 addPassword is 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.

Example of encryption request performed by an application CSClient using the library InterAppCommunication.

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>

Decryption request

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.

Example of decryption request performed by an application CSClient using the library InterAppCommunication.

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.
  • plaintext (string, required): decrypted message. plaintext is 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 plaintext is Base 64 encoded and must be handled as file's content.

Example of response request returned by Core Secret.

csclient://x-callback-url/IACRequestResponse?&IACRequestID=93C69763-5F10-409B-AD35-ADC4310ED3E6&IACResponseType=0&description=Example&plaintext=<secret message>