kmip-go

A go implementation of the KMIP protocol and client, supporting KMIP v1.0 to v1.4. See KMIP v1.4 protocole specification

This library is developped for and tested against OVHcloud KMS.

Usage

Add it to your project by running

go get github.com/ovh/kmip-go@latest

and import required packages

import (
	"github.com/ovh/kmip-go"
	"github.com/ovh/kmip-go/kmipclient"
	"github.com/ovh/kmip-go/payloads"
	"github.com/ovh/kmip-go/ttlv"
)

Then you can connect to your KMS service:

const (
	ADDR = "eu-west-rbx.okms.ovh.net:5696"
	CA   = "ca.pem"
	CERT = "cert.pem"
	KEY  = "key.pem"
)

client, err := kmipclient.Dial(
	ADDR,
	// Optional if server's CA is known by the system
	// kmipclient.WithRootCAFile(CA),
	kmipclient.WithClientCertFiles(CERT, KEY),
	kmipclient.WithMiddlewares(
		kmipclient.CorrelationValueMiddleware(uuid.NewString),
		kmipclient.DebugMiddleware(os.Stdout, ttlv.MarshalXML),
	),
	// kmipclient.EnforceVersion(kmip.V1_4),
)
if err != nil {
	panic(err)
}
defer client.Close()
fmt.Println("Connected using KMIP version", client.Version())

You can then use the high level client helper methods to create and send requests to the server:

resp := client.Create().
	AES(256, kmip.CryptographicUsageEncrypt|kmip.CryptographicUsageDecrypt).
	WithName("my-key").
	MustExec()
fmt.Println("Created AES key with ID", resp.UniqueIdentifier)

Or alternatively if more flexibility is required, craft your kmip requests payloads:

request := payloads.CreateRequestPayload{
	ObjectType: kmip.ObjectTypeSymmetricKey,
	TemplateAttribute: kmip.TemplateAttribute{
		Attribute: []kmip.Attribute{
			{
				AttributeName:  kmip.AttributeNameCryptographicAlgorithm,
				AttributeValue: kmip.CryptographicAlgorithmAES,
			}, {
				AttributeName:  kmip.AttributeNameCryptographicLength,
				AttributeValue: int32(256),
			}, {
				AttributeName: kmip.AttributeNameName,
				AttributeValue: kmip.Name{
					NameType:  kmip.NameTypeUninterpretedTextString,
					NameValue: "another-key",
				},
			}, {
				AttributeName:  kmip.AttributeNameCryptographicUsageMask,
				AttributeValue: kmip.CryptographicUsageEncrypt | kmip.CryptographicUsageDecrypt,
			},
		},
	},
}

response, err := client.Request(context.Background(), &request)
if err != nil {
	panic(err)
}
id := response.(*payloads.CreateResponsePayload).UniqueIdentifier
fmt.Println("Created an AES key with ID", id)

You can also send batches of requests:

batchResponse, err := client.Batch(context.Background(), &request, &request)
if err != nil {
	panic(err)
}
id1 := batchResponse[0].ResponsePayload.(*payloads.CreateResponsePayload).UniqueIdentifier
id2 := batchResponse[1].ResponsePayload.(*payloads.CreateResponsePayload).UniqueIdentifier
fmt.Println("Created 2 AES keys with IDs", id1, id2)

And directly craft your request message with one or more payloads batched together:

msg := kmip.NewRequestMessage(client.Version(), &request, &request)
rMsg, err := client.Roundtrip(context.Background(), &msg)
if err != nil {
	panic(err)
}
id1 := rMsg.BatchItem[0].ResponsePayload.(*payloads.CreateResponsePayload).UniqueIdentifier
id2 := rMsg.BatchItem[1].ResponsePayload.(*payloads.CreateResponsePayload).UniqueIdentifier
fmt.Println("Created a 5th and 6th AES keys with IDs", id1, id2)

}

See examples for more possibilities.

Implementation status

Legend:

• N/A : Not Applicable
• ✅ : Fully compatible
• ❌ : Not implemented
• 🚧 : Work in progress / Partially compatible
• 💀 : Deprecated

Messages

	v1.0	v1.1	v1.2	v1.3	v1.4
