ttlv

func Details ¶

func Details(err error) string

Details prints details from the error, including a stacktrace when available.

func FormatEnum ¶

func FormatEnum(v uint32, enumMap EnumMap) string

FormatEnum formats an uint32 as a KMIP Enumeration string, as described in the KMIP Profiles spec. If the value is registered, the normalized name of the value will be returned. Otherwise, a four byte hex string is returned. Examples:

- SymmetricKey - 0x00000002

func FormatInt ¶

func FormatInt(i int32, enumMap EnumMap) string

FormatInt formats an integer as a KMIP bitmask string, as described in the KMIP Profiles spec for JSON under the "Special case for Masks" section. Examples:

- 0x0000100c - Encrypt|Decrypt|CertificateSign - CertificateSign|0x00000004|0x0000008 - CertificateSign|0x0000000c

func FormatTag ¶

func FormatTag(v uint32, enumMap EnumMap) string

FormatTag formats an uint32 as a KMIP Tag string, as described in the KMIP Profiles spec. If the value is registered, the normalized name of the value will be returned. Otherwise, a 3 byte hex string is returned. Examples:

- ActivationDate - 0x420001

func FormatTagCanonical ¶

func FormatTagCanonical(v uint32, enumMap EnumMap) string

FormatTagCanonical formats an uint32 as a canonical Tag name from the KMIP spec. If the value is registered, the canonical name of the value will be returned. Otherwise, a 3 byte hex string is returned. Examples:

- Activation Date - 0x420001

Canonical tag names are used in the AttributeName of Attribute structs.

func FormatType ¶

func FormatType(b byte, enumMap EnumMap) string

FormatType formats a byte as a KMIP Type string, as described in the KMIP Profiles spec. If the value is registered, the normalized name of the value will be returned.

Otherwise, a 1 byte hex string is returned, but this is not technically a valid encoding for types in the JSON and XML encoding specs. Hex values Should only be used for debugging. Examples:

- Integer - 0x42

func Hex2bytes ¶

func Hex2bytes(s string) []byte

Hex2bytes converts hex string to bytes. Any non-hex characters in the string are stripped first. panics on error

func NormalizeName ¶

func NormalizeName(s string) string

NormalizeName tranforms KMIP names from the spec into the normalized form of the name. Typically, this means removing spaces, and replacing some special characters. The normalized form of the name is used in the JSON and XML encodings from the KMIP Profiles. The spec describes the normalization process in 5.4.1.1 and 5.5.1.1

func ParseEnum ¶

func ParseEnum(s string, enumMap EnumMap) (uint32, error)

ParseEnum parses a string into a uint32 according to the rules in the KMIP Profiles regarding encoding enumeration values. See FormatEnum for examples of the formats which can be parsed. It will also parse numeric strings. Examples:

    ParseEnum("UnableToCancel", registry.EnumForTag(TagCancellationResult))
	   ParseEnum("0x00000002")
	   ParseEnum("2")

Returns ErrInvalidHexString if the string is invalid hex, or if the hex value is less than 1 byte or more than 4 bytes (ignoring leading zeroes).

Returns ErrUnregisteredEnumName if string value is not a registered enum value name.

func ParseInt ¶

func ParseInt(s string, enumMap EnumMap) (int32, error)

ParseInt parses a string into an int32 according the rules in the KMIP Profiles regarding encoding integers, including the special rules for bitmasks. See FormatInt for examples of the formats which can be parsed.

Returns ErrInvalidHexString if the string is invalid hex, or if the hex value is less than 1 byte or more than 4 bytes (ignoring leading zeroes).

Returns ErrUnregisteredEnumName if string value is not a registered enum value name.

func Print ¶

func Print(w io.Writer, prefix, indent string, t TTLV) error

Print pretty prints the TTLV value in a human-readable format. This format cannot be parsed back into TTLV.

Print is safe to call on any TTLV value, even one which is valid, not correctly encoded, or not actually TTLV bytes. Print will try and print as much of the value as it can decode, and return a parsing error.

b, _ := hex.DecodeString("420069010000002042006a0200000004000000010000000042006b02000000040000000000000000")
_ = Print(os.Stdout, "", "  ", b)

Output:

ProtocolVersion (Structure/32):
  ProtocolVersionMajor (Integer/4): 1
  ProtocolVersionMinor (Integer/4): 0

func PrintPrettyHex ¶

func PrintPrettyHex(w io.Writer, prefix, indent string, t TTLV) error

PrintPrettyHex pretty prints the TTLV value as hex values, with spacers between the segments of the TTLV. Like Print, this is safe to call even on invalid TTLV values. An error will only be returned if there is a problem with the writer.

