certificate

README

certificate

-- import "github.com/go-i2p/common/certificate"

Package certificate implements the certificate common-structure of I2P.

Package certificate implements the certificate common-structure of I2P.

Package certificate implements the certificate common-structure of I2P.

Usage

const (
	CERT_NULL     = iota //nolint:golint
	CERT_HASHCASH        //nolint:golint
	CERT_HIDDEN          //nolint:golint
	CERT_SIGNED          //nolint:golint
	CERT_MULTIPLE        //nolint:golint
	CERT_KEY             //nolint:golint
)

Certificate Types

const CERT_DEFAULT_TYPE_SIZE = 1

CERT_DEFAULT_TYPE_SIZE is the size in bytes for the certificate type field

const CERT_EMPTY_PAYLOAD_SIZE = 0

CERT_EMPTY_PAYLOAD_SIZE represents the size of an empty payload

const CERT_KEY_SIG_TYPE_OFFSET = 0

CERT_KEY_SIG_TYPE_OFFSET is the byte offset where signature type begins in KEY certificate payload

const CERT_LENGTH_FIELD_END = 3

CERT_LENGTH_FIELD_END is the end index for the certificate length field (2 bytes total)

const CERT_LENGTH_FIELD_SIZE = 2

CERT_LENGTH_FIELD_SIZE is the size in bytes for the certificate length field

const CERT_LENGTH_FIELD_START = 1

CERT_LENGTH_FIELD_START is the start index for the certificate length field

const CERT_MAX_PAYLOAD_SIZE = 65535

CERT_MAX_PAYLOAD_SIZE is the maximum allowed size for certificate payload according to I2P specification (2 bytes can represent up to 65535)

const CERT_MAX_TYPE_VALUE = 255

CERT_MAX_TYPE_VALUE is the maximum valid certificate type value that fits in a single byte (0-255 range)

const CERT_MIN_KEY_PAYLOAD_SIZE = 4

CERT_MIN_KEY_PAYLOAD_SIZE is the minimum payload size required for KEY certificates to contain the signature type field (2 bytes minimum)

const CERT_MIN_SIZE = 3

CERT_MIN_SIZE is the minimum size of a valid Certificate in []byte 1 byte for type 2 bytes for payload length

const CERT_SIGNING_KEY_TYPE_SIZE = 2 //nolint:golint

CERT_SIGNING_KEY_TYPE_SIZE is the size in bytes of the signing key type field in key certificates

const CERT_TYPE_FIELD_END = 1

CERT_TYPE_FIELD_END is the end index for the certificate type field (1 byte)

func GetSignatureTypeFromCertificate

func GetSignatureTypeFromCertificate(cert Certificate) (int, error)

GetSignatureTypeFromCertificate extracts the signature type from a KEY certificate. Returns an error if the certificate is not a KEY type or if the payload is too short.

type Certificate

type Certificate struct {
}

Certificate is the representation of an I2P Certificate.

https://geti2p.net/spec/common-structures#certificate

func NewCertificate

func NewCertificate() *Certificate

NewCertificate creates a new Certificate with default NULL type

func NewCertificateDeux

func NewCertificateDeux(certType int, payload []byte) (*Certificate, error)

NewCertificateDeux creates a new Certificate with specified type and payload. Deprecated: Use NewCertificateWithType instead. This function will be removed in v2.0.

func NewCertificateWithType

func NewCertificateWithType(certType uint8, payload []byte) (*Certificate, error)

NewCertificateWithType creates a new Certificate with specified type and payload

func ReadCertificate

func ReadCertificate(data []byte) (certificate Certificate, remainder []byte, err error)

ReadCertificate creates a Certificate from []byte and returns any ExcessBytes at the end of the input. returns err if the certificate could not be read.

func (*Certificate) Bytes

func (c *Certificate) Bytes() []byte

Bytes returns the entire certificate in []byte form, trims payload to specified length.

func (*Certificate) Data

func (c *Certificate) Data() (data []byte)

Data returns the payload of a Certificate, payload is trimmed to the specified length.

func (*Certificate) ExcessBytes

func (c *Certificate) ExcessBytes() []byte

ExcessBytes returns the excess bytes in a certificate found after the specified payload length.

