Commit c2274243 authored by Michael Hamburg's avatar Michael Hamburg

make doc now mostly works

parent 7527e91a
......@@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8
# title of most generated pages and in a few other places.
# The default value is: My Project.
PROJECT_NAME = "Ed448-Goldilocks"
PROJECT_NAME = "libdecaf"
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
......@@ -751,7 +751,7 @@ WARN_LOGFILE =
# spaces.
# Note: If this tag is empty the current directory is searched.
INPUT = build/include
INPUT = src/GENERATED/include src/GENERATED/include/decaf
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
......
......@@ -17,6 +17,8 @@ BUILD_INC = src/GENERATED/include
BUILD_BIN = build/bin
BUILD_IBIN = build/obj/bin
DOXYGEN ?= doxygen
ifeq ($(UNAME),Darwin)
CC = clang
CXX = clang++
......@@ -300,8 +302,8 @@ $(BUILD_DOC)/timestamp:
mkdir -p `dirname $@`
touch $@
#
doc: Doxyfile $(BUILD_OBJ)/timestamp $(HEADERS)
doxygen > /dev/null
doc: Doxyfile $(BUILD_OBJ)/timestamp gen_code_static
$(DOXYGEN) > /dev/null
gen_code_static: $(GEN_CODE)
gen_code: gen_code_static $(GEN_CODE_P2)
......
......@@ -38,12 +38,6 @@ const uint8_t NO_CONTEXT_POINTS_HERE = 0;
const uint8_t * const DECAF_ED25519_NO_CONTEXT = &NO_CONTEXT_POINTS_HERE;
#endif
/* EDDSA_BASE_POINT_RATIO = 1 or 2
* Because EdDSA25519 is not on E_d but on the isogenous E_sigma_d,
* its base point is twice ours.
*/
#define EDDSA_BASE_POINT_RATIO (1+EDDSA_USE_SIGMA_ISOGENY) /* TODO: remove */
static void clamp (
uint8_t secret_scalar_ser[DECAF_EDDSA_25519_PRIVATE_BYTES]
) {
......
......@@ -38,12 +38,6 @@ const uint8_t NO_CONTEXT_POINTS_HERE = 0;
const uint8_t * const DECAF_ED448_NO_CONTEXT = &NO_CONTEXT_POINTS_HERE;
#endif
/* EDDSA_BASE_POINT_RATIO = 1 or 2
* Because EdDSA25519 is not on E_d but on the isogenous E_sigma_d,
* its base point is twice ours.
*/
#define EDDSA_BASE_POINT_RATIO (1+EDDSA_USE_SIGMA_ISOGENY) /* TODO: remove */
static void clamp (
uint8_t secret_scalar_ser[DECAF_EDDSA_448_PRIVATE_BYTES]
) {
......
......@@ -18,7 +18,9 @@
#include <decaf/point_255.hxx>
#include <decaf/point_448.hxx>
/** Namespace for all C++ decaf objects. */
namespace decaf {
/** Given a template with a "run" function, run it for all curves */
template <template<typename Group> class Run>
void run_for_all_curves() {
Run<Ristretto>::run();
......
......@@ -21,8 +21,9 @@ extern "C" {
/* Goldilocks' build flags default to hidden and stripping executables. */
/** @cond internal */
#if defined(DOXYGEN) && !defined(__attribute__)
#define __attribute__((x))
#if DOXYGEN || defined(__attribute__)
#define __attribute__(x)
#define NOINLINE
#endif
#define DECAF_API_VIS __attribute__((visibility("default")))
#define DECAF_NOINLINE __attribute__((noinline))
......
......@@ -36,10 +36,17 @@ extern "C" {
#define DECAF_EDDSA_25519_SUPPORTS_CONTEXTLESS_SIGS 1
extern const uint8_t * const DECAF_ED25519_NO_CONTEXT DECAF_API_VIS;
/** Prehash context renaming macros. */
/** Prehash context (raw), because each EdDSA instance has a different prehash. */
#define decaf_ed25519_prehash_ctx_s decaf_sha512_ctx_s
/** Prehash context, array[1] form. */
#define decaf_ed25519_prehash_ctx_t decaf_sha512_ctx_t
/** Prehash update. */
#define decaf_ed25519_prehash_update decaf_sha512_update
/** Prehash destroy. */
#define decaf_ed25519_prehash_destroy decaf_sha512_destroy
/** EdDSA encoding ratio. */
......
......@@ -14,7 +14,6 @@
#ifndef __DECAF_ED255_HXX__
#define __DECAF_ED255_HXX__ 1
/*
* Example Decaf cyrpto routines, C++ wrapper.
* @warning These are merely examples, though they ought to be secure. But real
......@@ -38,6 +37,7 @@
#endif
/** @endcond */
/** Namespace for all libdecaf C++ objects. */
namespace decaf {
/** A public key for crypto over some Group */
......@@ -55,7 +55,14 @@ typedef class PrivateKeyBase PrivateKey, PrivateKeyPure, PrivateKeyPh;
typedef class PublicKeyBase PublicKey, PublicKeyPure, PublicKeyPh;
/** @endcond */
/**
* Signatures support a "context" block, which allows you to domain separate them if
* (for some reason) it's annoying to domain separate the message itself. The default
* is no context. For Ed25519, the spec defining contexts is an extension, and the
* default is not to use that extension. This makes "no context" different from
* the empty string. For Ed448, contexts are built-in and mandatory, so "no context"
* is the same as the empty string.
*/
#if DECAF_EDDSA_25519_SUPPORTS_CONTEXTLESS_SIGS
static inline const Block NO_CONTEXT() { return Block(DECAF_ED25519_NO_CONTEXT,0); }
#else
......@@ -65,6 +72,7 @@ static inline const Block NO_CONTEXT() { return Block(NULL,0); }
/** Prehash context for EdDSA. */
class Prehash : public SHA512 {
private:
/** @cond internal */
typedef SHA512 Super;
SecureBuffer context_;
template<class T, Prehashed Ph> friend class Signing;
......@@ -79,6 +87,7 @@ private:
decaf_ed25519_prehash_init((decaf_sha512_ctx_s *)wrapped);
}
/** @endcond */
public:
/** Number of output bytes in prehash */
......@@ -108,35 +117,10 @@ public:
}
};
/** Signing (i.e. private) key class template */
template<class CRTP, Prehashed ph> class Signing;
template<class CRTP> class Signing<CRTP,PREHASHED> {
public:
/* Sign a prehash context, and reset the context */
inline SecureBuffer sign_prehashed ( const Prehash &ph ) const /*throw(std::bad_alloc)*/ {
SecureBuffer out(CRTP::SIG_BYTES);
decaf_ed25519_sign_prehash (
out.data(),
((const CRTP*)this)->priv_.data(),
((const CRTP*)this)->pub_.data(),
(const decaf_ed25519_prehash_ctx_s*)ph.wrapped,
ph.context_.data(),
ph.context_.size()
);
return out;
}
/* Sign a message using the prehasher */
inline SecureBuffer sign_with_prehash (
const Block &message,
const Block &context = NO_CONTEXT()
) const /*throw(LengthException,CryptoException)*/ {
Prehash ph(context);
ph += message;
return sign_prehashed(ph);
}
};
/** Signing (i.e. private) key class, PureEdDSA version */
template<class CRTP> class Signing<CRTP,PURE> {
public:
/**
......@@ -169,12 +153,42 @@ public:
}
};
/** Signing (i.e. private) key class, prehashed version */
template<class CRTP> class Signing<CRTP,PREHASHED> {
public:
/** Sign a prehash context, and reset the context */
inline SecureBuffer sign_prehashed ( const Prehash &ph ) const /*throw(std::bad_alloc)*/ {
SecureBuffer out(CRTP::SIG_BYTES);
decaf_ed25519_sign_prehash (
out.data(),
((const CRTP*)this)->priv_.data(),
((const CRTP*)this)->pub_.data(),
(const decaf_ed25519_prehash_ctx_s*)ph.wrapped,
ph.context_.data(),
ph.context_.size()
);
return out;
}
/** Sign a message using the prehasher */
inline SecureBuffer sign_with_prehash (
const Block &message,
const Block &context = NO_CONTEXT()
) const /*throw(LengthException,CryptoException)*/ {
Prehash ph(context);
ph += message;
return sign_prehashed(ph);
}
};
/** Signing (i.e. private) key base class */
class PrivateKeyBase
: public Serializable<PrivateKeyBase>
, public Signing<PrivateKeyBase,PURE>
, public Signing<PrivateKeyBase,PREHASHED> {
public:
typedef class PublicKeyBase MyPublicKey;
/** Type of public key corresponding to this private key */
typedef class PublicKeyBase PublicKey;
private:
/** @cond internal */
friend class PublicKeyBase;
......@@ -243,14 +257,13 @@ public:
}
/** Return the corresponding public key */
inline MyPublicKey pub() const DECAF_NOEXCEPT {
MyPublicKey pub(*this);
inline PublicKey pub() const DECAF_NOEXCEPT {
PublicKey pub(*this);
return pub;
}
}; /* class PrivateKey */
/** Verification (i.e. public) EdDSA key, PureEdDSA version. */
template<class CRTP> class Verification<CRTP,PURE> {
public:
/** Verify a signature, returning DECAF_FAILURE if verification fails */
......@@ -296,10 +309,10 @@ public:
}
};
/** Verification (i.e. public) EdDSA key, prehashed version. */
template<class CRTP> class Verification<CRTP,PREHASHED> {
public:
/* Verify a prehash context. */
/** Verify that a signature is valid for a given prehashed message, given the context. */
inline decaf_error_t DECAF_WARN_UNUSED verify_prehashed_noexcept (
const FixedBlock<DECAF_EDDSA_25519_SIGNATURE_BYTES> &sig,
const Prehash &ph
......@@ -312,8 +325,8 @@ public:
ph.context_.size()
);
}
/* Verify a prehash context. */
/** Verify that a signature is valid for a given prehashed message, given the context. */
inline void verify_prehashed (
const FixedBlock<DECAF_EDDSA_25519_SIGNATURE_BYTES> &sig,
const Prehash &ph
......@@ -329,7 +342,7 @@ public:
}
}
/* Verify a message using the prehasher */
/** Hash and verify a message, using the prehashed verification mode. */
inline void verify_with_prehash (
const FixedBlock<DECAF_EDDSA_25519_SIGNATURE_BYTES> &sig,
const Block &message,
......@@ -341,24 +354,25 @@ public:
}
};
/** EdDSA Public key base class. */
class PublicKeyBase
: public Serializable<PublicKeyBase>
, public Verification<PublicKeyBase,PURE>
, public Verification<PublicKeyBase,PREHASHED> {
public:
typedef class PrivateKeyBase MyPrivateKey;
/** Private key corresponding to this type of public key */
typedef class PrivateKeyBase PrivateKey;
private:
/** @cond internal */
friend class PrivateKeyBase;
friend class Verification<PublicKey,PURE>;
friend class Verification<PublicKey,PREHASHED>;
/** @endcond */
private:
/** The pre-expansion form of the signature */
FixedArrayBuffer<DECAF_EDDSA_25519_PUBLIC_BYTES> pub_;
/** @endcond */
public:
/* PERF FUTURE: Pre-cached decoding? Precomputed table?? */
......@@ -372,7 +386,6 @@ public:
/** Serialization size. */
static const size_t SER_BYTES = DECAF_EDDSA_25519_PRIVATE_BYTES;
/** Create but don't initialize */
inline explicit PublicKeyBase(const NOINIT&) DECAF_NOEXCEPT : pub_((NOINIT())) { }
......@@ -383,7 +396,7 @@ public:
inline PublicKeyBase(const PublicKeyBase &k) DECAF_NOEXCEPT { *this = k; }
/** Copy constructor */
inline explicit PublicKeyBase(const MyPrivateKey &k) DECAF_NOEXCEPT { *this = k; }
inline explicit PublicKeyBase(const PrivateKey &k) DECAF_NOEXCEPT { *this = k; }
/** Assignment from string */
inline PublicKey &operator=(const FixedBlock<SER_BYTES> &b) DECAF_NOEXCEPT {
......@@ -397,7 +410,7 @@ public:
}
/** Assignment from private key */
inline PublicKey &operator=(const MyPrivateKey &p) DECAF_NOEXCEPT {
inline PublicKey &operator=(const PrivateKey &p) DECAF_NOEXCEPT {
return *this = p.pub_;
}
......
......@@ -35,10 +35,17 @@ extern "C" {
/** Does EdDSA support non-contextual signatures? */
#define DECAF_EDDSA_448_SUPPORTS_CONTEXTLESS_SIGS 0
/** Prehash context renaming macros. */
/** Prehash context (raw), because each EdDSA instance has a different prehash. */
#define decaf_ed448_prehash_ctx_s decaf_shake256_ctx_s
/** Prehash context, array[1] form. */
#define decaf_ed448_prehash_ctx_t decaf_shake256_ctx_t
/** Prehash update. */
#define decaf_ed448_prehash_update decaf_shake256_update
/** Prehash destroy. */
#define decaf_ed448_prehash_destroy decaf_shake256_destroy
/** EdDSA encoding ratio. */
......
......@@ -14,7 +14,6 @@
#ifndef __DECAF_ED448_HXX__
#define __DECAF_ED448_HXX__ 1
/*
* Example Decaf cyrpto routines, C++ wrapper.
* @warning These are merely examples, though they ought to be secure. But real
......@@ -38,6 +37,7 @@
#endif
/** @endcond */
/** Namespace for all libdecaf C++ objects. */
namespace decaf {
/** A public key for crypto over some Group */
......@@ -55,7 +55,14 @@ typedef class PrivateKeyBase PrivateKey, PrivateKeyPure, PrivateKeyPh;
typedef class PublicKeyBase PublicKey, PublicKeyPure, PublicKeyPh;
/** @endcond */
/**
* Signatures support a "context" block, which allows you to domain separate them if
* (for some reason) it's annoying to domain separate the message itself. The default
* is no context. For Ed25519, the spec defining contexts is an extension, and the
* default is not to use that extension. This makes "no context" different from
* the empty string. For Ed448, contexts are built-in and mandatory, so "no context"
* is the same as the empty string.
*/
#if DECAF_EDDSA_448_SUPPORTS_CONTEXTLESS_SIGS
static inline const Block NO_CONTEXT() { return Block(DECAF_ED448_NO_CONTEXT,0); }
#else
......@@ -65,6 +72,7 @@ static inline const Block NO_CONTEXT() { return Block(NULL,0); }
/** Prehash context for EdDSA. */
class Prehash : public SHAKE<256> {
private:
/** @cond internal */
typedef SHAKE<256> Super;
SecureBuffer context_;
template<class T, Prehashed Ph> friend class Signing;
......@@ -79,6 +87,7 @@ private:
decaf_ed448_prehash_init((decaf_shake256_ctx_s *)wrapped);
}
/** @endcond */
public:
/** Number of output bytes in prehash */
......@@ -108,35 +117,10 @@ public:
}
};
/** Signing (i.e. private) key class template */
template<class CRTP, Prehashed ph> class Signing;
template<class CRTP> class Signing<CRTP,PREHASHED> {
public:
/* Sign a prehash context, and reset the context */
inline SecureBuffer sign_prehashed ( const Prehash &ph ) const /*throw(std::bad_alloc)*/ {
SecureBuffer out(CRTP::SIG_BYTES);
decaf_ed448_sign_prehash (
out.data(),
((const CRTP*)this)->priv_.data(),
((const CRTP*)this)->pub_.data(),
(const decaf_ed448_prehash_ctx_s*)ph.wrapped,
ph.context_.data(),
ph.context_.size()
);
return out;
}
/* Sign a message using the prehasher */
inline SecureBuffer sign_with_prehash (
const Block &message,
const Block &context = NO_CONTEXT()
) const /*throw(LengthException,CryptoException)*/ {
Prehash ph(context);
ph += message;
return sign_prehashed(ph);
}
};
/** Signing (i.e. private) key class, PureEdDSA version */
template<class CRTP> class Signing<CRTP,PURE> {
public:
/**
......@@ -169,12 +153,42 @@ public:
}
};
/** Signing (i.e. private) key class, prehashed version */
template<class CRTP> class Signing<CRTP,PREHASHED> {
public:
/** Sign a prehash context, and reset the context */
inline SecureBuffer sign_prehashed ( const Prehash &ph ) const /*throw(std::bad_alloc)*/ {
SecureBuffer out(CRTP::SIG_BYTES);
decaf_ed448_sign_prehash (
out.data(),
((const CRTP*)this)->priv_.data(),
((const CRTP*)this)->pub_.data(),
(const decaf_ed448_prehash_ctx_s*)ph.wrapped,
ph.context_.data(),
ph.context_.size()
);
return out;
}
/** Sign a message using the prehasher */
inline SecureBuffer sign_with_prehash (
const Block &message,
const Block &context = NO_CONTEXT()
) const /*throw(LengthException,CryptoException)*/ {
Prehash ph(context);
ph += message;
return sign_prehashed(ph);
}
};
/** Signing (i.e. private) key base class */
class PrivateKeyBase
: public Serializable<PrivateKeyBase>
, public Signing<PrivateKeyBase,PURE>
, public Signing<PrivateKeyBase,PREHASHED> {
public:
typedef class PublicKeyBase MyPublicKey;
/** Type of public key corresponding to this private key */
typedef class PublicKeyBase PublicKey;
private:
/** @cond internal */
friend class PublicKeyBase;
......@@ -243,14 +257,13 @@ public:
}
/** Return the corresponding public key */
inline MyPublicKey pub() const DECAF_NOEXCEPT {
MyPublicKey pub(*this);
inline PublicKey pub() const DECAF_NOEXCEPT {
PublicKey pub(*this);
return pub;
}
}; /* class PrivateKey */
/** Verification (i.e. public) EdDSA key, PureEdDSA version. */
template<class CRTP> class Verification<CRTP,PURE> {
public:
/** Verify a signature, returning DECAF_FAILURE if verification fails */
......@@ -296,10 +309,10 @@ public:
}
};
/** Verification (i.e. public) EdDSA key, prehashed version. */
template<class CRTP> class Verification<CRTP,PREHASHED> {
public:
/* Verify a prehash context. */
/** Verify that a signature is valid for a given prehashed message, given the context. */
inline decaf_error_t DECAF_WARN_UNUSED verify_prehashed_noexcept (
const FixedBlock<DECAF_EDDSA_448_SIGNATURE_BYTES> &sig,
const Prehash &ph
......@@ -312,8 +325,8 @@ public:
ph.context_.size()
);
}
/* Verify a prehash context. */
/** Verify that a signature is valid for a given prehashed message, given the context. */
inline void verify_prehashed (
const FixedBlock<DECAF_EDDSA_448_SIGNATURE_BYTES> &sig,
const Prehash &ph
......@@ -329,7 +342,7 @@ public:
}
}
/* Verify a message using the prehasher */
/** Hash and verify a message, using the prehashed verification mode. */
inline void verify_with_prehash (
const FixedBlock<DECAF_EDDSA_448_SIGNATURE_BYTES> &sig,
const Block &message,
......@@ -341,24 +354,25 @@ public:
}
};
/** EdDSA Public key base class. */
class PublicKeyBase
: public Serializable<PublicKeyBase>
, public Verification<PublicKeyBase,PURE>
, public Verification<PublicKeyBase,PREHASHED> {
public:
typedef class PrivateKeyBase MyPrivateKey;
/** Private key corresponding to this type of public key */
typedef class PrivateKeyBase PrivateKey;
private:
/** @cond internal */
friend class PrivateKeyBase;
friend class Verification<PublicKey,PURE>;
friend class Verification<PublicKey,PREHASHED>;
/** @endcond */
private:
/** The pre-expansion form of the signature */
FixedArrayBuffer<DECAF_EDDSA_448_PUBLIC_BYTES> pub_;
/** @endcond */
public:
/* PERF FUTURE: Pre-cached decoding? Precomputed table?? */
......@@ -372,7 +386,6 @@ public:
/** Serialization size. */
static const size_t SER_BYTES = DECAF_EDDSA_448_PRIVATE_BYTES;
/** Create but don't initialize */
inline explicit PublicKeyBase(const NOINIT&) DECAF_NOEXCEPT : pub_((NOINIT())) { }
......@@ -383,7 +396,7 @@ public:
inline PublicKeyBase(const PublicKeyBase &k) DECAF_NOEXCEPT { *this = k; }
/** Copy constructor */
inline explicit PublicKeyBase(const MyPrivateKey &k) DECAF_NOEXCEPT { *this = k; }
inline explicit PublicKeyBase(const PrivateKey &k) DECAF_NOEXCEPT { *this = k; }
/** Assignment from string */
inline PublicKey &operator=(const FixedBlock<SER_BYTES> &b) DECAF_NOEXCEPT {
......@@ -397,7 +410,7 @@ public:
}
/** Assignment from private key */
inline PublicKey &operator=(const MyPrivateKey &p) DECAF_NOEXCEPT {
inline PublicKey &operator=(const PrivateKey &p) DECAF_NOEXCEPT {
return *this = p.pub_;
}
......
......@@ -15,7 +15,15 @@
#ifndef __DECAF_EDDSA_HXX__
#define __DECAF_EDDSA_HXX__ 1
namespace decaf { enum Prehashed { PURE, PREHASHED }; }
/** Namespace for all libdecaf C++ objects. */
namespace decaf {
/** How signatures handle hashing. */
enum Prehashed {
PURE, /**< Sign the message itself. This can't be done in one pass. */
PREHASHED /**< Sign the hash of the message. */
};
}
#include <decaf/ed255.hxx>
#include <decaf/ed448.hxx>
......
......@@ -64,10 +64,10 @@ typedef struct gf_25519_s {
/** Number of bytes in an x25519 private key */
#define DECAF_X25519_PRIVATE_BYTES 32
/** Twisted Edwards extended homogeneous coordinates */
/** Representation of a point on the elliptic curve. */
typedef struct decaf_255_point_s {
/** @cond internal */
gf_25519_t x,y,z,t;
gf_25519_t x,y,z,t; /* Twisted extended homogeneous coordinates */
/** @endcond */
} decaf_255_point_t[1];
......@@ -80,26 +80,26 @@ typedef struct decaf_255_precomputed_s decaf_255_precomputed_s;
/** Size and alignment of precomputed point tables. */
extern const size_t decaf_255_sizeof_precomputed_s DECAF_API_VIS, decaf_255_alignof_precomputed_s DECAF_API_VIS;
/** Scalar is stored packed, because we don't need the speed. */
/** Representation of an element of the scalar field. */
typedef struct decaf_255_scalar_s {
/** @cond internal */
decaf_word_t limb[DECAF_255_SCALAR_LIMBS];
/** @endcond */
} decaf_255_scalar_t[1];
/** A scalar equal to 1. */
/** The scalar 1. */
extern const decaf_255_scalar_t decaf_255_scalar_one DECAF_API_VIS;
/** A scalar equal to 0. */
/** The scalar 0. */
extern const decaf_255_scalar_t decaf_255_scalar_zero DECAF_API_VIS;
/** The identity point on the curve. */
/** The identity (zero) point on the curve. */
extern const decaf_255_point_t decaf_255_point_identity DECAF_API_VIS;
/** An arbitrarily chosen base point on the curve. */
/** An arbitrarily-chosen base point on the curve. */
extern const decaf_255_point_t decaf_255_point_base DECAF_API_VIS;
/** Precomputed table for the base point on the curve. */
/** Precomputed table of multiples of the base point on the curve. */
extern const struct decaf_255_precomputed_s *decaf_255_precomputed_base DECAF_API_VIS;
/**
......@@ -386,19 +386,19 @@ decaf_error_t decaf_255_direct_scalarmul (
) DECAF_API_VIS DECAF_NONNULL DECAF_WARN_UNUSED DECAF_NOINLINE;
/**
* @brief RFC 7748 Diffie-Hellman scalarmul. This function uses a different
* (non-Decaf) encoding.
* @brief RFC 7748 Diffie-Hellman scalarmul, used to compute shared secrets.
* This function uses a different (non-Decaf) encoding.
*
* @param [out] scaled The scaled point base*scalar
* @param [in] base The point to be scaled.
* @param [in] scalar The scalar to multiply by.
* @param [out] shared The shared secret base*scalar
* @param [in] base The other party's public key, used as the base of the scalarmul.
* @param [in] scalar The private scalar to multiply by.
*
* @retval DECAF_SUCCESS The scalarmul succeeded.
* @retval DECAF_FAILURE The scalarmul didn't succeed, because the base
* point is in a small subgroup.
*/
decaf_error_t decaf_x25519 (
uint8_t out[DECAF_X25519_PUBLIC_BYTES],
uint8_t shared[DECAF_X25519_PUBLIC_BYTES],
const uint8_t base[DECAF_X25519_PUBLIC_BYTES],
const uint8_t scalar[DECAF_X25519_PRIVATE_BYTES]
) DECAF_API_VIS DECAF_NONNULL DECAF_WARN_UNUSED DECAF_NOINLINE;
......@@ -429,7 +429,13 @@ void decaf_255_point_mul_by_ratio_and_encode_like_x25519 (
) DECAF_API_VIS DECAF_NONNULL;
/** The base point for X25519 Diffie-Hellman */
extern const uint8_t decaf_x25519_base_point[DECAF_X25519_PUBLIC_BYTES] DECAF_API_VIS;
extern const uint8_t
decaf_x25519_base_point[DECAF_X25519_PUBLIC_BYTES]
#ifndef DOXYGEN
/* For some reason Doxygen chokes on this despite the defense in common.h... */
DECAF_API_VIS
#endif
;
/**
* @brief RFC 7748 Diffie-Hellman base point scalarmul. This function uses
......@@ -438,8 +444,8 @@ extern const uint8_t decaf_x25519_base_point[DECAF_X25519_PUBLIC_BYTES] DECAF_AP
* @deprecated Renamed to decaf_x25519_derive_public_key.
* I have no particular timeline for removing this name.
*
* @param [out] scaled The scaled point base*scalar
* @param [in] scalar The scalar to multiply by.
* @param [out] out The public key base*scalar.
* @param [in] scalar The private scalar.
*/
void decaf_x25519_generate_key (
uint8_t out[DECAF_X25519_PUBLIC_BYTES],
......@@ -453,8 +459,8 @@ void decaf_x25519_generate_key (
* Does exactly the same thing as decaf_x25519_generate_key,
* but has a better name.
*
* @param [out] scaled The scaled point base*scalar
* @param [in] scalar The scalar to multiply by.
* @param [out] out The public key base*scalar
* @param [in] scalar The private scalar.
*/
void decaf_x25519_derive_public_key (
uint8_t out[DECAF_X25519_PUBLIC_BYTES],
......@@ -737,22 +743,20 @@ decaf_255_invert_elligator_uniform (
uint32_t which
) DECAF_API_VIS DECAF_NONNULL DECAF_NOINLINE DECAF_WARN_UNUSED;
/**
* @brief Overwrite scalar with zeros.
*/
/** Securely erase a scalar. */
void decaf_255_scalar_destroy (
decaf_255_scalar_t scalar
) DECAF_NONNULL DECAF_API_VIS;
/**
* @brief Overwrite point with zeros.
/** Securely erase a point by overwriting it with zeros.
* @warning This causes the point object to become invalid.
*/
void decaf_255_point_destroy (
decaf_255_point_t point
) DECAF_NONNULL DECAF_API_VIS;
/**
* @brief Overwrite precomputed table with zeros.
/** Securely erase a precomputed table by overwriting it with zeros.
* @warning This causes the table object to become invalid.
*/
void decaf_255_precomputed_destroy (
decaf_255_precomputed_s *pre
......