[SEP-53] Sign and Verify Messages

[overcat]

In SEP-43, we added the sign message API, but did not describe how to implement it. I think we should add a separate SEP to describe how to implement this feature. Suggestions for modifications, discussions, and additions are welcome.

Preamble

SEP: <TBD>
Title: Sign and Verify Messages
Author: <TBD>
Track: Informational
Status: Draft
Created: 2025-02-01
Updated: 2025-02-01
Version: 0.0.1
Discussion: https://github.com/stellar/stellar-protocol/discussions/1641

Simple Summary

This SEP proposes a canonical method for signing and verifying arbitrary messages using Stellar key pairs. It aims to standardize message signing functionality across various Stellar wallets, libraries, and services, preventing ecosystem fragmentation and ensuring interoperability.

Abstract

Stellar uses ed25519 keys for transaction signatures by design, but there is currently no canonical specification for signing arbitrary messages outside the normal transaction flow. This proposal defines:

• A message format supporting user-supplied data in various encodings
• SHA-256 as the standard hashing function
• Standardized procedures for signing and verifying messages off-chain

By adopting this SEP, developers can seamlessly incorporate message signing capabilities for multi-lingual text or arbitrary binary data, enabling proof-of-ownership and authentication in off-chain scenarios such as social platform verification, cross-chain operations, and general data validation.

Motivation

Many blockchain ecosystems provide "Sign Message" capabilities for proving key ownership outside of normal transactions. While Stellar has the fundamental cryptographic primitives, there is no official, widely adopted protocol for signing arbitrary messages. Without standardization of how bytes are composed, hashed, and verified, different implementations risk incompatibility.

This functionality is particularly useful for:

• Proving control of a Stellar address on social platforms,
• Verifying off-chain agreements or terms
• Integrating with cross-chain or multi-chain dApps that require address proof

Specification

Prefix and Encodings

To prevent confusion with raw transactions and to mitigate replay attacks, a fixed prefix string is used: "Stellar Signed Message:\n",

The implementation MUST handle the user-provided message in the way it is supplied:

• If the message is provided as a string, it SHOULD be interpreted as UTF-8 text.
• If the message is provided as raw bytes, it SHOULD be processed as binary data.

A signed message can be any data, but human-readable text is generally recommended as it is easier for users to verify visually. Wallets and libraries MUST clearly display or otherwise confirm the content being signed, especially for complex or user-supplied data.

Message Format

The canonical signing payload is constructed by concatenating: <prefixBytes><message>.

Where:

• <prefixBytes>: Fixed UTF-8 encoded string "Stellar Signed Message:\n".
• <messageBytes>: The byte representation of the message. If the input was a string, it should be UTF-8 encoded. If the input was already bytes, no further conversion is needed.

Why "Stellar Signed Message:\n"

Bitcoin uses the prefix "Bitcoin Signed Message:\n" and Ethereum uses "Ethereum Signed Message:\n" for their respective message signing implementations. By adopting a similar format, Stellar's off-chain message signing maintains consistency with established approaches in other blockchains, making it easier for developers with multi-chain experience to understand and implement.

Hashing Algorithm

This proposal standardizes on single-round SHA-256 for hashing: messageHash = SHA256(encodedMessage). This approach is widely regarded as secure and efficient.

Signing Procedure

1. Convert the message to a byte array if it is a string, using UTF-8 encoding.
2. Serialize the prefix (bytes) and the user’s message (bytes) as described (prefix + message).
3. Compute messageHash = SHA256(encodedMessage).
4. Sign messageHash using the Stellar private key (ed25519). This yields a 64-byte signature.

Verification Procedure

1. Convert the message to a byte array if it is a string (same UTF-8 method used during signing).
2. Reconstruct the same canonical payload using the known prefix and the byte array message.
3. Compute messageHash = SHA256(encodedMessage).
4. Use the corresponding public key to verify the 64-byte ed25519 signature.
5. If the signature matches, verification is successful; otherwise, it fails.

Handling Multi-language and Binary Data