func (*Certificate) Length

func (c *Certificate) Length() (length int)

Length returns the payload length of a Certificate.

func (*Certificate) RawBytes

func (c *Certificate) RawBytes() []byte

RawBytes returns the entire certificate in []byte form, includes excess payload data.

func (*Certificate) Type

func (c *Certificate) Type() (certType int)

Type returns the Certificate type specified in the first byte of the Certificate,

certificate

github.com/go-i2p/common/certificate

go-i2p template file

Documentation

Overview

Package certificate implements the certificate common-structure of I2P.

Package certificate implements the certificate common-structure of I2P.

Package certificate implements the certificate common-structure of I2P.

Package certificate implements the certificate common-structure of I2P.

Package certificate implements the I2P Certificate common data structure according to specification version 0.9.67.

Certificates are used throughout I2P to provide cryptographic metadata about keys, signatures, and other security parameters. They support multiple certificate types and provide flexible payload storage.

Overview

The Certificate structure consists of:

• Type: Certificate type identifier (NULL, HASHCASH, HIDDEN, SIGNED, MULTIPLE, KEY)
• Length: Payload length in bytes (0-65535)
• Payload: Variable-length data specific to the certificate type

Certificate Types

The package supports six certificate types:

• CERT_NULL (0): No certificate (legacy)
• CERT_HASHCASH (1): HashCash proof-of-work
• CERT_HIDDEN (2): Hidden service certificate
• CERT_SIGNED (3): Signed certificate
• CERT_MULTIPLE (4): Multiple certificates
• CERT_KEY (5): Key certificate with signing/crypto type info

Safe Constructors

The package provides validated construction through the builder pattern:

// Create a KEY certificate with validation
builder := certificate.NewCertificateBuilder()
builder, err := builder.WithType(certificate.CERT_KEY)
if err != nil {
    return err
}
builder, err = builder.WithKeyTypes(7, 4)  // Ed25519/X25519
if err != nil {
    return err
}
cert, err := builder.Build()
if err != nil {
    return err
}

// Create a NULL certificate (no payload)
cert, err := certificate.NewCertificateBuilder().
    WithType(certificate.CERT_NULL).
    Build()

Parsing from Bytes

Certificates can be safely parsed from byte streams:

cert, remainder, err := certificate.ReadCertificate(data)
if err != nil {
    return err
}
if !cert.IsValid() {
    return errors.New("invalid certificate")
}

Validation

All certificates support validation to ensure proper initialization:

// Check if certificate is properly initialized
if err := cert.Validate(); err != nil {
    return err
}

// Boolean validation
if !cert.IsValid() {
    return errors.New("invalid certificate")
}

Accessing Certificate Data

Certificate fields can be safely accessed with error handling:

certType, err := cert.Type()
if err != nil {
    return err
}

length, err := cert.Length()
if err != nil {
    return err
}

payload, err := cert.Data()
if err != nil {
    return err
}

Builder Pattern

The CertificateBuilder provides fluent API with early validation:

// Builder validates configuration at each step
builder := NewCertificateBuilder()
builder, err := builder.WithType(CERT_KEY)
if err != nil {
    return err  // Invalid type rejected immediately
}

// Validate before building
if err := builder.Validate(); err != nil {
    // Fix configuration issues
}

cert, err := builder.Build()

Best Practices

• Use the builder pattern for creating new certificates
• Always validate certificates after parsing from bytes
• Use safe accessor methods (Type(), Length(), Data()) with error checking
• Prefer KEY certificates for modern cryptographic parameters

Specification

Reference: https://geti2p.net/spec/common-structures#certificate

This implementation follows I2P specification version 0.9.67 and provides comprehensive validation and error handling for all certificate operations.

Index

• Constants
• func BuildKeyTypePayload(signingType, cryptoType int) []byte
• func GetSignatureTypeFromCertificate(cert Certificate) (int, error)
• type Certificate
  • func NewCertificate() *Certificate
  • func NewCertificateWithType(certType uint8, payload []byte) (*Certificate, error)
  • func ReadCertificate(data []byte) (certificate *Certificate, remainder []byte, err error)
  • func (c *Certificate) Bytes() []byte
  • func (c *Certificate) Data() (data []byte, err error)
  • func (c *Certificate) ExcessBytes() []byte
  • func (c *Certificate) IsValid() bool
  • func (c *Certificate) Length() (length int, err error)
  • func (c *Certificate) RawBytes() []byte
  • func (c *Certificate) Type() (certType int, err error)
