Commit 860740a9 authored by Richard van der Hoff's avatar Richard van der Hoff Committed by GitHub
Browse files

Merge pull request #42 from matrix-org/rav/megolm_export

Export and import of megolm session data
parents 14c30da0 c04b770c
......@@ -85,7 +85,8 @@ size_t olm_unpickle_inbound_group_session(
/**
* Start a new inbound group session, based on the parameters supplied.
* Start a new inbound group session, from a key exported from
* olm_outbound_group_session_key
*
* Returns olm_error() on failure. On failure last_error will be set with an
* error code. The last_error will be:
......@@ -99,6 +100,23 @@ size_t olm_init_inbound_group_session(
uint8_t const * session_key, size_t session_key_length
);
/**
* Import an inbound group session, from a previous export.
*
* Returns olm_error() on failure. On failure last_error will be set with an
* error code. The last_error will be:
*
* * OLM_INVALID_BASE64 if the session_key is not valid base64
* * OLM_BAD_SESSION_KEY if the session_key is invalid
*/
size_t olm_import_inbound_group_session(
OlmInboundGroupSession *session,
/* base64-encoded keys; note that it will be overwritten with the base64-decoded
data. */
uint8_t const * session_key, size_t session_key_length
);
/**
* Get an upper bound on the number of bytes of plain-text the decrypt method
* will write for a given input message length. The actual size could be
......@@ -165,6 +183,50 @@ size_t olm_inbound_group_session_id(
uint8_t * id, size_t id_length
);
/**
* Get the first message index we know how to decrypt.
*/
uint32_t olm_inbound_group_session_first_known_index(
const OlmInboundGroupSession *session
);
/**
* Check if the session has been verified as a valid session.
*
* (A session is verified either because the original session share was signed,
* or because we have subsequently successfully decrypted a message.)
*
* This is mainly intended for the unit tests, currently.
*/
int olm_inbound_group_session_is_verified(
const OlmInboundGroupSession *session
);
/**
* Get the number of bytes returned by olm_export_inbound_group_session()
*/
size_t olm_export_inbound_group_session_length(
const OlmInboundGroupSession *session
);
/**
* Export the base64-encoded ratchet key for this session, at the given index,
* in a format which can be used by olm_import_inbound_group_session
*
* Returns the length of the ratchet key on success or olm_error() on
* failure. On failure last_error will be set with an error code. The
* last_error will be:
* * OUTPUT_BUFFER_TOO_SMALL if the buffer was too small
* * OLM_UNKNOWN_MESSAGE_INDEX if we do not have a session key corresponding to the
* given index (ie, it was sent before the session key was shared with
* us)
*/
size_t olm_export_inbound_group_session(
OlmInboundGroupSession *session,
uint8_t * key, size_t key_length, uint32_t message_index
);
#ifdef __cplusplus
} // extern "C"
......
......@@ -61,6 +61,15 @@ InboundGroupSession.prototype['create'] = restore_stack(function(session_key) {
);
});
InboundGroupSession.prototype['import_session'] = restore_stack(function(session_key) {
var key_array = array_from_string(session_key);
var key_buffer = stack(key_array);
inbound_group_session_method(Module['_olm_import_inbound_group_session'])(
this.ptr, key_buffer, key_array.length
);
});
InboundGroupSession.prototype['decrypt'] = restore_stack(function(
message
) {
......@@ -123,4 +132,21 @@ InboundGroupSession.prototype['session_id'] = restore_stack(function() {
return Pointer_stringify(session_id);
});
InboundGroupSession.prototype['first_known_index'] = restore_stack(function() {
return inbound_group_session_method(
Module['_olm_inbound_group_session_first_known_index']
)(this.ptr);
});
InboundGroupSession.prototype['export_session'] = restore_stack(function(message_index) {
var key_length = inbound_group_session_method(
Module['_olm_export_inbound_group_session_length']
)(this.ptr);
var key = stack(key_length + NULL_BYTE_PADDING_LENGTH);
outbound_group_session_method(Module['_olm_export_inbound_group_session'])(
this.ptr, key, key_length, message_index
);
return Pointer_stringify(key);
});
olm_exports['InboundGroupSession'] = InboundGroupSession;
......@@ -2,3 +2,4 @@
/*.account
/*.session
/*.group_session
/group_message
......@@ -268,6 +268,19 @@ def build_arg_parser():
default=sys.stdin)
inbound_group.set_defaults(func=do_inbound_group)
import_inbound_group = commands.add_parser(
"import_inbound_group",
help="Create an inbound group session based an exported inbound group"
)
import_inbound_group.add_argument("session_file", help="Local inbound group session file")
import_inbound_group.add_argument(
"export_file",
help="File to read credentials from (default stdin)",
type=argparse.FileType('r'), nargs='?',
default=sys.stdin,
)
import_inbound_group.set_defaults(func=do_import_inbound_group)
group_decrypt = commands.add_parser("group_decrypt", help="Decrypt a group message")
group_decrypt.add_argument("session_file", help="Local inbound group session file")
group_decrypt.add_argument("message_file", help="Message file (default stdin)",
......@@ -277,6 +290,27 @@ def build_arg_parser():
type=argparse.FileType('wb'), nargs='?',
default=sys.stdout)
group_decrypt.set_defaults(func=do_group_decrypt)
export_inbound_group = commands.add_parser(
"export_inbound_group",
help="Export the keys for an inbound group session",
)
export_inbound_group.add_argument(
"session_file", help="Local inbound group session file",
)
export_inbound_group.add_argument(
"export_file", help="File to export to (default stdout)",
type=argparse.FileType('w'), nargs='?',
default=sys.stdout,
)
export_inbound_group.add_argument(
"--message_index",
help="Index to export session at. Defaults to the earliest known index",
type=int,
)
export_inbound_group.set_defaults(func=do_export_inbound_group)
return parser
def do_outbound_group(args):
......@@ -324,6 +358,19 @@ def do_inbound_group(args):
with open(args.session_file, "wb") as f:
f.write(session.pickle(args.key))
def do_import_inbound_group(args):
if os.path.exists(args.session_file):
sys.stderr.write("Session %r file already exists\n" % (
args.session_file,
))
sys.exit(1)
data = args.export_file.read().translate(None, "\r\n")
session = InboundGroupSession()
session.import_session(data)
with open(args.session_file, "wb") as f:
f.write(session.pickle(args.key))
def do_group_decrypt(args):
session = InboundGroupSession()
session.unpickle(args.key, read_base64_file(args.session_file))
......@@ -333,6 +380,15 @@ def do_group_decrypt(args):
f.write(session.pickle(args.key))
args.plaintext_file.write(plaintext)
def do_export_inbound_group(args):
session = InboundGroupSession()
session.unpickle(args.key, read_base64_file(args.session_file))
index = args.message_index
if index is None:
# default to first known index
index = session.first_known_index()
args.export_file.write(session.export_session(index))
if __name__ == '__main__':
parser = build_arg_parser()
args = parser.parse_args()
......
......@@ -36,6 +36,10 @@ inbound_group_session_function(
lib.olm_init_inbound_group_session, c_void_p, c_size_t
)
inbound_group_session_function(
lib.olm_import_inbound_group_session, c_void_p, c_size_t
)
inbound_group_session_function(
lib.olm_group_decrypt_max_plaintext_length, c_void_p, c_size_t
)
......@@ -49,6 +53,13 @@ inbound_group_session_function(
inbound_group_session_function(lib.olm_inbound_group_session_id_length)
inbound_group_session_function(lib.olm_inbound_group_session_id, c_void_p, c_size_t)
lib.olm_inbound_group_session_first_known_index.argtypes = (c_void_p,)
lib.olm_inbound_group_session_first_known_index.restypes = c_uint32
inbound_group_session_function(lib.olm_export_inbound_group_session_length)
inbound_group_session_function(lib.olm_export_inbound_group_session, c_void_p, c_size_t, c_uint32)
class InboundGroupSession(object):
def __init__(self):
self.buf = create_string_buffer(lib.olm_inbound_group_session_size())
......@@ -76,6 +87,12 @@ class InboundGroupSession(object):
self.ptr, key_buffer, len(session_key)
)
def import_session(self, session_key):
key_buffer = create_string_buffer(session_key)
lib.olm_import_inbound_group_session(
self.ptr, key_buffer, len(session_key)
)
def decrypt(self, message):
message_buffer = create_string_buffer(message)
max_plaintext_length = lib.olm_group_decrypt_max_plaintext_length(
......@@ -95,5 +112,15 @@ class InboundGroupSession(object):
def session_id(self):
id_length = lib.olm_inbound_group_session_id_length(self.ptr)
id_buffer = create_string_buffer(id_length)
lib.olm_inbound_group_session_id(self.ptr, id_buffer, id_length);
lib.olm_inbound_group_session_id(self.ptr, id_buffer, id_length)
return id_buffer.raw
def first_known_index(self):
return lib.olm_inbound_group_session_first_known_index(self.ptr)
def export_session(self, message_index):
length = lib.olm_export_inbound_group_session_length(self.ptr)
buffer = create_string_buffer(length)
lib.olm_export_inbound_group_session(self.ptr, buffer, length,
message_index)
return buffer.raw
......@@ -10,10 +10,11 @@ ALICE_GROUP_SESSION=alice.group_session
BOB_ACCOUNT=bob.account
BOB_SESSION=bob.session
BOB_GROUP_SESSION=bob.group_session
CHARLIE_GROUP_SESSION=charlie.group_session
rm $ALICE_ACCOUNT $BOB_ACCOUNT
rm $ALICE_SESSION $BOB_SESSION
rm $ALICE_GROUP_SESSION $BOB_GROUP_SESSION
rm -f $ALICE_ACCOUNT $BOB_ACCOUNT
rm -f $ALICE_SESSION $BOB_SESSION
rm -f $ALICE_GROUP_SESSION $BOB_GROUP_SESSION $CHARLIE_GROUP_SESSION
$OLM create_account $ALICE_ACCOUNT
$OLM create_account $BOB_ACCOUNT
......@@ -31,4 +32,8 @@ echo "Hello world" | $OLM encrypt $ALICE_SESSION - - | $OLM inbound $BOB_ACCOUNT
$OLM outbound_group $ALICE_GROUP_SESSION
$OLM group_credentials $ALICE_GROUP_SESSION | $OLM inbound_group $BOB_GROUP_SESSION
echo "Hello group" | $OLM group_encrypt $ALICE_GROUP_SESSION - - | $OLM group_decrypt $BOB_GROUP_SESSION
echo "Hello group" | $OLM group_encrypt $ALICE_GROUP_SESSION - group_message
$OLM group_decrypt $BOB_GROUP_SESSION group_message
$OLM export_inbound_group $BOB_GROUP_SESSION | $OLM import_inbound_group $CHARLIE_GROUP_SESSION
$OLM group_decrypt $CHARLIE_GROUP_SESSION group_message
......@@ -30,8 +30,9 @@
#define OLM_PROTOCOL_VERSION 3
#define GROUP_SESSION_ID_LENGTH ED25519_PUBLIC_KEY_LENGTH
#define PICKLE_VERSION 1
#define PICKLE_VERSION 2
#define SESSION_KEY_VERSION 2
#define SESSION_EXPORT_VERSION 1
struct OlmInboundGroupSession {
/** our earliest known ratchet value */
......@@ -43,6 +44,17 @@ struct OlmInboundGroupSession {
/** The ed25519 signing key */
struct _olm_ed25519_public_key signing_key;
/**
* Have we ever seen any evidence that this is a valid session?
* (either because the original session share was signed, or because we
* have subsequently successfully decrypted a message)
*
* (We don't do anything with this currently, but we may want to bear it in
* mind when we consider handling key-shares for sessions we already know
* about.)
*/
int signing_key_verified;
enum OlmErrorCode last_error;
};
......@@ -71,19 +83,24 @@ size_t olm_clear_inbound_group_session(
return sizeof(OlmInboundGroupSession);
}
#define SESSION_EXPORT_RAW_LENGTH \
(1 + 4 + MEGOLM_RATCHET_LENGTH + ED25519_PUBLIC_KEY_LENGTH)
#define SESSION_KEY_RAW_LENGTH \
(1 + 4 + MEGOLM_RATCHET_LENGTH + ED25519_PUBLIC_KEY_LENGTH\
+ ED25519_SIGNATURE_LENGTH)
/** init the session keys from the un-base64-ed session keys */
static size_t _init_group_session_keys(
OlmInboundGroupSession *session,
const uint8_t *key_buf
const uint8_t *key_buf,
int export_format
) {
const uint8_t expected_version =
(export_format ? SESSION_EXPORT_VERSION : SESSION_KEY_VERSION);
const uint8_t *ptr = key_buf;
size_t version = *ptr++;
if (version != SESSION_KEY_VERSION) {
if (version != expected_version) {
session->last_error = OLM_BAD_SESSION_KEY;
return (size_t)-1;
}
......@@ -103,11 +120,15 @@ static size_t _init_group_session_keys(
);
ptr += ED25519_PUBLIC_KEY_LENGTH;
if (!_olm_crypto_ed25519_verify(
&session->signing_key, key_buf, ptr - key_buf, ptr
)) {
session->last_error = OLM_BAD_SIGNATURE;
return (size_t)-1;
if (!export_format) {
if (!_olm_crypto_ed25519_verify(&session->signing_key, key_buf,
ptr - key_buf, ptr)) {
session->last_error = OLM_BAD_SIGNATURE;
return (size_t)-1;
}
/* signed keyshare */
session->signing_key_verified = 1;
}
return 0;
}
......@@ -131,11 +152,35 @@ size_t olm_init_inbound_group_session(
}
_olm_decode_base64(session_key, session_key_length, key_buf);
result = _init_group_session_keys(session, key_buf);
result = _init_group_session_keys(session, key_buf, 0);
_olm_unset(key_buf, SESSION_KEY_RAW_LENGTH);
return result;
}
size_t olm_import_inbound_group_session(
OlmInboundGroupSession *session,
const uint8_t * session_key, size_t session_key_length
) {
uint8_t key_buf[SESSION_EXPORT_RAW_LENGTH];
size_t raw_length = _olm_decode_base64_length(session_key_length);
size_t result;
if (raw_length == (size_t)-1) {
session->last_error = OLM_INVALID_BASE64;
return (size_t)-1;
}
if (raw_length != SESSION_EXPORT_RAW_LENGTH) {
session->last_error = OLM_BAD_SESSION_KEY;
return (size_t)-1;
}
_olm_decode_base64(session_key, session_key_length, key_buf);
result = _init_group_session_keys(session, key_buf, 1);
_olm_unset(key_buf, SESSION_EXPORT_RAW_LENGTH);
return result;
}
static size_t raw_pickle_length(
const OlmInboundGroupSession *session
) {
......@@ -144,6 +189,7 @@ static size_t raw_pickle_length(
length += megolm_pickle_length(&session->initial_ratchet);
length += megolm_pickle_length(&session->latest_ratchet);
length += _olm_pickle_ed25519_public_key_length(&session->signing_key);
length += _olm_pickle_bool_length(session->signing_key_verified);
return length;
}
......@@ -171,6 +217,7 @@ size_t olm_pickle_inbound_group_session(
pos = megolm_pickle(&session->initial_ratchet, pos);
pos = megolm_pickle(&session->latest_ratchet, pos);
pos = _olm_pickle_ed25519_public_key(pos, &session->signing_key);
pos = _olm_pickle_bool(pos, session->signing_key_verified);
return _olm_enc_output(key, key_length, pickled, raw_length);
}
......@@ -194,7 +241,7 @@ size_t olm_unpickle_inbound_group_session(
pos = pickled;
end = pos + raw_length;
pos = _olm_unpickle_uint32(pos, end, &pickle_version);
if (pickle_version != PICKLE_VERSION) {
if (pickle_version < 1 || pickle_version > PICKLE_VERSION) {
session->last_error = OLM_UNKNOWN_PICKLE_VERSION;
return (size_t)-1;
}
......@@ -202,6 +249,14 @@ size_t olm_unpickle_inbound_group_session(
pos = megolm_unpickle(&session->latest_ratchet, pos, end);
pos = _olm_unpickle_ed25519_public_key(pos, end, &session->signing_key);
if (pickle_version == 1) {
/* pickle v1 had no signing_key_verified field (all keyshares were
* verified at import time) */
session->signing_key_verified = 1;
} else {
pos = _olm_unpickle_bool(pos, end, &(session->signing_key_verified));
}
if (end != pos) {
/* We had the wrong number of bytes in the input. */
session->last_error = OLM_CORRUPTED_PICKLE;
......@@ -257,6 +312,32 @@ size_t olm_group_decrypt_max_plaintext_length(
);
}
/**
* get a copy of the megolm ratchet, advanced
* to the relevant index. Returns 0 on success, -1 on error
*/
static size_t _get_megolm(
OlmInboundGroupSession *session, uint32_t message_index, Megolm *result
) {
/* pick a megolm instance to use. If we're at or beyond the latest ratchet
* value, use that */
if ((message_index - session->latest_ratchet.counter) < (1U << 31)) {
megolm_advance_to(&session->latest_ratchet, message_index);
*result = session->latest_ratchet;
return 0;
} else if ((message_index - session->initial_ratchet.counter) >= (1U << 31)) {
/* the counter is before our intial ratchet - we can't decode this. */
session->last_error = OLM_UNKNOWN_MESSAGE_INDEX;
return (size_t)-1;
} else {
/* otherwise, start from the initial megolm. Take a copy so that we
* don't overwrite the initial megolm */
*result = session->initial_ratchet;
megolm_advance_to(result, message_index);
return 0;
}
}
/**
* decrypt an un-base64-ed message
*/
......@@ -268,8 +349,7 @@ static size_t _decrypt(
) {
struct _OlmDecodeGroupMessageResults decoded_results;
size_t max_length, r;
Megolm *megolm;
Megolm tmp_megolm;
Megolm megolm;
_olm_decode_group_message(
message, message_length,
......@@ -316,38 +396,30 @@ static size_t _decrypt(
return (size_t)-1;
}
/* pick a megolm instance to use. If we're at or beyond the latest ratchet
* value, use that */
if ((decoded_results.message_index - session->latest_ratchet.counter) < (1U << 31)) {
megolm = &session->latest_ratchet;
} else if ((decoded_results.message_index - session->initial_ratchet.counter) >= (1U << 31)) {
/* the counter is before our intial ratchet - we can't decode this. */
session->last_error = OLM_UNKNOWN_MESSAGE_INDEX;
return (size_t)-1;
} else {
/* otherwise, start from the initial megolm. Take a copy so that we
* don't overwrite the initial megolm */
tmp_megolm = session->initial_ratchet;
megolm = &tmp_megolm;
r = _get_megolm(session, decoded_results.message_index, &megolm);
if (r == (size_t)-1) {
return r;
}
megolm_advance_to(megolm, decoded_results.message_index);
/* now try checking the mac, and decrypting */
r = megolm_cipher->ops->decrypt(
megolm_cipher,
megolm_get_data(megolm), MEGOLM_RATCHET_LENGTH,
megolm_get_data(&megolm), MEGOLM_RATCHET_LENGTH,
message, message_length,
decoded_results.ciphertext, decoded_results.ciphertext_length,
plaintext, max_plaintext_length
);
_olm_unset(&tmp_megolm, sizeof(tmp_megolm));
_olm_unset(&megolm, sizeof(megolm));
if (r == (size_t)-1) {
session->last_error = OLM_BAD_MESSAGE_MAC;
return r;
}
/* once we have successfully decrypted a message, set a flag to say the
* session appears valid. */
session->signing_key_verified = 1;
return r;
}
......@@ -391,3 +463,62 @@ size_t olm_inbound_group_session_id(
session->signing_key.public_key, GROUP_SESSION_ID_LENGTH, id
);
}
uint32_t olm_inbound_group_session_first_known_index(
const OlmInboundGroupSession *session
) {
return session->initial_ratchet.counter;
}
int olm_inbound_group_session_is_verified(
const OlmInboundGroupSession *session
) {
return session->signing_key_verified;
}
size_t olm_export_inbound_group_session_length(
const OlmInboundGroupSession *session
) {
return _olm_encode_base64_length(SESSION_EXPORT_RAW_LENGTH);
}
size_t olm_export_inbound_group_session(
OlmInboundGroupSession *session,
uint8_t * key, size_t key_length, uint32_t message_index
) {
uint8_t *raw;
uint8_t *ptr;
Megolm megolm;
size_t r;
size_t encoded_length = olm_export_inbound_group_session_length(session);
if (key_length < encoded_length) {
session->last_error = OLM_OUTPUT_BUFFER_TOO_SMALL;
return (size_t)-1;
}
r = _get_megolm(session, message_index, &megolm);
if (r == (size_t)-1) {
return r;
}
/* put the raw data at the end of the output buffer. */
raw = ptr = key + encoded_length - SESSION_EXPORT_RAW_LENGTH;
*ptr++ = SESSION_EXPORT_VERSION;
// Encode message index as a big endian 32-bit number.
for (unsigned i = 0; i < 4; i++) {
*ptr++ = 0xFF & (message_index >> 24); message_index <<= 8;
}
memcpy(ptr, megolm_get_data(&megolm), MEGOLM_RATCHET_LENGTH);
ptr += MEGOLM_RATCHET_LENGTH;
memcpy(
ptr, session->signing_key.public_key,
ED25519_PUBLIC_KEY_LENGTH
);
ptr += ED25519_PUBLIC_KEY_LENGTH;
return _olm_encode_base64(raw, SESSION_EXPORT_RAW_LENGTH, key);
}
......@@ -127,17 +127,18 @@ int main() {
assert_equals(msglen, res);
assert_equals(1U, olm_outbound_group_session_message_index(session));
/* build the inbound session */
size = olm_inbound_group_session_size();
uint8_t inbound_session_memory[size];
OlmInboundGroupSession *inbound_session =
olm_inbound_group_session(inbound_session_memory);
assert_equals(0, olm_inbound_group_session_is_verified(inbound_session));
res = olm_init_inbound_group_session(
inbound_session, session_key, session_key_len);
assert_equals((size_t)0, res);
assert_equals(1, olm_inbound_group_session_is_verified(inbound_session));
/* Check the session ids */
......@@ -174,6 +175,85 @@ int main() {
assert_equals(message_index, uint32_t(0));
}
{
TestCase test_case("Inbound group session export/import");