Platform support legends:
- ✅ = tier 1 support. Things just work.
⚠️ = tier 2 support. Things compile but might not work as expected. Basically works but with papercuts- Note: the papercuts will majorly be with the build process. Things might be very rough to integrate as no polish at all has been given yet.
- ❌ = tier 3 support. It doesn't work just yet, but we plan to make it work.
git-conventional changelog
- Do not assert keypackage expiration when joining a group via external commit
git-conventional changelog
- Remove cached is_e2ei_capable flag
- KeyPackage lifetime validation when receiving messages
- Integrate -pre version to iDB store version
- WASM: Integrated pre-version into the calculation of the IndexedDB store version
- This issue was preventing migrations between CC 1.0.0-[pre|rc] versions on Web
- Only assert keypackage expiration when being the sender of a commit/proposal
- Internal: Remove the cached flag determining the client's ability to perform E2EI operations.
- This is precautionary to avoid potential state discrepancies when rotating credentials for example.
- Fixed an issue with incorrect code in TypeScript bindings
git-conventional changelog
- Harden x509 validation & revocation checks
- Update all doc warnings including a lot of broken links
- Add serialNumber, notBefore & notAfter in
WireIdentityobject - Add display name in dpop token
- Fix some clippy lints
- Verify that registering a TA twice fails
- Integrated the display name in the JWT DPoP token
- Reworked and hardened all x.509 verifications (including revocation)
- Added
serialNumber,notBeforeandnotAfterfields to theWireIdentitystruct. These fields are pulled directly from the relevant fields in End-identity X.509 certificates
git-conventional changelog
- Intermediates were not registered during enrollment
- Add getter for external sender to seed subconversations
- Clippy warnings
- Add
getExternalSender()to init a subconversation with the parent external sender - Fix e2ei issue when intermediates were not registered during the enrollment.
git-conventional changelog
- [breaking] Add dedicated error for stale commits and proposals
- Verify GroupInfo
- Allow revoked Credentials in MLS operations
- Reenable E2EI tests
- Update tests
- Post-rebase fixes
- Consider x509 credentials as always valid if no PKI environment is available
- Adapt calls to OpenMLS new async methods
- Disable non working (MissingSki) E2EI tests
- Undo WASM binding API mistake
- [breaking]
clientPublicKeynow also works for x509 credentials - Validate x509 credentials when introduced
- Update deps
- Do not clone MLS signature keypair while creating the enrollment
- Get rid of rcgen-based x509 cert generation
- Fixed an issue with the WASM FFI where many fields were incorrectly exposed and were leading to constant
undefinedvalues (i.e.epochHasChangedissue) - Avoided a clone of the signature public key when performing E2EI enrollment
- API BREAKING CHANGES:
clientPublicKeynow works with X.509 credentials. This implies that the CredentialType now has to be provided to fetch the correct credential.- We now return dedicated errors for commits and proposals from older epochs instead of a generic
WrongEpocherror. Respectively, we now returnStaleCommitandStaleProposal.
- BEHAVIORAL BREAKING CHANGES:
- We now verify (as per the MLS spec / RFC9420) GroupInfo prior to joining via external commit
- We also verify Welcomes prior to joining a group
- We now properly validate X.509 credentials against the set up PKI Environment
- Note: Expired or Revoked credentials do not constitute hard errors in MLS operations but alter the E2EI status of a conversation
git-conventional changelog
- E2EI:
- Fix: intermediates certificates registration was not working because extracting the key was not working
git-conventional changelog
- Register intermediate certificates at issuance since they're not fetchable afterwards
- [breaking] Return CRL Distribution Points when registering intermediate certificates
- E2EI:
- BREAKING CHANGE
e2eiMlsInitOnly()also returns CRL Distribution Point - Fix: register intermediates at issuance since they're not provided by the /federation endpoint
- Fix: register CRL Distribution Points on intermediates
- BREAKING CHANGE
git-conventional changelog
- [breaking] Change certificate expiry from days to seconds in the public API
- E2EI:
- BREAKING CHANGE change certificate expiry from days to seconds in the public API
- BREAKING CHANGE add the potential new CRL Distribution points to:
decryptMessageprocessWelcomeMessagejoinByExternalCommitaddClientsToConversationnewAddProposale2eiRotateAll
git-conventional changelog
- Restore pki_env from disk whenever necessary
- Relax uniqueness constraint on intermediate certificates and CRLs on sqlite
- Filter out root CA when registering intermediates in case the provider repeats it
- [breaking] Remove refreshToken handling from WASM altogether as it is not used
- E2EI:
- Fixed a bug on mobile where intermediate certificates & CRLs had a uniqueness constraint
- Fixed a bug where the PkiEnv was not restored from disk after restarts
- Ignore TrustAnchor when registering intermediate certificates
- Remove RefreshToken handling on Web
git-conventional changelog
- Remove unused test
- Use forked x509-cert to fix WASM compilation
- Fix tests
- Duration overflow in x509 expiration setting
- Typo in E2eiAcmeCA registration SQL query
- Add missing CRLDP field to FFI + fill it up
- Add full PKI test harness
- E2EI:
- Fixed a bug with Root CA Trust Anchor registration that wasn't working on native platforms (non-WASM)
- Fixed a bug with the initialization of our Intermediate CA store causing CRL & End-Identity certificate validation to fail
- Fixed a missing field in the FFI (CRL distribution-points) and added the logic to fill up the field
- Fixed an integer overflow in the X.509 expiration setting
- MLS:
- Fixed errors when a single certificate is contained in a Credential (obsolete check)
- Misc:
- Updated dependencies in many libraries
- fix(e2ei): use 2 ACME authorizations instead of 1
git-conventional changelog
- Wrong rusty-jwt-tools pinned in rc30
- [breaking] Expose keyauth in ACME authz
- fix(e2ei): include "keyauth" in the ACME authorization, turn challenge non-optional in ACME authorization and stop including keyauth in the ACME challenge request. This version only works with IdP supporting extra OAuth claims (and by consequence only work with Keycloak and not Dex)
git-conventional changelog
- Pin rusty-jwt-tools v0.8.4 fixing an issue with the wrong signature key being used for the client DPoP token
- fix(e2ei): issue with the wrong signature key being used for the client DPoP token
- fix(e2ei): issue related to invalid 'keyauth'
- fix(e2ei): e2ei keystore method 'find_all' was unimplemented on WASM for intermediate CAs & CRLs
git-conventional changelog
- Pin e2ei package tag
- Add PKI API to bindings
- Added support for PKI environment
- Change ClientId & Handle format to URIs
- feat(e2ei): add methods to register root/intermediate certificates and CRLs. Also checks revocation status when asking for a conversation/user/device state.
- feat(e2ei): change ClientId & Handle to URIs with the scheme 'wireapp://'. Use '!' as delimiter in the ClientId
git-conventional changelog
- Null pointer in Javascript when calling 'new_oidc_challenge_response'
- Swift wrapper for E2eiEnrollment was not used in other methods
- Use 'implementation' Gradle configuration not to enforce dependencies version into consumers. Fixes #451
- [breaking] Remove PerDomainTrustAnchor extension altogether. Backward incompatible changes !
- feat(mls)!: remove
PerDomainTrustAnchorextension from required capabilities. Backward incompatible changes ! If you ever migrate from a previous version to this one take care of deleting all your groups - fix(e2ei): fix a null pointer in the Javascript API
- fix(e2ei): Swift wrapper for E2eiEnrollment was not used in other methods
- fix: use 'implementation' Gradle configuration not to enforce dependencies version into consumers
git-conventional changelog
- README mentions a task which doesn't exist (#445)
- Remove unnecessary boxing of values before persisting them in IndexedDb
- [breaking] Remove 'clientId' from activation & rotate enrollment now that we expect a specific ClientId format
- [breaking] Add
get_credential_in_use()to check the e2ei state from a GroupInfo - [breaking] Rename
E2eiConversationState::Degradedin toE2eiConversationState::NotVerified - [breaking] Managed OIDC refreshToken (wpb-5012)
- Remove unused 'MlsSignatureKeyPairExt' trait and 'get_indexed' method
- Streamline "collection" in wasm storage
- WasmEncryptedStorage::get_many was not used
- Verify that clients can create conversation with x509 credentials
- feat(e2ei)!: manage OIDC refreshToken in CoreCrypto's encrypted-at-rest store. As a consequence, some methods went async (all the enrollment ones in WASM). The refreshToken has to be supplied in
newOidcChallengeRequest()and is persisted innewOidcChallengeResponse(). Clients should fetch it back from anEnrollmentcreated bynewRotateEnrollment()with the newgetRefreshToken()method. - feat(e2ei)!: remove 'clientId' from
newActivationEnrollment()&newRotateEnrollment(). We can do this now that we expect a specific ClientId format. - feat(e2ei): add
getCredentialInUse(GroupInfo)to check the e2ei state from a GroupInfo. This allows verifying the state of a conversation before joining it (and potentially degrading the e2ei state). - feat(e2ei)!: rename
E2eiConversationState::Degradedin toE2eiConversationState::NotVerified
git-conventional changelog
- [breaking] Canonicalize ClientId keeping only the regular version where the UserId portion is the hyphenated string representation of the UUID. Also apply this to 'getUserIdentities()'
- feat!: canonicalize ClientId keeping only the regular version where the UserId portion is the hyphenated string representation of the UUID. Also apply this to
getUserIdentities()
git-conventional changelog
- Better errors: 'ImplementationError' was way too often used as a fallback when the developer was too lazy to create a new error. This tries to cure that, especially with e2ei errors. It also tries to distinguish client errors from internal errors
- [breaking] Simplify API of 'add_clients_to_conversation' by not requiring to repeat the ClientId of the new members alongside their KeyPackage when the former can now be extracted from the latter
- [breaking] Introduce handle & team in the client dpop token
- Test DB migration from 0.9.2
- feat!:
addClientToConversationAPI has been simplified. It just requires bareKeyPackages without theClientId - feat!(e2ei): better errors ; almost got rid of
ImplementationErrorused too much so far. This should help debugging - feat!(e2ei): added
TeamandHandlein the client DPoP token - build: bumped tls_codec from 0.3.0 to 0.4.0
git-conventional changelog
- Add new keystore regression test to CI
- Test keystore migration regressions
- feat!(e2ei):
get_user_identitiesget_device_identitiesand a newget_user_identitiesadded to list identities in a group belonging to the same user - feat!(e2ei):
get_device_identitiesnow accepts aClientIdas it is present in the MLS group and not as present in the Credential's X509 - feat(e2ei): handle is format changed from
im:wireapp={input}toim:wireapp=%40{input}@{domain} - feat!(e2ei): WireIdentity contains JWK thumbprint of the certificate public key and a validation status (Valid/Expired/Revoked) (even though revocation is not implemented yet)
- fix: X509 signature validation was failing when issuer had a different signature scheme than the subject
git-conventional changelog
- Native platforms only: Preserve database schema upgrade path from 0.8.x, 1.0.0-pre.6+schemafix-0007 and onwards.
git-conventional changelog
- Don't depend on OpenSSL on WASM
- Dynamic linking issue on Android with the atomic lib
- Release v1.0.0-rc.17 (#425)
- Use actual CI cache
- Remove dependency of OpenSSL for Wasm
- Fix linking issue on Android
git-conventional changelog
- Prevent CI from overriding RUSTFLAGS
- Added missing d.ts declarations
- KP test was taking too much time
- Updated README.md noting Bun usage
- Switch from node to bun
- Release v1.0.0-rc.16
- [BREAKING-WASM ONLY]: We now bundle our TypeScript and WASM bindings using Bun
- This shouldn't result in any fundamental changes API-wise
- BREAKING NPM Package: The WASM file isn't shipped in the
platforms/web/assetssubfolder anymore. It is shipped inplatforms/webnow.
- Fixed RUSTFLAGS being overridden in CI context
git-conventional changelog
- Add '-latomic' flag when building for Android to dynamically link atomic lib which is supposedly causing issues with openssl
- Re-export e2ei types
- Fix some clippy lints
- fix: add '-latomic' flag when building for Android to dynamically link atomic lib which is supposedly causing issues with openssl
- feat: re-export e2ei types
git-conventional changelog
- Backward incompatible database schemas. It only preserves Proteus compatibility when migrating from CC 0.11.0 -> 1.0.0. For anything MLS-related it is recommended to wipe all the groups
- Release 1.0.0-rc.14
- fix: backward incompatible database schemas. It only preserves Proteus compatibility when migrating from CC 0.11.0 -> 1.0.0. For anything MLS-related it is recommended to wipe all the groups
git-conventional changelog
- Do not reapply buffered messages when rejoining with external commit
- Coarsetime issue causing compilation error on WASM
- [breaking] Make initial number of generated KeyPackage configurable
- Add e2ei ffi in Swift wrapper
- [breaking] Add LeafNode validation
- Release 1.0.0-rc.13
- Use wasm_bindgen macros to generate Typescript classes used in e2ei enrollment process
- Try fixing flaky time-based LeafNode validation tests
- feat!: introduce missing LeafNode validation at different step in the protocol. As a consequence, previous KeyPackages are not compatible with newly created groups and vice versa. It is recommended to purge everything. Otherwise, joining a group is likely to fail with a "InsufficientCapabilities" error.
- feat!: initial number of KeyPackage is now configurable, defaulting to 100
- feat: add e2ei methods for certificate enrollment in Swift wrapper
- fix: in the case where an external commit is used to rejoin a group, buffered messages are ignored since they probably aren't recoverable given this way to use external commit is often a last resort solution.
git-conventional changelog
- Use sed in a cross-platform way for kt edits
- Release v1.0.0-rc.12
- fix: Use sed in cross platform way for ffi build
git-conventional changelog
- [breaking] UniFFI Errors
- Release v1.0.0-rc.11
- fix!: Fix Kotlin & Swift FFI errors
- This includes a breaking change where CoreCrypto and E2EI errors are separated, so change accordingly
git-conventional changelog
- UniFFI symbol matching
- Release v1.0.0-rc.10
- Make UniFFI produce the correct symbol in bindings
- Change e2ei enrollment identifier causing collision now that keypairs are reused
- Regenerate changelog
- [breaking] Return raw PEM certificate in
getUserIdentitiesfor display purpose - [breaking] Bump rusty-jwt-tools to v0.5.0. Add 'revokeCert' to AcmeDirectory
- Release v1.0.0-rc.9
- TLS serialization of x509 credential
- [breaking] UniFFI Async cancellable routines + bytes
- Make interop runner pick up CHROME_PATH from env
- Expose
getUserIdentitiesthrough the FFI - [breaking] Also restore buffered messages on the receiver side
- Increase max past epoch to 3 since backend inordering of messages requires client's config to backend's one + 1
- Release 1.0.0-rc.8
- Fix clippy lint on wasm tests
- Quiet clippy new lint about non send in Arc because it comes from wasm-bindgen wrapped Javascript object which cannot be shared between threads anyway
- Remove useless application message epoch check
- Borrow conversation_id in
new_conversation
- Fix wasm test hitting a limit. Just split them for now, waiting for a proper solution
- Fix spinoff 0.8 compilation
- Kotlin tests not compiling after methods became async
- Correlate RotateBundle with a GroupId
- Release 1.0.0-rc.7
e2eiRotateAllreturn type was not wrapped- Signature KeyPair was rotated when credentials were which was zealous. Also fixes an important bug caused by inverted private & public keypair part when rotating credentials
- [breaking] Handle the case when a client tries to decrypt a Welcome referring to a KeyPackage he already has deleted locally
- Add keystore dump exporter CLI tool
- Release 1.0.0-rc.6
- Add a roundtrip test for e2ei credential rotation to tackle a false positive regression
- E2ei enum for conversation state was unused and failing the Typescript publication. Now CI will have the same compiler flags when checking bindings in order to prevent this again
- Release 1.0.0-rc.5
- Release 1.0.0-rc.4
- Patch visibility issue for enum 'E2eiConversationState' which was failing when building Typescript bindings
- Proteus wasm test now uses wasm-browser-run
- Cargo doc fixes for wasm-browser-run
- Interop runner now uses wasm-browser-run to install chromedriver
- Support chromedriver 115 delivery method
e2ei_rotate_allwas returning 'undefined' on WASM- [breaking] Entities leaked. Some methods handling the lifecycle of a MLS group were not cleaning created entities correctly. This avoids required storage space to grow linearly.
- [breaking] Rename
e2eiIsDegradedbye2eiConversationStateand change return type to an enumeration instead of a boolean to match all the e2ei states a conversation could have. - Add
e2ei_is_enabledfor clients to spot if their MLS client is enrolled for end-to-end identity
- Release 1.0.0-rc.3
- Update rstest versions
- Updated xtask deps
- [breaking] Expose 'ClientId' in e2ei methods for credential rotation since the e2ei client identifier differs from the one used in MLS
- Include certificate roots and certificate policy in GroupContext - WPB-1188
- Release v1.0.0-rc.2
- fix: Fix Kotin & Swift wrappers by producing correct symbols
git-conventional changelog
- Make UniFFI produce the correct symbol in bindings
- Change e2ei enrollment identifier causing collision now that keypairs are reused
- Regenerate changelog
- [breaking] Return raw PEM certificate in
getUserIdentitiesfor display purpose - [breaking] Bump rusty-jwt-tools to v0.5.0. Add 'revokeCert' to AcmeDirectory
- Release v1.0.0-rc.9
- fix: tentatively fix the Kotlin & Swift wrapper by producing correct symbols
- fix: e2ei enrollment persistence collision (only used by web)
- fix: bump rusty-jwt-tools to v0.5.0 and fix
userIdencoding - feat: expose
getUserIdentities()(for e2ei purposes) in the FFI - feat: add raw X.509 certificate in
WireIdentityto display the certificate in the app
git-conventional changelog
- TLS serialization of x509 credential
- [breaking] UniFFI Async cancellable routines + bytes
- Make interop runner pick up CHROME_PATH from env
- Expose
getUserIdentitiesthrough the FFI - [breaking] Also restore buffered messages on the receiver side
- Increase max past epoch to 3 since backend inordering of messages requires client's config to backend's one + 1
- Release 1.0.0-rc.8
- Fix clippy lint on wasm tests
- Quiet clippy new lint about non send in Arc because it comes from wasm-bindgen wrapped Javascript object which cannot be shared between threads anyway
- Remove useless application message epoch check
- Borrow conversation_id in
new_conversation
- Fix wasm test hitting a limit. Just split them for now, waiting for a proper solution
- Fix spinoff 0.8 compilation
- [BREAKING] regular commits were also (in addition to external commits) impacted by unordered backend messages. As a
consequence, both
commitAcceptedanddecryptMessagesnow return buffered messages. - Improved Kotlin wrapper: documented, tested, type safe
- fix: Rust future was leaked when Kotlin coroutine cancelled
- fix: TLS serialization of x509 Credential which makes this release interoperable with wire-server
- feat: expose
getUserIdentitiesto list the identity of MLS group members using e2ei - increase max past epoch from 2 to 3 to respect backend's configuration
git-conventional changelog
- Kotlin tests not compiling after methods became async
- Correlate RotateBundle with a GroupId
- Release 1.0.0-rc.7
- [BREAKING]
RotateBundlenow returns aMap<ConversationId, CommitBundle>instead of aVec<CommitBundle>in order to correlate the commit with its group id and to merge it afterwards. Note that theConversationIdhere is hex encoded due to limitations at the FFI boundary.
git-conventional changelog
e2eiRotateAllreturn type was not wrapped- Signature KeyPair was rotated when credentials were which was zealous. Also fixes an important bug caused by inverted private & public keypair part when rotating credentials
- [breaking] Handle the case when a client tries to decrypt a Welcome referring to a KeyPackage he already has deleted locally
- Add keystore dump exporter CLI tool
- Release 1.0.0-rc.6
- Add a roundtrip test for e2ei credential rotation to tackle a false positive regression
- Add keystore dump CLI tool to debug internal applications and export the content of the keystore for further analysis
- handle the "orphan welcome" corner case when the client receives a Welcome but already has deleted the associated KeyPackage. In that case he has to catch & ignore the "OrphanWelcome" error and to rejoin the group with an external commit.
- Fix credential rotation in end-to-end identity was signing the certificate with the wrong keypair part
- Fix
e2eiRotateAllreturn type was not correctly wrapped in a object in Typescript
git-conventional changelog
- E2ei enum for conversation state was unused and failing the Typescript publication. Now CI will have the same compiler flags when checking bindings in order to prevent this again
- Release 1.0.0-rc.5
- Fix WASM publication issues
git-conventional changelog
- Release 1.0.0-rc.4
- Patch visibility issue for enum 'E2eiConversationState' which was failing when building Typescript bindings
- Fix WASM publication issues
git-conventional changelog
- Proteus wasm test now uses wasm-browser-run
- Cargo doc fixes for wasm-browser-run
- Interop runner now uses wasm-browser-run to install chromedriver
- Support chromedriver 115 delivery method
e2ei_rotate_allwas returning 'undefined' on WASM- [breaking] Entities leaked. Some methods handling the lifecycle of a MLS group were not cleaning created entities correctly. This avoids required storage space to grow linearly.
- [breaking] Rename
e2eiIsDegradedbye2eiConversationStateand change return type to an enumeration instead of a boolean to match all the e2ei states a conversation could have. - Add
e2ei_is_enabledfor clients to spot if their MLS client is enrolled for end-to-end identity
- Release 1.0.0-rc.3
- Update rstest versions
- Updated xtask deps
- Ensure that all operations do not leak data (uncleared from the keystore). This was mostly happening with update proposals & credential rotation. Also introduced a separate table for storing epoch keypairs.
- [BREAKING] as a consequence (of the new table) all existing conversations are becoming unusable. It is strongly advised to wipe them all.
- Fix method
e2eiRotateAllwas returning undefined on WASM - Add method
e2eiIsEnabledto tell if a MLS client has a valid Credential for the given Ciphersuite - [BREAKING] rename
e2eiIsDegradede2eiConversationStatewhich returns now an enumeration giving the state of the conversation regarding end-to-end identity. - Adapt CI to execute WASM tests with chromedriver 115
git-conventional changelog
- Added support for x509 certificate roots and policies in MLS GroupContext through a TrustAnchor GroupContextExtension #346
- Fixed a CI issue that prevented Swift and JVM package publication
git-conventional changelog
- [BREAKING] With this release, CoreCrypto is now RFC9420 compliant.
- This will cause Draft-20 clients to be unable to process keypackages emitted by RFC clients; But the opposite isn't true as RFC clients will ignore the extraneous
CapabilitiesDraft-20 clients emit.
- This will cause Draft-20 clients to be unable to process keypackages emitted by RFC clients; But the opposite isn't true as RFC clients will ignore the extraneous
- [BREAKING] With our update to UniFFI 0.24, the FFI & bindings have significant breaking changes
- Most if not all APIs are now
asyncand will use the platform's executor thanks to UniFFI's integration with them. In terms of platforms, the consequences are the following:- Kotlin: Almost all APIs are now
suspend - Swift: Almost all APIs are now
async - TypeScript: A couple more APIs are now
asynccompared to before
- Kotlin: Almost all APIs are now
- Some other things might have changed - the callbacks ABI has changed but this change should not affect users of our bindings as we try to erase those minute differences by wrapping everything in a stable API
- Most if not all APIs are now
- [BREAKING] CoreCrypto now handles self-commits sent by the backend and decrypted by the client.
- In a particular case, when the backend replays a commit, the client is not to blame.
- In that case,
decryptMessagewill return aSelfCommitIgnoredwhich you should catch and ignore. It means you are likely to already have merged this commit.
- In that case,
- In a particular case, when the backend replays a commit, the client is not to blame.
- [BREAKING] CoreCrypto now handles duplicate application or handshake messages.
- When such a case happens,
decryptMessagewill return aDuplicateMessageerror encapsulating aGenerationOutOfBounderror. The latter variant also has been removed.
- When such a case happens,
- [BREAKING] To mitigate unordered messages when joining with an external commit, incoming messages are now buffered until you merge the external commit with
mergePendingGroupFromExternalCommit.- At that point they are replayed and their result return in the method return type ; hence make sure to read and handle it!
- Note that for messages arriving during the external commit merge window,
decryptMessagewill return aUnmergedPendingGrouperror which means the edge case has been identified and the message will be reapplied later; so feel free to catch and ignore this error.
- [SEMI-BREAKING] CoreCrypto now prevents overwriting an existing conversation when creating a new conversation, joining one with a Welcome or joining with an external commit.
- This is within an effort to harden our data storage policies and to provide better feedback to API consumers as to what is actually happening.
- This change also is a breaking behavior change - But you should not be abusing the existing mechanic anyway to replace conversations as this was an unintended bug
- Our CI is now building the Swift bindings with Xcode 14.3.1
- We managed to reduce the size of our libraries by stripping them afterwards
- [EXPERIMENTAL] This version of CoreCrypto is the first to ship with a Proteus compatibility layer that uses the same cryptographic primitives as the MLS counterparts
- This yields in practice performance gains between 20% and 900% depending on the type of operation
- Again, as this is an experimental change, things might break.
git-conventional changelog
- Use correct env var for maven central credentials (#355)
- Release v1.0.0-pre.8
- This is a release that contains nothing new. This is to fix the previous Kotlin release that was not correctly built & released.
git-conventional changelog
- Make clippy happy
- Xtask release fix for kotlin sonatype publishing
- Disable stripping to allow FFI to build
- Incorrect error value in tests
- [breaking] Prevent conversation overwrite when joining
- [breaking] Detect duplicate messages from previous epoch and fail with a dedicated error
- Publish to Sonatype instead of Github Packages (#347)
- Release v1.0.0-pre.7
- Pin dependencies on wireapp org forks
- [BREAKING] We now detect duplicate messages from previous epochs, as such the
GenerationOutOfBounderror is now namedDuplicateMessage. - [BREAKING] We now throw errors when consumers try to create or join a group via Welcome message BUT the group already exists within our store. This is to prevent accidental group erasure in case of duplicate notifications from the DS. Note that the API does not change with this but presents a breaking behavior change.
- We pinned some private forks under the @wireapp GitHub org to secure our software supply chain.
git-conventional changelog
- Wrong HPQ ciphersuite identifier
- Address review & de-flakify cert expiration test
- Target correct branches
- PQ support for FFI
- Benches modification
- [breaking] Credential rotation
- PostQuantum Ciphersuite
- [breaking] Remove
export_group_info()
- feat!: PostQuantum Ciphersuite support ! Using Xyber768 for Key Exchange.
- feat! Credential rotation support (for E2E Identity). It allows to change the local client Credential in a MLS group, replacing it with a X509 Certificate one.
- feat!: remove
export_group_info()method that wasn't used
git-conventional changelog
- Backend sends raw GroupInfo, we were trying to deserialize it from a MlsMessage
- fix:
joinByExternalCommitwas expecting aGroupInfowrapped in a MlsMessage
git-conventional changelog
- build: fixed different sources of tls_codec
git-conventional changelog
- Pin a version of openmls with a fix in tls_codec related to variable length encoding
- Fix external commit test was not merging the external commit
- fix: tls_codec had an issue with variable length encoding
git-conventional changelog
- CoreCrypto draft-20 upgrade
- Generate XCFramework when releasing for Swift (#330)
- Add
e2ei_is_degradedto flag a conversation as degraded when at least 1 member is not using a e2ei certificate
- Usize to u64 conversion error on Android in
client_valid_keypackages_count. Whatever the reason this applies a default meaningful value - [breaking] Creating a MLS group does not consume an existing KeyPackage anymore, instead it always generates a new local one. Also, explicitly ask for the credential type of the creator before creating a new MLS group.
- Mobile FFI was failing when initializing MLS client due to a Arc being incremented one too many times. Also add the E2EI API in the Kotlin wrapper and a test for it
- [breaking] Hide everywhere
Vec<Ciphersuite>appears in the public API since it seems to fail for obscure reasons on aarch64 Android devices. Undo when we have a better understanding of the root cause of this
- [BREAKING]: MLS draft-20 !
- internally use the latest version of openmls compatible with draft-20 (not yet RFC9420)
Public Group Statemethods/fields etc.. have been renamed intoGroup InfoCommitBundlefields (welcome, commit, group_info) are now wrapped in MLS messagesnew_external_proposal()has been removed- By default, partial commits (w/o UpdatePath) are created
git-conventional changelog
- Add
e2ei_is_degradedto flag a conversation as degraded when at least 1 member is not using a e2ei certificate
- [BREAKING]: fix Ciphersuite lowering for mobile FFI, using either a 16-bit integer (or a List of it) to lower those types across the FFI.
- [BREAKING]: removed optional entropy_seed from public API only on mobile since it was not required there and was causing the aforementioned issue with list of ciphersuites.
git-conventional changelog
- [BREAKING]: creating a MLS group was consuming an existing KeyPackage which could lead to inconsistencies if the
former isn't pruned on the backend side. As a consequence,
createConversation()now expects the CredentialType to pick the right credential the author wants to join the group with. - [BREAKING]: fixed unsound bug happening on aarch64 Android devices because of lowering a List of enumerations across
the FFI. Still uncertain about the root cause but to move on all the parameters like:
ciphersuite: List<Ciphersuite>in the public API have been replaced with a default value - Fixed Android FFI bug in
e2eiMlsInitwhere a reference counter had one too many reference when trying to destroy it
git-conventional changelog
- New table was mistakenly in an old migration file
- Release v0.9.2
- Fixed migrations not running because of a mistakenly added table in an older migration version
- Fixed excessive bloat in the FFI layer due to emitting rlibs
git-conventional changelog
- Reload proteus sessions when
restore_from_diskis called - Return finalize & certificate url
- Add persistence options to e2ei enrollment instance
- [breaking] Enable multi ciphersuite and multi credential type support
- [breaking] Support & expose "target" in ACME challenges
- Fix clippy lints for wasm target
- Moved Client methods related to keypackage in a dedicated mod
- Moved function
identity_keyinto a trait - Replace
eitherby a dedicated enum since after all there could be more than just 2 types of credentials - Move ClientId to dedicated mod
- Have interop runner verify the generic FFI
- First iteration of multi-ciphersuite support. The API now explicitly requires a Ciphersuite to be supplied anywhere where it's necessary. For now on you should only use the default one. Same thing for
MlsCredentialType, useBasicwhenever required - Allow persisting an e2e identity enrollment for web's needs
check_order_response&finalize_responsenow return the URL for where the next step's payload has to be sent- ACME challenges now have a "target" field which indicates the URL of the OAuth authorization and the access token endpoint
- build: fix Android packaging (again) by sourcing bindings
git-conventional changelog
- build: fix Android packaging
git-conventional changelog
- Fixed iOS keychain handling with proper attributes
- Verify x509 credential identity and return identity (client_id, handle, display_name, domain) once message is decrypted
- Release v0.7.0
- Update deps & cargo-deny configuration
- Get rid of internal 'CredentialSupplier' test util
- [BREAKING](e2e identity): added an expiry in seconds in
create_dpop_token)
git-conventional changelog
- Fixed iOS keychain handling with proper attributes
- Verify x509 credential identity and return identity (client_id, handle, display_name, domain) once message is decrypted
- Release v0.7.0
- Update deps & cargo-deny configuration
- Get rid of internal 'CredentialSupplier' test util
- [breaking] Tweak WASM API
- Use schnellru fork for GroupStore faillible inserts
- Fixed GroupStore memory limiter behavior
- Remove any transitive crate using ring. As a consequence supports EcDSA on WASM
- Copy/modify kotlin wrapper from Kalium (#284)
- [breaking] Support creating a MLS client from an e2e identity certificate
- Release v0.7.0-rc.4
- Update interop runner
dirsdep - Appease clippy
- Proteus auto prekey ids not incrementing
- Release v0.7.0-rc.3
- Release v0.7.0-rc.2
- [breaking] Make FFI parameters compliant with rfc8555
- Added missing version() function to Swift bindings
- Enable ios-wal-compat for iOS builds by default
- Exclude self from self-remove-commit delay
- Fix rustsec advisories on xtask deps
- [breaking] Latest e2e identity iteration. ClientId (from MLS) is used instead of requiring just parts of it
- Added API to check the
Arcstrongref counter - [breaking] Add ability to mark subconversations
- [breaking] Change proteus auto prekey return type to include prekey id
- [breaking] Added LRU cache-based underlying group store to replace the HashMaps
- Release 0.7.0-rc.1
- Use crates.io sparse protocol on CI via env
- Android upgrade to NDK 25 + openssl android build fix
- Updated serde-wasm-bindgen to 0.5.0
- Updated crypto deps (p256/384 & ecdsa)
- Updated changelog for LRU store changes
- [breaking] Drop LRU from keystore
- Bump webdriver version to 110
- Please see the previous RC releases for the full changelog
- Fixed a bug in the iOS WAL compatibility layer that didn't specific correct keychain attributes on the stored SQLCipher salt
- Updated internal dependencies
- Implemented E2EI credential identity verification
- We are now returning extra data on decrypted messages; you'll be able to get the sender's full identity in them.
git-conventional changelog
- [breaking] Tweak WASM API
- Use schnellru fork for GroupStore faillible inserts
- Fixed GroupStore memory limiter behavior
- Remove any transitive crate using ring. As a consequence supports EcDSA on WASM
- Copy/modify kotlin wrapper from Kalium (#284)
- [breaking] Support creating a MLS client from an e2e identity certificate
- Release v0.7.0-rc.4
- Update interop runner
dirsdep - Appease clippy
- Updated UniFFI to 0.23
- Might or might not contain breaking changes depending on your use case, please refer to UniFFI's documentation
- Fixed a small bug in the new GroupStore internals that was a bit too eager in limiting memory usage
- [BREAKING]: Renamed the WASM
strongRefCount(): numberAPI toisLocked(): boolean.- This essentially hides the implementation details across the FFI and should minimize brittleness
- Removed our dependency on ring, an external crypto library. It was mostly used for validating x509 certificates and crafting Certificate Signing Request
- By removing
ring, we now support the following MLS Ciphersuites using NIST elliptic curves / ECDSA on WASM:MLS_128_DHKEMP256_AES128GCM_SHA256_P256(0x0002)MLS_256_DHKEMP384_AES256GCM_SHA384_P384(0x0007)
- By removing
- [BREAKING]: Overhauled parts of the E2EI implementation
* Moved from a stateless API to a stateful one. As a consequence, methods have less parameters, less structs need to be exposed. All of this is wrapped under Rust's safe sync primitives in order to be able to perform the ACME enrollment in parallel.
* The new API allows creating a MLS group from the enrollment process.
*
certificateResponse()e2eiMlsInit()has been introduced and permits ending the enrollment flow and use the x509 certificate to initialize a MLS client. *ClientIdis now a string as per RFC8555. It does not anymore require to be prefixed (byimpp:wireapp=) and is exactly the same as the one used for MLS * X509 SAN URIs are now prefixed byim:wireapp=instead ofimpp:wireapp=* This release has been tested against a real OIDC provider (Dex), federating identity from a LDAP server. The OAuth2 flow used for testing is Authorization Code with PKCE * Private key materials are now properly zeroized
git-conventional changelog
- Proteus auto prekey ids not incrementing
- Release v0.7.0-rc.3
- Fixed a bug where
proteus_new_prekey_autoreturning the same prekey ID in particular cases- In case of "gaps" in the prekey id sequence, the previous algorithm (using the number of prekeys stored) would return the same ID over and over. As a consequence, the same prekey id would be overwritten over and over.
- Fix on documentation that prevented release on many platforms
git-conventional changelog
- [BREAKING] proteus_new_prekey_auto() now returns a tuple of (prekey_id, CBOR-serialized PreKeyBundle) for backend requirements
- On bindings, this translates to a new struct ProteusAutoPrekeyBundle which contains two fields:
id: the proteus prekey id (u16)pkb: the CBOR-serialized proteus PreKeyBundle
- On bindings, this translates to a new struct ProteusAutoPrekeyBundle which contains two fields:
- [BREAKING] Added an API to mark subconversations as child of another one (
mark_conversation_as_child_of)- This is breaking because this now allows us to provide the parent conversation's client list in the
client_is_existing_group_usercallback, which adds a new parameter to it
- This is breaking because this now allows us to provide the parent conversation's client list in the
- [BREAKING]
wipe_conversationis now automatically called when a commit removing the local client is received. - [BREAKING] Huge internal change on how we cache MLS groups and Proteus sessions in memory
- This affects some APIs that became async on the TS bindings
- Our previous
HashMap-based cache could grow indefinitely in the case of massive accounts with many, many groups/conversations, each containing a ton of clients. This replaces this memory store by a LRU cache having the following properties:- Limited by number of entries AND occupied memory
- Defaults for memory: All the available system memory on other platforms / 100MB on WASM
- Defaults for number of entries:
- 100 MLS groups
- 200 Proteus sessions
- Flow for retrieving a value
- Check the LRU store if the value exists, if yes, it's promoted as MRU (Most Recently Used) and returned
- If not found, it might have been evicted, so we search the keystore
- If found in the keystore, the value is placed as MRU and returned
- Special case: we evict the store as much as needed to fit the new MRU value in this case. This is designed to infaillible.
- If not found, we return a
Nonevalue
- Limited by number of entries AND occupied memory
- This approach potentially allows to have an unlimited number of groups/sessions as long as a single item does not exceed the maximum memory limit.
- As a consequence of the internal mutability requirements of the new map and the automatic keystore fetches, many if not all APIs are now
async. This does not concern the Mobile FFI.
- [BREAKING] Because of Rust 1.68's release, CoreCrypto is now incompatible with Android NDK versions under 25.2 (the LTS version) and Android API level 24.
- [BREAKING] E2EI: The API is now compliant with RFC8555
- Another change will come soon to be able to initialize a MLS client using the X509 certificate issued by the E2EI process
- Enabled the iOS WAL compatibility layer to prevent spurious background kills
- Added a WASM api to check the Arc strongref counter
git-conventional changelog
- Improve compatbillity with older linux versions when running core-crypto-jvm by building on Ubuntu LTS (22.04).
git-conventional changelog
- Fixed commitDelay being undefined when FFI says 0
- Release v0.6.2
- Fix native libraries not loading by moving them to the package root (#255)
- Fixed a bug in the TypeScript bindings where the
DecryptedMessagebundle could havecommitDelayset toundefinedwhen it should be 0- This could happen in the case of external proposals where the system would determine that the proposals should be immediately committed
git-conventional changelog
- Publishing for JVM generating empty artifacts (#251)
- Fall back on false when the callback doesn't retrurn a Promise
- Proteus auto prekey might overwrite Last Resort prekey
- Release 0.6.1 (#253)
- Remove proteus double persistence as it's already automatically eager
- Xtask release outputs dry-run log unconditionally
- Adapt with acme client library tested on real acme-server forked. Also some nits & dependencies pinned
- Release v0.6.0
- Fixed a bug where the Proteus last resort prekey could be overwritten.
- Fixed JVM publishing creating broken packages.
- WASM callbacks return false by default if no promise is returned.
- Benchmarks: Remove redundant save when persisting proteus sessions.
git-conventional changelog
- Xtask release outputs dry-run log unconditionally
- Adapt with acme client library tested on real acme-server forked. Also some nits & dependencies pinned
- Release v0.6.0
- Added support for Proteus Last Resort PreKeys (boooo!)
- [breaking] Async callbacks
- Externally-generated clients
- Release v0.6.0-rc.8
- Updated webdriver version to chrome 110
- Fixed E2E interop test for breaking api changes
- New e2eidentityerror enum member wasn't exposed over ffi
- TS/WASM build issues & test
- Release v0.6.0-rc.7
- Proteus error system not working (at all)
- Force cargo to use git cli to avoid intermittent CI failures
- Release v0.6.0-rc.6
- Updated rstest_reuse to 0.5
- Updated spinoff to 0.7
- Added codecov settings
- Update node to LTS 18 & enable JS e2e testing
- Make npm build run wasm-opt in Os
- Update JVM publish workflow to build on native platforms (#229)
- [breaking] Added conversation id to clientIsExistingGroupUser callback
- Increment IndexedDB store version when crate version changes
- Added support for Proteus error codes
- Cut release 0.6.0-rc.5
- Moved codecov from tarpaulin to llvm-cov
- Updated RustCrypto primitives & git dep in xtask
- Aarch64-apple-ios-sim target not compiling (#213)
- Cryptobox import now throws errors on missing/incorrect store
- Expose end to end identity web API
- Add end to end identity bindings
- 0.6.0-rc.4 release
- Updated base64, lru and spinoff deps
- Added WebDriver-based WASM test runner
- Xtask improvements
- Fix 1.66 clippy warnings
- Update base64 to 0.20
- Fixed wrong documentation link in TS bindings docs
- Update UniFFI to 0.22
- Kotlin FFI docs + makefile fixes for other platforms
- Added missing Proteus APIs and docs
- Release v0.6.0-rc.3
- Functional Android NDK 21 CI
- Publish android CI
- Unreachable pub makes docs build fail
- Release v0.6.0-rc.2
- Fix advisory stuff
- Broken Proteus implementation
- Prevent application messages signed by expired KeyPackages
- Fix cryptobox import on WASM [CL-119]
- Incorrect TS return types [CL-118]
- Expose a 'WrongEpoch' error whenever one attempts to decrypt a message in the wrong epoch
- Add 'restore_from_disk' to enable using multiple MlsCentral instances in iOS extensions
- Add specialized error when trying to break forward secrecy
- Add 'out_of_order_tolerance' & 'maximum_forward_distance' to configuration without exposing them and verify they are actually applied
- [breaking] Change 'client_id' in CoreCrypto constructor from a String to a byte array to remain consistent across the API
- Expose proteus prekey fingerprint - CL-107
- Release v0.6.0-rc.1
- Use NDK 21 for android artifacts - CL-111
- Ensure we are immune to duplicate commits and out of order commit/proposal
- Expose proteus session fingerprints (local and remote) - CL-108
- Support deferred MLS initialization for proteus purposes [CL-106]
- Remove C-FFI
- [breaking] Incorrect handling of enums across WASM FFI
- Commits could lead to inconsistent state in keystore in case PGS serialization fails
- Make tags have semantic versioning names and downgrading to swift 5.5 - CL-49
- Publication of swift packages
- Expose session exists through the ffi - CL-101
- Fix new clippy test warnings in 1.65
- Fix new clippy warnings in 1.65
- Ensure everything keeps working when pure ciphertext format policy is selected
- Change the internal type of the public group info to Vec so we don't have extra bytes in the serialized message - FS-1127
- Adding actions to check bindings and to publish swift package - CL-49
- Add action to publish jvm/android packages and change rust toolchain in ci (#157)
- Add support for Proteus within interop runner
- 'join_by_external_commit' returns a non TLS serialized conversation id
- [breaking] Expose a 'PublicGroupStateBundle' struct used in 'CommitBundle' variants
- [breaking] Remove all the final_* methods returning a TLS encoded CommitBundle
- Returning if decrypted message changed the epoch - CL-92 (#152)
- Exporting secret key derived from the group and client ids from the members - CL-97 - CL-98 (#142)
- Added API to generate Proteus prekeys
- Fixed Cryptobox import for WASM
- Added support for migrating Cryptobox data
- Added FFI for CoreCrypto-Proteus
- Added support for Proteus
- Validate received external commits making sure the sender's user already belongs to the MLS group and has the right role
- [breaking] Rename callback~~
client_id_belongs_to_one_of~~ intoclient_is_existing_group_user - [breaking] External commit returns a bundle containing the PGS
- [breaking] Add
clear_pending_group_from_external_committo cleanly abort an external commit. Also renamedgroup_stateargument intopublic_group_statewherever found which can be considered a breaking change in some languages - [breaking] Rename
MlsConversationInitMessage#groupintoMlsConversationInitMessage#conversation_idbecause it was misleading about the actual returned value
- Apply suggestions from code review
- Updated bundled FFI files
- Added Proteus testing infra
- Added missing docs
- Nits, fmt & cargo-deny tweak
- Add m1 support for the jvm bindings (#139)
- Remove unneeded
map_err(CryptoError::from) - Remove useless code
- Fix external commit tests allowing member to rejoin a group by external commit
- Add a default impl for 'TestCase', very useful when one has to debug on IntelliJ
- Parameterize ciphers
- Ensure external senders can be inferred when joining by external commit or welcome
- Fix rcgen failing on WASM due to some unsupported elliptic curve methods invoked at compile time
- Ensure external commit are retriable
Platform support status:
- x86_64-unknown-linux-gnu ✅
- x86_64-apple-darwin ✅
- armv7-linux-androideabi ✅
- aarch64-linux-android ✅
- i686-linux-android ✅
- x86_64-linux-android ✅
- aarch64-apple-ios ✅
- aarch64-apple-ios-sim ✅
- x86_64-apple-ios ✅
- wasm32-unknown-unknown ✅
- [BREAKING CHANGE] E2EI solution API overhauled from pre-release versions
- This was made to fix some incompatibilities between the DPoP RFC and our code; The API had to be changed as a consequence
- Please refer to the following point to see the changes
- First stable version of Wire's end-to-end identity client library. It allows a MLS client to generate a x509 certificate proving possession of its userId, clientId and displayName for a given domain/backend. This certificate will later be used as a MLS credential in place of the only currently supported "basic" one which consists of a public key.
- To generate such a certificate, use the
new_acme_enrollmentmethod on a partially initialized CoreCrypto instance. This will generate a temporary key material for the enrollment session with the ACME server. Note that only Ed25519 signature scheme is supported at the moment. - Only the "enrollment" flow is defined for the moment. Later on, "refresh" and "revocation" flows will be added.
- This library is heavily opinionated and only suited for Wire custom flow, with our fork of the acme server. Any attempt to use it as a generic purpose acme client library will fail terribly.
- To make sure this works as expected, this library has been tested against the actual acme-server thanks to testcontainers. Only the OIDC provider has been mocked for the moment due to the fact that the target provider Dex does not yet support Ed25519 signatures.
- To generate such a certificate, use the
- Added support for externally-generated MLS clients
- This allows you to generate a standalone Credential/KeyPair, submit it to your MLS Authentication Service, and then update this credential with a newly-attributed Client ID.
- Added APIs to support Proteus Last Resort Prekeys
- Added support for Proteus error codes
- WASM:
- all errors are now instances of
CoreCryptoErrorwhich extends the standard JavaScriptErrorbut with additional properties:rustStackTracecontains the original Rust error string.proteusErrorCodecontains the error code for Proteus calls. If it's 0, no error, otherwise it contains the code
- WASM/TS now has access to the
CoreCrypto.proteusLastErrorCode()method which allows to retrieve the last-occured proteus error and thus brings it to parity with other FFIs
- all errors are now instances of
- On other platforms, the FFI has gained a
proteus_last_error_codemethod.
- WASM:
- Fixed a bug where the keystore would not execute its IndexedDB upgrade handler on WASM, leading to older stores and/or new tables not being structurally consistent
- Added missing Proteus APIs to bindings and FFI:
proteus_new_prekey_auto: generates a new PreKeyBundle with an automatically incremented ID- To do this, CoreCrypto finds the first "free" ID within the
0..u16::MAX - 1range and creates a PreKey using this ID.
- To do this, CoreCrypto finds the first "free" ID within the
- Added Proteus compatibility layer support
- Added API to export secret key derived from the group and client ids from the members
- Change
DecryptedMessagesignature- The
decryptAPI now returns if the decrypted message changed the epoch through thehasEpochChangedfield
- The
- Members can now rejoin group by external commits
- Validate received external commits
- Added
clear_pending_group_from_external_commit - External commit returns a bundle containing the PGS
- [BREAKING CHANGE] Changed callbacks to be async
- This allows consumers to perform async I/O within the callbacks
- Note this doesn't affect the Kotlin/Swift bindings as UniFFI does not support async yet.
- BREAKING Renamed callback
client_id_belongs_to_one_oftoclient_is_existing_group_user - BREAKING WASM: Omitted in last build;
CoreCrypto.deferredInitnow takes an object with the parameters much likeinit()for consistency reasons. - BREAKING No one was probably using it, but the C-FFI has been removed
There has been an extensive pre-release period (with many -pre and -rc releases), the original changelog for those has been collapsed below:
0.6.0 pre-releases changelog
git-conventional changelog
- Added support for Proteus Last Resort PreKeys (boooo!)
- [breaking] Async callbacks
- Externally-generated clients
- Release v0.6.0-rc.8
- Updated webdriver version to chrome 110
- Added support for externally-generated MLS clients
- This allows you to generate a standalone Credential/KeyPair, submit it to your MLS Authentication Service, and then update this credential with a newly-attributed Client ID.
- [BREAKING CHANGE] Changed callbacks to be async
- This allows consumers to perform async I/O within the callbacks
- Note this doesn't affect the Kotlin/Swift bindings as UniFFI does not support async yet.
- Added APIs to support Proteus Last Resort Prekeys
git-conventional changelog
- Fixed E2E interop test for breaking api changes
- New e2eidentityerror enum member wasn't exposed over ffi
- TS/WASM build issues & test
- Release v0.6.0-rc.7
- Fixed WASM build when imported from the outside
- Made sure we're not leaking internal/private interfaces anymore and causing issues
- Also added a test to our JS E2E suite to make sure importing the package with TS is successful and we do not encounter regressions like these anymore
- BREAKING WASM: Omitted in last build;
CoreCrypto.deferredInitnow takes an object with the parameters much likeinit()for consistency reasons.
git-conventional changelog
- Proteus error system not working (at all)
- Force cargo to use git cli to avoid intermittent CI failures
- Release v0.6.0-rc.6
- Updated rstest_reuse to 0.5
- Updated spinoff to 0.7
- Added codecov settings
- Update node to LTS 18 & enable JS e2e testing
- Make npm build run wasm-opt in Os
- Update JVM publish workflow to build on native platforms (#229)
IMPORTANT: The previous release (0.6.0-rc.5) is non-functional in general. The proteus error reporting does NOT work
There's a post mortem available here: wireapp#230 (comment)
- Fixed support for Proteus error codes
- WASM:
- all errors are now instances of
CoreCryptoErrorwhich extends the standard JavaScriptErrorbut with additional properties:rustStackTracecontains the original Rust error string.proteusErrorCodecontains the error code for Proteus calls. If it's 0, no error, otherwise it contains the code
- WASM/TS now has access to the
CoreCrypto.proteusLastErrorCode()method which allows to retrieve the last-occured proteus error and thus brings it to parity with other FFIs
- all errors are now instances of
- On other platforms, the API is unchanged, but now works.
- WASM:
git-conventional changelog
- [breaking] Added conversation id to clientIsExistingGroupUser callback
- Increment IndexedDB store version when crate version changes
- Added support for Proteus error codes
- Cut release 0.6.0-rc.5
- Moved codecov from tarpaulin to llvm-cov
- Updated RustCrypto primitives & git dep in xtask
- BREAKING: Changed the signature of the
client_is_existing_group_usercallback to add the group id as the first argument- Before:
client_is_existing_group_user(client_id: ClientId, existing_clients: Vec<ClientId>) -> bool - After:
client_is_existing_group_user(conversation_id: ConversationId, client_id: ClientId, existing_clients: Vec<ClientId>) -> bool
- Before:
- Added support for Proteus error codes
- On WASM, the JS Error contains a
proteusErrormethod that returns the error code as an integer. If there's no error it returns 0. - On other platforms, the FFI has gained a
proteus_last_error_codemethod.
- On WASM, the JS Error contains a
- Fixed a bug where the keystore would not execute its IndexedDB upgrade handler on WASM, leading to older stores and/or new tables not being structurally consistent
- Updated RustCrypto dependencies
- Tooling: moved code coverage CI from Tarpaulin to LLVM-Cov
- This lowered the execution time of our codecov CI from ~25-30 minutes down to ~15-20 minutes
- This leads to more accurate code coverage as well - along with some false negatives such as
#[derive]statements
git-conventional changelog
- Aarch64-apple-ios-sim target not compiling (#213)
- Cryptobox import now throws errors on missing/incorrect store
- Expose end to end identity web API
- Add end to end identity bindings
- 0.6.0-rc.4 release
- Updated base64, lru and spinoff deps
- Added WebDriver-based WASM test runner
- Xtask improvements
- Fix 1.66 clippy warnings
- Update base64 to 0.20
- Fixed wrong documentation link in TS bindings docs
- Update UniFFI to 0.22
- Kotlin FFI docs + makefile fixes for other platforms
- First bytes of end to end identity exposed. Thanks to the ACME protocol, it allows requesting a x509 certificate from an authority and then use it to create a MLS Credential.
- Fixed
cargo-makeMakefile.toml to allow building JVM bindings whatever the platform you're running- This is done by adding tests to the relevant tasks, allowing to conditionally execute them.
- Added a Makefile task to build the
core_crypto_ffiKotlin binding docs (via Dokka) and integrate them into the doc package - Updated UniFFI to 0.22
- Other minor improvements on internal build/release tools (mainly our
cargo xtaskcommand) - Semi-breaking: Behavior change on
ProteusCentral::import_cryptobox(aka Cryptobox import).- WASM: If the provided store
pathis missing or doesn't have the expected tables, we now throw aCryptoboxMigrationError::ProvidedPathDoesNotExisterror - Other platforms: If the provided cryptobox folder at
pathis missing, we now throw aCryptoboxMigrationError::ProvidedPathDoesNotExisterror - Likewise, on all platforms, if the Cryptobox Identity is not present, we now throw a
CryptoboxMigrationError::IdentityNotFounderror and abort the process
- WASM: If the provided store
- Tooling: Added a custom WASM test runner based on WebDriver (BiDi interactive test progress reporting in progress still)
git-conventional changelog
- Added missing Proteus APIs and docs
- Release v0.6.0-rc.3
- Added missing Proteus APIs to bindings and FFI:
proteus_new_prekey_auto: generates a new PreKeyBundle with an automatically incremented ID- To do this, CoreCrypto finds the first "free" ID within the
0..u16::MAXrange and creates a PreKey using this ID.
- To do this, CoreCrypto finds the first "free" ID within the
- Added missing documentation when it comes to Proteus eager Session persistence.
- Previously undocumented change, but since
0.6.0-rc.1, CoreCrypto eagerly persists Proteus Sessions (much like it does with MLS groups) when needed:- Decrypting or Encrypting messages, as ratcheting key material can be produced and as such must be persisted
- We'll add a more "manual" API later on if you want to control when data is persisted (because it is performance heavy)
- Initializing Sessions through PreKeyBundles or incoming Messages
- Decrypting or Encrypting messages, as ratcheting key material can be produced and as such must be persisted
- Previously undocumented change, but since
git-conventional changelog
- Functional Android NDK 21 CI
- Publish android CI
- Unreachable pub makes docs build fail
- Release v0.6.0-rc.2
- Fix advisory stuff
- This release contains nothing. It's only there to fix the faulty Android release CI.
git-conventional changelog
- Broken Proteus implementation
- Prevent application messages signed by expired KeyPackages
- Fix cryptobox import on WASM [CL-119]
- Incorrect TS return types [CL-118]
- Expose a 'WrongEpoch' error whenever one attempts to decrypt a message in the wrong epoch
- Add 'restore_from_disk' to enable using multiple MlsCentral instances in iOS extensions
- Add specialized error when trying to break forward secrecy
- Add 'out_of_order_tolerance' & 'maximum_forward_distance' to configuration without exposing them and verify they are actually applied
- [breaking] Change 'client_id' in CoreCrypto constructor from a String to a byte array to remain consistent across the API
- Expose proteus prekey fingerprint - CL-107
- Release v0.6.0-rc.1
- Use NDK 21 for android artifacts - CL-111
- Ensure we are immune to duplicate commits and out of order commit/proposal
- Fixed a compilation issue related to the
sha1crate's ASM - Added a
restore_from_diskAPI to enable using CoreCrypto from various instances - Various internal improvements to testing to increase resistance to uncommon scenarios
- Proteus:
- Expose proteus prekey fingerprint
- Fixed the TypeScript exposed types
- Fixed Cryptobox import
- Fixed broken Proteus implementation that led to decryption errors after key import
- MLS:
- Expose a
WrongEpocherror - Added an error when trying to break PFS
- BREAKING: Tweaked the configuration format, removed and added some options
- Expose a
git-conventional changelog
- Expose proteus session fingerprints (local and remote) - CL-108
- Support deferred MLS initialization for proteus purposes [CL-106]
- Remove C-FFI
- chore: Get rid of the C-FFI
- feature: Added support for deferred MLS initialization
- Proteus:
- Expose Proteus session Fingerprints (local & remote)
git-conventional changelog
- [breaking] Incorrect handling of enums across WASM FFI
- Commits could lead to inconsistent state in keystore in case PGS serialization fails
- Make tags have semantic versioning names and downgrading to swift 5.5 - CL-49
- Publication of swift packages
- Expose session exists through the ffi - CL-101
- Fix new clippy test warnings in 1.65
- Fix new clippy warnings in 1.65
- Ensure everything keeps working when pure ciphertext format policy is selected
- fix: Publication of swift packages [CL-49] by @augustocdias in wireapp#165
- fix: Make tags have semantic versioning names and downgrading to swift 5.5 - CL-49 by @augustocdias in wireapp#166
- feat: Expose session exists through the ffi - CL-101 by @augustocdias in wireapp#167
- chore: fix new clippy warnings in 1.65 by @beltram in wireapp#170
- fix: consistent commits by @beltram in wireapp#169
- fix!: Incorrect handling of enums across WASM FFI [CL-104] by @OtaK in wireapp#168
- test: pure ciphertext by @beltram in wireapp#160
- Release 0.6.0-pre.4 by @augustocdias in wireapp#171
Full Changelog: https://github.com/wireapp/core-crypto/blob/develop/CHANGELOG.md
git-conventional changelog
- Change the internal type of the public group info to Vec so we don't have extra bytes in the serialized message - FS-1127
- Adding actions to check bindings and to publish swift package - CL-49
- Add action to publish jvm/android packages and change rust toolchain in ci (#157)
- Add support for Proteus within interop runner
- Move github action for rust to a maintained one. (More info: actions-rs/toolchain#216)
git-conventional changelog
- Enable proteus support
git-conventional changelog
- Add Apple M1 support for the JVM bindings
- Rename callback
client_id_belongs_to_one_of - Added Proteus compatibility layer support
- Added API to export secret key derived from the group and client ids from the members
- Change CommitBundle signature
- The
decryptAPI now returns if the decrypted message changed the epoch
- The
- Members can now rejoin group by external commits
- Validate received external commits
- Added
clear_pending_group_from_external_commit - External commit returns a bundle containing the PGS
git-conventional changelog
- Wire-server sends a base64 encoded ed25519 key afterall. Consumers are in charge of base64 decoding it and pass it to core-crypto
- TS Ciphersuite enum not correctly exported
- Add installation instructions for e2e runner on macos
- Release v0.5.2
- Fix: supplied backend's removal key was not TLS serialized but base64 encoded. In this release, it is up to consumer to base64 decode the key and supply it to core-crypto
- Fix: Typescript enumerations could not be used by value
git-conventional changelog
- Incorrect null handing in Typescript wrapper for 'commitPendingProposals'
- External_senders public key was not TLS deserialized causing rejection of external remove proposals
- Better explanation of what DecryptedMessage#proposals contains
- Release v0.5.1
- Added E2E interop testing tool
- Fix: supplied backend's removal key (used for verifying external remove proposals) was not TLS deserialized
- Fix: incorrect null handing in Typescript wrapper for 'commitPendingProposals' causing an error when there was no proposal to commit
- New test runner for running interoperability tests between various core-crypto clients. Currently, only native & WASM are supported. Most of all, those tests can be run in our Continuous Integration.
git-conventional changelog
- NPM publish workflow missing npm ci + wrong method names in TS bindings
- NPM publish workflow missing npm i
- Rollback openmls & chrono in order to release 0.5.0
- Pin openmls without vulnerable chrono
- Wee_alloc memory leak + NPM publish issue
- Unreachable pub struct breaks docgen
- Fixed iOS SQLCipher salt handling within keychain
- [breaking] Changed misleading callback API and docs
- [breaking] Added missing TS API to set CoreCrypto callbacks
- Force software implementation for sha2 on target architectures not supporting hardware implementation (i686 & armv7 in our case)
- Add forgotten 0.4.0 changelog
- [breaking] 'commit_pending_proposals' now returns an optional CommitBundle when there is no pending proposals to commit
- Release v0.5.0 Redux
- Update UniFFI to 0.20
- Release v0.5.0
- Update node version from 12 to 16 LTS
- Update dependencies
- Remove es2020-specific operators and target es2020 only
- Updated changelog
Platform support status:
- x86_64-unknown-linux-gnu ✅
- x86_64-apple-darwin ✅
- x86_64-pc-windows-msvc ❌
- armv7-linux-androideabi ✅ (
⚠️ ) - aarch64-linux-android ✅ (
⚠️ ) - i686-linux-android ✅ (
⚠️ ) - x86_64-linux-android ✅ (
⚠️ ) - aarch64-apple-ios ✅
- aarch64-apple-ios-sim ✅
- x86_64-apple-ios ✅
- wasm32-unknown-unknown ✅
Note: all the platforms marked with (
- [BREAKING]:
commit_pending_proposalsnow returns an optionalCommitBundle- This was made to handle the case where there are no queued proposals to commit and this method would be called, causing the operation to fail.
- [BREAKING]: Changed the API for callbacks for clarity
- This also contains documentation changes that make the use and intent of callbacks easier to understand.
- Fixed the iOS-specific database salt handling to allow using several databases on the same device.
- TypeScript bindings:
- Removed the use of ES2020-specific operators (
??Null-coalescing operator) to allow downstream to compile without transpiling. - Added callbacks API
- Removed the usage of
wee_allocallocator as it leaks memory: rustwasm/wee_alloc#106
- Removed the use of ES2020-specific operators (
- Kotlin & Swift bindings:
- Upgraded UniFFI to 0.20 which now generates a correct callback interface in
camelCaseinstead of erroneoussnake_case.- Note that you will have to adapt to the aforementioned breaking changes to the callback API anyway so this just makes it a bit nicer
- Upgraded UniFFI to 0.20 which now generates a correct callback interface in
git-conventional changelog
- Fixes runtime issues on Android caused by the sha2 crate.
git-conventional changelog
- Uniffi breaking changes in patch release and ffi error due to unused
TlsMemberAddedMessages
- Fixes build issues for mobile target
git-conventional changelog
- Ensure durable methods are well tested and actually durable
- Commits and group creation return a TLS serialized CommitBundle. The latter also contains a PublicGroupStateBundle to prepare future evolutions
- [breaking] 'decrypt_message' returns the sender client id
- Use 128 bytes of padding when encrypting messages instead of 16 previously
- Add function to return current epoch of a group [CL-80] (#96)
- Adding a wrapper for the swift API and initial docs [CL-62] (#89)
- Add '#[durable]' macro to verify the method is tolerant to crashes and persists the MLS group in keystore
- Expose 'clear_pending_commit' method
- Allow rollbacking a proposal
- [breaking] Expose 'clear_pending_commit' method
- [breaking] Allow rollbacking a proposal
- Migrate benchmarks to async and write some for core crypto operations
- Fixed WASM E2E tests
- Add reminder for x509 certificate tests
Platform support status:
- x86_64-unknown-linux-gnu ✅
- x86_64-apple-darwin ✅
- x86_64-pc-windows-msvc ❌
- armv7-linux-androideabi ✅ (
⚠️ ) - aarch64-linux-android ✅ (
⚠️ ) - i686-linux-android ✅ (
⚠️ ) - x86_64-linux-android ✅ (
⚠️ ) - aarch64-apple-ios ✅
- aarch64-apple-ios-sim ✅
- x86_64-apple-ios ✅
- wasm32-unknown-unknown ✅
Note: all the platforms marked with (
- Allow rollbacking proposals. Now every method for creating a proposal also returns a proposal reference
(unique identifier) one can use later on to
clear_pending_proposal - Add
clear_pending_proposalto wipe out local pending proposals - Add
clear_pending_committo wipe out local pending commit - Add
conversation_epochto get the current conversation's MLS epoch - Now
decrypt_messagereturns the sender client_id when the message is an application message. To use in calling. - Durability: Now all the mutable operations are checked for durability i.e. would a process crash turn the application into an inconsistent state. It boils down to verifying that we persist the MLS group in the keystore after every operation mutating it
- Added a clean and documented Swift wrapper and tasks to build it more easily
- use 128 bytes of padding when encrypting messages instead of 16 previously
- Add some commit methods
final_add_clients_to_conversation,final_remove_clients_from_conversation,final_update_keying_material&final_commit_pending_proposalswhich return a TLS serialized CommitBundle. It cannot be used now since wire-server does not yet have an endpoint for supplying it. It can be used to test the endpoint. In the end, thefinal_prefix will removed and the not prefixed methods will be deprecated. - Benchmarks have been improved and now also cover MLS operations
Maintenance release to prepare for the next release
- Pinned all git dependencies via git tags to avoid breakage in the future
git-conventional changelog
- Clippy fix impl eq
- Libgcc swizzling for android was removed
- Cleaned up FFI names for clearer intent
- Caught up WASM api with the internal API changes
- Doctests were failing because included markdown snippets were parsed and compiled
- Defer validation that a callback has to be set for validating external add proposal after incoming proposal identified as such
- Updated RustCrypto dependencies to match hpke-rs requirements
- Group was not persisted after decrypting an application message
- UniFFI wrong type defs
- Aes_gcm compilation issue
- WASM persistence & CoreCrypto Async edition
- 'client_keypackages' does not require mutable access on 'mls_client'
- Add_member/remove_member IoError
- Incorrect number of keypackages returned
- Added support for MLS Group persistence [CL-5]
- Added bindings docs where appropriate + generated gh-pages
- Fix Client struct documentation
- Improving docs of Core-Crypto - [CL-50] (#60)
- Review external add proposal validation and remove 'InvalidProposalType' error
- Remove required KeyPackage when creating an external add proposal
- Remove commits auto-merge behaviour
- Expose GroupInfo after commit operation
- Use draft-16 implementation of external sender. Expose a correct type through ffi for remove key
- Add API to wipe specific group from core crypto [CL-55] (#81)
- Adding validation to external proposal [CL-51] (#71)
- Decrypting a commit now also return a delay when there are pending proposals
- Decrypting a commit now also return a delay when there are pending proposals
- 'commit_delay' now uses openmls provided leaf index instead of computing it ourselves. It is also now infallible.
- Ensure consistent state
- [breaking] Add commit delay when a message with prending proposals is processed [CL-52] (#67)
- Added KeyPackage Pruning
- Added support for external entropy seed
- Join by external commit support - CL-47 (#57)
- Added Entity testing to keystore
- External remove proposal support
- Supports and validates x509 certificates as credential
- Expose function to self update the key package to FFI and Wasm #CL-17 (#48)
- Added support for wasm32-unknown-unknown target
- Support external add proposal
- Added method to leave a conversation
- Enforce (simple) invariants on MlsCentralConfiguration
- Expose add/update/remove proposal
- Bump WASM bundle version to 0.3.0
- Added Changelog generator
- Fix nits on CHANGELOG-HUMAN.md
- Add changelog generator configuration + human changelog
- Disable crate publishing + UniFFI catchup
- Rename 'group_info' into 'public_group_state' to remain consistent with draft-12
- Remove 'SelfKeypackageNotFound' error which is not used
- Fix some clippy lints
- Remove 'group()' test helper and inlined it
- Fix cli compilation and update it a bit
- Removed CryptoError variant
CentralConfigurationError - Avoid cloning credential
- Use shorthand for not using generics in conversation
- Factorize group accessors in conversation.rs
- Fix some clippy warnings
- Remove .idea in sample anroid app
- Remove unnecessary path prefixes imports
- Remove useless mutable borrow in Client methods
- Add Intellij files to gitignore
- Bump jvm and android version
- Add jvm linux support
- Avoid cloning conversation extra members when creating the former
- Moved run_with_* test utils in a test_utils mod
- Use shorthand for generics in Central
- Factorize keystore update when group state change from a conversation pov
- Add tests for 'commit_pending_proposals'
- Verify that commit operation are returning a valid welcome if any
- Use Index trait to access conversation from Central instead of duplicate accessor
- Use central instead of conversation
- Fix minor clippy lints in tests
- Apply clippy suggestions on test sources
- Reorganize tests in conversation.rs
- Nest conversation tests in dedicated modules
- Verify adding a keypackage to a ConversationMember
This second major release focuses on expanding our platform support and featureset
Platform support status:
- x86_64-unknown-linux-gnu ✅
- x86_64-apple-darwin ✅
- x86_64-pc-windows-msvc ❌
- armv7-linux-androideabi ✅ (
⚠️ ) - aarch64-linux-android ✅ (
⚠️ ) - i686-linux-android ✅ (
⚠️ ) - x86_64-linux-android ✅ (
⚠️ ) - aarch64-apple-ios ✅ (
⚠️ ) - aarch64-apple-ios-sim ✅ (
⚠️ ) - x86_64-apple-ios ✅ (
⚠️ ) - wasm32-unknown-unknown ✅
Note: all the platforms marked with (
-
Majorly improved documentation across all crates. Documentation for the
mainbranch can be found here. TheHEADof this branch should only be a tagged version.- This documentation is available here: https://wireapp.github.io/core-crypto/core_crypto/
-
Moved the codebase to
async- This was a requirement to make everything work on the WASM target, as we cannot block the JavaScript runtime without making the browsers freeze up completely
- As a consequence, we forked
openmlsto wireapp/openmls- Our incremental changes, including the
asyncrewrite ofopenmlsis located here
- Our incremental changes, including the
-
Added support for MLS Group Persistence, as this was preventing clients from continuing use of their joined groups (oops!)
-
All methods creating a commit e.g.
add_clients_to_conversationnow require to callcommit_acceptedwhen Delivery Service responds200 OK. Otherwise, it might indicate there was a409 CONFLICT, i.e. another client sent a commit for current epoch before and got accepted. In that case, do nothing and let things get reconciled indecrypt_message -
Added support for lifetime-expired Keypackage pruning
-
Added support for external CSPRNG entropy pool seeding
-
Dropped the
openmls-rust-crypto-providerin favour of ourmls-crypto-providerwith support for more ciphersuites and updated dependencies- As a consequence, we forked
hpke-rsto wireapp/hpke-rs- Our changes can be found here
- Ciphersuite support details:
MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519✅MLS_128_DHKEMP256_AES128GCM_SHA256_P256✅MLS_128_DHKEMX25519_CHACHA20POLY1305_SHA256_Ed25519✅MLS_256_DHKEMX448_AES256GCM_SHA512_Ed448❌- There is no suitable
ed448rust crate yet
- There is no suitable
MLS_256_DHKEMP521_AES256GCM_SHA512_P521❌p521RustCrypto crate is a WIP and not ready just yet. It shouldn't take too long though.
MLS_256_DHKEMX448_CHACHA20POLY1305_SHA512_Ed448❌- There is no suitable
ed448rust crate yet
- There is no suitable
MLS_256_DHKEMP384_AES256GCM_SHA384_P384✅
- As a consequence, we forked
-
Expanded the API to include:
- Conversations:
- Ability to wipe
- Ability to leave
- Ability to force clients to update their keying material (i.e. self-update)
- Support for MLS proposals
- Exposed methods to create
Add/Remove/Updateproposals
- Exposed methods to create
- Support for MLS external commits
- Added ability to export MLS Public Group State for a given conversation
- A
PublicGroupStateis also returned everytime you create a commit. This comes from the need to keep the MLS Delivery Service up to date on thePublicGroupStateso that external commits can be made by other clients.
- A
- Added support for creating an external commit to join a conversation (
join_by_external_commit)
- Added ability to export MLS Public Group State for a given conversation
- Support for MLS external Add (
new_external_add_proposal) and Remove Proposal (new_external_remove_proposal). - Support for X.509 credentials
- Added a commit delay hint to prevent clients from rushing to commit to the server - which would cause epoch conflicts and high load
- Returned in
decrypt_message
- Returned in
- Conversations:
-
Changed most
messagefields to be namedcommit, as this would cause less confusion for consumers. Those fields always contained MLS commits and should be treated as such. -
All commit methods now return a
CommitBundlestruct containing * the commit message * an optionalWelcomeif there were pending add proposals * aPublicGroupStateto upload to the Delivery Servicedecrypt_messagenow returns aDecryptedMessagestruct containing:- an optional application message
- optional pending proposals renewed for next epoch to fan out
- a
is_activeboolean indicating if the decrypted commit message caused the client to be removed from the group - the aforementioned commit delay
- Added WASM bindings support to target
wasm32-unknown-unknownas a new tier 1 target.- Added a full-fledged TypeScript wrapper with a full documentation to abstract the wasm-specific issues.
- This now means that CoreCrypto is also now a NPM package. It is currently published at @otak/core-crypto
- Incremental improvements to the Kotlin & Swift UniFFI bindings
- Caught up the bindings' API to match our internal CoreCrypto APIs
- Added a C-FFI for maybe future work involving other targets than Kotlin & Swift
- Added support for WASM through an AES-GCM256-encrypted IndexedDB backend
- This introduced a major refactoring to structure the code around having different backends depending on the platform.
git-conventional changelog
Initial stable release with a reduced featureset
Platform support status:
- x86_64-unknown-linux-gnu ✅
- x86_64-apple-darwin ✅
- x86_64-pc-windows-msvc ❌
- armv7-linux-androideabi
⚠️ - aarch64-linux-android
⚠️ - i686-linux-android
⚠️ - x86_64-linux-android
⚠️ - aarch64-apple-ios
⚠️ - aarch64-apple-ios-sim
⚠️ - x86_64-apple-ios
⚠️ - wasm32-unknown-unknown ❌
This release contains the following features:
- Client abstraction
- Handles creating/retrieving the locally stored client identity automatically
- Conversation handling
- Ability to create conversations
- Message encryption/decryption
- Ability to add/remove users from a conversation
- Encrypted-at-rest Keystore for persistence of client keying material and keypackages
- Added Swift and Kotlin bindings through UniFFI
- Added support for Proteus PreKeys
- Fixed iOS-specific WAL behavior to preserve backgrounding capabilities
- See the comment at
https://wireapp.github.io/core-crypto/src/core_crypto_keystore/connection/platform/generic/mod.rs#99for more details
- See the comment at
- Fix for migrations being incorrectly defined