vcert

README

This open source project is community-supported. To report a problem or share an idea, use Issues; and if you have a suggestion for fixing the issue, please include those details, too. In addition, use Pull Requests to contribute actual bug fixes or proposed enhancements. We welcome and appreciate all contributions. Got questions or want to discuss something with our team? Join us on Slack!

VCert

VCert is a Go library, SDK, and command line utility designed to simplify key generation and enrollment of machine identities (also known as SSL/TLS certificates and keys) that comply with enterprise security policy by using the Venafi Trust Protection Platform or Venafi as a Service.

See VCert CLI for Venafi Trust Protection Platform or VCert CLI for Venafi as a Service to get started with the command line utility.

Compatibility

VCert releases are tested using the latest version of Trust Protection Platform. General functionality of the latest VCert release should be compatible with Trust Protection Platform 17.3 or higher. Custom Fields and Instance Tracking require TPP 18.2 or higher, and Token Authentication requires TPP 20.1 or higher.

Developer Setup

1. Configure your Go environment according to https://golang.org/doc/install.
2. Verify that GOPATH environment variable is set correctly
3. Download the source code:

go get github.com/Venafi/vcert/v4

or

Pre Go 1.13

git clone https://github.com/Venafi/vcert.git $GOPATH/src/github.com/Venafi/vcert/v4

Go 1.11 with go modules enabled or go 1.13 and up make sure to clone outside of $GOPATH/src

git clone https://github.com/Venafi/vcert.git

1. Build the command line utilities for Linux, MacOS, and Windows:

make build

Using VCert to integrate Venafi with your application

For code samples of programmatic use, please review the files in /examples.

Common part

1. In your main.go file, make the following import declarations: github.com/Venafi/vcert/v4, github.com/Venafi/vcert/v4/pkg/certificate, and github.com/Venafi/vcert/v4/pkg/endpoint.
2. Create a configuration object of type &vcert.Config that specifies the Venafi connection details. Solutions are typically designed to get those details from a secrets vault, .ini file, environment variables, or command line parameters.

Enroll certificate

1. Instantiate a client by calling the NewClient method of the vcert class with the configuration object.
2. Compose a certiticate request object of type &certificate.Request.
3. Generate a key pair and CSR for the certificate request by calling the GenerateRequest method of the client.
4. Submit the request by passing the certificate request object to the RequestCertificate method of the client.
5. Use the request ID to pickup the certificate using the RetrieveCertificate method of the client.

New TLS listener for domain

1. Call vcert.Config method NewListener with list of domains as arguments. For example ("test.example.com:8443", "example.com")
2. Use gotten net.Listener as argument to built-in http.Serve or other https servers.

Samples are in a state where you can build/execute them using the following commands (after setting the environment variables discussed later):

go build -o cli ./example
go test -v ./example -run TestRequestCertificate

Prerequisites for using with Trust Protection Platform

1. A user account that has been granted WebSDK Access
2. A folder (zone) where the user has been granted the following permissions: View, Read, Write, Create, Revoke (for the revoke action), and Private Key Read (for the pickup action when CSR is service generated)
3. Policy applied to the folder which specifies:
   1. CA Template that Trust Protection Platform will use to enroll certificate requests submitted by VCert
   2. Subject DN values for Organizational Unit (OU), Organization (O), City (L), State (ST) and Country (C)
   3. Management Type not locked or locked to 'Enrollment'
   4. Certificate Signing Request (CSR) Generation unlocked or not locked to 'Service Generated CSR'
   5. Generate Key/CSR on Application not locked or locked to 'No'
   6. (Recommended) Disable Automatic Renewal set to 'Yes'
   7. (Recommended) Key Bit Strength set to 2048 or higher
   8. (Recommended) Domain Whitelisting policy appropriately assigned

The requirement for the CA Template to be assigned by policy follows a long standing Venafi best practice which also met our design objective to keep the certificate request process simple for VCert users. If you require the ability to specify the CA Template with the request you can use the TPP REST APIs but please be advised this goes against Venafi recommendations.

Testing with Trust Protection Platform and Venafi as a Service

Unit tests:

make test

Integration tests for Trust Protection Platform and Venafi as a Service require access to those products. Environment variables are used to specify required settings including credentials. The VaaS API key and zone value fragments (i.e. Application Name\Issuing Template API Alias) are readily available in the web interface.

export TPP_URL=https://tpp.venafi.example/vedsdk
export TPP_USER=tpp-user
export TPP_PASSWORD=tpp-password
export TPP_ZONE='some\suggested_policy'
export TPP_ZONE_RESTRICTED='some\locked_policy'
export TPP_ZONE_ECDSA='some\ecdsa_policy'

make tpp_test

export CLOUD_URL=https://api.venafi.cloud/v1
export CLOUD_APIKEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export CLOUD_ZONE='My Application\Permissive CIT'
export CLOUD_ZONE_RESTRICTED='Your Application\Restrictive CIT'

make cloud_test

Command line utility tests make use of Cucumber & Aruba feature files.

• To run tests for all features in parallel:

make cucumber

• To run tests only for a specific feature (e.g. basic, config, enroll, format, gencsr, renew, or revoke):

