package curve25519

Import Path
	vendor/golang.org/x/crypto/curve25519 (on go.dev)

Dependency Relation
	imports 3 packages, and imported by one package

Involved Source Files

	   #d curve25519.go
		Package curve25519 provides an implementation of the X25519 function, which
		performs scalar multiplication on the elliptic curve known as Curve25519.
		See RFC 7748.

	      curve25519_amd64.go
	      curve25519_generic.go
	      curve25519_amd64.s
Package-Level Type Names (only one, which is unexported)

	/* sort exporteds by: alphabet | popularity */
	/* one unexported ... *//* one unexported: */
	 type fieldElement ([...]T)
		fieldElement represents an element of the field GF(2^255 - 19). An element
		t, entries t[0]...t[9], represents the integer t[0]+2^26 t[1]+2^51 t[2]+2^77
		t[3]+2^102 t[4]+...+2^230 t[9]. Bounds on each t[i] vary depending on
		context.

		As Inputs Of (at least 12, none are exported)
			/* 12+ unexporteds ... *//* 12+ unexporteds: */
			func feAdd(dst, a, b *fieldElement)
			func feCopy(dst, src *fieldElement)
			func feCSwap(f, g *fieldElement, b int32)
			func feFromBytes(dst *fieldElement, src *[32]byte)
			func feInvert(out, z *fieldElement)
			func feMul(h, f, g *fieldElement)
			func feMul121666(h, f *fieldElement)
			func feOne(fe *fieldElement)
			func feSquare(h, f *fieldElement)
			func feSub(dst, a, b *fieldElement)
			func feToBytes(s *[32]byte, h *fieldElement)
			func feZero(fe *fieldElement)