Request Message	✅	✅	✅	✅	✅
Response Message	✅	✅	✅	✅	✅

Operations

Operation	v1.0	v1.1	v1.2	v1.3	v1.4
Create	✅	✅	✅	✅	✅
Create Key Pair	✅	✅	✅	✅	✅
Register	✅	✅	✅	✅	✅
Re-key	✅	✅	✅	✅	✅
DeriveKey	❌	❌	❌	❌	❌
Certify	❌	❌	❌	❌	❌
Re-certify	❌	❌	❌	❌	❌
Locate	✅	✅	✅	✅	✅
Check	❌	❌	❌	❌	❌
Get	✅	✅	✅	✅	✅
Get Attributes	✅	✅	✅	✅	✅
Get Attribute List	✅	✅	✅	✅	✅
Add Attribute	✅	✅	✅	✅	✅
Modify Attribute	✅	✅	✅	✅	✅
Delete Attribute	✅	✅	✅	✅	✅
Obtain Lease	✅	✅	✅	✅	✅
Get Usage Allocation	✅	✅	✅	✅	✅
Activate	✅	✅	✅	✅	✅
Revoke	✅	✅	✅	✅	✅
Destroy	✅	✅	✅	✅	✅
Archive	✅	✅	✅	✅	✅
Recover	✅	✅	✅	✅	✅
Validate	❌	❌	❌	❌	❌
Query	✅	✅	✅	✅	✅
Cancel	❌	❌	❌	❌	❌
Poll	❌	❌	❌	❌	❌
Notify	❌	❌	❌	❌	❌
Put	❌	❌	❌	❌	❌
Discover	N/A	✅	✅	✅	✅
Re-key Key Pair	N/A	❌	❌	❌	❌
Encrypt	N/A	N/A	✅	✅	✅
Decrypt	N/A	N/A	✅	✅	✅
Sign	N/A	N/A	✅	✅	✅
Signature Verify	N/A	N/A	✅	✅	✅
MAC	N/A	N/A	❌	❌	❌
MAC Verify	N/A	N/A	❌	❌	❌
RNG Retrieve	N/A	N/A	❌	❌	❌
RNG Seed	N/A	N/A	❌	❌	❌
Hash	N/A	N/A	❌	❌	❌
Create Split Key	N/A	N/A	❌	❌	❌
Join Split Key	N/A	N/A	❌	❌	❌
Export	N/A	N/A	N/A	N/A	❌
Import	N/A	N/A	N/A	N/A	❌

Managed Objects

Object	v1.0	v1.1	v1.2	v1.3	v1.4
Certificate	✅	✅	✅	✅	✅
Symmetric Key	✅	✅	✅	✅	✅
Public Key	✅	✅	✅	✅	✅
Private Key	✅	✅	✅	✅	✅
Split Key	✅	✅	✅	✅	✅
Template	✅	✅	✅	💀	💀
Secret Data	✅	✅	✅	✅	✅
Opaque Object	✅	✅	✅	✅	✅
PGP Key	N/A	N/A	✅	✅	✅

Base Objects

Object	v1.0	v1.1	v1.2	v1.3	v1.4
Attribute	✅	✅	✅	✅	✅
Credential	✅	✅	✅	✅	✅
Key Block	✅	✅	✅	✅	✅
Key Value	✅	✅	✅	✅	✅
Key Wrapping Data	✅	✅	✅	✅	✅
Key Wrapping Specification	✅	✅	✅	✅	✅
Transparent Key Structures	🚧	🚧	🚧	🚧	🚧
Template-Attribute Structures	✅	✅	✅	✅	✅
Extension Information	N/A	✅	✅	✅	✅
Data	N/A	N/A	✅	✅	✅
Data Length	N/A	N/A	❌	❌	❌
Signature Data	N/A	N/A	✅	✅	✅
MAC Data	N/A	N/A	❌	❌	❌
Nonce	N/A	N/A	✅	✅	✅
Correlation Value	N/A	N/A	N/A	✅	✅
Init Indicator	N/A	N/A	N/A	✅	✅
Final Indicator	N/A	N/A	N/A	✅	✅
RNG Parameter	N/A	N/A	N/A	✅	✅
Profile Information	N/A	N/A	N/A	✅	✅
Validation Information	N/A	N/A	N/A	✅	✅
Capability Information	N/A	N/A	N/A	✅	✅
Authenticated Encryption Additional Data	N/A	N/A	N/A	N/A	✅
Authenticated Encryption Tag	N/A	N/A	N/A	N/A	✅

