Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-megolm Reference Manual, version 1.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 03:51:55 2022 GMT+0.
Next: Systems, Previous: The cl-megolm Reference Manual, Up: The cl-megolm Reference Manual [Contents][Index]
These create usable bindings over the top of the Olm/Megolm library used for encryption on the matrix protocol see here
Its important that you run (cleanup <object>) on the instances of the classes
If you do not run (cleanup ..) on these after you are done with them the memory will not get cleaned up.
To run the tests for cl-megolm run:
(ql:quickload :cl-megolm)
(in-package :cl-megolm)
(asdf:test-system :cl-megolm)
If you find that any of the 71 tests fail, please create an issue and let me know.
Instantiate a new account with (make-account).
(let ((alice (make-account)))
(unwind-protect
(identity-keys alice)
(cleanup alice)))
(:|ed25519| "nu/bcRm/rSmg1Y16I6RdpjHqGya9dlEVeSlm+RTpjL8" :|curve25519|
"UCIuApFOW5KD5uQqcXNAALV7gBarVzWZH/XQly6XCQ4")
Generate one time keys for an account with (generate-one-time-keys <account> <count>).
(let ((alice (make-account)))
(unwind-protect
(progn
(generate-one-time-keys alice 1)
(one-time-keys alice))
(cleanup alice)))
(:|curve25519| (:AAAAAQ "9mjvuusuJR3CxPsTApXkkDjmo7uZohcyiF8QZwRDXSY"))
Mark them as published with (mark-keys-as-published <account>)
(let ((alice (make-account)))
(unwind-protect
(progn
(generate-one-time-keys alice 1)
(mark-keys-as-published alice)
(one-time-keys alice))
(cleanup alice)))
(:|curve25519| NIL)
You can pickle accounts with (pickle <account> <passphrase>) and unpickle with (from-pickle :account <passphrase>) If passphrase is wrong the condition bad-account-key is signalled.
Sessions are used to create peer to peer encrypted channels between two accounts.
(let* ((alice (make-account))
(bob (make-account)))
(unwind-protect
(progn (generate-one-time-keys bob 1)
(let ((id-key (curve bob))
(one-time (second (second (one-time-keys bob)))))
(make-outbound-session alice one-time id-key)))
(progn (cleanup alice)
(cleanup bob))))
#<OUTBOUND-SESSION {10069C3763}>
Its important to remember to run (cleanup ..) on the session you created once you
are done as this frees the foreign pointer and runs the appropriate olm function.
CL-MEGOLM> (let* ((alice (make-account))
(bob (make-account)))
(unwind-protect
(progn (generate-one-time-keys bob 1)
(let* ((id-key (curve bob))
(one-time (second (second (one-time-keys bob))))
(session (make-outbound-session
alice one-time id-key))
(encrypted (encrypt session "im a message"))
(bob-session
(make-inbound-session bob encrypted nil))
(decrypted (decrypt bob-session encrypted)))
(print (ciphertext encrypted))
(print decrypted)
(cleanup session);would be better in unwind-protect
(cleanup bob-session)))
(progn (cleanup alice)
(cleanup bob))))
"AwogqG666oomJS3QTDzlPOBjrRqBkNa1l3IvekmTrHgHeF4SIG/beUrUuCCYR5OwX5u0QdJpnR8lnQBpfAODx4/fkQB6GiAjSwCQ9FTABplH+1RxPEcYGMrbqPeLMzTvdgYJTedPIiI/Awog2c5GHjNKlFLBh6yAJu5EFAs+Jo75BFZwUkRT68lvN2MQACIQcoDAnBDFfE1C6e8PeyDMIQf7UhYDYS+y"
"im a message"
Pickle session with (pickle <session> <passphrase>) unpickle with (from-pickle :session <pickle> <passphrase>)
Passphrase can be an empty string like "".
Group sessions allow for one-to-many encrypted channels. All participants need to know the group session key in order to participate. Its important to share the key before any messages are encrypted because the key is ratcheted.
CL-MEGOLM> (let* ((alice-g (make-outbound-group-session))
(bob-i-g (make-inbound-group-session (session-key alice-g))))
(cleanup alice-g)
(cleanup bob-i-g))
NIL
Its important to note that when decrypt is called with an inbound-group-session it returns multiple values, the decrypted message and the message index.
CL-MEGOLM> (let* ((alice-g (make-outbound-group-session))
(bob-i-g (make-inbound-group-session (session-key alice-g))))
(unwind-protect
(let ((encrypt (encrypt alice-g "Im a message")))
(print encrypt)
(multiple-value-bind (message message-index)
(decrypt bob-i-g encrypt)
(print message)
(print message-index)))
(progn
(cleanup alice-g)
(cleanup bob-i-g))))
"AwgAEhAlVvR9vy7jRlH897toXmVgD9neM5jrkPtBIXJOwOE4R1BOLiuNpsH/zyG7aQ1UBKzXHUFHwiXgHVBjQDHnjAWJ8VzfQUSqOymBH7u+ZVB4qMQqg1XBiGEJ"
"Im a message"
0
To pickle group sessions use (pickle <inbound-group | outbound-group> <passphrase>) to unpickle
use (from-pickle <:inbound-group | :outbound-group> <passphrase> ) the keyword will depend on the whether you pickled an inbound group or and outbound group.
All conditions are a subclass of olm-error. All the conditions
that will be signalled listed in src/conditions.lisp
If at any point the condition condition-missing is signalled, please create an
issue with the stacktrace and I will add the condition.
MIT
Next: Modules, Previous: Introduction, Up: The cl-megolm Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
A copy of the python functionality provided as bindings for Olm.
See: https://gitlab.matrix.org/matrix-org/olm/-/blob/master/python/. Big thanks to
Borodust for creating the initial bindings using Claw.
K1D77A
MIT
1.0.1
src (module).
Next: Files, Previous: Systems, Up: The cl-megolm Reference Manual [Contents][Index]
Modules are listed depth-first from the system components tree.
cl-megolm (system).
Next: Packages, Previous: Modules, Up: The cl-megolm Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: cl-megolm/src/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
cl-megolm (system).
Next: cl-megolm/src/olm.lisp, Previous: cl-megolm/cl-megolm.asd, Up: Lisp [Contents][Index]
src (module).
Next: cl-megolm/src/conditions.lisp, Previous: cl-megolm/src/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
src (module).
Next: cl-megolm/src/classes.lisp, Previous: cl-megolm/src/olm.lisp, Up: Lisp [Contents][Index]
olm.lisp (file).
src (module).
Next: cl-megolm/src/helpers.lisp, Previous: cl-megolm/src/conditions.lisp, Up: Lisp [Contents][Index]
conditions.lisp (file).
src (module).
Next: cl-megolm/src/utility.lisp, Previous: cl-megolm/src/classes.lisp, Up: Lisp [Contents][Index]
classes.lisp (file).
src (module).
Next: cl-megolm/src/session.lisp, Previous: cl-megolm/src/helpers.lisp, Up: Lisp [Contents][Index]
helpers.lisp (file).
src (module).
Next: cl-megolm/src/account.lisp, Previous: cl-megolm/src/utility.lisp, Up: Lisp [Contents][Index]
utility.lisp (file).
src (module).
%make-olm-message (function).
Next: cl-megolm/src/group-session.lisp, Previous: cl-megolm/src/session.lisp, Up: Lisp [Contents][Index]
session.lisp (file).
src (module).
gen-account (function).
Next: cl-megolm/src/pk.lisp, Previous: cl-megolm/src/account.lisp, Up: Lisp [Contents][Index]
account.lisp (file).
src (module).
Next: cl-megolm/src/sas.lisp, Previous: cl-megolm/src/group-session.lisp, Up: Lisp [Contents][Index]
group-session.lisp (file).
src (module).
Previous: cl-megolm/src/pk.lisp, Up: Lisp [Contents][Index]
pk.lisp (file).
src (module).
Next: Definitions, Previous: Files, Up: The cl-megolm Reference Manual [Contents][Index]
Packages are listed by definition order.
common-lisp.
Next: Indexes, Previous: Packages, Up: The cl-megolm Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Public Interface, Up: Public Interface [Contents][Index]
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
Create a new Olm account. Creates a new account and its matching identity key pair. Signals ’olm-account-error on failure. If there weren’t enough random bytes signals ’olm-account-not-enough-random.
Create a new inbound group session.
Start a new inbound group session, from a key exported from
an outbound group session. Signals ’olm-invalid-base64 if the session
key is not valid base64 or ’olm-bad_session_key if the session key is
invalid.
Create a new Olm message with the supplied ciphertext
Create a make Olm prekey message with the supplied ciphertext
Create a new outbound group session.
Start a new outbound group session. Raises OlmGroupSessionError on
failure.
Create a new PK Decryption object. If fails signals either ’olm-input-buffer-too-small or ’output-buffer-too-small
Create a new PK encryption object. Creates a pointer that has to be freed later.
Creates a new instance of pk-signing from a randomly generated seed.
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
automatically generated reader method
automatically generated reader method
automatically generated writer method
automatically generated writer method
Used to free the pointer associated with the object.
Super important to call this when done using an object that needs it.
Decrypt a previously encrypted pk message.
Decrypt a message
Returns a tuple of the decrypted plain-text and the message index of
the decrypted message or signals various conditions on failure.
On failure the potential conditions are:
olm-invalid-base64 if the message is not valid base64
olm-bad-message-version if the message was encrypted with an
unsupported version of the protocol
olm-bad-message-format if the message headers could not be
decoded
olm-bad-message-mac if the message could not be verified
olm-unknown-message-index if we do not have a session key
corresponding to the message’s index (i.e., it was sent before
the session key was shared with us)
Decrypts a message using the session. Returns the plaintext string
on success. Raises OlmSessionError on failure. If the base64 couldn’t
be decoded then the error message will be ’invalid-base64. If the message is for an unsupported version of the protocol the condition signalled
will be ’bad-message-version. if the message couldn’t be decoded then
the condition signalled will be ’bad-message-format. if the mac on the
message was invalid then the condition will be ’bad-message-mac
Returns the encrypted pk-message instance.
Encrypt a plaintext for the recipient set using
%olm:pk-encryption-set-recipient-key. Writes to the ciphertext, mac, and
ephemeral_key buffers, whose values should be sent to the recipient. mac is
a Message Authentication Code to ensure that the data is received and
decrypted properly. ephemeral_key is the public part of the ephemeral key
used (together with the recipient’s key) to generate a symmetric encryption
key. If the ciphertext, mac, or
ephemeral_key buffers were too small then the condition
will be output-buffer-too-small. If there weren’t enough random bytes then
the condition olm-input-buffer-too-small will be signalled.
Encrypt a message. Returns the encrypted ciphertext.
automatically generated reader method
automatically generated writer method
Export an inbound group session
Export the base64-encoded ratchet key for this session, at the given
index, in a format which can be used by import_session().
Signals 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)
The first message index we know how to decrypt
Restore a previously stored PkDecryption object.
Creates a PkDecryption object from a pickled base64 string. Decrypts
the pickled object using the supplied passphrase.
If the passphrase doesn’t match the one used to encrypt the
session then the error message for the condition ’bad-account-key is signalled.
If the base64 the pickle couldn’t be decoded then the condition signalled will be
’invalid-base64
Load a previously stored outbound group session.
loads an outbound group session from a pickled base64 string and
returns an outboundgroupsession object. decrypts the session using the
supplied passphrase. raises olmsessionerror on failure. if the
passphrase doesn’t match the one used to encrypt the session then the
condition signalled for the exception will be ’bad-account-key. if the
base64 couldn’t be decoded then the condition signalled will be’invalid-base64.
Load a previously stored inbound group session.
Loads an inbound group session from a pickled base64 string and returns
an inbound-group-session object. Decrypts the session using the supplied
passphrase. If the passphrase doesn’t match the one used to encrypt
the session then signals ’olm-inbound-bad-account-key. If the base64
couldn’t be decoded then signals ’olm-inbound-invalid-base-64.
Load a previously stored olm account.
Loads an account from a pickled base64-encoded string and returns an
Account object. Decrypts the account using the supplied passphrase.
If the passphrase doesn’t match the
one used to encrypt the account then the condition signalled for the
exception will be ’bad-account-key. if the base64 couldn’t be decoded
then the condition signalled will be ’invalid-base64.
Load a previously stored Olm session.
Loads a session from a pickled base64 string and returns a Session object. Decrypts the session using the supplied passphrase. Raises OlmSessionError on failure. If the passphrase doesn’t match the one used to encrypt the session then the error message for the exception will be ’bad-account-key. If the base64 couldn’t be decoded then the error message will be ’invalid-base64.
A base64 encoded identifier for this session.
A base64 encoded identifier for this session.
Create an InboundGroupSession from an exported session key.
Creates an InboundGroupSession with an previously exported session key.
Signals ’olm-invalid-base-64 if the session_key is not valid base64 or
’olm-bad-session-key if the session_key is invalid
automatically generated reader method
mac.
automatically generated writer method
mac.
Create a new inbound Olm session.
create a new in-bound session for sending/receiving messages from an
incoming prekey message. raises olmsessionerror on failure. if the
base64 couldn’t be decoded then condition signalled will be invalid-base64.
if the message was for an unsupported protocol version then
the error message will be bad-message-version. if the message
couldn’t be decoded then then the condition signalled will be
bad-message-format. if the message refers to an unknown one-time
key then the condition signalled will be bad-message-key-id.
Checks if the PRE_KEY message is for this in-bound session.
This can happen if multiple messages are sent to this session before
this session sends a message in reply. Returns True if the session
matches. returns false if the session does not match. raises
olmsessionerror on failure. if the base64 couldn’t be decoded then the
condition signalled will be ’invalid-base64. if the message was for an
unsupported protocol version then the condition signalled will be
’bad-message-version. if the message couldn’t be decoded then then the
condition signalled will be * ’bad-message-format.
The current message index of the session.
Each message is encrypted with an increasing index. This is the index
for the next message.
Stores decryption object as a base64 string. Encrypts the object using the supplied key. Returns the base64 string.
Store an outbound group session.
Stores a group session as a base64 string. Encrypts the session using
the supplied passphrase. Returns a byte object containing the base64
encoded string of the pickled session.
Store an inbound group session.
Stores a group session as a base64 string. Encrypts the session using the supplied passphrase. Returns a byte object containing the base64 encoded string of the pickled session.
Store an Olm account.
Stores an account as a base64 string. Encrypts the account using the
supplied passphrase. Returns a byte object containing the base64
encoded string of the pickled account. Signals ’olm-account-error on
failure.
automatically generated reader method
automatically generated reader method
automatically generated writer method
automatically generated writer method
The base64-encoded current ratchet key for this session.
Each message is encrypted with a different ratchet key. This function
returns the ratchet key that will be used for the next message.
Sign a message.
Next: Conditions, Previous: Generic functions, Up: Public Interface [Contents][Index]
Next: Classes, Previous: Standalone methods, Up: Public Interface [Contents][Index]
Signalled when an attempt was made to signal a condition from SEARCHED-FOR but none were found.
:searched-for
Signalled when ciphertext within object is empty
:object
Signalled when an empty id-key has been passed to a fun
:id-key
Signalled when an empty one-time-key has been passed to a fun
:one-time-key
:message-type
condition.
Previous: Conditions, Up: Public Interface [Contents][Index]
:account
%olm:*message-type-message*
%olm:*message-type-pre-key*
:pk-encrypt
:session
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
An example of how common calls like ’pickle’ could be written
Wraps body in an unwind-protect and then takes a list of lists, each list whose car is a pointer to foreign string and the second the length, then 0s the foreign string.
This is just a normal ’cffi:with-foreign-strings’ however each of the buffer
names you assign ie (mapcar #’first bindings) has (cffi:foreign-string-to-lisp ..)
called on it and the value assigned to a variable and returned as multiple return
values, so you have to wrap this in a multiple-value-bind. The values are returned
in the same order as the bindings so for example if bindings were the following:
((cipher-text (make-string cipher-len))
(mac (make-string mac-len))
(eph (make-string eph-key-size)))
then the final values are returned as cipher-text mac eph.
binding should look like either ((buf buf-len) <bytes>) or (buf <bytes>)
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
Generates a new pk-decryption object. Creates a pointer that has to be freed later
Gets the value associated with KEY in PLIST.
takes in a string (STRING) and looks in *conditions* for an associated condition if one is found then that condition is signalled, if not ’condition-missing is signalled.
Next: Conditions, Previous: Ordinary functions, Up: Internals [Contents][Index]
This generic is used to convert between the error strings and
lisp conditions. Firstly it will check if to-check is equal to (%olm:error)
if so it calls the most applicable method for class
Checks to make sure that TO-CHECK is actually in an error state before evaluating call-next-method
automatically generated reader method
automatically generated writer method
automatically generated reader method
automatically generated writer method
automatically generated reader method
automatically generated writer method
automatically generated reader method
automatically generated writer method
Next: Classes, Previous: Generic functions, Up: Internals [Contents][Index]
Previous: Conditions, Up: Internals [Contents][Index]
:utility
Previous: Definitions, Up: The cl-megolm Reference Manual [Contents][Index]
| Jump to: | %
(
A C D E F G I M O P R S T U W |
|---|
| Jump to: | %
(
A C D E F G I M O P R S T U W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
A C E I M O P S U |
|---|
| Jump to: | *
A C E I M O P S U |
|---|
| Jump to: | %
A B C E F G H I M N O P S U |
|---|
| Jump to: | %
A B C E F G H I M N O P S U |
|---|