Package-Level Functions (total 32, in which 3 are exported)

	 func ScalarBaseMult(dst, scalar *[32]byte)
		ScalarBaseMult sets dst to the product scalar * base where base is the
		standard generator.

		It is recommended to use the X25519 function with Basepoint instead, as
		copying into fixed size arrays can lead to unexpected bugs.

	 func ScalarMult(dst, scalar, point *[32]byte)
		ScalarMult sets dst to the product scalar * point.

		Deprecated: when provided a low-order point, ScalarMult will set dst to all
		zeroes, irrespective of the scalar. Instead, use the X25519 function, which
		will return an error.

	 func X25519(scalar, point []byte) ([]byte, error)
		X25519 returns the result of the scalar multiplication (scalar * point),
		according to RFC 7748, Section 5. scalar, point and the return value are
		slices of 32 bytes.

		scalar can be generated at random, for example with crypto/rand. point should
		be either Basepoint or the output of another X25519 call.

		If point is Basepoint (but not if it's a different slice with the same
		contents) a precomputed implementation might be used for performance.

	/* 29 unexporteds ... *//* 29 unexporteds: */
	 func checkBasepoint()
	 func cswap(inout *[5]uint64, v uint64)
	 func feAdd(dst, a, b *fieldElement)
	 func feCopy(dst, src *fieldElement)
	 func feCSwap(f, g *fieldElement, b int32)
		feCSwap replaces (f,g) with (g,f) if b == 1; replaces (f,g) with (f,g) if b == 0.

		Preconditions: b in {0,1}.

	 func feFromBytes(dst *fieldElement, src *[32]byte)
	 func feInvert(out, z *fieldElement)
		feInvert sets out = z^-1.

	 func feMul(h, f, g *fieldElement)
		feMul calculates h = f * g
		Can overlap h with f or g.

		Preconditions:
		   |f| bounded by 1.1*2^26,1.1*2^25,1.1*2^26,1.1*2^25,etc.
		   |g| bounded by 1.1*2^26,1.1*2^25,1.1*2^26,1.1*2^25,etc.

		Postconditions:
		   |h| bounded by 1.1*2^25,1.1*2^24,1.1*2^25,1.1*2^24,etc.

		Notes on implementation strategy:

		Using schoolbook multiplication.
		Karatsuba would save a little in some cost models.

		Most multiplications by 2 and 19 are 32-bit precomputations;
		cheaper than 64-bit postcomputations.

		There is one remaining multiplication by 19 in the carry chain;
		one *19 precomputation can be merged into this,
		but the resulting data flow is considerably less clean.

		There are 12 carries below.
		10 of them are 2-way parallelizable and vectorizable.
		Can get away with 11 carries, but then data flow is much deeper.

		With tighter constraints on inputs can squeeze carries into int32.

	 func feMul121666(h, f *fieldElement)
		feMul121666 calculates h = f * 121666. Can overlap h with f.

		Preconditions:
		   |f| bounded by 1.1*2^26,1.1*2^25,1.1*2^26,1.1*2^25,etc.

		Postconditions:
		   |h| bounded by 1.1*2^25,1.1*2^24,1.1*2^25,1.1*2^24,etc.

	 func feOne(fe *fieldElement)
	 func feSquare(h, f *fieldElement)
		feSquare calculates h = f*f. Can overlap h with f.

		Preconditions:
		   |f| bounded by 1.1*2^26,1.1*2^25,1.1*2^26,1.1*2^25,etc.

		Postconditions:
		   |h| bounded by 1.1*2^25,1.1*2^24,1.1*2^25,1.1*2^24,etc.

	 func feSub(dst, a, b *fieldElement)
	 func feToBytes(s *[32]byte, h *fieldElement)
		feToBytes marshals h to s.
		Preconditions:
		  |h| bounded by 1.1*2^25,1.1*2^24,1.1*2^25,1.1*2^24,etc.

		Write p=2^255-19; q=floor(h/p).
		Basic claim: q = floor(2^(-255)(h + 19 2^(-25)h9 + 2^(-1))).

		Proof:
		  Have |h|<=p so |q|<=1 so |19^2 2^(-255) q|<1/4.
		  Also have |h-2^230 h9|<2^230 so |19 2^(-255)(h-2^230 h9)|<1/4.

		  Write y=2^(-1)-19^2 2^(-255)q-19 2^(-255)(h-2^230 h9).
		  Then 0<y<1.

		  Write r=h-pq.
		  Have 0<=r<=p-1=2^255-20.
		  Thus 0<=r+19(2^-255)r<r+19(2^-255)2^255<=2^255-1.

		  Write x=r+19(2^-255)r+y.
		  Then 0<x<2^255 so floor(2^(-255)x) = 0 so floor(q+2^(-255)x) = q.

		  Have q+2^(-255)x = 2^(-255)(h + 19 2^(-25) h9 + 2^(-1))
		  so floor(2^(-255)(h + 19 2^(-25) h9 + 2^(-1))) = q.

	 func feZero(fe *fieldElement)
	 func freeze(inout *[5]uint64)
	 func init()
	 func invert(r *[5]uint64, x *[5]uint64)
		invert calculates r = x^-1 mod p using Fermat's little theorem.

	 func ladderstep(inout *[5][5]uint64)
	 func load3(in []byte) int64
		load3 reads a 24-bit, little-endian value from in.

	 func load4(in []byte) int64
		load4 reads a 32-bit, little-endian value from in.

	 func mladder(xr, zr *[5]uint64, s *[32]byte)
		mladder uses a Montgomery ladder to calculate (xr/zr) *= s.

	 func mul(dest, a, b *[5]uint64)
	 func pack(out *[32]byte, x *[5]uint64)
		pack sets out = x where out is the usual, little-endian form of the 5,
		51-bit limbs in x.

	 func scalarMult(out, in, base *[32]byte)
	 func scalarMultGeneric(out, in, base *[32]byte)
	 func setint(r *[5]uint64, v uint64)
	 func square(out, in *[5]uint64)
	 func unpack(r *[5]uint64, x *[32]byte)
		unpack sets r = x where r consists of 5, 51-bit limbs in little-endian
		order.

	 func x25519(dst *[32]byte, scalar, point []byte) ([]byte, error)
Package-Level Variables (total 2, in which 1 are exported)

	  var Basepoint []byte
		Basepoint is the canonical Curve25519 generator.

	/* one unexported ... *//* one unexported: */
	  var basePoint [32]byte
Package-Level Constants (total 2, both are exported)

	const PointSize = 32
		PointSize is the size of the point input to X25519.

	const ScalarSize = 32
		ScalarSize is the size of the scalar input to X25519.

The pages are generated with Golds v0.4.2. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.