sshcert

README

sshcert

sshcert is a package and CLI for handling SSH user certs. Consult the Getting Started Guide to get started!

Installation

go get github.com/ejcx/sshcert

Usage

Creating an SSH certificate authority

Calling NewCA will create a new SSH user certificate authority.

ca, err := NewCA()

Signing an SSH user certificate

The SignCert method is used to sign a new certificate to provide access to a server who is trusting a certificate.

SignCert requires an ssh.PublicKey and SigningArguments be passed in order to sign a public key.

NewSigningArguments can be used to instantiate a SigningArgument struct. Pass NewSigningArguments the list of Linux users that you providing the cert to. If you wish to log in as root (which is a bad practice) pass root.

sa := NewSigningArguments([]string{"evan"})
ca.SignCert(evanPublicKey, sa)

Marshalling and Unmarshalling a CA

CA cannot be marshalled using the json package. Instead call Bytes to convert the SSH key to it's binary format, or call PrivateString to convert the CA to a PEM encoded private key, that can then be converted back to a CA using ParsePrivateString

Converting to binary format

buf, err := ca.Bytes()
if err != nil {
    log.Fatalf("Could not parse CA: %s", err)
}

To unmarshal call FromBytes.

var ca sshcert.CA
err := ca.FromBytes(buf)
if err != nil {
    log.Fatalf("Could not parse CA: %s", err)
}

Converting to PEM encoded format

pemKey, err := ca.PrivateString()
if err != nil {
    log.Fatalf("Could not convert CA to PEM encoded key: %s", err)
}

var newCA sshcert.CA
err = newCA.ParsePrivateString(pemKey)
if err != nil {
    log.Fatalf("Could not convert the PEM encoded key into CA: %s", err)
}

Documentation

Index

• Variables
• func ParsePublicKey(pub string) (ssh.PublicKey, error)
• type CA
  • func NewCA() (CA, error)
  • func (c *CA) Bytes() ([]byte, error)
  • func (c *CA) FromBytes(data []byte) error
  • func (c *CA) ParsePrivateString(data []byte) error
  • func (c *CA) PrivateString() (string, error)
  • func (c *CA) SetName(name string)
  • func (c *CA) SignCert(pub ssh.PublicKey, signArgs *SigningArguments) (*Cert, error)
  • func (c *CA) Signer() ssh.Signer
  • func (c *CA) String() string
• type Cert
  • func (c *Cert) String() string
  • func (c *Cert) Type() string
• type SigningArguments
  • func NewSigningArguments(principals []string) *SigningArguments
  • func (s *SigningArguments) SetDuration(d time.Duration)
  • func (s *SigningArguments) SetPermissions(permissions ssh.Permissions)
  • func (s *SigningArguments) SetPrincipals(principals []string)

Examples

• NewCA
• ParsePublicKey

Variables

var (
	// DefaultPermissions are the default permissions associated with the
	// signing of an ssh user certificate. In this case, we specify three
	// extensions.
	// - permit-pty:
	//     Is set because creating a new pty on connection is required for
	//     the best shell ux.
	// - permit-user-rc:
	//     Allow users to forward their ssh agent to use jumpboxes.
	// - permit-agent-forwarding
	//     Allows your engineers to utilize a jumpbox seamlessly.
	DefaultPermissions = ssh.Permissions{
		Extensions: map[string]string{
			"permit-pty":              "",
			"permit-user-rc":          "",
			"permit-port-forwarding":  "",
			"permit-agent-forwarding": "",
		},
	}
)

Functions

func ParsePublicKey

func ParsePublicKey(pub string) (ssh.PublicKey, error)

ParsePublicKey will parse and return an SSH public key from it's non-wire format.

Example

// To parse ssh public keys
pubBytes, _ := ioutil.ReadFile("example.pub")
pubKey, err := ParsePublicKey(string(pubBytes))
if err != nil {
	log.Fatalf("Could not parse public key: %s", err)
}
fmt.Println(pubKey)

Types

type CA

type CA struct {
	PrivateKey *ecdsa.PrivateKey
	// contains filtered or unexported fields
}

CA represents an SSH certificate authority.

func NewCA

func NewCA() (CA, error)

NewCA will instantiate a new CA and generate a fresh ecdsa Private key.

Example

// Your CA is has sensitive fields. It contains a PrivateKey
// that is the root of all trust in your infrastructure.
ca, err := NewCA()
if err != nil {
	log.Fatalf("Could not create new ca: %s", err)
}
// This will print the public key of your certificate authority
// in a format that can be used by the `TrustedUserCAKeys` sshd
// config directive.
fmt.Println(ca)

func (*CA) Bytes

func (c *CA) Bytes() ([]byte, error)

Bytes converts the certificate authority private key to it's SSH key bytes.

func (*CA) FromBytes

func (c *CA) FromBytes(data []byte) error

FromBytes hydreates a CA with the private key bytes.

func (*CA) ParsePrivateString

func (c *CA) ParsePrivateString(data []byte) error

ParsePrivateString hydrates a CA type with a PEM encoded private key. This method will modify the CA's private key.

func (*CA) PrivateString

func (c *CA) PrivateString() (string, error)

PrivateString converts a CA in to a PEM encoded private key

func (*CA) SetName

func (c *CA) SetName(name string)

func (*CA) SignCert

func (c *CA) SignCert(pub ssh.PublicKey, signArgs *SigningArguments) (*Cert, error)

SignCert is called to sign an ssh public key and produce an ssh certificate. It's required to pass in SigningArguments or the signing will fail.

func (*CA) Signer

func (c *CA) Signer() ssh.Signer

Signer returns the signer associated with a private key.

func (*CA) String

func (c *CA) String() string

String will output the public key of the Certificate Authority that is used with the `TrustedUserCAKeys` directive in an sshd config.

type Cert

type Cert struct {
	Certificate *ssh.Certificate
}

Cert represents an SSH public key that has been signed by a certificate authority.

func (*Cert) String

func (c *Cert) String() string

String will output the SSH certificate in a format that can be used with an ssh client.

func (*Cert) Type

func (c *Cert) Type() string

Type returns the certificate's algorithm name.

type SigningArguments

type SigningArguments struct {
	Principals  []string
	Permissions ssh.Permissions
	Duration    time.Duration
}

SigningArguments is the information that the SSH Certificate Authority needs in order to sign an SSH public key. All of these fields are required. If you would like to read more about how to configure the SigningArguments then I found the following to be a good source of information:

• https://github.com/metacloud/openssh/blob/master/PROTOCOL.certkeys

If you would like to use default settings then call `NewSigningArguments`

func NewSigningArguments

func NewSigningArguments(principals []string) *SigningArguments

NewSigningArguments will create a default SigningArguments type with the principals passed in. The list of principals passed in to this function is the list of linux users that the user will be able to ssh to.

func (*SigningArguments) SetDuration

func (s *SigningArguments) SetDuration(d time.Duration)

SetDuration will set the duration of a SigningArguments type.

func (*SigningArguments) SetPermissions

func (s *SigningArguments) SetPermissions(permissions ssh.Permissions)

SetPermissions will set the permissions of a SigningArguments type.

func (*SigningArguments) SetPrincipals

func (s *SigningArguments) SetPrincipals(principals []string)

// SetPrincipals will set the principals of a SigningArguments type.