API Reference

Complete API documentation for the Shamir package.

Shamir Facade

Static facade providing convenient access to ShamirManager functionality.

split()

Split a secret into shares (static API).

public static function split(
    string $secret,
    int $threshold,
    int $shares,
): ShareCollection

Parameters:

• $secret - The secret to split (any binary string)
• $threshold - Minimum shares needed to reconstruct (k)
• $shares - Total number of shares to generate (n)

Returns: ShareCollection - Collection of generated shares

Throws:

• InvalidArgumentException - If threshold > shares or threshold < 2

Example:

$shares = Shamir::split('my-secret', threshold: 3, shares: 5);

for()

Begin fluent split operation.

public static function for(string $secret): SplitConductor

Parameters:

• $secret - The secret to split

Returns: SplitConductor - Fluent conductor for configuration

Example:

$shares = Shamir::for('my-secret')
    ->threshold(3)
    ->shares(5)
    ->split();

combine()

Reconstruct a secret from shares (static API).

public static function combine(iterable $shares): string

Parameters:

• $shares - Iterable of Share objects or share strings

Returns: string - The reconstructed secret

Throws:

• InsufficientSharesException - If fewer shares than threshold
• InvalidShareException - If share format is invalid or checksum fails
• IncompatibleSharesException - If shares are from different splits

Example:

$secret = Shamir::combine([$share1, $share2, $share3]);

from()

Begin fluent combine operation.

public static function from(iterable $shares): CombineConductor

Parameters:

• $shares - Iterable of Share objects or share strings

Returns: CombineConductor - Fluent conductor for combination

Example:

$secret = Shamir::from([$share1, $share2, $share3])->combine();

withConfig()

Create manager with different configuration.

public static function withConfig(Config $config): ShamirManager

Parameters:

• $config - Configuration instance

Returns: ShamirManager - New manager with config

Example:

$config = new Config(prime: Config::PRIME_512, encoding: 'hex');
$manager = Shamir::withConfig($config);
$shares = $manager->split('secret', 3, 5);

areCompatible()

Check if shares are from the same split operation.

public static function areCompatible(Share ...$shares): bool

Parameters:

• ...$shares - Variable number of Share objects

Returns: bool - True if shares have the same threshold

Example:

if (Shamir::areCompatible($share1, $share2, $share3)) {
    // Safe to combine
}

ShamirManager

Central manager for orchestrating secret sharing operations.

Constructor

public function __construct(private Config $config = new Config())

split()

Split a secret into shares.

public function split(
    string $secret,
    int $threshold,
    int $shares,
): ShareCollection

combine()

Reconstruct a secret from shares.

public function combine(iterable $shares): string

for()

Begin fluent split operation.

public function for(string $secret): SplitConductor

from()

Begin fluent combine operation.

public function from(iterable $shares): CombineConductor

withConfig()

Create new manager with different config.

public function withConfig(Config $config): self

areCompatible()

Verify shares are compatible.

public function areCompatible(Share ...$shares): bool

getConfig()

Get current configuration.

public function getConfig(): Config

Conductors

SplitConductor

Fluent API for configuring split operations.

threshold()

Set minimum shares needed.

public function threshold(int $threshold): self

shares()

Set total shares to generate.

public function shares(int $shares): self

split()

Execute the split operation.

public function split(): ShareCollection

Example:

$shares = $manager->for($secret)
    ->threshold(3)
    ->shares(5)
    ->split();

CombineConductor

Fluent API for combine operations.

combine()

Execute the combine operation.

public function combine(): string

Example:

$secret = $manager->from($shares)->combine();

Share Class

Pure value object representing a single share in the secret sharing scheme.

Constructor

public function __construct(
    private int $index,
    private string $value,
    private int $threshold,
    private string $checksum,
)

Methods

getIndex()

public function getIndex(): int

Get the share’s index (1-based).

getValue()

public function getValue(): string

Get the encoded share value.

getThreshold()

public function getThreshold(): int

Get the threshold required to reconstruct the secret.

getChecksum()

public function getChecksum(): string

Get the share’s checksum for validation.

toString()

public function toString(): string

Serialize to portable string format: "index:threshold:checksum:value"

Delegates to ShareSerializer internally.

Example:

$shareString = $share->toString();
// "1:3:abc123...:encoded_value"