• Libraries SHOULD accept either a string or a byte array for the message.
• If a string is provided, libraries MUST use UTF-8 encoding internally to get the byte array.
• If binary data is provided, libraries MUST preserve the raw byte sequence (no extra encoding steps).
• Wallet UIs can choose how to display non-ASCII or non-printable data (e.g., by rendering hex or base64). They SHOULD clearly communicate the data format to the user.
• Visual verification for end users is critically important, we generally recommend using human-readable text (e.g., UTF-8–encoded strings) for most use cases.

Reference Implementation (Pseudo-Code)

function encodeMessage(message):
   prefix = "Stellar Signed Message:\n"
   # Convert message to bytes (if needed)
   if isString(message):
       messageBytes = utf8Encode(message)
   else:
       messageBytes = message
   return prefixBytes + messageBytes

function stellarSignMessage(privateKey, message):
   signedMessageBase = encodeMessage(message)
   messageHash = SHA256(encodedPayload)
   signature = ed25519_sign(privateKey, messageHash)
   return signature

function stellarVerifyMessage(publicKey, message, signature):
   signedMessageBase = encodeMessage(message)
   messageHash = SHA256(encodedPayload)
   return ed25519_verify(publicKey, messageHash, signature)

Test cases

1. Sign a simple ASCII message

• Message: Hello, World!
• Seed: SAKICEVQLYWGSOJS4WW7HZJWAHZVEEBS527LHK5V4MLJALYKICQCJXMW
• Address: GBXFXNDLV4LSWA4VB7YIL5GBD7BVNR22SGBTDKMO2SBZZHDXSKZYCP7L
• Signature (base64 encoded): fO5dbYhXUhBMhe6kId/cuVq/AfEnHRHEvsP8vXh03M1uLpi5e46yO2Q8rEBzu3feXQewcQE5GArp88u6ePK6BA==

2. Sign a Japanese message

• Message: こんにちは、世界！
• Seed: SAKICEVQLYWGSOJS4WW7HZJWAHZVEEBS527LHK5V4MLJALYKICQCJXMW
• Address: GBXFXNDLV4LSWA4VB7YIL5GBD7BVNR22SGBTDKMO2SBZZHDXSKZYCP7L
• Signature (base64 encoded): CDU265Xs8y3OWbB/56H9jPgUss5G9A0qFuTqH2zs2YDgTm+++dIfmAEceFqB7bhfN3am59lCtDXrCtwH2k1GBA==

3. Sign a binary message

• Message (base64 encoded): 2zZDP1sa1BVBfLP7TeeMk3sUbaxAkUhBhDiNdrksaFo=
• Seed: SAKICEVQLYWGSOJS4WW7HZJWAHZVEEBS527LHK5V4MLJALYKICQCJXMW
• Address: GBXFXNDLV4LSWA4VB7YIL5GBD7BVNR22SGBTDKMO2SBZZHDXSKZYCP7L
• Signature (base64 encoded): VA1+7hefNwv2NKScH6n+Sljj15kLAge+M2wE7fzFOf+L0MMbssA1mwfJZRyyrhBORQRle10X1Dxpx+UOI4EbDQ==

Limitations

• Ownership of a private key does not imply control of the account.
  Even though signatures prove that a signer controls a private key corresponding to a particular address, that does not necessarily mean they control the corresponding Stellar account. In multi-signer scenarios, possession of just one key may not grant full control over the account.

Backwards Compatibility

This is a new standard that does not conflict with existing SEPs, though it provides off-chain signature functionality distinct from transaction signing methods.

Acknowledgments

• Inspired by message signing patterns in Bitcoin, Ethereum, etc.

References

• https://github.com/bitcoin/bips/blob/master/bip-0137.mediawiki

[overcat]

A Python Implementation

Open

import base64

from stellar_sdk import Keypair
from stellar_sdk.exceptions import BadSignatureError
from stellar_sdk.utils import sha256


def encode_message(message: str | bytes):
    prefix = b"Stellar Signed Message:\n"
    if isinstance(message, str):
        message = message.encode('utf-8')
    return prefix + message


def sign_message(message: str | bytes, secret: str) -> bytes:
    kp = Keypair.from_secret(secret)
    signed_message_base = encode_message(message)
    message_hash = sha256(signed_message_base)
    return kp.sign(message_hash)


