package phcformat

Import Path
	go.pact.im/x/phcformat (on go.dev)

Dependency Relation
	imports 5 packages, and imported by one package


Involved Source Files

	      append.go
	      params.go
	      parse.go
	
		Package phcformat implements PHC string format parser and encoder.

		See https://github.com/P-H-C/phc-string-format


Code Examples

	
		package main
		
		import (
			"fmt"
			"go.pact.im/x/option"
			"go.pact.im/x/phcformat"
			"go.pact.im/x/phcformat/encode"
		)
		
		func main() {
			var (
				// version is the version of the Argon2 algorithm.
				//
				// Example:
				//  version := argon2.Version
				version = 19
				// salt is the random salt bytes.
				//
				// Example:
				//  import "crypto/rand"
				//  salt := make([]byte, 16)
				//  if _, err := io.ReadFull(rand.Reader, salt); err != nil {
				//      panic(err)
				//  }
				salt = []byte{
					0x81, 0x98, 0x95, 0xFC, 0xCD, 0x60, 0x3D, 0xCD,
					0xB6, 0x12, 0x50, 0x07, 0xFC, 0x98, 0x75, 0x1F,
				}
				// time is the time constraint parameter.
				time = uint32(2)
				// memory is the time constraint parameter.
				memory = uint32(64 * 1024)
				// threads is the parallelism parameter.
				threads = uint8(1)
				// output is the hash function output.
				//
				// Example:
				//  output := argon2.IDKey([]byte("pass"), salt, time, memory, threads, 32)
				output = []byte{
					0xDA, 0x9F, 0xFE, 0x1E, 0x01, 0x48, 0xD4, 0xE1,
					0x07, 0x32, 0xFD, 0xAA, 0x88, 0xC3, 0x7A, 0x5C,
					0xC8, 0xC0, 0xC4, 0x23, 0xC7, 0xED, 0xA5, 0xC9,
					0x09, 0x78, 0x21, 0xE7, 0xD9, 0x7C, 0x0D, 0xBD,
				}
			)
			newParam := func(k string, v uint) encode.KV[encode.String, encode.Byte, encode.Uint] {
				return encode.NewKV(encode.NewByte('='), encode.NewString(k), encode.NewUint(v))
			}
			fmt.Println(string(phcformat.Append(nil,
				encode.String("argon2id"),
				option.Value(encode.NewUint(uint(version))),
				option.Value(encode.NewList(
					encode.NewByte(','),
					newParam("m", uint(memory)),
					newParam("t", uint(time)),
					newParam("p", uint(threads)),
				)),
				option.Value(encode.NewBase64(salt)),
				option.Value(encode.NewBase64(output)),
			)))
		}

	
		package main
		
		import (
			"fmt"
			"go.pact.im/x/option"
			"go.pact.im/x/phcformat"
		)
		
		func main() {
			params := option.Value("a=b,c=d")
			it := phcformat.IterParams(option.UnwrapOrZero(params))
			for ; it.Valid; it = it.Next() {
				fmt.Println(it.Name, it.Value)
			}
			if it.After != "" {
				panic("parse error")
			}
		}

	
		package main
		
		import (
			"fmt"
			"go.pact.im/x/option"
			"go.pact.im/x/phcformat"
		)
		
		func main() {
			h := phcformat.MustParse("$name$v=42$k=v$salt$hash")
			fmt.Println(h)
			fmt.Println(h.ID)
			fmt.Println(option.UnwrapOrZero(h.Version))
			fmt.Println(option.UnwrapOrZero(h.Params))
			fmt.Println(option.UnwrapOrZero(h.Salt))
			fmt.Println(option.UnwrapOrZero(h.Output))
		}




Package-Level Type Names (total 2, both are exported)


	/* sort exporteds by:  |  */
	
		Hash represents a hash function in PHC string format.

		
			
				ID is the symbolic name for the function. The function symbolic name
				is a sequence of characters in: [a-z0-9-] (lowercase letters, digits,
				and the minus sign). No other characters are allowed. A name must not
				exceed 32 characters in length. Note that it is allowed to be empty.

			
				Output is the base64-encoded function output.

			
				Params is a comma-separated sequence of "key=value" parameter pairs.

			
				Raw is the unparsed hash in PHC string format.

			
				Salt is an encoded salt string.

			
				Version is the algorithm version. The function version is a sequence
				of characters in: [0-9]. Note that it is allowed to be empty.
				prohibited)

		
			
				String implements the fmt.Stringer interface. It returns the hash in PHC
				string format.

		
			 Hash : expvar.Var
			 Hash : fmt.Stringer
			
		
			func MustParse(s string) Hash
			func Parse(s string) (Hash, bool)


	
		ParamsIterator iterates over comma-separated key=value parameter pairs. Note
		that iterator does not validate characters in parameter’s key and value.

		
			
				After is the string with remaining parameters.

			
				Name is the name of the current parameter.

			
				Valid indicates that the iterator is valid. On parse error, After
				will contain unparsed bytes.

			
				Value is the value of the current parameter.

		
			
				Next advances to the next parameter in the sequence.

		
			func IterParams(s string) ParamsIterator
			func ParamsIterator.Next() ParamsIterator




Package-Level Functions (total 12, in which 4 are exported)


	

		Type Parameters:
			NameAppender: encode.Appender
			VersionAppender: encode.Appender
			ParamsAppender: encode.Appender
			SaltAppender: encode.Appender
			OutputAppender: encode.Appender

		Append appends the given parameters in a PHC string format to dst and returns
		the resulting slice.

		The caller is responsible for ensuring that:
		 • name is a sequence of characters in “a-z0-9-”.
		 • version is a sequence of characters in “0-9”.
		 • params is a sequence of comma-separated name and value pairs (separated by
		   equals sign) where name is a sequence of characters in “a-z0-9-” and value
		   is a sequence of characters in “a-zA-Z0-9/+.-”. If version is not set and
		   only a single parameter named “v” is given, to avoid ambiguity, its value
		   must not be a sequence of characters in “0-9” (as in version).
		 • salt is a sequence of characters in “a-zA-Z0-9/+.-”.
		 • output is a sequence of characters in “A-Za-z0-9+/” (base64 character set)
		   and salt is set. That is, it must be a base64-encoded string and implies
		   that salt is set.


	
		IterParams returns a ParamsIterator for the given string.


	
		MustParse is like Parse but panics on parse error.


	
		Parse parses PHC formatted string s. It returns the parsed hash and a boolean
		value indicating either success or parse error.