Go SDK

package main

import (
    "encoding/hex"
    "encoding/base64"
    "fmt"
    "github.com/sha224-org/sha224-go"
)

func main() {
    // Hash a byte slice
    data := []byte("Hello, world!")
    hash := sha224.Sum(data)
    fmt.Printf("Byte slice hash: %x\n", hash)
    
    // Hash a string directly
    strHash := sha224.SumString("Hello, world!")
    fmt.Printf("String hash: %x\n", strHash)
    
    // Hash an integer
    intBytes := make([]byte, 4)
    intBytes[0] = byte(12345 >> 24)
    intBytes[1] = byte(12345 >> 16)
    intBytes[2] = byte(12345 >> 8)
    intBytes[3] = byte(12345)
    intHash := sha224.Sum(intBytes)
    fmt.Printf("Integer hash: %x\n", intHash)
    
    // Different output formats
    hexStr := hex.EncodeToString(hash[:])
    fmt.Println("Hex:", hexStr)
    
    base64Str := base64.StdEncoding.EncodeToString(hash[:])
    fmt.Println("Base64:", base64Str)
}

package main

import (
    "fmt"
    "github.com/sha224-org/sha224-go"
)

func main() {
    // Create a hasher
    h := sha224.New()
    
    // Write data incrementally
    h.Write([]byte("Part 1: "))
    h.Write([]byte("Part 2: "))
    h.Write([]byte("Part 3"))
    
    // Get the final hash
    sum := h.Sum(nil)
    fmt.Printf("Incremental hash: %x\n", sum)
    
    // Get the hash size and block size
    fmt.Printf("Hash size: %d bytes\n", h.Size())
    fmt.Printf("Block size: %d bytes\n", h.BlockSize())
    
    // Reset and reuse
    h.Reset()
    h.Write([]byte("Fresh start"))
    newSum := h.Sum(nil)
    fmt.Printf("After reset: %x\n", newSum)
}

package main

import (
    "crypto/subtle"
    "fmt"
    "github.com/sha224-org/sha224-go"
)

func main() {
    // Create a hash
    data := []byte("Important data to verify")
    hash := sha224.Sum(data)
    hexHash := fmt.Sprintf("%x", hash)
    fmt.Println("Original hash:", hexHash)
    
    // Verify the data hasn't been modified
    isValid := sha224.Verify(hexHash, data)
    fmt.Println("Valid data:", isValid) // true
    
    // Verify modified data
    modifiedData := []byte("Important data to verify!")
    isModifiedValid := sha224.Verify(hexHash, modifiedData)
    fmt.Println("Valid modified data:", isModifiedValid) // false
    
    // Manual secure comparison (constant-time)
    otherHash := sha224.Sum([]byte("Important data to verify"))
    // Use subtle.ConstantTimeCompare for secure comparison
    secureCompare := subtle.ConstantTimeCompare(hash[:], otherHash[:]) == 1
    fmt.Println("Secure comparison:", secureCompare) // true
}

File Operation Examples

Hashing Files

package main

import (
    "fmt"
    "github.com/sha224-org/sha224-go"
    "log"
    "os"
)