def verify_message(message: str | bytes, signature: bytes, public_key: str):
    kp = Keypair.from_public_key(public_key)
    signed_message_base = encode_message(message)
    message_hash = sha256(signed_message_base)
    return kp.verify(message_hash, signature)


if __name__ == '__main__':
    kp = Keypair.from_secret("SAKICEVQLYWGSOJS4WW7HZJWAHZVEEBS527LHK5V4MLJALYKICQCJXMW")
    message = "Hello, World!"
    signature = sign_message(message, kp.secret)
    print(f"Signature: {base64.b64encode(signature)}")
    try:
        verify_message(message, signature, kp.public_key)
        print("Signature is valid")
    except BadSignatureError:
        print("Bad Signature")

[tupui]

Very nice 👍 some thoughts (not necessarily in order, as they come 😅)

I would add some text saying why we would add into the message the byte lengths.

On the attack side we could elaborate a bit. You mention replay, but here to me it's not clear how the design mitigates it. I suppose this can be achieved with passing a random value as part of the message itself from the client asking for authentication.

In general for the UX, I think we should push to ask that a special representation of these messages is made. Right now, some dApp show a modal explaining why they have to sign a transaction to authenticate, but I think that this should be done by the wallet. A bit like a oauth2 flow where you have the modal telling you what you are connecting to and what that means.

Going a bit further in that direction, I would add the concept of scopes in the message. This way, wallets can show a clear authentication pop up with clear information about scoping (of course there is no pre authorization on these scopes with a normal address, but passkey wallets and other smart wallets can have policy signing as @kalepail demonstrated.)

[overcat]

Hi @tupui, thanks for your feedback.

I would add some text saying why we would add into the message the byte lengths.

By including the message length, it defines clear data boundaries for reliable parsing and enables flexible handling of variable-length messages.

On the attack side we could elaborate a bit. You mention replay, but here to me it's not clear how the design mitigates it. I suppose this can be achieved with passing a random value as part of the message itself from the client asking for authentication.

I have made these concepts a bit confusing, and I have removed it.

For two different blockchain systems A and B that use the same signature algorithm, a signature generated for a message in system A will also be valid in system B. An additional header can ensure that different signatures are produced.

However, I currently have no intention of adding a nonce, as it increases complexity; if needed, developers can add it to the message body.

In general for the UX, I think we should push to ask that a special representation of these messages is made. Right now, some dApp show a modal explaining why they have to sign a transaction to authenticate, but I think that this should be done by the wallet. A bit like a oauth2 flow where you have the modal telling you what you are connecting to and what that means.

This should be specified in the sign message API of SEP-43.

Going a bit further in that direction, I would add the concept of scopes in the message. This way, wallets can show a clear authentication pop up with clear information about scoping (of course there is no pre authorization on these scopes with a normal address, but passkey wallets and other smart wallets can have policy signing as @kalepail demonstrated.)

Could you provide the address of the demo? I'm not quite sure which one you're referring to.

[tupui]

I think that was this do_math demo https://github.com/kalepail/do-math/blob/main/contracts/do-math-policy/src/lib.rs with policies.

[overcat]

For messageLength, Bitcoin and Ethereum use different algorithms: Bitcoin uses a VarInt, while Ethereum uses a decimal number in string form. For example:

Bitcoin format:
\x18Bitcoin Signed Message:\n\x0bHello World

Ethereum format:
\x19Ethereum Signed Message:\n11Hello World

These two methods are rarely used in Stellar, and I’m not sure which one people prefer. Directly using a fixed-length int encoding might be simpler.

[tomerweller]

For Binary data, is it worth suggesting a specific encoding? One of the things I dislike the most about ETH blob signing is how opaque it is. For example, we could mandate that the binary format is an ScVal which is a polymorphic type that, hopefully, wallets are already capable of rendering

[orbitlens]

What is the issue with the opaque data?
Usually both signing and verifying parties know the format of expected binary data in advance. They can agree to use ScVal, ProtoBuf, Utf8, Bson, or whatever format they like. Any service that is going to display or validate the signature, will know in advance how the signed payload is encoded and how to parse it.

To my mind, additional restrictions to use some specific binary encoding format (e.g. ScVal) unnecessary complicates the SEP.

[tomerweller]

Usually both signing and verifying parties know the format of expected binary data in advance.