make cucumber FEATURE=./features/basic/version.feature

When run, these tests will be executed in their own Docker container using the Ruby version of Cucumber.
The completed test run will report on the number of test "scenarios" and "steps" that passed, failed, or were skipped.

Contributing to VCert

Venafi welcomes contributions from the developer community.

1. Fork it to your account (https://github.com/Venafi/vcert/fork)
2. Clone your fork (git clone git@github.com:youracct/vcert.git)
3. Create a feature branch (git checkout -b your-branch-name)
4. Implement and test your changes
5. Commit your changes (git commit -am 'Added some cool functionality')
6. Push to the branch (git push origin your-branch-name)
7. Create a new Pull Request (https://github.com/youracct/vcert/pull/new/your-branch-name)

License

Copyright © Venafi, Inc. All rights reserved.

VCert is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Please direct questions/comments to opensource@venafi.com.

Documentation

Overview

• Copyright 2018 Venafi, Inc. *
• Licensed under the Apache License, Version 2.0 (the "License");
• you may not use this file except in compliance with the License.
• You may obtain a copy of the License at *
• http://www.apache.org/licenses/LICENSE-2.0 *
• Unless required by applicable law or agreed to in writing, software
• distributed under the License is distributed on an "AS IS" BASIS,
• WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
• See the License for the specific language governing permissions and
• limitations under the License.

VCert is a Go library, SDK, and command line utility designed to simplify key generation and enrollment of machine identities (also known as SSL/TLS certificates and keys) that comply with enterprise security policy by using the Venafi Platform or Venafi Cloud.

Index

• func GetFormatedBuildTimeStamp() string
• func GetFormattedVersionString() string
• func NewClient(cfg *Config, args ...interface{}) (endpoint.Connector, error)
• type Config
  • func LoadConfigFromFile(path, section string) (cfg Config, err error)
  • func (cfg *Config) NewClient(args ...interface{}) (connector endpoint.Connector, err error)
  • func (cfg *Config) NewListener(domains ...string) net.Listener

Functions

func GetFormatedBuildTimeStamp

func GetFormatedBuildTimeStamp() string

func GetFormattedVersionString

func GetFormattedVersionString() string

GetFormattedVersionString gets a friendly printable string to represent the version

func NewClient

func NewClient(cfg *Config, args ...interface{}) (endpoint.Connector, error)

NewClient returns a connector for either Trust Protection Platform (TPP) or Venafi Cloud based on provided configuration. Config should have Credentials compatible with the selected ConnectorType. Returned connector is a concurrency-safe interface to TPP or Venafi Cloud that can be reused without restriction. Connector can also be of type "fake" for local tests, which doesn't connect to any backend and all certificates enroll locally. The returned connector will be authenticated by default, but it's possible to pass a bool argument to indicate if it's desired to get the connector authenticated already or not.

Types

type Config

type Config struct {
	// ConnectorType specify what do you want to use. May be "Cloud", "TPP" or "Fake" for development.
	ConnectorType endpoint.ConnectorType
	// BaseUrl should be specified for Venafi Platform. Optional for Cloud implementations that do not use https://venafi.cloud/.
	BaseUrl string
	// Zone is name of a policy zone in Venafi Platform or Cloud. For TPP, if necessary, escape backslash symbols.   For example,  "test\\zone" or `test\zone`.
	Zone string
	// Credentials should contain either User and Password for TPP connections or an APIKey for Cloud.
	Credentials *endpoint.Authentication
	// ConnectionTrust  may contain a trusted CA or certificate of server if you use self-signed certificate.
	ConnectionTrust string // *x509.CertPool
	LogVerbose      bool
	// http.Client to use durring construction
	Client *http.Client
}

Config is a basic structure for high level initiating connector to Trust Platform (TPP)/Venafi Cloud

func LoadConfigFromFile

func LoadConfigFromFile(path, section string) (cfg Config, err error)

LoadConfigFromFile is deprecated. In the future will be rewrited.

func (*Config) NewClient

func (cfg *Config) NewClient(args ...interface{}) (connector endpoint.Connector, err error)

NewClient returns a connector for either Trust Protection Platform (TPP) or Venafi Cloud based on provided configuration. Config should have Credentials compatible with the selected ConnectorType. Returned connector is a concurrency-safe interface to TPP or Venafi Cloud that can be reused without restriction. Connector can also be of type "fake" for local tests, which doesn't connect to any backend and all certificates enroll locally. The returned connector will be authenticated by default, but it's possible to pass a bool argument to indicate if it's desired to get the connector authenticated already or not.

func (*Config) NewListener

func (cfg *Config) NewListener(domains ...string) net.Listener

NewListener returns a net.Listener that listens on the first port specified in domains list (like "example.com:8443") or on default (443) port on all interfaces and returns *tls.Conn connections with certificates enrolled via Venafi for the provided domain.

It enables one-line HTTPS servers:

log.Fatal(http.Serve(vcert.NewListener("example.com"), handler))

The returned listener uses a *tls.Config that enables HTTP/2, and should only be used with servers that support HTTP/2.

The returned Listener also enables TCP keep-alives on the accepted connections. The returned *tls.Conn are returned before their TLS handshake has completed.