csr

Documentation

Overview

Package csr defines the structures and interfaces to generate certificate signing requests.

Index

• type AgentKey
• type Generator
• type ReqParam
  • func NewReqParam(envGetter func(string) string, osArgsGetter func() []string) (*ReqParam, error)
  • func (p *ReqParam) Validate() error
• type Signer

Types

type AgentKey

type AgentKey interface {
	CSRs() []*proto.SSHCertificateSigningRequest
	AddCertsToAgent(certs []ssh.PublicKey, comments []string) error
}

AgentKey represents a private key in ssh agent, but also holds certificate signing requests. It interacts with the client agent to insert certificates. A CSR agent key operates certificates for one private key only.

type Generator

type Generator interface {
	// Generate generates certificate signing requests given by the request param,
	// and returns agent keys containing those CSRs.
	Generate(*ReqParam) ([]AgentKey, error)
}

Generator contains the methods to generate agent keys containing CSRs.

type ReqParam

type ReqParam struct {
	// TODO: rewrite this comment. It is still confusing for new users.
	// NamespacePolicy indicates the policy whether requester is authorized to request a principal under another
	// namespace, such as “Screwdriver:xxxx”.
	// Possible values:
	// 1. NSOK (Name Space OK)
	// It means the requested principals can be included in another namespace, such as xxx can be included in "Screwdriver".
	// 2. NONS (NO Name Space)
	// It means the ssh principal should start with the requested principal, such as "user:touch".
	NamespacePolicy common.NamespacePolicy
	// TODO: re-think do we need HandlerName field. It seems no entity relies on it.
	// HandlerName indicates which handler should handle the certificate request and generate CSRs.
	// Users may define their own handler names.
	HandlerName string
	ClientIP    string
	// LogName is the name of the user who is currently interacts with the current SSHD server.
	LogName string
	// ReqUser is the user name that sends request to RA.
	ReqUser string
	// ReqHost is the user host name that sends request to RA.
	ReqHost string
	// TransID stands for transaction ID and serves as the unique identifier for a request.
	// It should be generated on server-side right after receiving client request.
	TransID string
	// SSHClientVersion is the version of the SSH Client.
	SSHClientVersion version.Version
	// SignatureAlgo is the signing algorithm of the requested certificate.
	SignatureAlgo x509.SignatureAlgorithm
	// Attrs stores information that client passes to RA, containing attributes of SSH certificate that the client requests for.
	Attrs *message.Attributes
}

ReqParam stores options to invoke gensign.Handler.

func NewReqParam

func NewReqParam(envGetter func(string) string, osArgsGetter func() []string) (*ReqParam, error)

NewReqParam initializes a ReqParam properly. If any required field is missing or invalid, an error will be returned. envGetter is typically os.Getenv; osArgsGetter typically just returns os.Args.

func (*ReqParam) Validate

func (p *ReqParam) Validate() error

Validate is a standard way for handlers to validate the input ReqParam so that we do not need to implement the input validation in every function that uses ReqParam. Call this function before using the ReqParam. If this function returns nil, every field in ReqParam is valid in format and can be safely used. For example, required field is not empty, ip address string is valid in format, etc. A ReqParam generated by NewReqParam without error should pass this validation. If not there may be some fatal error.

type Signer

type Signer interface {
	// Sign signs the given CSR and returns the signed certificate and the corresponding comment.
	Sign(ctx context.Context, request *proto.SSHCertificateSigningRequest) (cert []ssh.PublicKey, comment []string, err error)
}

Signer describes an external structure that encapsulates the process to sign certificate requests.