scep

Documentation

Overview

Package scep implements Simple Certificate Enrollment Protocol related functionality.

Index

• func NewContext(ctx context.Context, a *Authority) context.Context
• func NewProvisionerContext(ctx context.Context, p Provisioner) context.Context
• type Authority
  • func FromContext(ctx context.Context) (a *Authority, ok bool)
  • func MustFromContext(ctx context.Context) *Authority
  • func New(signAuth SignAuthority, opts Options) (*Authority, error)
  • func (a *Authority) CreateFailureResponse(ctx context.Context, _ *x509.CertificateRequest, msg *PKIMessage, ...) (*PKIMessage, error)
  • func (a *Authority) DecryptPKIEnvelope(ctx context.Context, msg *PKIMessage) error
  • func (a *Authority) GetCACaps(ctx context.Context) []string
  • func (a *Authority) GetCACertificates(ctx context.Context) (certs []*x509.Certificate, err error)
  • func (a *Authority) LoadProvisionerByName(name string) (provisioner.Interface, error)
  • func (a *Authority) NotifyFailure(ctx context.Context, csr *x509.CertificateRequest, transactionID string, ...) error
  • func (a *Authority) NotifySuccess(ctx context.Context, csr *x509.CertificateRequest, cert *x509.Certificate, ...) error
  • func (a *Authority) SignCSR(ctx context.Context, csr *x509.CertificateRequest, msg *PKIMessage) (*PKIMessage, error)
  • func (a *Authority) UpdateProvisioners(scepProvisionerNames []string)
  • func (a *Authority) Validate() error
  • func (a *Authority) ValidateChallenge(ctx context.Context, csr *x509.CertificateRequest, ...) error
• type CertRepMessage
• type FailInfo
• type FailInfoName
• type Options
  • func (o *Options) Validate() error
• type PKIMessage
• type Provisioner
• type SignAuthority

Functions

func NewContext

func NewContext(ctx context.Context, a *Authority) context.Context

NewContext adds the given authority to the context.

func NewProvisionerContext

func NewProvisionerContext(ctx context.Context, p Provisioner) context.Context

Types

type Authority

type Authority struct {
	// contains filtered or unexported fields
}

Authority is the layer that handles all SCEP interactions.

func FromContext

func FromContext(ctx context.Context) (a *Authority, ok bool)

FromContext returns the current authority from the given context.

func MustFromContext

func MustFromContext(ctx context.Context) *Authority

MustFromContext returns the current authority from the given context. It will panic if the authority is not in the context.

func New

func New(signAuth SignAuthority, opts Options) (*Authority, error)

New returns a new Authority that implements the SCEP interface.

func (*Authority) CreateFailureResponse

func (a *Authority) CreateFailureResponse(ctx context.Context, _ *x509.CertificateRequest, msg *PKIMessage, info FailInfoName, infoText string) (*PKIMessage, error)

CreateFailureResponse creates an appropriately signed reply for PKI operations

func (*Authority) DecryptPKIEnvelope

func (a *Authority) DecryptPKIEnvelope(ctx context.Context, msg *PKIMessage) error

DecryptPKIEnvelope decrypts an enveloped message

func (*Authority) GetCACaps

func (a *Authority) GetCACaps(ctx context.Context) []string

GetCACaps returns the CA capabilities

func (*Authority) GetCACertificates

func (a *Authority) GetCACertificates(ctx context.Context) (certs []*x509.Certificate, err error)

GetCACertificates returns the certificate (chain) for the CA.

This methods returns the "SCEP Server (RA)" certificate, the issuing CA up to and excl. the root. Some clients do need the root certificate however; also see: https://github.com/openxpki/openxpki/issues/73

In case a provisioner specific decrypter is available, this is used as the "SCEP Server (RA)" certificate instead of the CA intermediate directly. This uses a distinct instance of a KMS for doing the SCEP key operations, so that RSA can be used for just SCEP.

Using an RA does not seem to exist in https://tools.ietf.org/html/rfc8894, but is mentioned in https://tools.ietf.org/id/draft-nourse-scep-21.html.

func (*Authority) LoadProvisionerByName

func (a *Authority) LoadProvisionerByName(name string) (provisioner.Interface, error)

LoadProvisionerByName calls out to the SignAuthority interface to load a provisioner by name.

func (*Authority) NotifyFailure

func (a *Authority) NotifyFailure(ctx context.Context, csr *x509.CertificateRequest, transactionID string, errorCode int, errorDescription string) error

func (*Authority) NotifySuccess

