scep

package
v0.0.0-...-29c6822 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 3, 2018 License: MIT, MIT Imports: 14 Imported by: 0

README

scep is a Simple Certificate Enrollment Protocol server and client

Installation

A binary release is available on the releases page.

Compiling

To compile the SCEP client and server, there are a few requirements.

  • You must have a Go compiler. The compiler is normally in the golang package.
  • You must have a shell variable set for $GOPATH. This is a directory used by the Go compiler and utilities for all Go projects.
  1. Once all of those are set, clone the repository with go get github.com/micromdm/scep
  2. Install dependencies: make deps
  3. Compile the server and client binaries: make build The binaries will be compiled in the build/ folder.

Example

Minimal example for both server and client.

# create a new CA
scepserver ca -init
# start server
scepserver -depot depot -port 2016 -challenge=secret

# SCEP request:
# in a separate terminal window, run a client
# note, if the client.key doesn't exist, the client will create a new rsa private key. Must be in PEM format.
scepclient -private-key client.key -server-url=http://scep.groob.io:2016/scep -challenge=secret

# NDES request:
# note, this should point to an NDES server, scepserver does not provide NDES.
scepclient -private-key client.key -server-url=https://scep.example.com:4321/certsrv/mscep/ -ca-fingerprint="81C827D2 3DAAF3B4 73999632 67609B30"

Server Usage

The default flags configure and run the scep server.
depot must be the path to a folder with ca.pem and ca.key files.

If you don't already have a CA to use, you can create one using the scep ca subcommand.

The scepserver currently provides one HTTP endpoint /scep.

Usage of ./cmd/scepserver/scepserver:
  -allowrenew string
    	do not allow renewal until n days before expiry, set to 0 to always allow (default "14")
  -capass string
    	passwd for the ca.key
  -challenge string
    	enforce a challenge password
  -crtvalid string
    	validity for new client certificates in days (default "365")
  -csrverifierexec string
    	will be passed the CSRs for verification
  -debug
    	enable debug logging
  -depot string
    	path to ca folder (default "depot")
  -log-json
    	output JSON logs
  -port string
    	port to listen on (default "8080")
  -version
    	prints version information

scep ca -init to create a new CA and private key.

Usage of ./cmd/scepserver/scepserver ca:
  -country string
    	country for CA cert (default "US")
  -depot string
    	path to ca folder (default "depot")
  -init
    	create a new CA
  -key-password string
    	password to store rsa key
  -keySize int
    	rsa key size (default 4096)
  -organization string
    	organization for CA cert (default "scep-ca")
  -years int
    	default CA years (default 10)

Client Usage

Usage of scepclient:
  -ca-fingerprint string
    	md5 fingerprint of CA certificate for NDES server.
  -certificate string
    	certificate path, if there is no key, scepclient will create one
  -challenge string
    	enforce a challenge password
  -cn string
    	common name for certificate (default "scepclient")
  -country string
    	country code in certificate (default "US")
  -debug
    	enable debug logging
  -keySize int
    	rsa key size (default 2048)
  -locality string
    	locality for certificate
  -log-json
    	use JSON for log output
  -organization string
    	organization for cert (default "scep-client")
  -ou string
    	organizational unit for certificate (default "MDM")
  -private-key string
    	private key path, if there is no key, scepclient will create one
  -province string
    	province for certificate
  -server-url string
    	SCEP server url
  -version
    	prints version information

Note: Make sure to specify the desired endpoint in your -server-url value (e.g. 'http://scep.groob.io:2016/scep')

To obtain a certificate through Network Device Enrollment Service (NDES), set -server-url to a server that provides NDES. This most likely uses the /certsrv/mscep path instead. You will need to add the -ca-fingerprint client argument during this request.

Docker

docker pull micromdm/scep
# create CA
docker run -it --rm -v /path/to/ca/folder:/depot micromdm/scep ./scep ca -init

# run
docker run -it --rm -v /path/to/ca/folder:/depot -p 8080:8080 micromdm/scep

SCEP library

go get github.com/micromdm/scep/scep

For detailed usage, see godoc

Example:

// read a request body containing SCEP message
body, err := ioutil.ReadAll(r.Body)
if err != nil {
    // handle err
}

// parse the SCEP message
msg, err := scep.ParsePKIMessage(body)
if err != nil {
    // handle err
}

// do something with msg
fmt.Println(msg.MessageType)

// extract encrypted pkiEnvelope
err := msg.DecryptPKIEnvelope(CAcert, CAkey)
if err != nil {
    // handle err
}

// use the csr from decrypted PKCRS request
csr := msg.CSRReqMessage.CSR

// create cert template
tmpl := &x509.Certificate{
	SerialNumber: big.NewInt(1),
	Subject:      csr.Subject,
	NotBefore:    time.Now().Add(-600).UTC(),
	NotAfter:     time.Now().AddDate(1, 0, 0).UTC(),
	SubjectKeyId: id,
	ExtKeyUsage: []x509.ExtKeyUsage{
		x509.ExtKeyUsageAny,
		x509.ExtKeyUsageClientAuth,
	},
}

// create a CertRep message from the original
certRep, err := msg.SignCSR(CAcert, CAkey, tmlp)
if err != nil {
    // handle err
}

// send response back
// w is a http.ResponseWriter
w.Write(certRep.Raw)

Server library

You can import the scep endpoint into another Go project. For an example take a look at cmd/scep/main.go

Documentation

Overview

Package scep provides common functionality for encoding and decoding Simple Certificate Enrolment Protocol pki messages as defined by https://tools.ietf.org/html/draft-gutmann-scep-02

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CACerts 

