TheArchive/session-android
1
0
Fork 0
mirror of https://github.com/oxen-io/session-android.git synced 2024-12-03 15:05:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated README

Browse Source
This commit is contained in:
Moxie Marlinspike 2014-07-13 17:30:59 -07:00
parent 0a23b5fcd5
commit 5a9e5672d3
1 changed files with 25 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
libaxolotl/README.md
View File

@ -1,16 +1,17 @@
# Overview # Overview
The axolotl protocol is a "ratcheting" forward secrecy protocol that works in synchronous and This is a ratcheting forward secrecy protocol that works in synchronous and asynchronous messaging
asynchronous messaging environments. The protocol overview is available [here](https://github.com/trevp/axolotl/wiki), environments. The protocol overview is available [here](https://github.com/trevp/axolotl/wiki),
and the details of the wire format are available [here](https://github.com/WhisperSystems/TextSecure/wiki/ProtocolV2). and the details of the wire format are available [here](https://github.com/WhisperSystems/TextSecure/wiki/ProtocolV2).
## PreKeys ## PreKeys
This protocol implementation heavily leverages the concept of PreKeys. A PreKey is simply an This protocol uses a concept called 'PreKeys'. A PreKey is an ECPublicKey and an associated unique
ECPublicKey and unique PreKey ID. At install time, clients generate a large list of PreKeys ID which are stored together by a server. PreKeys can also be signed.
and transmit them to the server. The server will then remove PreKeys from that list and hand
them to other clients when requested. A single PreKey can never be used twice. At install time, clients generate a single signed PreKey, as well as a large list of unsigned
PreKeys, and transmit all of them to the server.
## Sessions ## Sessions
@ -20,8 +21,8 @@ has been established.
Sessions are established in one of three ways: Sessions are established in one of three ways:
1. PreKeys. A client that wishes to send a message to a recipient can establish a session by 1. PreKeyBundles. A client that wishes to send a message to a recipient can establish a session by
retrieving a PreKey for that recipient from the server. retrieving a PreKeyBundle for that recipient from the server.
1. PreKeyWhisperMessages. A client can receive a PreKeyWhisperMessage from a recipient and use it 1. PreKeyWhisperMessages. A client can receive a PreKeyWhisperMessage from a recipient and use it
to establish a session. to establish a session.
1. KeyExchangeMessages. Two clients can exchange KeyExchange messages to establish a session. 1. KeyExchangeMessages. Two clients can exchange KeyExchange messages to establish a session.
@ -36,6 +37,7 @@ State is kept in the following places:
1. Identity State. Clients will need to maintain the state of their own identity key pair, as well 1. Identity State. Clients will need to maintain the state of their own identity key pair, as well
as identity keys received from other clients. as identity keys received from other clients.
1. PreKey State. Clients will need to maintain the state of their generated PreKeys. 1. PreKey State. Clients will need to maintain the state of their generated PreKeys.
1. Signed PreKey States. Clients will need to maintain the state of their signed PreKeys.
1. Session State. Clients will need to maintain the state of the sessions they have established. 1. Session State. Clients will need to maintain the state of the sessions they have established.
# Using libaxolotl # Using libaxolotl
@ -49,25 +51,30 @@ prekeys.
int registrationId = KeyHelper.generateRegistrationId(); int registrationId = KeyHelper.generateRegistrationId();
List<PreKeyRecord> preKeys = KeyHelper.generatePreKeys(startId, 100); List<PreKeyRecord> preKeys = KeyHelper.generatePreKeys(startId, 100);
PreKeyRecord lastResortKey = KeyHelper.generateLastResortKey(); PreKeyRecord lastResortKey = KeyHelper.generateLastResortKey();
SignedPreKeyRecord signedPreKey = KeyHelper.generateSignedPreKey(identityKeyPair, 5);
// Store identityKeyPair somewhere durable and safe. // Store identityKeyPair somewhere durable and safe.
// Store registrationId somewhere durable and safe. // Store registrationId somewhere durable and safe.
// Store preKeys somewhere durable and safe.
// Store preKeys in PreKeyStore.
// Store signed prekey in SignedPreKeyStore.
## Building a session ## Building a session
A libaxolotl client needs to implement three interfaces: IdentityKeyStore, PreKeyStore, and A libaxolotl client needs to implement four interfaces: IdentityKeyStore, PreKeyStore,
SessionStore. These will manage loading and storing of identity, prekeys, and session state. SignedPreKeyStore, and SessionStore. These will manage loading and storing of identity,
prekeys, signed prekeys, and session state.
Once those are implemented, building a session is fairly straightforward: Once those are implemented, building a session is fairly straightforward:
SessionStore sessionStore = new MySessionStore(); SessionStore sessionStore = new MySessionStore();
PreKeyStore preKeyStore = new MyPreKeyStore(); PreKeyStore preKeyStore = new MyPreKeyStore();
SignedPreKeyStore signedPreKeyStore = new MySignedPreKeyStore();
IdentityKeyStore identityStore = new MyIdentityKeyStore(); IdentityKeyStore identityStore = new MyIdentityKeyStore();
// Instantiate a SessionBuilder for a remote recipientId + deviceId tuple. // Instantiate a SessionBuilder for a remote recipientId + deviceId tuple.
SessionBuilder sessionBuilder = new SessionBuilder(sessionStore, preKeyStore, identityStore, SessionBuilder sessionBuilder = new SessionBuilder(sessionStore, preKeyStore, signedPreKeyStore,
recipientId, deviceId); identityStore, recipientId, deviceId);
// Build a session with a PreKey retrieved from the server. // Build a session with a PreKey retrieved from the server.
sessionBuilder.process(retrievedPreKey); sessionBuilder.process(retrievedPreKey);