Documentation
¶
Overview ¶
Package plugin implements the age plugin protocol.
Recipient and Identity are plugin clients, that execute plugin binaries to perform encryption and decryption operations.
Plugin is a framework for writing age plugins, that exposes an age.Recipient and/or age.Identity implementation as a plugin binary.
Index ¶
- func EncodeHybridRecipient(pq *mlkem.EncapsulationKey768, t *ecdh.PublicKey) (string, error)
- func EncodeIdentity(name string, data []byte) string
- func EncodeRecipient(name string, data []byte) string
- func EncodeX25519Recipient(pk *ecdh.PublicKey) (string, error)
- func ParseIdentity(s string) (name string, data []byte, err error)
- func ParseRecipient(s string) (name string, data []byte, err error)
- type ClientUI
- type Identity
- type NotFoundError
- type Plugin
- func (p *Plugin) Confirm(prompt, yes, no string) (choseYes bool, err error)
- func (p *Plugin) DisplayMessage(message string) error
- func (p *Plugin) HandleIdentity(f func(data []byte) (age.Identity, error))
- func (p *Plugin) HandleIdentityAsRecipient(f func(data []byte) (age.Recipient, error))
- func (p *Plugin) HandleIdentityEncoding(f func(identity string) (age.Identity, error))
- func (p *Plugin) HandleIdentityEncodingAsRecipient(f func(identity string) (age.Recipient, error))
- func (p *Plugin) HandleRecipient(f func(data []byte) (age.Recipient, error))
- func (p *Plugin) HandleRecipientEncoding(f func(recipient string) (age.Recipient, error))
- func (p *Plugin) IdentityV1() int
- func (p *Plugin) Main() int
- func (p *Plugin) Name() string
- func (p *Plugin) RecipientV1() int
- func (p *Plugin) RegisterFlags(fs *flag.FlagSet)
- func (p *Plugin) RequestValue(prompt string, secret bool) (string, error)
- func (p *Plugin) SetIO(stdin io.Reader, stdout, stderr io.Writer)
- type Recipient
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EncodeHybridRecipient ¶
EncodeHybridRecipient encodes a native MLKEM768-X25519 recipient from a crypto/mlkem.EncapsulationKey768 and a crypto/ecdh.X25519 public key. It's meant for plugins that implement identities that are compatible with native recipients.
func EncodeIdentity ¶
EncodeIdentity encodes a plugin identity string for a plugin with the given name. If the name is invalid, it returns an empty string.
func EncodeRecipient ¶
EncodeRecipient encodes a plugin recipient string for a plugin with the given name. If the name is invalid, it returns an empty string.
func EncodeX25519Recipient ¶
EncodeX25519Recipient encodes a native X25519 recipient from a crypto/ecdh.X25519 public key. It's meant for plugins that implement identities that are compatible with native recipients.
func ParseIdentity ¶
ParseIdentity decodes a plugin identity string. It returns the plugin name in lowercase and the encoded data.
Types ¶
type ClientUI ¶
type ClientUI struct {
// DisplayMessage displays the message, which is expected to have lowercase
// initials and no final period.
DisplayMessage func(name, message string) error
// RequestValue requests a secret or public input, with the provided prompt.
RequestValue func(name, prompt string, secret bool) (string, error)
// Confirm requests a confirmation with the provided prompt. The yes and no
// value are the choices provided to the user. no may be empty. The return
// value indicates whether the user selected the yes or no option.
Confirm func(name, prompt, yes, no string) (choseYes bool, err error)
// WaitTimer is invoked once (Un)Wrap has been waiting for 5 seconds on the
// plugin, for example because the plugin is waiting for an external event
// (e.g. a hardware token touch). Unlike the other callbacks, WaitTimer runs
// in a separate goroutine, and if missing it's simply ignored.
WaitTimer func(name string)
}
ClientUI holds callbacks that will be invoked by (Un)Wrap if the plugin wishes to interact with the user. If any of them is nil or returns an error, failure will be reported to the plugin, but note that the error is otherwise discarded. Implementations are encouraged to display errors to the user before returning them.
func NewTerminalUI ¶
NewTerminalUI returns a ClientUI that uses the terminal to request inputs, and the provided functions to display messages and errors.
The terminal is reached directly through /dev/tty or CONIN$/CONOUT$, bypassing standard input and output, so this UI can be used even when standard input or output are redirected.
type Identity ¶
type Identity struct {
// contains filtered or unexported fields
}
func NewIdentityWithoutData ¶
func (*Identity) Name ¶
Name returns the plugin name, which is used in the recipient ("age1name1...") and identity ("AGE-PLUGIN-NAME-1...") encodings, as well as in the plugin binary name ("age-plugin-name").
func (*Identity) Recipient ¶
Recipient returns a Recipient wrapping this identity. When that Recipient is used to encrypt a file key, the identity encoding is provided as-is to the plugin, which is expected to support encrypting to identities.
type NotFoundError ¶
type NotFoundError struct {
// Name is the plugin (not binary) name.
Name string
// Err is the underlying error, usually an [exec.Error] wrapping
// [exec.ErrNotFound].
Err error
}
NotFoundError is returned by Recipient.Wrap and Identity.Unwrap when the plugin binary cannot be found.
func (*NotFoundError) Error ¶
func (e *NotFoundError) Error() string
func (*NotFoundError) Unwrap ¶
func (e *NotFoundError) Unwrap() error
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is a framework for writing age plugins. It allows exposing regular age.Recipient and age.Identity implementations as plugins, and handles all the protocol details.
Example (Main) ¶
package main
import (
"log"
"os"
"github.com/luxfi/age"
"github.com/luxfi/age/plugin"
)
type Recipient struct{}
func (r *Recipient) Wrap(fileKey []byte) ([]*age.Stanza, error) {
panic("unimplemented")
}
func NewRecipient(data []byte) (*Recipient, error) {
return &Recipient{}, nil
}
type Identity struct{}
func (i *Identity) Unwrap(s []*age.Stanza) ([]byte, error) {
panic("unimplemented")
}
func NewIdentity(data []byte) (*Identity, error) {
return &Identity{}, nil
}
func main() {
p, err := plugin.New("example")
if err != nil {
log.Fatal(err)
}
p.HandleRecipient(func(data []byte) (age.Recipient, error) {
return NewRecipient(data)
})
p.HandleIdentity(func(data []byte) (age.Identity, error) {
return NewIdentity(data)
})
os.Exit(p.Main())
}
Output:
func New ¶
New creates a new Plugin with the given name.
For example, a plugin named "frood" would be invoked as "age-plugin-frood".
func (*Plugin) Confirm ¶
Confirm requests a confirmation from the user through the client, with the provided prompt. The yes and no value are the choices provided to the user. no may be empty. The return value choseYes indicates whether the user selected the yes or no option. Confirm returns an error if the client can't request the confirmation.
It must only be called by a Wrap or Unwrap method invoked by Plugin.Main.
func (*Plugin) DisplayMessage ¶
DisplayMessage requests that the client display a message to the user. The message should start with a lowercase letter and have no final period. DisplayMessage returns an error if the client can't display the message, and may return before the message has been displayed to the user.
It must only be called by a Wrap or Unwrap method invoked by Plugin.Main.
func (*Plugin) HandleIdentity ¶
HandleIdentity registers a function to parse identities of the form AGE-PLUGIN-NAME-1... into age.Identity values. data is the decoded Bech32 payload.
It must be called before Plugin.Main, and can be called at most once. Otherwise, it panics.
func (*Plugin) HandleIdentityAsRecipient ¶
HandleIdentityAsRecipient registers a function to parse identities of the form AGE-PLUGIN-NAME-1... into age.Recipient values, for when identities are used as recipients. data is the decoded Bech32 payload.
If the returned Recipient implements age.RecipientWithLabels, Plugin will use it and enforce consistency across every returned stanza in an execution. If the client supports labels, they will be passed through the protocol.
It must be called before Plugin.Main, and can be called at most once. Otherwise, it panics.
func (*Plugin) HandleIdentityEncoding ¶
HandleIdentityEncoding is like Plugin.HandleIdentity but provides the full identity encoding string to the callback.
It allows using functions like ParseIdentity directly.
func (*Plugin) HandleIdentityEncodingAsRecipient ¶
HandleIdentityEncodingAsRecipient is like Plugin.HandleIdentityAsRecipient but provides the full identity encoding string to the callback.
func (*Plugin) HandleRecipient ¶
HandleRecipient registers a function to parse recipients of the form age1name1... into age.Recipient values. data is the decoded Bech32 payload.
If the returned Recipient implements age.RecipientWithLabels, Plugin will use it and enforce consistency across every returned stanza in an execution. If the client supports labels, they will be passed through the protocol.
It must be called before Plugin.Main, and can be called at most once. Otherwise, it panics.
func (*Plugin) HandleRecipientEncoding ¶
HandleRecipientEncoding is like Plugin.HandleRecipient but provides the full recipient encoding string to the callback.
It allows using functions like ParseRecipient directly.
func (*Plugin) IdentityV1 ¶
IdentityV1 implements the identity-v1 state machine. It returns an exit code to pass to os.Exit.
Most plugins should call Plugin.Main instead of this method.
func (*Plugin) Main ¶
Main runs the plugin protocol. It returns an exit code to pass to os.Exit.
It automatically calls Plugin.RegisterFlags and flag.Parse if they were not called before.
func (*Plugin) RecipientV1 ¶
RecipientV1 implements the recipient-v1 state machine. It returns an exit code to pass to os.Exit.
Most plugins should call Plugin.Main instead of this method.
func (*Plugin) RegisterFlags ¶
RegisterFlags registers the plugin's flags with the given flag.FlagSet, or with the default flag.CommandLine if fs is nil. It must be called before flag.Parse and Plugin.Main.
This allows the plugin to expose additional flags when invoked manually, for example to implement a keygen mode.
func (*Plugin) RequestValue ¶
RequestValue requests a secret or public input from the user through the client, with the provided prompt. It returns an error if the client can't request the input or if the user dismisses the prompt.
It must only be called by a Wrap or Unwrap method invoked by Plugin.Main.
type Recipient ¶
type Recipient struct {
// contains filtered or unexported fields
}
func (*Recipient) Name ¶
Name returns the plugin name, which is used in the recipient ("age1name1...") and identity ("AGE-PLUGIN-NAME-1...") encodings, as well as in the plugin binary name ("age-plugin-name").
func (*Recipient) String ¶
String returns the recipient encoding string ("age1name1...") or "<identity-based recipient>" if r was created by Identity.Recipient.
Source Files