Transparent Key Structures

Object	v1.0	v1.1	v1.2	v1.3	v1.4
Symmetric Key	✅	✅	✅	✅	✅
DSA Private/Public Key	❌	❌	❌	❌	❌
RSA Private/Public Key	✅	✅	✅	✅	✅
DH Private/Public Key	❌	❌	❌	❌	❌
ECDSA Private/Public Key	✅	✅	✅	💀	💀
ECDH Private/Public Key	❌	❌	❌	💀	💀
ECMQV Private/Public	❌	❌	❌	💀	💀
EC Private/Public	N/A	N/A	N/A	✅	✅

Attributes

Attribute	v1.0	v1.1	v1.2	v1.3	v1.4
Unique Identifier	✅	✅	✅	✅	✅
Name	✅	✅	✅	✅	✅
Object Type	✅	✅	✅	✅	✅
Cryptographic Algorithm	✅	✅	✅	✅	✅
Cryptographic Length	✅	✅	✅	✅	✅
Cryptographic Parameters	✅	✅	✅	✅	✅
Cryptographic Domain Parameters	✅	✅	✅	✅	✅
Certificate Type	✅	✅	✅	✅	✅
Certificate Identifier	✅	💀	💀	💀	💀
Certificate Subject	✅	💀	💀	💀	💀
Certificate Issuer	✅	💀	💀	💀	💀
Digest	✅	✅	✅	✅	✅
Operation Policy Name	✅	✅	✅	💀	💀
Cryptographic Usage Mask	✅	✅	✅	✅	✅
Lease Time	✅	✅	✅	✅	✅
Usage Limits	✅	✅	✅	✅	✅
State	✅	✅	✅	✅	✅
Initial Date	✅	✅	✅	✅	✅
Activation Date	✅	✅	✅	✅	✅
Process Start Date	✅	✅	✅	✅	✅
Protect Stop Date	✅	✅	✅	✅	✅
Deactivation Date	✅	✅	✅	✅	✅
Destroy Date	✅	✅	✅	✅	✅
Compromise Occurrence Date	✅	✅	✅	✅	✅
Compromise Date	✅	✅	✅	✅	✅
Revocation Reason	✅	✅	✅	✅	✅
Archive Date	✅	✅	✅	✅	✅
Object Group	✅	✅	✅	✅	✅
Link	✅	✅	✅	✅	✅
Application Specific Information	✅	✅	✅	✅	✅
Contact Information	✅	✅	✅	✅	✅
Last Change Date	✅	✅	✅	✅	✅
Custom Attribute	✅	✅	✅	✅	✅
Certificate Length	N/A	✅	✅	✅	✅
X.509 Certificate Identifier	N/A	✅	✅	✅	✅
X.509 Certificate Subject	N/A	✅	✅	✅	✅
X.509 Certificate Issuer	N/A	✅	✅	✅	✅
Digital Signature Algorithm	N/A	✅	✅	✅	✅
Fresh	N/A	✅	✅	✅	✅
Alternative Name	N/A	N/A	✅	✅	✅
Key Value Present	N/A	N/A	✅	✅	✅
Key Value Location	N/A	N/A	✅	✅	✅
Original Creation Date	N/A	N/A	✅	✅	✅
Random Number Generator	N/A	N/A	N/A	✅	✅
PKCS#12 Friendly Name	N/A	N/A	N/A	N/A	✅
Description	N/A	N/A	N/A	N/A	✅
Comment	N/A	N/A	N/A	N/A	✅
Sensitive	N/A	N/A	N/A	N/A	✅
Always Sensitive	N/A	N/A	N/A	N/A	✅
Extractable	N/A	N/A	N/A	N/A	✅
Never Extractable	N/A	N/A	N/A	N/A	✅