func main() {
    // Hash a file by path
    fileHash, err := sha224.SumFile("document.pdf")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("File hash: %x\n", fileHash)
    
    // Hash a file with progress reporting
    bigFile, err := os.Open("large-file.bin")
    if err != nil {
        log.Fatal(err)
    }
    defer bigFile.Close()
    
    fileInfo, err := bigFile.Stat()
    if err != nil {
        log.Fatal(err)
    }
    
    fileSize := fileInfo.Size()
    
    // Rewind to the beginning
    bigFile.Seek(0, 0)
    
    hash, err := sha224.SumReaderWithProgress(bigFile, fileSize, func(bytesRead, totalSize int64) {
        progress := float64(bytesRead) / float64(totalSize) * 100
        fmt.Printf("\rProgress: %.2f%%", progress)
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("\nLarge file hash: %x\n", hash)
}

Directory Hashing

package main

import (
    "fmt"
    "github.com/sha224-org/sha224-go"
    "io/ioutil"
    "log"
    "os"
    "path/filepath"
    "sort"
)

func main() {
    dirPath := "./project-directory"
    dirHash, err := hashDirectory(dirPath)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Directory hash: %x\n", dirHash)
}

func hashDirectory(dirPath string) ([28]byte, error) {
    // Get all files recursively
    var files []string
    err := filepath.Walk(dirPath, func(path string, info os.FileInfo, err error) error {
        if err != nil {
            return err
        }
        if !info.IsDir() {
            files = append(files, path)
        }
        return nil
    })
    if err != nil {
        return [28]byte{}, err
    }
    
    // Sort files by path for consistency
    sort.Strings(files)
    
    // Create a master hasher
    h := sha224.New()
    
    // Hash each file and add its path and hash to the master hasher
    for _, filePath := range files {
        relPath, err := filepath.Rel(dirPath, filePath)
        if err != nil {
            return [28]byte{}, err
        }
        
        fileHash, err := sha224.SumFile(filePath)
        if err != nil {
            return [28]byte{}, err
        }
        
        // Add the relative path and hash to the master hasher
        h.Write([]byte(relPath))
        h.Write(fileHash[:])
        
        fmt.Printf("Hashed: %s - %x\n", relPath, fileHash)
    }
    
    // Get the final hash
    var result [28]byte
    sum := h.Sum(nil)
    copy(result[:], sum)
    
    return result, nil
}

File Integrity Verification

package main

import (
    "fmt"
    "github.com/sha224-org/sha224-go"
    "io/ioutil"
    "log"
    "os"
    "path/filepath"
)

func main() {
    // Create a file to verify
    filePath := "important-document.txt"
    err := ioutil.WriteFile(filePath, []byte("This is important data that should not be modified."), 0644)
    if err != nil {
        log.Fatal(err)
    }
    
    // Calculate and save hash
    hash, err := sha224.SumFile(filePath)
    if err != nil {
        log.Fatal(err)
    }
    
    hashHex := fmt.Sprintf("%x", hash)
    hashFilePath := filePath + ".sha224"
    
    err = ioutil.WriteFile(hashFilePath, []byte(hashHex), 0644)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Created file with hash: %s\n", hashHex)
    
    // Later, verify the file
    isValid, err := verifyFileIntegrity(filePath, hashFilePath)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("File integrity valid:", isValid)
    
    // Modify the file and check again
    err = ioutil.WriteFile(filePath, []byte("This is important data that should not be modified. THIS IS A MODIFICATION!"), 0644)
    if err != nil {
        log.Fatal(err)
    }
    
    isStillValid, err := verifyFileIntegrity(filePath, hashFilePath)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Modified file integrity valid:", isStillValid) // Should be false
}

func verifyFileIntegrity(filePath, hashFilePath string) (bool, error) {
    // Read the stored hash
    hashData, err := ioutil.ReadFile(hashFilePath)
    if err != nil {
        return false, err
    }
    expectedHash := string(hashData)
    
    // Verify the file
    return sha224.VerifyFile(expectedHash, filePath)
}

Advanced Examples

Custom I/O Wrappers

package main

import (
    "fmt"
    "github.com/sha224-org/sha224-go"
    "io"
    "log"
    "os"
)

// HashingReader wraps an io.Reader to compute a hash while reading
type HashingReader struct {
    reader io.Reader
    hasher io.Writer
}

func NewHashingReader(r io.Reader) *HashingReader {
    h := sha224.New()
    return &HashingReader{
        reader: r,
        hasher: h,
    }
}

func (hr *HashingReader) Read(p []byte) (n int, err error) {
    n, err = hr.reader.Read(p)
    if n > 0 {
        hr.hasher.Write(p[:n])
    }
    return
}

func (hr *HashingReader) Sum() [28]byte {
    h := hr.hasher.(sha224.Hash)
    var result [28]byte
    sum := h.Sum(nil)
    copy(result[:], sum)
    return result
}

// HashingWriter wraps an io.Writer to compute a hash while writing
type HashingWriter struct {
    writer io.Writer
    hasher io.Writer
}

func NewHashingWriter(w io.Writer) *HashingWriter {
    h := sha224.New()
    return &HashingWriter{
        writer: w,
        hasher: h,
    }
}

func (hw *HashingWriter) Write(p []byte) (n int, err error) {
    n, err = hw.writer.Write(p)
    if n > 0 {
        hw.hasher.Write(p[:n])
    }
    return
}

func (hw *HashingWriter) Sum() [28]byte {
    h := hw.hasher.(sha224.Hash)
    var result [28]byte
    sum := h.Sum(nil)
    copy(result[:], sum)
    return result
}

func main() {
    // Example with HashingReader
    file, err := os.Open("document.pdf")
    if err != nil {
        log.Fatal(err)
    }
    defer file.Close()
    
    hashingReader := NewHashingReader(file)
    
    // Read and process the file
    buffer := make([]byte, 1024)
    for {
        _, err := hashingReader.Read(buffer)
        if err == io.EOF {
            break
        }
        if err != nil {
            log.Fatal(err)
        }
        // Process buffer data...
    }
    
    // Get the hash
    hash := hashingReader.Sum()
    fmt.Printf("File hash: %x\n", hash)
    
    // Example with HashingWriter
    outFile, err := os.Create("output.txt")
    if err != nil {
        log.Fatal(err)
    }
    defer outFile.Close()
    
    hashingWriter := NewHashingWriter(outFile)
    
    // Write data
    data := []byte("This is test data that will be written to the file.")
    _, err = hashingWriter.Write(data)
    if err != nil {
        log.Fatal(err)
    }
    
    // Get the hash of written data
    writeHash := hashingWriter.Sum()
    fmt.Printf("Written data hash: %x\n", writeHash)
}

Memory-Mapped Files

package main

import (
    "fmt"
    "github.com/sha224-org/sha224-go"
    "log"
    "os"
    "syscall"
)

func main() {
    filePath := "large-file.bin"
    
    // Hash with memory mapping for very large files
    hash, err := hashWithMemoryMapping(filePath)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Memory-mapped hash: %x\n", hash)
}

func hashWithMemoryMapping(filePath string) ([28]byte, error) {
    // Open the file
    file, err := os.Open(filePath)
    if err != nil {
        return [28]byte{}, err
    }
    defer file.Close()
    
    // Get file info for size
    fileInfo, err := file.Stat()
    if err != nil {
        return [28]byte{}, err
    }
    
    size := fileInfo.Size()
    if size == 0 {
        return sha224.Sum([]byte{}), nil
    }
    
    // Memory map the file
    mmap, err := syscall.Mmap(
        int(file.Fd()),
        0,
        int(size),
        syscall.PROT_READ,
        syscall.MAP_SHARED,
    )
    if err != nil {
        return [28]byte{}, err
    }
    
    // Ensure munmap
    defer syscall.Munmap(mmap)
    
    // Hash the mapped memory
    return sha224.Sum(mmap), nil
}

Content-Addressable Storage

package main

import (
    "fmt"
    "github.com/sha224-org/sha224-go"
    "io"
    "io/ioutil"
    "log"
    "os"
    "path/filepath"
)

// ContentStore implements a simple content-addressable storage
type ContentStore struct {
    basePath string
}

// NewContentStore creates a new content-addressable storage
func NewContentStore(basePath string) (*ContentStore, error) {
    err := os.MkdirAll(basePath, 0755)
    if err != nil {
        return nil, err
    }
    
    return &ContentStore{basePath: basePath}, nil
}

// Store adds a file to the content store
func (cs *ContentStore) Store(filePath string) (string, error) {
    // Calculate the hash
    hash, err := sha224.SumFile(filePath)
    if err != nil {
        return "", err
    }
    
    hashHex := fmt.Sprintf("%x", hash)
    storedPath := filepath.Join(cs.basePath, hashHex)
    
    // Check if the file already exists
    if _, err := os.Stat(storedPath); err == nil {
        fmt.Printf("File already exists in store: %s\n", hashHex)
        return hashHex, nil
    }
    
    // Copy the file
    err = copyFile(filePath, storedPath)
    if err != nil {
        return "", err
    }
    
    fmt.Printf("Stored file with hash: %s\n", hashHex)
    return hashHex, nil
}

// Retrieve gets a file from the content store
func (cs *ContentStore) Retrieve(hashHex string) (string, error) {
    storedPath := filepath.Join(cs.basePath, hashHex)
    
    // Check if the file exists
    if _, err := os.Stat(storedPath); os.IsNotExist(err) {
        return "", fmt.Errorf("file with hash %s not found", hashHex)
    }
    
    return storedPath, nil
}

// Verify checks if a file matches its expected hash
func (cs *ContentStore) Verify(hashHex, filePath string) (bool, error) {
    return sha224.VerifyFile(hashHex, filePath)
}

// Helper function to copy a file
func copyFile(src, dst string) error {
    sourceFile, err := os.Open(src)
    if err != nil {
        return err
    }
    defer sourceFile.Close()
    
    destFile, err := os.Create(dst)
    if err != nil {
        return err
    }
    defer destFile.Close()
    
    _, err = io.Copy(destFile, sourceFile)
    return err
}

func main() {
    // Create a content store
    store, err := NewContentStore("./content_store")
    if err != nil {
        log.Fatal(err)
    }
    
    // Create some test files
    for i := 1; i <= 3; i++ {
        filePath := fmt.Sprintf("file%d.txt", i)
        content := fmt.Sprintf("This is test file %d content.", i)
        err := ioutil.WriteFile(filePath, []byte(content), 0644)
        if err != nil {
            log.Fatal(err)
        }
        
        // Store the file
        hash, err := store.Store(filePath)
        if err != nil {
            log.Fatal(err)
        }
        
        fmt.Printf("File %d stored with hash: %s\n", i, hash)
        
        // Verify the stored file
        isValid, err := store.Verify(hash, filePath)
        if err != nil {
            log.Fatal(err)
        }
        fmt.Printf("File %d verification: %v\n", i, isValid)
    }
    
    // Try to retrieve and verify
    hashToRetrieve := "7d92e8759c21ff6243e249061231d33fbf16cd78b38d8245741bd128" // Example hash
    filePath, err := store.Retrieve(hashToRetrieve)
    if err == nil {
        fmt.Printf("Retrieved file: %s\n", filePath)
    } else {
        fmt.Printf("Retrieval error: %s\n", err)
    }
}

API Client Examples

Basic API Usage

package main

import (
    "fmt"
    "github.com/sha224-org/sha224-go/api"
    "log"
    "time"
)

func main() {
    // Initialize the API client
    client := api.NewClient("YOUR_API_KEY")
    
    // Configure the client
    client.SetBaseURL("https://api.sha224.com/v1")
    client.SetTimeout(5 * time.Second)
    
    // Hash text using the API
    hash, err := client.HashText("Hello, world!")
    if err != nil {
        log.Fatal("API hash error:", err)
    }
    fmt.Println("API hash:", hash)
    
    // Hash with custom encoding
    latinHash, err := client.HashTextWithEncoding("Café", "latin1")
    if err != nil {
        log.Fatal("API encoding hash error:", err)
    }
    fmt.Println("Latin1 encoded hash:", latinHash)
    
    // Verify a hash
    isValid, err := client.Verify(hash, "Hello, world!")
    if err != nil {
        log.Fatal("API verify error:", err)
    }
    fmt.Println("Hash verification:", isValid) // true
}

Batch Operations

package main

import (
    "fmt"
    "github.com/sha224-org/sha224-go/api"
    "log"
)

func main() {
    // Initialize the API client
    client := api.NewClient("YOUR_API_KEY")
    
    // Create batch items
    items := []api.BatchItem{
        {ID: "item1", Text: "First item"},
        {ID: "item2", Text: "Second item"},
        {ID: "item3", Text: "Third item"},
    }
    
    // Batch hash
    results, err := client.BatchHash(items)
    if err != nil {
        log.Fatal("Batch hash error:", err)
    }
    
    fmt.Println("Batch hash results:")
    for _, result := range results {
        fmt.Printf("ID: %s, Hash: %s\n", result.ID, result.Hash)
    }
    
    // Create verification items
    verifyItems := []api.BatchVerifyItem{
        {
            ID:   "item1",
            Hash: results[0].Hash,
            Text: "First item",
        },
        {
            ID:   "item2",
            Hash: results[1].Hash,
            Text: "Modified item", // This should fail verification
        },
        {
            ID:   "item3",
            Hash: results[2].Hash,
            Text: "Third item",
        },
    }
    
    // Batch verify
    verifyResults, err := client.BatchVerify(verifyItems)
    if err != nil {
        log.Fatal("Batch verify error:", err)
    }
    
    fmt.Println("\nBatch verify results:")
    for _, result := range verifyResults {
        fmt.Printf("ID: %s, Valid: %t\n", result.ID, result.Valid)
    }
}

File Hashing with Progress

package main

import (
    "fmt"
    "github.com/sha224-org/sha224-go/api"
    "log"
)

func main() {
    // Initialize the API client
    client := api.NewClient("YOUR_API_KEY")
    
    // Hash a file with progress reporting
    hash, err := client.HashFileWithProgress("large-file.bin", func(bytesRead, totalSize int64) {
        if totalSize > 0 {
            progress := float64(bytesRead) / float64(totalSize) * 100
            fmt.Printf("\rProgress: %.2f%%", progress)
        } else {
            fmt.Printf("\rBytes read: %d", bytesRead)
        }
    })
    
    fmt.Println() // New line after progress
    
    if err != nil {
        log.Fatal("File hash error:", err)
    }
    fmt.Println("File hash:", hash)
    
    // Verify the file
    isValid, err := client.VerifyFile(hash, "large-file.bin")
    if err != nil {
        log.Fatal("File verify error:", err)
    }
    fmt.Println("File verification:", isValid)
}

Error Handling and Retries

package main

import (
    "fmt"
    "github.com/sha224-org/sha224-go/api"
    "log"
    "net/http"
    "time"
)

// Custom HTTP client with retries
type RetryTransport struct {
    MaxRetries  int
    BaseBackoff time.Duration
    transport   http.RoundTripper
}

func NewRetryTransport(maxRetries int, baseBackoff time.Duration) *RetryTransport {
    return &RetryTransport{
        MaxRetries:  maxRetries,
        BaseBackoff: baseBackoff,
        transport:   http.DefaultTransport,
    }
}

func (rt *RetryTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    var resp *http.Response
    var err error
    
    for attempt := 0; attempt <= rt.MaxRetries; attempt++ {
        // Clone the request body for retry
        if attempt > 0 {
            fmt.Printf("Retry attempt %d/%d\n", attempt, rt.MaxRetries)
            time.Sleep(rt.BaseBackoff * time.Duration(1<