github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/crypto/internal/edwards25519/scalar.go (about)

     1  // Copyright (c) 2016 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package edwards25519
     6  
     7  // A Scalar is an integer modulo
     8  //
     9  //	l = 2^252 + 27742317777372353535851937790883648493
    10  //
    11  // which is the prime order of the edwards25519 group.
    12  //
    13  // This type works similarly to math/big.Int, and all arguments and
    14  // receivers are allowed to alias.
    15  //
    16  // The zero value is a valid zero element.
    17  type Scalar struct {
    18  	// s is the scalar in the Montgomery domain, in the format of the
    19  	// fiat-crypto implementation.
    20  	s fiatScalarMontgomeryDomainFieldElement
    21  }
    22  
    23  // NewScalar returns a new zero Scalar.
    24  func NewScalar() *Scalar
    25  
    26  // MultiplyAdd sets s = x * y + z mod l, and returns s. It is equivalent to
    27  // using Multiply and then Add.
    28  func (s *Scalar) MultiplyAdd(x, y, z *Scalar) *Scalar
    29  
    30  // Add sets s = x + y mod l, and returns s.
    31  func (s *Scalar) Add(x, y *Scalar) *Scalar
    32  
    33  // Subtract sets s = x - y mod l, and returns s.
    34  func (s *Scalar) Subtract(x, y *Scalar) *Scalar
    35  
    36  // Negate sets s = -x mod l, and returns s.
    37  func (s *Scalar) Negate(x *Scalar) *Scalar
    38  
    39  // Multiply sets s = x * y mod l, and returns s.
    40  func (s *Scalar) Multiply(x, y *Scalar) *Scalar
    41  
    42  // Set sets s = x, and returns s.
    43  func (s *Scalar) Set(x *Scalar) *Scalar
    44  
    45  // SetUniformBytes sets s = x mod l, where x is a 64-byte little-endian integer.
    46  // If x is not of the right length, SetUniformBytes returns nil and an error,
    47  // and the receiver is unchanged.
    48  //
    49  // SetUniformBytes can be used to set s to a uniformly distributed value given
    50  // 64 uniformly distributed random bytes.
    51  func (s *Scalar) SetUniformBytes(x []byte) (*Scalar, error)
    52  
    53  // SetCanonicalBytes sets s = x, where x is a 32-byte little-endian encoding of
    54  // s, and returns s. If x is not a canonical encoding of s, SetCanonicalBytes
    55  // returns nil and an error, and the receiver is unchanged.
    56  func (s *Scalar) SetCanonicalBytes(x []byte) (*Scalar, error)
    57  
    58  // SetBytesWithClamping applies the buffer pruning described in RFC 8032,
    59  // Section 5.1.5 (also known as clamping) and sets s to the result. The input
    60  // must be 32 bytes, and it is not modified. If x is not of the right length,
    61  // SetBytesWithClamping returns nil and an error, and the receiver is unchanged.
    62  //
    63  // Note that since Scalar values are always reduced modulo the prime order of
    64  // the curve, the resulting value will not preserve any of the cofactor-clearing
    65  // properties that clamping is meant to provide. It will however work as
    66  // expected as long as it is applied to points on the prime order subgroup, like
    67  // in Ed25519. In fact, it is lost to history why RFC 8032 adopted the
    68  // irrelevant RFC 7748 clamping, but it is now required for compatibility.
    69  func (s *Scalar) SetBytesWithClamping(x []byte) (*Scalar, error)
    70  
    71  // Bytes returns the canonical 32-byte little-endian encoding of s.
    72  func (s *Scalar) Bytes() []byte
    73  
    74  // Equal returns 1 if s and t are equal, and 0 otherwise.
    75  func (s *Scalar) Equal(t *Scalar) int