This is the cl-megolm Reference Manual, version 1.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 15:27:08 2024 GMT+0.
cl-megolm/cl-megolm.asdcl-megolm/src/package.lispcl-megolm/src/olm.lispcl-megolm/src/conditions.lispcl-megolm/src/classes.lispcl-megolm/src/helpers.lispcl-megolm/src/utility.lispcl-megolm/src/session.lispcl-megolm/src/account.lispcl-megolm/src/group-session.lispcl-megolm/src/pk.lispcl-megolm/src/sas.lispThe main system appears first, followed by any subsystem dependency.
cl-megolmA 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
ironclad (system).
claw-olm (system).
jonathan (system).
cffi (system).
lisp-unit (system).
s-base64 (system).
str (system).
alexandria (system).
src (module).
Modules are listed depth-first from the system components tree.
cl-megolm/srccl-megolm (system).
package.lisp (file).
olm.lisp (file).
conditions.lisp (file).
classes.lisp (file).
helpers.lisp (file).
utility.lisp (file).
session.lisp (file).
account.lisp (file).
group-session.lisp (file).
pk.lisp (file).
sas.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
cl-megolm/cl-megolm.asdcl-megolm/src/package.lispcl-megolm/src/olm.lispcl-megolm/src/conditions.lispcl-megolm/src/classes.lispcl-megolm/src/helpers.lispcl-megolm/src/utility.lispcl-megolm/src/session.lispcl-megolm/src/account.lispcl-megolm/src/group-session.lispcl-megolm/src/pk.lispcl-megolm/src/sas.lispcl-megolm/src/conditions.lispolm.lisp (file).
src (module).
bad-account-key (condition).
bad-message-format (condition).
bad-message-key-id (condition).
bad-message-mac (condition).
bad-message-version (condition).
condition-missing (condition).
def-trivial-condition (macro).
empty-ciphertext (condition).
empty-id-key (condition).
empty-one-time-key (condition).
id-key (reader method).
(setf id-key) (writer method).
invalid-base64 (condition).
invalid-message-type (condition).
not-enough-random (condition).
olm-bad-message-format (condition).
olm-bad-message-mac (condition).
olm-bad-message-version (condition).
olm-error (condition).
olm-group-session-error (condition).
olm-input-buffer-too-small (condition).
olm-invalid-base64 (condition).
olm-sas-their-key-not-set (condition).
olm-unknown-message-index (condition).
one-time-key (reader method).
(setf one-time-key) (writer method).
output-buffer-too-small (condition).
unknown-message-index (condition).
*conditions* (special variable).
bad-session-key (condition).
bad-signature (condition).
empty-string (condition).
message-type (reader method).
(setf message-type) (writer method).
object (reader method).
(setf object) (writer method).
searched-for (reader method).
(setf searched-for) (writer method).
string->condition (function).
unknown-pickle-version (condition).
cl-megolm/src/classes.lispconditions.lisp (file).
src (module).
account (reader method).
(setf account) (writer method).
account (class).
ciphertext (reader method).
ciphertext (reader method).
(setf ciphertext) (writer method).
(setf ciphertext) (writer method).
cleanup (generic function).
clear (method).
clear (method).
clear (method).
clear (method).
clear (method).
clear (method).
clear (method).
clear (method).
clear (method).
ephemeral (reader method).
(setf ephemeral) (writer method).
inbound-group-session (class).
inbound-session (class).
mac (reader method).
(setf mac) (writer method).
olm-message (class).
olm-message-pre-key (class).
outbound-group-session (class).
outbound-session (class).
pk-decryption (class).
pk-encryption (class).
pk-message (class).
pk-signing (class).
public-key (reader method).
public-key (reader method).
(setf public-key) (writer method).
(setf public-key) (writer method).
sas (reader method).
(setf sas) (writer method).
sas (class).
session (reader method).
(setf session) (writer method).
session (class).
%check-error (method).
%check-error (method).
%check-error (method).
%check-error (method).
%check-error (method).
%check-error (method).
%check-error (method).
%check-error (method).
%check-error (method).
%olm-message (class).
message-type (reader method).
(setf message-type) (writer method).
pk-decrypt (reader method).
(setf pk-decrypt) (writer method).
pk-encrypt (reader method).
(setf pk-encrypt) (writer method).
pk-sign (reader method).
(setf pk-sign) (writer method).
utility (reader method).
(setf utility) (writer method).
utility (class).
cl-megolm/src/helpers.lispclasses.lisp (file).
src (module).
check-error (macro).
to-bytes (function).
%check-error (generic function).
%pickle (macro).
clean-after (macro).
mbyte-array (function).
pkv (macro).
plist-key-val (function).
random-string (function).
to-bool (function).
with-foreign-strings-as-lisp (macro).
with-foreign-vector (macro).
cl-megolm/src/utility.lisphelpers.lisp (file).
src (module).
ed25519-verify-p (function).
sha256 (function).
%ed25519-verify (method).
%sha256 (method).
ed25519-verify (function).
gen-utility (function).
cl-megolm/src/session.lisputility.lisp (file).
src (module).
clear-session (method).
decrypt (method).
encrypt (method).
from-pickle (method).
id (method).
make-inbound-session (method).
make-inbound-session (method).
make-inbound-session (method).
make-olm-message (function).
make-olm-pre-key-message (function).
make-outbound-session (method).
make-outbound-session (method).
make-session (function).
matchesp (method).
matchesp (method).
matchesp (method).
matchesp (method).
matchesp (method).
pickle (method).
print-object (method).
%make-olm-message (function).
cl-megolm/src/account.lispsession.lisp (file).
src (module).
curve (method).
ed25519 (method).
from-pickle (method).
generate-one-time-keys (method).
identity-keys (method).
make-account (function).
mark-keys-as-published (method).
max-one-time-keys (method).
one-time-keys (method).
pickle (method).
remove-one-time-keys (method).
sign (method).
gen-account (function).
cl-megolm/src/group-session.lispaccount.lisp (file).
src (module).
decrypt (method).
encrypt (method).
export-session (method).
first-known-index (method).
from-pickle (method).
from-pickle (method).
id (method).
id (method).
import-session (method).
make-inbound-group-session (function).
make-outbound-group-session (function).
message-index (method).
pickle (method).
pickle (method).
session-key (method).
gen-inbound-group-session (function).
gen-outbound-group-session (function).
cl-megolm/src/pk.lispgroup-session.lisp (file).
src (module).
decrypt (method).
encrypt (method).
from-pickle (method).
make-pk-decryption (function).
make-pk-encryption (function).
make-pk-signing (function).
pickle (method).
sign (method).
gen-pk-decryption (function).
make-pk-message (function).
cl-megolm/src/sas.lisppk.lisp (file).
src (module).
calculate-mac (method).
calculate-mac-long-kdf (method).
create-sas (method).
create-sas (method).
generate-bytes (method).
make-sas (function).
other-key-set-p (method).
pubkey (method).
set-their-public-key (method).
Packages are listed by definition order.
cl-megolmcommon-lisp.
account (generic reader).
(setf account) (generic writer).
account (class).
bad-account-key (condition).
bad-message-format (condition).
bad-message-key-id (condition).
bad-message-mac (condition).
bad-message-version (condition).
calculate-mac (generic function).
calculate-mac-long-kdf (generic function).
check-error (macro).
ciphertext (generic reader).
(setf ciphertext) (generic writer).
cleanup (generic function).
clear (generic function).
clear-session (generic function).
condition-missing (condition).
create-sas (generic function).
curve (generic function).
decrypt (generic function).
def-trivial-condition (macro).
ed25519 (generic function).
ed25519-verify-p (function).
empty-ciphertext (condition).
empty-id-key (condition).
empty-one-time-key (condition).
encrypt (generic function).
ephemeral (generic reader).
(setf ephemeral) (generic writer).
export-session (generic function).
first-known-index (generic function).
from-pickle (generic function).
generate-bytes (generic function).
generate-one-time-keys (generic function).
id (generic function).
id-key (generic reader).
(setf id-key) (generic writer).
identity-keys (generic function).
import-session (generic function).
inbound-group-session (class).
inbound-session (class).
invalid-base64 (condition).
invalid-message-type (condition).
mac (generic reader).
(setf mac) (generic writer).
make-account (function).
make-inbound-group-session (function).
make-inbound-session (generic function).
make-olm-message (function).
make-olm-pre-key-message (function).
make-outbound-group-session (function).
make-outbound-session (generic function).
make-pk-decryption (function).
make-pk-encryption (function).
make-pk-signing (function).
make-sas (function).
make-session (function).
mark-keys-as-published (generic function).
matchesp (generic function).
max-one-time-keys (generic function).
message-index (generic function).
not-enough-random (condition).
olm-bad-message-format (condition).
olm-bad-message-mac (condition).
olm-bad-message-version (condition).
olm-error (condition).
olm-group-session-error (condition).
olm-input-buffer-too-small (condition).
olm-invalid-base64 (condition).
olm-message (class).
olm-message-pre-key (class).
olm-sas-their-key-not-set (condition).
olm-unknown-message-index (condition).
one-time-key (generic reader).
(setf one-time-key) (generic writer).
one-time-keys (generic function).
other-key-set-p (generic function).
outbound-group-session (class).
outbound-session (class).
output-buffer-too-small (condition).
pickle (generic function).
pk-decryption (class).
pk-encryption (class).
pk-message (class).
pk-signing (class).
pubkey (generic function).
public-key (generic reader).
(setf public-key) (generic writer).
remove-one-time-keys (generic function).
sas (generic reader).
(setf sas) (generic writer).
sas (class).
session (generic reader).
(setf session) (generic writer).
session (class).
session-key (generic function).
set-their-public-key (generic function).
sha256 (function).
sign (generic function).
to-bytes (function).
unknown-message-index (condition).
%check-error (generic function).
%ed25519-verify (generic function).
%make-olm-message (function).
%olm-message (class).
%pickle (macro).
%sha256 (generic function).
*conditions* (special variable).
bad-session-key (condition).
bad-signature (condition).
clean-after (macro).
ed25519-verify (function).
empty-string (condition).
gen-account (function).
gen-inbound-group-session (function).
gen-outbound-group-session (function).
gen-pk-decryption (function).
gen-utility (function).
make-pk-message (function).
mbyte-array (function).
message-type (generic reader).
(setf message-type) (generic writer).
object (generic reader).
(setf object) (generic writer).
pk-decrypt (generic reader).
(setf pk-decrypt) (generic writer).
pk-encrypt (generic reader).
(setf pk-encrypt) (generic writer).
pk-sign (generic reader).
(setf pk-sign) (generic writer).
pkv (macro).
plist-key-val (function).
random-string (function).
searched-for (generic reader).
(setf searched-for) (generic writer).
string->condition (function).
to-bool (function).
unknown-pickle-version (condition).
utility (generic reader).
(setf utility) (generic writer).
utility (class).
with-foreign-strings-as-lisp (macro).
with-foreign-vector (macro).
Definitions are sorted by export status, category, package, and then by lexicographic order.
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.
%olm-message)) ¶automatically generated reader method
pk-message)) ¶automatically generated reader method
%olm-message)) ¶automatically generated writer method
pk-message)) ¶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.
pk-signing)) ¶pk-decryption)) ¶pk-encryption)) ¶outbound-group-session)) ¶inbound-group-session)) ¶pk-signing)) ¶pk-decryption)) ¶pk-encryption)) ¶pk-decryption) (pk-message pk-message)) ¶Decrypt a previously encrypted pk message.
inbound-group-session) (cipher-text string)) ¶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)
session) (message %olm-message)) ¶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
pk-encryption) (plaintext string)) ¶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.
outbound-group-session) (plaintext string)) ¶Encrypt a message. Returns the encrypted ciphertext.
pk-message)) ¶automatically generated reader method
pk-message)) ¶automatically generated writer method
inbound-group-session) message-index) ¶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)
inbound-group-session)) ¶The first message index we know how to decrypt
(eql :pk-decrypt)) (pickle string) (passphrase string)) ¶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
(eql :outbound-group)) (pickle string) (passphrase string)) ¶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.
(eql :inbound-group)) (pickle string) (passphrase string)) ¶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.
(eql :account)) (pickle string) (passphrase string)) ¶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.
(eql :session)) (pickle string) (passphrase string)) ¶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.
outbound-group-session)) ¶A base64 encoded identifier for this session.
inbound-group-session)) ¶A base64 encoded identifier for this session.
empty-id-key)) ¶empty-id-key)) ¶(eql :inbound)) session-key) ¶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
pk-message)) ¶automatically generated reader method
mac.
pk-message)) ¶automatically generated writer method
mac.
account) (message olm-message-pre-key) id-key) ¶account) (message olm-message-pre-key) (id-key string)) ¶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.
account) (message olm-message-pre-key) id-key) ¶session) (message olm-message-pre-key) (id-key null)) ¶session) (message olm-message-pre-key) (id-key string)) ¶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.
session) (message olm-message-pre-key) id-key) ¶outbound-group-session)) ¶The current message index of the session.
Each message is encrypted with an increasing index. This is the index
for the next message.
empty-one-time-key)) ¶empty-one-time-key)) ¶pk-decryption) (passphrase string)) ¶Stores decryption object as a base64 string. Encrypts the object using the supplied key. Returns the base64 string.
outbound-group-session) (passphrase 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.
inbound-group-session) (passphrase string)) ¶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.
account) (passphrase string)) ¶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.
pk-signing)) ¶automatically generated reader method
pk-decryption)) ¶automatically generated reader method
pk-signing)) ¶automatically generated writer method
pk-decryption)) ¶automatically generated writer method
outbound-group-session)) ¶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.
pk-signing) (message string)) ¶Sign a message.
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.
bad-account-key.
bad-message-format.
bad-message-key-id.
bad-message-mac.
bad-message-version.
bad-session-key.
bad-signature.
condition-missing.
empty-ciphertext.
empty-string.
invalid-base64.
invalid-message-type.
not-enough-random.
olm-bad-message-format.
olm-bad-message-mac.
olm-bad-message-version.
olm-group-session-error.
olm-input-buffer-too-small.
olm-invalid-base64.
olm-sas-their-key-not-set.
olm-unknown-message-index.
output-buffer-too-small.
unknown-message-index.
unknown-pickle-version.
%check-error.
(setf account).
account.
cleanup.
clear.
curve.
ed25519.
generate-one-time-keys.
identity-keys.
make-inbound-session.
make-inbound-session.
make-inbound-session.
make-outbound-session.
make-outbound-session.
mark-keys-as-published.
max-one-time-keys.
one-time-keys.
pickle.
remove-one-time-keys.
sign.
:account
%olm:*message-type-message*
%olm:*message-type-pre-key*
:pk-encrypt
:session
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>)
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.
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
outbound-group-session) check-it) ¶inbound-group-session) check-it) ¶pk-signing) to-check) ¶pk-decryption) to-check) ¶pk-encryption) to-check) ¶%olm-message)) ¶automatically generated reader method
invalid-message-type)) ¶%olm-message)) ¶automatically generated writer method
invalid-message-type)) ¶empty-ciphertext)) ¶empty-ciphertext)) ¶pk-decryption)) ¶automatically generated reader method
pk-decryption)) ¶automatically generated writer method
pk-encryption)) ¶automatically generated reader method
pk-encryption)) ¶automatically generated writer method
pk-signing)) ¶automatically generated reader method
pk-signing)) ¶automatically generated writer method
condition-missing)) ¶condition-missing)) ¶:utility
| 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 |
|---|
| 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 |
|---|