fromString()

public static function fromString(string $encoded): self

Parse a share from string format.

Delegates to ShareSerializer internally.

Throws: InvalidShareException - If format is invalid

Example:

$share = Share::fromString('1:3:checksum:value');

fromArray()

public static function fromArray(array $data): self

Create share from array (JSON deserialization).

Delegates to ShareSerializer internally.

Throws: InvalidShareException - If required fields are missing

Example:

$data = json_decode($json, true);
$share = Share::fromArray($data);

jsonSerialize()

public function jsonSerialize(): array

Serialize to array for JSON encoding.

Delegates to ShareSerializer internally.

Example:

$json = json_encode($share);

ShareSerializer

Service for serializing and deserializing Share objects.

toString()

Serialize a share to string format.

public function toString(Share $share): string

fromString()

Deserialize a share from string format.

public function fromString(string $encoded): Share

Throws: InvalidShareException

toArray()

Serialize a share to array format.

public function toArray(Share $share): array

fromArray()

Deserialize a share from array format.

public function fromArray(array $data): Share

Throws: InvalidShareException

Example:

$serializer = new ShareSerializer();

// String serialization
$string = $serializer->toString($share);
$share = $serializer->fromString($string);

// Array serialization
$array = $serializer->toArray($share);
$share = $serializer->fromArray($array);

ShareCollection Class

Collection of shares with utility methods.

Constructor

public function __construct(private array $shares)

Methods

get()

public function get(int $index): Share

Get share by index (1-based).

Throws: InvalidShareException - If share not found

take()

public function take(int $count): self

Take first N shares.

random()

public function random(int $count): self

Get N random shares.

Throws: InvalidArgumentException - If count > available shares

count()

public function count(): int

Get total number of shares.

toArray()

public function toArray(): array

Convert to plain array of Share objects.

forDistribution()

public function forDistribution(): array

Get shares in randomized order, indexed by share number.

Returns: array<int, Share> - Shares indexed by their index

Example:

foreach ($shares->forDistribution() as $index => $share) {
    sendToKeyHolder($index, $share);
}

Config Class

Configuration options for Shamir operations.

Constructor

public function __construct(
    public string $prime = Config::PRIME_256,
    public string $encoding = 'base64',
)

Constants

Prime Field Sizes

// 128-bit prime (secrets up to ~16 bytes per chunk)
Config::PRIME_128

// 256-bit prime (secrets up to ~32 bytes per chunk) - DEFAULT
Config::PRIME_256

// 512-bit prime (larger secrets)
Config::PRIME_512

Properties

$prime

The prime number defining the Galois field size.

$encoding

Encoding format for share values: 'base64' (default) or 'hex'.

Example

$config = new Config(
    prime: Config::PRIME_512,
    encoding: 'hex',
);

$shares = Shamir::split($secret, 3, 5, $config);

Exceptions

ShamirException

Base exception for all Shamir-related errors.

InsufficientSharesException

Thrown when fewer shares than threshold are provided.

Static Constructor:

InsufficientSharesException::notEnoughShares(int $provided, int $required)

InvalidShareException

Thrown when share format is invalid or checksum fails.

Static Constructors:

InvalidShareException::invalidFormat(string $encoded)
InvalidShareException::missingRequiredFields()
InvalidShareException::shareNotFound(int $index)
InvalidShareException::checksumMismatch()

IncompatibleSharesException

Thrown when shares are from different split operations.

Static Constructors:

IncompatibleSharesException::differentThresholds()
IncompatibleSharesException::differentChecksums()

SecretTooLargeException

Thrown when secret exceeds field size (rarely occurs due to automatic chunking).

Static Constructor:

SecretTooLargeException::exceedsFieldSize(int $secretSize, int $maxSize)

Type Reference

Iterables

The combine() method accepts any iterable of shares:

// Array of Share objects
Shamir::combine([$share1, $share2, $share3]);

// ShareCollection
Shamir::combine($shares->take(3));

// Array of strings
Shamir::combine([
    '1:3:checksum:value1',
    '2:3:checksum:value2',
    '3:3:checksum:value3',
]);

// Mixed
Shamir::combine([
    $shareObject,
    '2:3:checksum:value',
    Share::fromString('3:3:checksum:value'),
]);