I'm not sure if that's true. Many times I found myself signing opaque blobs in Metamask wishing the wallet would actually render it in a meaningful way.

Not super religious about it and I agree that it complicates the SEP. Maybe a good solution is just to encourage messages to be strings, which are trivially renderable.

[overcat]

Not super religious about it and I agree that it complicates the SEP. Maybe a good solution is just to encourage messages to be strings, which are trivially renderable.

Maybe we can add this to the SEP: A signed message can be any data, but it is generally recommended to use human-readable text, as this is easier for a user to verify visually.

[orbitlens]

Client apps can try to parse the binary payload as ScVal by default. If the parsing fails, they should display it as Utf8 string or base64-encoded string. @tomerweller will it solve the problem?

[tomerweller]

Yeah @orbitlens I think that achieves the same goal and TBH I'm fairly un-opinionated about doing that vs. leigh's more explicit approach above. @leighmcculloch wdyt?

[leighmcculloch]

This functionality is particularly useful for:

• Proving control of a Stellar address on social platforms,
• Verifying off-chain agreements or terms,
• Integrating with cross-chain or multi-chain dApps that require address proof.

Something that's challenging for all these use cases is that it only proves control of a key, not of an address, unless the off-chain system has an intimate understanding of what it means for that key's signature in the context of an address. That's a similar challenge faced by SEP-10 and SEP-45 which is why those SEPs are focused on how to validate the account, not only the key.

Something that was helpful in some past proposals was to go into more detail on the use cases. I think it would be helpful add a section for each use case with an example of how it will be used for that case, and discuss the limitations as well. The limitations might be fine, this doesn't have to support all types of accounts necessarily if not all accounts will use it.

[overcat]

Hi @leighmcculloch, I noticed you mentioned "it only proves control of a key, not of an address" - shouldn't this be "proves control of a key, not of an account"? Since signers are configured at the account level rather than the address level.

[leighmcculloch]

👍🏻 Yes to say an account would be more accurate. Same as to what @earrietadev pointed out: #1641 (comment).

Any system that uses only this proposal without any additional checks won't be confirming that an account is owned by the participant, unless they take other steps such as what SEP-10 and SEP-45 outline. So any system that naively assumes proof of a key is proof of a account will be vulnerable to being fooled.

Proving holding of a key is still valuable imo, but folks need to be careful to select the appropriate approach given the needs.

[orbitlens]

Very well written SEP 👍
We have a very similar implementation in Albedo since 2019.
Two key differences:

• We do not support binary data (not a problem, can be added relatively easily)
• The prefix is an StrKey-encoded public key of the keypair used to sign the message (we cannot adopt the new standard without breaking existing integrations)

function signMessage(message, keypair) {
  const publicKey = keypair.publicKey()
  const signedMessage = keypair.publicKey()+':'+message //protection from spoofing
  const messageHash = sha256(signedMessage)
  const signature = keypair.sign(messageHash).toString('hex')
  return {publicKey, signature, signedMessage}
}

During a conversation with the community long, long time ago (on public Stellar Slack) people voted for this prefix format (I originally also proposed a static string prefix). There were some arguments in favor of using a deterministic variable prefix (hence the pubkey) for security reasons, but I'm not a cryptography expert myself.

Can we utilize our format (StrKey-encoded public key + message) to prevent breaking existing integrations?

[overcat]

This version does not include the message length in the signedMessage. In both Bitcoin and Ethereum, the length of the message is included. I spent a lot of time researching why they do this. Many explanations online say it is to prevent length extension attacks, but I can't conceive how it could cause harm in the context of signing messages. Another explanation is that it serves as part of the salt, but I'm not sure if this really improves security.

I'm eager to hear thoughts from other community members on this topic! Please feel free to share your knowledge and insights.

[orbitlens]

@piyalbasu Could you please comment on this one?

[piyalbasu]

My gut reaction is that a deterministic variable would serve as a better "salt" here if the aim is security.