• type CertificateBuilder
  • func NewCertificateBuilder() *CertificateBuilder
  • func (cb *CertificateBuilder) Build() (*Certificate, error)
  • func (cb *CertificateBuilder) Validate() error
  • func (cb *CertificateBuilder) WithKeyTypes(signingType, cryptoType int) (*CertificateBuilder, error)
  • func (cb *CertificateBuilder) WithPayload(payload []byte) *CertificateBuilder
  • func (cb *CertificateBuilder) WithType(certType uint8) (*CertificateBuilder, error)

Constants

const (
	CERT_NULL     = iota //nolint:golint
	CERT_HASHCASH        //nolint:golint
	CERT_HIDDEN          //nolint:golint
	CERT_SIGNED          //nolint:golint
	CERT_MULTIPLE        //nolint:golint
	CERT_KEY             //nolint:golint
)

Certificate Types

const CERT_DEFAULT_TYPE_SIZE = 1

CERT_DEFAULT_TYPE_SIZE is the size in bytes for the certificate type field

const CERT_EMPTY_PAYLOAD_SIZE = 0

CERT_EMPTY_PAYLOAD_SIZE represents the size of an empty payload

const CERT_KEY_SIG_TYPE_OFFSET = 0

CERT_KEY_SIG_TYPE_OFFSET is the byte offset where signature type begins in KEY certificate payload

const CERT_LENGTH_FIELD_END = 3

CERT_LENGTH_FIELD_END is the end index for the certificate length field (2 bytes total)

const CERT_LENGTH_FIELD_SIZE = 2

CERT_LENGTH_FIELD_SIZE is the size in bytes for the certificate length field

const CERT_LENGTH_FIELD_START = 1

CERT_LENGTH_FIELD_START is the start index for the certificate length field

const CERT_MAX_PAYLOAD_SIZE = 65535

CERT_MAX_PAYLOAD_SIZE is the maximum allowed size for certificate payload according to I2P specification (2 bytes can represent up to 65535)

const CERT_MAX_TYPE_VALUE = 255

CERT_MAX_TYPE_VALUE is the maximum valid certificate type value that fits in a single byte (0-255 range)

const CERT_MIN_KEY_PAYLOAD_SIZE = 4

CERT_MIN_KEY_PAYLOAD_SIZE is the minimum payload size required for KEY certificates to contain the signature type field (2 bytes minimum)

const CERT_MIN_SIZE = 3

CERT_MIN_SIZE is the minimum size of a valid Certificate in []byte 1 byte for type 2 bytes for payload length

const CERT_SIGNING_KEY_TYPE_SIZE = 2 //nolint:golint

CERT_SIGNING_KEY_TYPE_SIZE is the size in bytes of the signing key type field in key certificates

const CERT_TYPE_FIELD_END = 1

CERT_TYPE_FIELD_END is the end index for the certificate type field (1 byte)

Functions

func BuildKeyTypePayload

func BuildKeyTypePayload(signingType, cryptoType int) []byte

BuildKeyTypePayload is a convenience function to build key type payload without using builder. This is useful when you just need to generate the payload bytes.

Parameters:

• signingType: The signing key type
• cryptoType: The crypto key type

Returns:

• []byte: The 4-byte payload [signing_type][crypto_type]

func GetSignatureTypeFromCertificate

func GetSignatureTypeFromCertificate(cert Certificate) (int, error)

GetSignatureTypeFromCertificate extracts the signature type from a KEY certificate. Returns an error if the certificate is not a KEY type or if the payload is too short.

Types

type Certificate

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

Certificate is the representation of an I2P Certificate.

https://geti2p.net/spec/common-structures#certificate

func NewCertificate

func NewCertificate() *Certificate

NewCertificate creates a new Certificate with default NULL type

func NewCertificateWithType

func NewCertificateWithType(certType uint8, payload []byte) (*Certificate, error)