b, _ := hex.DecodeString("420069010000002042006a0200000004000000010000000042006b02000000040000000000000000")
_ = PrintPrettyHex(os.Stdout, "", "  ", b)

Output:

420069 | 01 | 00000020
  42006a | 02 | 00000004 | 0000000100000000
  42006b | 02 | 00000004 | 0000000000000000

func RegisterTypes ¶

func RegisterTypes(r *Registry)

func Unmarshal ¶

func Unmarshal(ttlv TTLV, v interface{}) error

Unmarshal parses TTLV encoded data and stores the result in the value pointed to by v.

An error will be returned if v is nil or not a point, or if b is not valid TTLV.

Unmarshal will allocate values to store the result in, similar to the json.Marshal. Generally, the destination value can be a pointer or or a direct value. Currently, Unmarshal does not support anonymous fields. They will be ignored. Private fields are ignored.

Unmarshal maps TTLV values to golang values according to the following rules:

1. If the destination value is interface{}, it will be set to the result of TTLV.Value()
2. If the destination implements Unmarshaler, that will be called.
3. If the destination is a slice (except for []byte), append the unmarshalled value to the slice
4. Structure unmarshals into a struct. See rules below for matching struct fields to the values in the Structure.
5. Interval unmarshals into an int64
6. DateTime and DateTimeExtended ummarshal into time.Time
7. ByteString unmarshals to a []byte
8. TextString unmarshals into a string
9. Boolean unmarshals into a bool
10. Enumeration can unmarshal into an int, int8, int16, int32, or their uint counterparts. If the KMIP value overflows the destination, a *UnmarshalerError with cause ErrIntOverflow is returned.
11. Integer can unmarshal to the same types as Enumeration, with the same overflow check.
12. LongInteger unmarshals to int64 or uint64
13. BitInteger unmarshals to big.Int.

If the destination value is not a supported type, an *UnmarshalerError with cause ErrUnsupportedTypeError is returned. If the source value's type is not recognized, *UnmarshalerError with cause ErrInvalidType is returned.

Unmarshaling Structure ¶

Unmarshal will try to match the values in the Structure with the fields in the destination struct. Structure is an array of values, while a struct is more like a map, so not all Structure values can be accurately represented by a golang struct. In particular, a Structure can hold the same tag multiple times, e.g. 3 TagComment values in a row.

For each field in the struct, Unmarshal infers a KMIP Tag by examining both the name and type of the field. It uses the following rules, in order:

1. If the type of a field is a struct, and the struct contains a field named "TTLVTag", and the field has a "ttlv" struct tag, the value of the struct tag will be parsed using ParseTag(). If parsing fails, an error is returned. The type and value of the TTLVTag field is ignored. In this example, the F field will map to TagDeactivationDate:

   type Bar struct { F Foo } type Foo struct { TTLVTag struct{} `ttlv:"DeactivationDate"` }

   If Bar uses a struct tag on F indicating a different tag, it is an error:

   type Bar struct { F Foo `ttlv:"DerivationData"` // this will cause an ErrTagConflict // because conflict Bar's field tag // conflicts with Foo's intrinsic tag F2 Foo `ttlv:"0x420034"` // the value can also be hex }

2. If the type of the field is a struct, and the struct contains a field named "TTLVTag", and that field is of type ttlv.Tag and is not empty, the value of the field will be the inferred Tag. For example:

   type Foo struct { TTLVTag ttlv.Tag } f := Foo{TTLVTag: ttlv.TagState}

   This allows you to dynamically set the KMIP tag that a value will marshal to.

3. The "ttlv" struct tag can be used to indicate the tag for a field. The value will be parsed with ParseTag()

   type Bar struct { F Foo `ttlv:"DerivationData"` }

4. The name of the field is parsed with ParseTag():

type Bar struct {
    DerivationData int
}

5. The name of the field's type is parsed with ParseTab():

type DerivationData int

type Bar struct {
    dd DerivationData
}

If no tag value can be inferred, the field is ignored. Multiple fields *cannot* map to the same KMIP tag. If they do, an ErrTagConflict will be returned.

Each value in the Structure will be matched against the first field in the struct with the same inferred tag.

If the value cannot be matched with a field, Unmarshal will look for the first field with the "any" struct flag set and unmarshal into that:

type Foo struct {
    Comment string                            // the Comment will unmarshal into this
    EverythingElse []interface{}  `,any`      // all other values will unmarshal into this
    AnotherAny []interface{}  `,any`          // allowed, but ignored.  first any field will always match
    NotLegal []interface{}  `TagComment,any`  // you cannot specify a tag and the any flag.
                                              // will return error
}

If after applying these rules no destination field is found, the KMIP value is ignored.