pw_crypto

Oveview

Main docs: https://pigweed.dev/pw_crypto.

Classes
class	pw::crypto::sha256::Sha256

Enumerations
enum class	pw::crypto::sha256::Sha256State { Sha256State::kReady = 1 , Sha256State::kFinalized = 2 , Sha256State::kError = 3 }
	A state machine of a hashing session. More...

Functions
Status	pw::crypto::ecdsa::VerifyP256Signature (ConstByteSpan public_key, ConstByteSpan digest, ConstByteSpan signature)
Status	pw::crypto::sha256::backend::DoInit (NativeSha256Context &ctx)
Status	pw::crypto::sha256::backend::DoUpdate (NativeSha256Context &ctx, ConstByteSpan data)
Status	pw::crypto::sha256::backend::DoFinal (NativeSha256Context &ctx, ByteSpan out_digest)
Sha256 &	pw::crypto::sha256::Sha256::Update (ConstByteSpan data)
Status	pw::crypto::sha256::Sha256::Final (ByteSpan out_digest)
Status	pw::crypto::sha256::Hash (ConstByteSpan message, ByteSpan out_digest)
Status	pw::crypto::sha256::Hash (stream::Reader &reader, ByteSpan out_digest)

Variables
constexpr uint32_t	pw::crypto::sha256::kDigestSizeBytes = 32
	The size of a SHA256 digest in bytes.

Enumeration Type Documentation

Sha256State

enum class pw::crypto::sha256::Sha256State

strong

A state machine of a hashing session.

Enumerator
kReady	Initialized and accepting input (via Update()).
kFinalized	Finalized by Final(). Any additional requests to Update() or Final() will trigger a transition to kError.
kError	In an unrecoverable error state.

Function Documentation

Final()

Status pw::crypto::sha256::Sha256::Final ( ByteSpan  out_digest )

inline

Finishes the hashing session and outputs the final digest in the first kDigestSizeBytes of out_digest. out_digest must be at least kDigestSizeBytes long.

Final() locks down the Sha256 instance from any additional use.

Any error, including those occurring inside the constructor or Update() will be reflected in the return value of Final().

Hash()

Status pw::crypto::sha256::Hash ( ConstByteSpan  message, ByteSpan  out_digest  )

inline

Calculates the SHA256 digest of message and stores the result in out_digest. out_digest must be at least kDigestSizeBytes long.

One-shot digest example:

#include "pw_crypto/sha256.h"
 
std::byte digest[32];
if (!pw::crypto::sha256::Hash(message, digest).ok()) {
    // Handle errors.
}
 
// The content can also come from a pw::stream::Reader.
if (!pw::crypto::sha256::Hash(reader, digest).ok()) {
    // Handle errors.
}

Long, potentially non-contiguous message example:

#include "pw_crypto/sha256.h"
 
std::byte digest[32];
 
if (!pw::crypto::sha256::Sha256()
    .Update(chunk1).Update(chunk2).Update(chunk...)
    .Final().ok()) {
    // Handle errors.
}

Update()

Sha256 & pw::crypto::sha256::Sha256::Update ( ConstByteSpan  data )

inline

Feeds data to the running hasher. The feeding can involve zero or more Update() calls and the order matters.

VerifyP256Signature()

Status pw::crypto::ecdsa::VerifyP256Signature	(	ConstByteSpan	public_key,
		ConstByteSpan	digest,
		ConstByteSpan	signature
	)

Verifies the signature of digest using public_key.

Example:

#include "pw_crypto/sha256.h"
 
// Verify a digital signature signed with ECDSA over the NIST P256 curve.
std::byte digest[32];
if (!pw::crypto::sha256::Hash(message, digest).ok()) {
    // handle errors.
}
 
if (!pw::crypto::ecdsa::VerifyP256Signature(public_key, digest,
                                            signature).ok()) {
    // handle errors.
}

Parameters

[in]	public_key	A byte string in SEC 1 uncompressed form (0x04||X||Y), which is exactly 65 bytes. Compressed forms (02/03||X) may not be supported by some backends, e.g. Mbed TLS.
[in]	digest	A raw byte string, truncated to 32 bytes.
[in]	signature	A raw byte string (r||s) of exactly 64 bytes.

Returns

embed:rst:inline :c:enumerator:`OK` 

for a successful verification, or an error Status otherwise.