func CACerts(data []byte) ([]*x509.Certificate, error)

CACerts extract CA Certificate or chain from pkcs7 degenerate signed data

func DegenerateCertificates 

func DegenerateCertificates(certs []*x509.Certificate) ([]byte, error)

DegenerateCertificates creates degenerate certificates pkcs#7 type

Types

type CSRReqMessage 

type CSRReqMessage struct {
	RawDecrypted []byte

	// PKCS#10 Certificate request inside the envelope
	CSR *x509.CertificateRequest

	ChallengePassword string
}

CSRReqMessage can be of the type PKCSReq/RenewalReq/UpdateReq and includes a PKCS#10 CSR request. The content of this message is protected by the recipient public key(example CA)

type CertRepMessage 

type CertRepMessage struct {
	PKIStatus
	RecipientNonce
	FailInfo

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

CertRepMessage is a type of PKIMessage

type FailInfo 

type FailInfo string

FailInfo is a SCEP failInfo attribute

The FailInfo attribute MUST contain one of the following failure reasons: 

const (
	BadAlg          FailInfo = "0"
	BadMessageCheck FailInfo = "1"
	BadRequest      FailInfo = "2"
	BadTime         FailInfo = "3"
	BadCertID       FailInfo = "4"
)

func (FailInfo) String 

func (info FailInfo) String() string

type MessageType 

type MessageType string

The MessageType attribute specifies the type of operation performed by the transaction. This attribute MUST be included in all PKI messages.

The following message types are defined: 

const (
	CertRep    MessageType = "3"
	RenewalReq MessageType = "17"
	UpdateReq  MessageType = "18"
	PKCSReq    MessageType = "19"
	CertPoll   MessageType = "20"
	GetCert    MessageType = "21"
	GetCRL     MessageType = "22"
)

Undefined message types are treated as an error.

func (MessageType) String 

func (msg MessageType) String() string

type Option 

type Option func(*config)

Option specifies custom configuration for SCEP.

func WithLogger 

func WithLogger(logger log.Logger) Option

WithLogger adds option logging to the SCEP operations.

type PKIMessage 

type PKIMessage struct {
	TransactionID
	MessageType
	SenderNonce
	*CertRepMessage
	*CSRReqMessage

	// DER Encoded PKIMessage
	Raw []byte

	// Used to sign message
	Recipients []*x509.Certificate

	// Signer info
	SignerKey  *rsa.PrivateKey
	SignerCert *x509.Certificate

	SCEPEncryptionAlgorithm int
	// contains filtered or unexported fields
}

PKIMessage defines the possible SCEP message types

func NewCSRRequest 

func NewCSRRequest(csr *x509.CertificateRequest, tmpl *PKIMessage, opts ...Option) (*PKIMessage, error)

NewCSRRequest creates a scep PKI PKCSReq/UpdateReq message

func ParsePKIMessage 

func ParsePKIMessage(data []byte, opts ...Option) (*PKIMessage, error)

ParsePKIMessage unmarshals a PKCS#7 signed data into a PKI message struct

func (*PKIMessage) DecryptPKIEnvelope 

func (msg *PKIMessage) DecryptPKIEnvelope(cert *x509.Certificate, key *rsa.PrivateKey) error

DecryptPKIEnvelope decrypts the pkcs envelopedData inside the SCEP PKIMessage

func (*PKIMessage) Fail 

func (msg *PKIMessage) Fail(crtAuth *x509.Certificate, keyAuth *rsa.PrivateKey, info FailInfo) (*PKIMessage, error)

func (*PKIMessage) SignCSR 

func (msg *PKIMessage) SignCSR(crtAuth *x509.Certificate, keyAuth *rsa.PrivateKey, template *x509.Certificate) (*PKIMessage, error)

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

type PKIStatus 

type PKIStatus string

PKIStatus is a SCEP pkiStatus attribute which holds transaction status information. All SCEP responses MUST include a pkiStatus.

The following pkiStatuses are defined: 

const (
	SUCCESS PKIStatus = "0"
	FAILURE PKIStatus = "2"
	PENDING PKIStatus = "3"
)

Undefined pkiStatus attributes are treated as an error

type RecipientNonce 

type RecipientNonce []byte

The RecipientNonce MUST be copied from the SenderNonce and included in the reply.

type SenderNonce 

type SenderNonce []byte

SenderNonce is a random 16 byte number. A sender must include the senderNonce in each transaction to a recipient.

type TransactionID 

type TransactionID string

The TransactionID is a text string generated by the client when starting a transaction. The client MUST generate a unique string as the transaction identifier, which MUST be used for all PKI messages exchanged for a given enrolment, encoded as a PrintableString.

Source Files

View all Source files

Directories

Path Synopsis
Package challenge defines an interface for a dynamic challenge password cache.
 Package challenge defines an interface for a dynamic challenge password cache.
bolt
crypto
x509util
package x509 provides utilities for working with x509 types.
 package x509 provides utilities for working with x509 types.
Package csrverifier defines an interface for CSR verification.
 Package csrverifier defines an interface for CSR verification.
executable
Package executablecsrverifier defines the ExecutableCSRVerifier csrverifier.CSRVerifier.
 Package executablecsrverifier defines the ExecutableCSRVerifier csrverifier.CSRVerifier.
bolt
file
Package pkcs7 implements parsing and generation of some PKCS#7 structures.
 Package pkcs7 implements parsing and generation of some PKCS#7 structures.
internal/x509util
package x509 provides utilities for working with x509 types.
 package x509 provides utilities for working with x509 types.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.