I'd generally be in favor of leaving out message length and opting for simplicity if we don't have a great reason for the value it brings (other than it's what btc and eth do).

But let me continue looking into this with the security team here and see if I can figure out what message length actually does

[piyalbasu]

I spoke with the security team here and here are their thoughts on length extension attacks:

What is a Length Extension Attack
A length extension attack is an attack against a messaging protocol that protects the message with a key with this type of construction:

auth_code = vulnerable_hash(k.append(M))

Here the auth_code is a hash of the concatenation of some secret k and the message M. The issue is when the hash is calculated, chunks of the string are repeatedly taken and plugged into the hashing algorithm (effectively concatenated with the previous "chunk" hash and hashed again). In vulnerable hashing algorithms, the resulting hash represents the complete state of the hashing algorithm at that time. This means that an attacker can append their own "chunks" onto the end of the previous hash to make a new valid auth_code. Importantly, the secret is only applied once in a fashion where it is agnostic of the message it is intended to protect. It is, consequently, also important to note that the messaging scheme suggested here does not follow this construction method.

Put more succinctly:
Length-extension attacks only allow you to take a valid H(k || m) and produce a valid H(k || m || padding || extra) hash that will validate, even if you don’t know k. They don’t magically create collisions out of thin air.

Do They Matter Here?
It is important to note that the proposed approach uses an ED25519 signature scheme to sign the hash. Again, the above linked article does a good job differentiating this from the vulnerable approach discussed above:
Digital signature algorithms–such as RSASSA, ECDSA, and EdDSA–take a cryptographic hash of a message and then perform some asymmetric cryptographic transformation of the hash with the secret key to produce a signature that can be verified with a public key. (The exact details are particular to the signature algorithm in question.)
The security of digital signature algorithms depends entirely on the secrecy of the signing key and the security of the asymmetric cryptographic transformation used to generate a signature.

Final Thoughts
Based on the above analysis, I would suggest that including the length here does nothing to forestall length extension attacks, since those are not effective here anyway. However, I would also suggest that the addition of the length doesn't hurt anything and may be beneficial in some other situations where a preliminary check of the length may identify any issues with the message quickly.

[piyalbasu]

Given that information, I'm still leaning towards not including the message length to keep the spec simpler and more straightforward

[earrietadev]

I started implementing messages signing in xBull during the weekend and I was following the approach from Albedo because that way it will be compatible with everything that already uses it... and being honest I like the idea of including the public key because that way the wallet knows what account needs to use to sign the message (SEP-43 optional address parameter now serves that purpose but I still like the idea of including the public key on the message).

Now, that being said... I believe SEP-10 serves better for everything related to account authentication because by just signing a message it doesn't directly validate the ownership of that stellar account (enough signature weight) which SEP-10 takes care of.

But being compatible (or at least similar) to what other chains use is also a good argument because it makes it easy for multi chain projects to adopt stellar. So I will pause the implementation on xBull for a couple of days while I see the evolution of this conversation.

[overcat]

If I understand correctly, this address header cannot achieve that purpose here. Generally speaking, the DApp should send a separated address and message to the wallet; the DApp does not care about the details of the signed message body

[piyalbasu]

In general, this proposal is looking good to me (other than my open question about message and prefix length). I also tend to agree it'd be best to try to urge devs to use 1 of a few specific encodings (but mostly text) as it would be nice to make displaying the message in a wallet UI a little more straightforward.

We've had a few devs in Discord who use signing/verifying to authenticate reach out to the Freighter team recently. I'll encourage them to take a look at this so we can get some participation from some others actively using this workflow

[MonsieurNicolas]

As you're asking people to use their PK, you also need to ensure proper domain separation with other blobs signed in the ecosystem. If you look at what is done for transactions, you'll also need the network ID in the prefix for example.

[leighmcculloch]

The other thing we need to ensure is that the message as a whole can't be a valid Stellar transaction. In Ethereum the \x19 first byte actually ensures that the message is not a valid Ethereum transaction (ref). If the first 32 bytes was the Stellar network ID, then the message format shifts to be more like a Stellar transaction, so we just need to make sure through other ways such as by prefixing something else first.

[orbitlens]

In order to be exploitable, a user's public key should be exactly equal to hash("Public Global Stellar Network ; September 2015"), which is the prefix of any signable tx payload. Chances of that are extremely low.

Even with some kind of a vanity keypair generator it's quite challenging. For example, it took me half a day to generate GALAXYVOIDAOPZTDLHILAJQKCVVFMD4IKLXLSZV5YHO7VY74IWZILUTO keypair on 8 cores, though GALAXYVOID is quite a short prefix. And then an attacker will have to trick a user to create an account using this keypair (which by itself already means that the secret key is compromised).

[piyalbasu]

@overcat This conversation has died down a bit. Would you mind outlining the outstanding questions that we need to agree on before moving forward with the proposal? This is a really useful SEP and I'd love to get this spec finalized

[overcat]

The main point of contention right now lies in the format of the message body. Currently, there are two proposals:

1. <stellarKey>:<message> (ex. GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF:Hello, world!)
2. Stellar Signed Message:\n<message> (ex. Stellar Signed Message:\nHello, world!)

For option 2, based on the discussion here, we've decided not to include a messageLength field. If it becomes necessary in the future, we can update this SEP accordingly.

The Albedo wallet currently uses option 1, so choosing option 1 would maintain compatibility with it.

We'd like to know which option everyone prefers. If you prefer option 1, please click ❤️. If you prefer option 2, please click 🚀. If you have other suggestions, please leave a comment. Thank you!

[orbitlens]

We had a few brainstorming sessions internally, and I think we have a solution. We can update our implementation to generate signatures in both formats (1 and 2) as soon as response parameter names are not colliding. Currently, Albedo returns signature result in the format {"signed_message":"...", "message_signature": "..."}. SEP43 draft proposes to return the result in the signedMessage response field. So we can combine these two response and return something like

{
  "signedMessageBase": "Stellar Signed Message:\nHello, world!",
  "signedMessage": "<signature_option2>"
  "signed_message": "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF:Hello, world!",
  "message_signature": "<signature_option1>"
}

This will retain the compatibility for existing Albedo integrations and will allow us to adopt the new signature format as well.

Also, I personally think the result filed name proposed in the SEP43 is a bit misleading. The field name containing signature should be "signature" or "messageSignature" instead of "signedMessage".

[piyalbasu]

This is a good callout. We can update signedMessage to messageSignature in SEP-43

[overcat]

Hello everyone, I've created a document and would like to invite you all to review it before I officially submit a PR. The document is open for editing, so if you have any suggestions, please feel free to make changes directly or add your comments. Thank you!

[tupui]

Thanks for the great draft 👏 I left some suggestions.

[overcat]

Hi, based on this discussion, I’ve created a PR to add this SEP, which you can view here.

Additionally, I’ve included everyone who participated in this discussion group in the list of authors. If you’d like me to remove your name from the list, please let me know. Thank you!

[merkle-maren]

Where does this proposal stand?

I'm porting an application from Ethereum and need Stellar's equivalent of Ethereum Signed Messages. The discussion at #1641 mentions two approaches, but SEP-0053 only reflects Option 2. Did this reach consensus, or is it still open?

Also: are there active projects supporting message signing and verification beyond Albedo?

One constraint worth noting for anyone else porting from EVM: Stellar's ed25519 has no signature recovery function — that's secp256k1 territory (Ethereum, Bitcoin). You have to pass the public key to the verifier explicitly. It doesn't need to be embedded in the signed message itself (passing it alongside works), but you do need to account for it in your verification flow.

[overcat]

ok +1

[leighmcculloch]

When considering Active vs Final, the distinction is really is it mutable or immutable. It's worth considering how easy it will be to evolve the SEP if you want to change it, in terms of coordination. For something like a message signing process that is small, simple, and changes would likely make it incompatible, i.e. new, it will be well suited to being immutable, and any change being a new message signing SEP. So I'd lean and definitely consider Final. But that's just my input, it's up for you folks.

[tupui]

Fair point 👍 I will wait a bit and make the PR.

[merkle-maren]

I implemented the SEP in my Rust code and it works well.

I have no opinion on "Active" or "Final", but moving out of "Draft" would signal the community agreement that clearly exists.

[tupui]

I created the PR now #1922 PTAL. Proposing "Final Comment Period (Final)" for the whole month of Mai.

[tupui]

We just entered the Final Comment Period (Final). I will make a PR to either get the SEP back to draft of promote it to Final on June 15th.

[tupui]

I created #1963 to promote from Final Comment Period (Final) to Final.