NewCertificateWithType creates a new Certificate with specified type and payload

func ReadCertificate

func ReadCertificate(data []byte) (certificate *Certificate, remainder []byte, err error)

ReadCertificate creates a Certificate from []byte and returns any ExcessBytes at the end of the input. Returns nil certificate on error (not partial certificate).

func (*Certificate) Bytes

func (c *Certificate) Bytes() []byte

Bytes returns the entire certificate in []byte form, trims payload to specified length.

func (*Certificate) Data

func (c *Certificate) Data() (data []byte, err error)

Data returns the payload of a Certificate, payload is trimmed to the specified length. Data returns the payload of a Certificate, trimmed to the specified length. Returns error if length is invalid.

func (*Certificate) ExcessBytes

func (c *Certificate) ExcessBytes() []byte

ExcessBytes returns the excess bytes in a certificate found after the specified payload length.

func (*Certificate) IsValid

func (c *Certificate) IsValid() bool

IsValid returns true if the certificate is fully initialized and valid. This method checks that all required fields (kind, len) are present and non-empty. Note: payload can be empty for NULL certificates.

func (*Certificate) Length

func (c *Certificate) Length() (length int, err error)

Length returns the payload length of a Certificate. Length returns the payload length of a Certificate, with validation and error context.

func (*Certificate) RawBytes

func (c *Certificate) RawBytes() []byte

RawBytes returns the entire certificate in []byte form, includes excess payload data.

func (*Certificate) Type

func (c *Certificate) Type() (certType int, err error)

Type returns the Certificate type specified in the first byte of the Certificate, Type returns the certificate type as int, with validation and error context.

type CertificateBuilder

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

CertificateBuilder provides a fluent interface for building certificates. This pattern simplifies certificate construction, especially for complex cases with custom payloads or key types.

Example usage:

cert, err := certificate.NewCertificateBuilder().
    WithKeyTypes(certificate.KEYCERT_SIGN_ED25519, certificate.KEYCERT_CRYPTO_X25519).
    Build()

func NewCertificateBuilder

func NewCertificateBuilder() *CertificateBuilder

NewCertificateBuilder creates a new certificate builder with default NULL type.

func (*CertificateBuilder) Build

func (cb *CertificateBuilder) Build() (*Certificate, error)

Build creates the certificate with the configured options. Returns error if the configuration is invalid.

Example:

cert, err := NewCertificateBuilder().
    WithKeyTypes(7, 4).
    Build()

func (*CertificateBuilder) Validate

func (cb *CertificateBuilder) Validate() error

Validate checks the builder configuration for consistency. This allows catching configuration errors before calling Build().

Example:

builder := NewCertificateBuilder().WithType(CERT_KEY)
if err := builder.Validate(); err != nil {
    // Fix configuration before building
}

func (*CertificateBuilder) WithKeyTypes

func (cb *CertificateBuilder) WithKeyTypes(signingType, cryptoType int) (*CertificateBuilder, error)

WithKeyTypes sets signing and crypto key types (for CERT_KEY type). This is a convenience method that automatically:

• Sets the certificate type to CERT_KEY
• Builds the appropriate 4-byte payload

Parameters:

• signingType: The signing key type (e.g., 7 for Ed25519)
• cryptoType: The crypto key type (e.g., 4 for X25519)

Returns error if the key types are invalid (negative values).

Example:

builder.WithKeyTypes(7, 4) // Ed25519 signing, X25519 crypto

func (*CertificateBuilder) WithPayload

func (cb *CertificateBuilder) WithPayload(payload []byte) *CertificateBuilder

WithPayload sets custom payload data. This overrides any payload that would be generated from key types.

Example:

builder.WithType(certificate.CERT_SIGNED).WithPayload(signatureData)

func (*CertificateBuilder) WithType

func (cb *CertificateBuilder) WithType(certType uint8) (*CertificateBuilder, error)

WithType sets the certificate type. Valid types are: CERT_NULL, CERT_HASHCASH, CERT_HIDDEN, CERT_SIGNED, CERT_MULTIPLE, CERT_KEY. Returns error if the certificate type is invalid.

Example:

builder.WithType(certificate.CERT_KEY)