-
Notifications
You must be signed in to change notification settings - Fork 99
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Version 2 upgrade of go-crypto #182
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
2af20ea
to
fbf5a75
Compare
91539a3
to
a9c0e0a
Compare
Updates the parsing and serialization methods to support v6 keys. Adds the AEAD s2k type for secret key encryption but does not implement the feature yet.
This change implements the necessary updates for parsing and serializing v6 signature packets. Further it implements the v6 signature salt. V6 signatures require that a salt is prepended to the signing content before creating the signature hash. In this commit, we add this feature, which requires a change in the API for signing content. The Sign API takes an externally created hasher object as an argument to sign. To ensure that the salt is hashed before the conten in v6 singatures, we introduce a PrepareSignature method that creates a hasher object with prepended salt.
This commit introduces support for direct-key signatures and ensures that version 6 keys store their properties in it. Instead of calling PrimaryIdentity to access a keys properties, one should now call PrimarySelfSignature to get the primary self-signature of a key.
This commit implements version 6 one-pass-signatures. Further, it updates the read/write API to support v6 signatures with salt and fingerprints.
This change removes armor checksums and removes checks accordingly.
All these constants should have the type SignatureType and not int.
The OpenPGP crypto refresh allows to encrypt secret keys with AEAD encryption. In this commit, we add AEAD secret key encryption and the addtional HKDF step in key derivation. The packet.Config contains a new field to configure the type of secret key encryption.
wussler
approved these changes
Dec 11, 2023
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Few remaining comments, then good to go for me 🚀
Co-authored-by: Aron Wussler <aron@wussler.it>
3531b43
to
38191b9
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This pull request includes the version 2 upgrade in a subfolder in openpgp and the v6 changes from #161.
See here for the v2 changes history.
Version 2 Update
This document summarizes the major changes for reading and writing OpenPGP message introduced by
ProtonMail/go-crypto/openpgp/v2
compared toProtonMail/go-crypto/openpgp
with the v6 update (#161.).Import
The v2 API can be imported as:
API breaking changes
openpgp.v2.Entity
struct fields have changed:SelfSignature *packet.Signature
removedSignatures []*packet.Signature
removedDirectSignatures []*packet.VerifiableSignature
addedRevocations []*packet.VerifiableSignature
changed typeopenpgp.v2.Entity
changed API methods:PrimaryIdentity(date time.Time)
has a time argument now.EncryptionKey(date time.Time, config *packet.Config)
has a new config argument.CertificationKey(date time.Time, config *packet.Config)
has a new config argument.CertificationKeyById(date time.Time, id uint64, config *packet.Config)
has a new config argument.SigningKey(date time.Time, config *packet.Config)
has a new config argument.SigningKeyById(date time.Time, id uint64, config *packet.Config)
has a new config argument.Revoke(reason packet.ReasonForRevocation, reasonText string, config *packet.Config)
changed name instead of RevokeKey.openpgp.v2.Entity
removed API methods:RevokeSubkey(...)
replaced by(Subkey).Revoke(...)
openpgp.v2.Subkey
struct fields have changed:Sig *packet.Signature
removedBindings []*packet.VerifiableSignature
addedPrimary *Entity
added, points to the primary key.Revocations []*packet.VerifiableSignature
changed typeopenpgp.v2.Subkey
changed API methods:Revoked(selfCertification *packet.Signature, date time.Time)
has a new selfCertification argument, which points to the self signature to be used.openpgp.v2.Identity
struct fields have changed:SelfSignature *packet.Signature
removedSignatures []*packet.Signature
removedSelfCertifications []*packet.VerifiableSignature
addedOtherCertifications []*packet.VerifiableSignature
addedPrimary *Entity
added, points to the primary key.Revocations []*packet.VerifiableSignature
changed typeopenpgp.v2.Identity
changed API methods:Revoked(selfCertification *packet.Signature, date time.Time)
has a new selfCertification argument, which points to the self signature to be used.openpgp.v2.Key
struct fields have changed:PrimarySelfSignature *packet.Signature
added, which points to the selected self signature of the primary key.Revocations []*packet.VerifiableSignature
changed typeopenpgp.v2.KeyRing
interface has has changed:KeysByIdUsage(...)
removedDecryptionKeys(...)
removedEntitiesById(id uint64) []*Entity
added. This is the main internal method to access keys from the keyring now.openpgp.v2.FileHints
struct field has changed:IsBinary
removed andIsUTF8
addedopenpgp.v2
API changes for reading messages:VerifyDetachedSignatureAndHash(...)
removed, headers in clearsigned messages are no longer checked.VerifyDetachedSignatureAndSaltedHash(...)
removedCheckDetachedSignature(...)
removed, callVerifyDetachedSignature(...)
insteadCheckDetachedSignatureAndSaltedHash(...)
removedCheckDetachedSignatureAndHash(...)
removedCheckArmoredDetachedSignature
removed callVerifyArmoredDetachedSignature
insteadopenpgp.v2
API changes for writing messages:DetachSign(..., signers []*Entity,...)
takes now a slice of entities instead of a single entity as an argument.ArmoredDetachSign(..., signers []*Entity,..., , params *SignParams)
takes now a slice of entities instead of a single entity as an argument and replaces arguments with a SignParams object.DetachSignText(..., signers []*Entity,...)
takes now a slice of entities instead of a single entity as an argument.ArmoredDetachSignText(..., signers []*Entity,...)
takes now a slice of entities instead of a single entity as an argument.EncryptText(...)
removed callEncryptWithParams(...)
insteadEncryptSplit(...)
removed callEncryptWithParams(...)
insteadEncryptTextSplit(...)
removed callEncryptWithParams(...)
insteadEncrypt(..., toHidden []*Entity, signers []*Entity)
now takes an additional toHidden recipients argument and takes now a slice of signer entities instead of a single entity as an argument.Sign(..., signers []*Entity,...)
takes now a slice of entities instead of a single entity as an argument.Features added
Intended recipients
Version 2 of the ProtonMail/go-crypto library introduces a feature for including the recipients' key fingerprints in signatures during message encryption.
When encrypting and signing a message, the intended recipients are automatically included in the signature, unless specifically hidden (i.e., hidden recipients).
During the decryption process, if the signature contains intended recipients and the appropriate configuration flag is set, the library verifies whether the primary ID of the decryption key is present in the recipient list.
This check can be disabled in the config when a hidden recipient decrypts the message.
Multi-signature support
In previous iterations of ProtonMail/go-crypto, only a single signature creation and verification were supported in a PGP message.
However, in Version 2, the library introduces the ability to sign messages with multiple signatures using different keys, such as a v4 and a v6 key.
The encryption and signing methods now accept multiple signing keys as arguments, with each key designated for a specific signature.
When reading PGP messages with Version 2, the library maintains an internal state for each known signature and verifies all of them within the message.
To facilitate this functionality, the message details struct includes a new field that stores the verification state for each signature. A message is considered valid if at least one of the signatures successfully validates without any errors.
For callers, the process of checking for signature errors remains similar to previous versions.
However, if the caller requires the verification state of all signatures, they can utilize the new field in the message details struct.
Rework how signatures in keys and signatures are verified
In previous iterations of ProtonMail/go-crypto, key verification occurred during import based on the current time, while signature verification did not involve further key checks.
However, this approach had limitations, as invalid keys could have been valid at the time of signature creation and mistakenly considered invalid.
Version 2 changes how and when signatures are verified in keys (i.e., direct-signatures, self-signatures of userids, binding signatures in subkeys, revocations, etc).
Unlike before, key signature verification no longer takes place during parsing.
Instead, keys are now validated when they are utilized, following a similar approach to key handling in OpenPGP.js.
Additionally, all signatures and expirations are validated to adhere to the key lifecycle outlined in the RFC.
The validity of keys can now be checked at different points in time, leading to the following specific modifications:
Further, version 2 includes various small improvements to increase the robustness of the key parsing functions.
Weak algorithm rejection
Version 2 introduces the option to specify weak algorithms for signatures in the config.
Signatures that use weak algorithms are considered invalid.
Optional packet sequence checker
Version 2 introduces a new feature that enables the validation of packet sequences in PGP messages.
This functionality can be enabled in the config struct.
In particular, it implements the pushdown automata (PDA) from PGPainless, developed by Paul Schaub.
By leveraging this feature, users can ensure that the packet sequences in their PGP messages are valid and comply with the required structure.
This addition further enhances the overall reliability and security of PGP message handling in Version 2.
Session key encryption and decryption
Version 2 allows advanced users to retrieve the session key while encrypting a message by setting the respective flag in the config.
In decryption, a caller can provide a session key that should be used for decryption.
Unify write/read API
Version 2 improves the compatibility between different APIs to allow combinations.
The
DetachSign
function requires the caller to provide aReader
for the message, whileencrypt returns a
WriteCloser
to which the message is written to.The new version adds a function
DetachSignWriter
, which returns aWriteCloser
similar to the encryption API.On the reading side, the verify detached signature API now relies on the
same signature verification logic as the other read functions.
Additionally, a new
VerifyDetachedSignatureReader
method similar to theReadMessage
API is introduced.It returns a message details struct that once read verifies the signature.
Allows to chain different readers from the API, for example, to have a streaming API for encrypted detached signatures.
Params struct as a function argument in the write API
With the inclusion of new features, the write functions in go-crypto experienced significant growth in numbers. Each combination has its dedicated function.
Version 2 introduces an
EncryptWithParams
/SignWithParams
function that takes anEncryptParams
/SignParams
struct as an argument. The struct allows configuring the different features.This approach effectively reduces the number of API methods and simplifies the process of adding new features while maintaining compatibility with previous versions.
Others
armor.Encode
methodunarmor
more robust to empty header valuesIdentity