func (a *Authority) NotifySuccess(ctx context.Context, csr *x509.CertificateRequest, cert *x509.Certificate, transactionID string) error

func (*Authority) SignCSR

func (a *Authority) SignCSR(ctx context.Context, csr *x509.CertificateRequest, msg *PKIMessage) (*PKIMessage, error)

SignCSR creates an x509.Certificate based on a CSR template and Cert Authority credentials returns a new PKIMessage with CertRep data

func (*Authority) UpdateProvisioners

func (a *Authority) UpdateProvisioners(scepProvisionerNames []string)

UpdateProvisioners updates the SCEP Authority with the new, and hopefully current SCEP provisioners configured. This allows the Authority to be validated with the latest data.

func (*Authority) Validate

func (a *Authority) Validate() error

Validate validates if the SCEP Authority has a valid configuration. The validation includes a check if a decrypter is available, either an authority wide decrypter, or a provisioner specific decrypter.

func (*Authority) ValidateChallenge

func (a *Authority) ValidateChallenge(ctx context.Context, csr *x509.CertificateRequest, challenge, transactionID string) error

type CertRepMessage

type CertRepMessage struct {
	smallscep.PKIStatus
	smallscep.RecipientNonce
	smallscep.FailInfo

	Certificate *x509.Certificate
	// contains filtered or unexported fields
}

CertRepMessage is a type of PKIMessage

type FailInfo

type FailInfo struct {
	Name FailInfoName
	Text string
}

FailInfo models a failInfo object consisting of a name/identifier and a failInfoText, the latter of which can be more descriptive and is intended to be read by humans.

type FailInfoName

type FailInfoName smallscep.FailInfo

FailInfoName models the name/value of failInfo

type Options

type Options struct {
	// Roots contains the (federated) CA roots certificate(s)
	Roots []*x509.Certificate `json:"-"`
	// Intermediates points issuer certificate, along with any other bundled certificates
	// to be returned in the chain for consumers.
	Intermediates []*x509.Certificate `json:"-"`
	// SignerCert points to the certificate of the CA signer. It usually is the same as the
	// first certificate in the CertificateChain.
	SignerCert *x509.Certificate `json:"-"`
	// Signer signs CSRs in SCEP. Configured in the ca.json key property.
	Signer crypto.Signer `json:"-"`
	// Decrypter decrypts encrypted SCEP messages. Configured in the ca.json key property.
	Decrypter crypto.Decrypter `json:"-"`
	// DecrypterCert points to the certificate of the CA decrypter.
	DecrypterCert *x509.Certificate `json:"-"`
	// SCEPProvisionerNames contains the currently configured SCEP provioner names. These
	// are used to be able to load the provisioners when the SCEP authority is being
	// validated.
	SCEPProvisionerNames []string
}

func (*Options) Validate

func (o *Options) Validate() error

Validate checks the fields in Options.

type PKIMessage

type PKIMessage struct {
	smallscep.TransactionID
	smallscep.MessageType
	smallscep.SenderNonce
	*smallscep.CSRReqMessage

	*CertRepMessage

	// DER Encoded PKIMessage
	Raw []byte

	// parsed
	P7 *pkcs7.PKCS7

	// Used to sign message
	Recipients []*x509.Certificate
	// contains filtered or unexported fields
}

PKIMessage defines the possible SCEP message types

type Provisioner

type Provisioner interface {
	provisioner.Interface
	GetOptions() *provisioner.Options
	GetCapabilities() []string
	ShouldIncludeRootInChain() bool
	ShouldIncludeIntermediateInChain() bool
	GetDecrypter() (*x509.Certificate, crypto.Decrypter)
	GetSigner() (*x509.Certificate, crypto.Signer)
	GetContentEncryptionAlgorithm() int
	ValidateChallenge(ctx context.Context, csr *x509.CertificateRequest, challenge, transactionID string) error
	NotifySuccess(ctx context.Context, csr *x509.CertificateRequest, cert *x509.Certificate, transactionID string) error
	NotifyFailure(ctx context.Context, csr *x509.CertificateRequest, transactionID string, errorCode int, errorDescription string) error
}

Provisioner is an interface that embeds the provisioner.Interface and adds some SCEP specific functions.

type SignAuthority

type SignAuthority interface {
	SignWithContext(ctx context.Context, cr *x509.CertificateRequest, opts provisioner.SignOptions, signOpts ...provisioner.SignOption) ([]*x509.Certificate, error)
	LoadProvisionerByName(string) (provisioner.Interface, error)
}

SignAuthority is the interface for a signing authority