iabconsent

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Mar 30, 2020 License: MIT Imports: 6 Imported by: 2

README

iabconsent

Build Status

Go Report Card

A Golang implementation of the IAB Consent String 1.1 Spec as well as the IAB Transparency and Consent String v2.0.

To install:

go get -v github.com/LiveRamp/iabconsent

This package defines a two structs (ParsedConsent and V2ParsedConsent) which contain all of the fields of the IAB v1.1 Consent String and the IAB Transparency and Consent String v2.0 respectively.

Each spec has their own parsing function (ParseV1 and ParseV2). If the caller is unsure of which version a consent string is, they can use ParseVersion to receive a StringVersion to determine which parsing function is appropriate.

Example use:

package main

import "github.com/LiveRamp/iabconsent"

func main() {
    var consent = "COvzTO5OvzTO5BRAAAENAPCoALIAADgAAAAAAewAwABAAlAB6ABBFAAA"

    var c, err = iabconsent.ParseVersion(consent)
    if err != nil {
        panic(err)
    }
    
    switch c {
    case iabconsent.V1:
        var v1, err = iabconsent.ParseV1(consent)
        // Use v1 consent.
    case iabconsent.V2:
        var v2, err = iabconsent.ParseV2(consent)
        // Use v2 consent.
    default:
        panic("unknown version")
    }
}

The function Parse(s string) is deprecated, and should no longer be used.

Documentation

Overview

Package iabconsent provides structs and methods for parsing vendor consent strings as defined by the IAB. Current two versions of consent strings are supported.

The IAB Consent String 1.1 Spec which can be found here: https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/47b45ab362515310183bb3572a367b8391ef4613/Consent%20string%20and%20vendor%20list%20formats%20v1.1%20Final.md#vendor-consent-string-format-

The IAB Transparency and Consent String 2 Spec which can be found here: https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/47b45ab362515310183bb3572a367b8391ef4613/TCFv2/IAB%20Tech%20Lab%20-%20Consent%20string%20and%20vendor%20list%20formats%20v2.md#about-the-transparency--consent-string-tc-string

Copyright (c) 2020 LiveRamp. All rights reserved.

Written by Andy Day, Software Engineer @ LiveRamp for use in the LiveRamp Pixel Server.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ConsentReader added in v0.2.0 

type ConsentReader struct {
	*bits.Reader
}

ConsentReader provides additional Consent String-specific bit-reading functionality on top of bits.Reader.

func NewConsentReader added in v0.2.0 

func NewConsentReader(src []byte) *ConsentReader

NewConsentReader returns a new ConsentReader backed by src.

func (*ConsentReader) ReadBitField added in v0.2.0 

func (r *ConsentReader) ReadBitField(n uint) (map[int]bool, error)

ReadBitField reads the next n bits and converts them to a map[int]bool.

func (*ConsentReader) ReadInt added in v0.2.0 

func (r *ConsentReader) ReadInt(n uint) (int, error)

ReadInt reads the next n bits and converts them to an int.

func (*ConsentReader) ReadPubRestrictionEntries added in v0.3.0 

func (r *ConsentReader) ReadPubRestrictionEntries(n uint) ([]*PubRestrictionEntry, error)

ReadPubRestrictionEntries reads n publisher restriction entries.

func (*ConsentReader) ReadPublisherTCEntry added in v0.3.0 

func (r *ConsentReader) ReadPublisherTCEntry() (*PublisherTCEntry, error)

ReadPublisherTCEntry reads in a publisher TC entry. It's assumed that the segment type bit has already been read, despite those bits being grouped together in the spec. This is done because the logic for the remaining bits differs based on the segment type.

func (*ConsentReader) ReadRangeEntries added in v0.2.0 

func (r *ConsentReader) ReadRangeEntries(n uint) ([]*RangeEntry, error)

ReadRangeEntries reads n range entries of 1 + 16 or 32 bits.

func (*ConsentReader) ReadRestrictionType added in v0.3.0 

func (r *ConsentReader) ReadRestrictionType() (RestrictionType, error)

ReadRestrictionType reads two bits and returns an enum |RestrictionType|.

func (*ConsentReader) ReadSegmentType added in v0.3.0 

func (r *ConsentReader) ReadSegmentType() (SegmentType, error)

ReadSegmentType reads three bits and returns an enum |SegmentType|.

func (*ConsentReader) ReadString added in v0.2.0 

func (r *ConsentReader) ReadString(n uint) (string, error)

ReadString returns a string of length n by reading the next 6 * n bits.

func (*ConsentReader) ReadTime added in v0.2.0 

func (r *ConsentReader) ReadTime() (time.Time, error)

ReadTime reads the next 36 bits representing the epoch time in deciseconds and converts it to a time.Time.

func (*ConsentReader) ReadVendors added in v0.3.0 

func (r *ConsentReader) ReadVendors(t SegmentType) (*OOBVendorList, error)

ReadVendors reads in a vendor list representing either disclosed or allowed vendor lists. It's assumed that the segment type bit has already been read, despite those bits being grouped together in the spec. This is done because the logic for the remaining bits differs based on the segment type.

type OOBVendorList added in v0.3.0 

type OOBVendorList struct {
	// Enum type.
	SegmentType SegmentType
	// The maximum Vendor ID that is included.
	MaxVendorID int
	// The encoding scheme used to encode the IDs in the section – Either a BitField Section or Range Section follows.
	// Encoding logic should choose the encoding scheme that results in the smaller output size for a given set.
	IsRangeEncoding bool

	// The value for each Vendor ID from 1 to MaxVendorId. Set the bit corresponding to a given Vendor ID to 1 if the
	// Publisher permits the vendor to use OOB legal bases.
	Vendors map[int]bool

	// Number of RangeEntry sections to follow.
	NumEntries int
	// A single or range of Vendor ID(s) of Vendor(s) who are allowed to use OOB legal bases on the given publisher’s
	// digital property. If a Vendor ID is not within the bounds of the ranges then they are not allowed to use OOB
	// legal bases on the given publisher's digital property.
	VendorEntries []*RangeEntry
}

OOBVendorList is represents either a DisclosedVendors or AllowedVendors list.

type ParsedConsent 

type ParsedConsent struct {
	Version           int
	Created           time.Time
	LastUpdated       time.Time
	CMPID             int
	CMPVersion        int
	ConsentScreen     int
	ConsentLanguage   string
	VendorListVersion int
	PurposesAllowed   map[int]bool
	MaxVendorID       int
	IsRangeEncoding   bool
	ConsentedVendors  map[int]bool
	DefaultConsent    bool
	NumEntries        int
	RangeEntries      []*RangeEntry
}

ParsedConsent represents data extracted from an IAB Consent String, v1.1.

func Parse deprecated 

func Parse(s string) (*ParsedConsent, error)

Parse takes a base64 Raw URL Encoded string which represents a Vendor Consent String and returns a ParsedConsent with its fields populated with the values stored in the string.

Example Usage: 

var pc, err = iabconsent.Parse("BONJ5bvONJ5bvAMAPyFRAL7AAAAMhuqKklS-gAAAAAAAAAAAAAAAAAAAAAAAAAA")

Deprecated: Use ParseV1 to parse V1 consent strings.

func ParseV1 added in v0.3.0 

func ParseV1(s string) (*ParsedConsent, error)

ParseV1 takes a base64 Raw URL Encoded string which represents a TCF v1.1 string and returns a ParsedConsent with its fields populated with the values stored in the string.

Example Usage: 

var pc, err = iabconsent.ParseV1("BONJ5bvONJ5bvAMAPyFRAL7AAAAMhuqKklS-gAAAAAAAAAAAAAAAAAAAAAAAAAA")

func (*ParsedConsent) EveryPurposeAllowed added in v0.2.0 

func (p *ParsedConsent) EveryPurposeAllowed(ps []int) bool

EveryPurposeAllowed returns true iff every purpose number in ps exists in the ParsedConsent, otherwise false.

func (*ParsedConsent) VendorAllowed 

func (p *ParsedConsent) VendorAllowed(v int) bool

VendorAllowed returns true if the ParsedConsent contains affirmative consent for VendorID v.

type PubRestrictionEntry added in v0.3.0 

type PubRestrictionEntry struct {
	// The Vendor’s declared Purpose ID that the publisher has indicated that they are overriding.
	PurposeID int
	// The restriction type.
	RestrictionType RestrictionType
	// Number of RangeEntry sections to follow.
	NumEntries int
	// A single or range of Vendor ID(s) who the publisher has designated as restricted under the
	// Purpose ID in this PubRestrictionsEntry.
	RestrictionsRange []*RangeEntry
}

PubRestrictionEntry is made up of three parts: Purpose ID, Restriction Type and, List of Vendor IDs under that Purpose restriction.

type PublisherTCEntry added in v0.3.0 

type PublisherTCEntry struct {
	// Enum type
	SegmentType SegmentType
	// The user's consent value for each Purpose established on the legal basis of consent, for the publisher.
	// The Purposes are numerically identified and published in the Global Vendor List.
	PubPurposesConsent map[int]bool
	// The Purpose’s transparency requirements are met for each Purpose established on the legal basis of legitimate
	// interest and the user has not exercised their “Right to Object” to that Purpose. By default or if the user has
	// exercised their “Right to Object to a Purpose, the corresponding bit for that purpose is set to 0.
	PubPurposesLITransparency map[int]bool
	// The number of Custom Purposes.
	NumCustomPurposes int
	// The consent value for each CustomPurposeId from 1 to NumberCustomPurposes,
	CustomPurposesConsent map[int]bool
	// The legitimate Interest disclosure establishment value for each CustomPurposeId from 1 to NumberCustomPurposes.
	CustomPurposesLITransparency map[int]bool
}

PublisherTCEntry represents Publisher Purposes Transparency and Consent.

type RangeEntry added in v0.2.0 

type RangeEntry struct {
	StartVendorID int
	EndVendorID   int
}

RangeEntry defines an inclusive range of vendor IDs from StartVendorID to EndVendorID.

type RestrictionType added in v0.3.0 

type RestrictionType int

RestrictionType is an enum type of publisher restriction types. 

const (
	// Purpose Flatly Not Allowed by Publisher (regardless of Vendor declarations).
	PurposeFlatlyNotAllowed RestrictionType = iota
	// Require Consent (if Vendor has declared the Purpose IDs legal basis as Legitimate
	// Interest and flexible)
	RequireConsent
	// Require Legitimate Interest (if Vendor has declared the Purpose IDs legal basis as Consent and flexible).
	RequireLegitimateInterest
	// Undefined (not used).
	Undefined
)

type SegmentType added in v0.3.0 

type SegmentType int

SegmentType is an enum type of possible Out-of-Band (OOB) legal bases. 

const (
	// The core string.
	CoreString SegmentType = iota
	// The DisclosedVendors is a TC String segment that signals which vendors have been disclosed to a given user
	// by a CMP. This segment is required when saving a global-context TC String. When a CMP updates a globally-scoped
	// TC String, the CMP MUST retain the existing values and only add new disclosed Vendor IDs that had not been added
	// by other CMPs in prior interactions with this user.
	DisclosedVendors
	// Signals which vendors the publisher permits to use OOB legal bases.
	AllowedVendors
	// Publishers may need to establish transparency and consent for a set of personal data processing
	// purposes for their own use. For example, a publisher that wants to set a frequency-capping first-party
	// cookie should request user consent for Purpose 1 "Store and/or access information on a device" in
	// jurisdictions where it is required.
	//
	// The Publisher TC segment in the TC string represents publisher purposes transparency & consent signals
	// which is different than the other TC String segments; they are used to collect consumer purposes transparency
	// & consent for vendors. This segment supports the standard list of purposes defined by the TCF as well as
	// Custom Purposes defined by the publisher if they so choose.
	PublisherTC
)

type SpecialFeature added in v0.3.0 

type SpecialFeature int

SpecialFeature is an enum type for special features. The TCF Policies designates certain Features as “special” which means a CMP must afford the user a means to opt in to their use. These “Special Features” are published and numerically identified in the Global Vendor List separately from normal Features. 

const (
	InvalidSpecialFeature SpecialFeature = iota
	// Vendors can:
	// - Collect and process precise geolocation data in support of one or more purposes.
	// - N.B. Precise geolocation means that there are no restrictions on the precision of a user’s location;
	//   this can be accurate to within several meters.
	UsePreciseGeolocation
	// Vendors can:
	// - Create an identifier using data collected via actively scanning a device for specific characteristics, e.g.
	//   installed fonts or screen resolution.
	// - Use such an identifier to re-identify a device.
	ActivelyScanDevice
)

type SpecialPurpose added in v0.3.0 

type SpecialPurpose int

SpecialPurpose is an enum type for special purposes. 

const (
	InvalidSpecialPurpose SpecialPurpose = iota
	// To ensure security, prevent fraud and debug vendors can:
	// - Ensure data are securely transmitted
	// - Detect and prevent malicious, fraudulent, invalid, or illegal activity.
	// - Ensure correct and efficient operation of systems and processes, including to monitor and enhance the
	//    performance of systems and processes engaged in permitted purposes.
	// Vendors cannot:
	// - Conduct any other data processing operation allowed under a different purpose under this purpose
	EnsureSecurity
	// To deliver information and respond to technical requests vendors can:
	// - Use a user’s IP address to deliver an ad over the internet
	// - Respond to a user’s interaction with an ad by sending the user to a landing page
	// - Use a user’s IP address to deliver content over the internet
	// - Respond to a user’s interaction with content by sending the user to a landing page
	// - Use information about the device type and capabilities for delivering ads or content, for example, to deliver
	// the right size ad creative or video file in a format supported by the device
	// Vendors cannot:
	// - Conduct any other data processing operation allowed under a different purpose under this purpose
	TechnicallyDeliverAds
)

type TCFVersion added in v0.3.0 

type TCFVersion int

TCFVersion is an enum type used for easily identifying which version a consent string is. 

const (
	// InvalidTCFVersion represents an invalid version.
	InvalidTCFVersion TCFVersion = iota
	// V1 represents a TCF v1.1 string.
	V1
	// V2 represents a TCF v2 string.
	V2
)

func TCFVersionFromTCString added in v0.3.0 

func TCFVersionFromTCString(s string) TCFVersion

TCFVersionFromTCString allows the caller to pass any valid consent string to determine which parse method is appropriate to call or otherwise return InvalidTCFVersion (0).

type V2ParsedConsent added in v0.3.0 

type V2ParsedConsent struct {
	// Version number of the encoding format.
	Version int
	// Epoch deciseconds when this TC String was first created (should not be changed
	// unless a new TCString is created from scratch).
	Created time.Time
	// Epoch deciseconds when TC String was last updated (Must be updated any time a
	// value is changed).
	LastUpdated time.Time
	// Consent Management Platform ID that last updated the TC String.
	// A unique ID will be assigned to each Consent Management Platform.
	CMPID int
	// Consent Management Platform version of the CMP that last updated this TC String.
	// Each change to a CMP should increment their internally assigned version number as
	// a record of which version the user gave consent and transparency was established.
	CMPVersion int
	// CMP Screen number at which consent was given for a user with the CMP that last
	// updated this TC String. The number is a CMP internal designation and is CMPVersion
	// specific. The number is used for identifying on which screen a user gave consent
	// as a record.
	ConsentScreen int
	// Two-letter ISO 639-1 language code in which the CMP UI was presented.
	ConsentLanguage string
	// Number corresponds to the Global Vendor List (GVL) vendorListVersion.
	VendorListVersion int
	// Version of policy used within GVL.
	TCFPolicyVersion int
	// Whether the signals encoded in this TC String were from service-specific storage
	// (true) versus ‘global’ consensu.org shared storage (false).
	IsServiceSpecific bool
	// Setting this to 1 means that a publisher-run CMP – that is still IAB Europe
	// registered – is using customized Stack descriptions and not the standard stack
	// descriptions defined in the Policies. A CMP that services multiple publishers sets
	// this value to 0.
	UseNonStandardStacks bool
	// The TCF Policies designates certain Features as “special” which means a CMP must
	// afford the user a means to opt in to their use. These “Special Features” are
	// published and numerically identified in the Global Vendor List separately from
	// normal Features.
	SpecialFeaturesOptIn map[int]bool
	// The user’s consent value for each Purpose established on the legal basis of consent.
	// The Purposes are numerically identified and published in the Global Vendor List.
	// From left to right, Purpose 1 maps to the 0th bit, purpose 24 maps to the bit at
	// index 23. Special Purposes are a different ID space and not included in this field.
	PurposesConsent map[int]bool
	// The Purpose’s transparency requirements are met for each Purpose on the legal basis
	// of legitimate interest and the user has not exercised their “Right to Object” to that
	// Purpose. By default or if the user has exercised their “Right to Object” to a Purpose,
	// the corresponding bit for that Purpose is set to 0. From left to right, Purpose 1 maps
	// to the 0th bit, purpose 24 maps to the bit at index 23. Special Purposes are a
	// different ID space and not included in this field.
	PurposesLITransparency map[int]bool
	// CMPs can use the PublisherCC field to indicate the legal jurisdiction the publisher is
	// under to help vendors determine whether the vendor needs consent for Purpose 1. In a
	// globally-scoped TC string, this field must always have a value of 0. When a CMP
	// encounters a globally-scoped TC String with PurposeOneTreatment=1 then it is considered
	// invalid and the CMP must discard it and re-establish transparency and consent.
	PurposeOneTreatment bool
	// The country code of the country that determines legislation of reference. Commonly,
	// this corresponds to the country in which the publisher’s business entity is established.
	PublisherCC string

	// The maximum Vendor ID that is represented in the following bit field or range encoding.
	MaxConsentVendorID int
	// The encoding scheme used to encode the IDs in the section – Either a BitField Section or
	// Range Section follows. Encoding logic should choose the encoding scheme that results in
	// the smaller output size for a given set.
	IsConsentRangeEncoding bool
	// The consent value for each Vendor ID.
	ConsentedVendors map[int]bool
	// Number of RangeEntry sections to follow.
	NumConsentEntries int
	// A single or range of Vendor ID(s) who have received consent. If a Vendor ID is not within
	// the bounds of the ranges then the vendor is assumed to have “No Consent”.
	ConsentedVendorsRange []*RangeEntry

	// The maximum Vendor ID that is represented in the following bit field or range encoding.
	MaxInterestsVendorID int
	// The encoding scheme used to encode the IDs in the section – Either a BitField Section or
	// Range Section follows. Encoding logic should encode with the encoding scheme that results
	// in the smaller output size for a given set.
	IsInterestsRangeEncoding bool
	// The legitimate interest value for each Vendor ID from 1 to MaxVendorId. Set the bit
	// corresponding to a given vendor to 1 if the CMP has established transparency for a vendor's
	// legitimate interest disclosures. If a user exercises their “Right To Object” to a vendor’s
	// processing based on a legitimate interest, then that vendor’s bit must be set to 0.
	InterestsVendors map[int]bool
	// 	Number of RangeEntry sections to follow.
	NumInterestsEntries int
	// A single or range of Vendor ID(s) who have established transparency for their legitimate
	// interest disclosures with the user. If a Vendor ID is not within the bounds of the ranges
	// then they have not established that transparency.
	InterestsVendorsRange []*RangeEntry

	// Number of restriction records to follow.
	NumPubRestrictions int
	// Each Publisher Restriction Entry is made up of three parts: Purpose ID, Restriction Type and,
	// List of Vendor IDs under that Purpose restriction.
	PubRestrictionEntries []*PubRestrictionEntry

	// The DisclosedVendors is a TC String segment that signals which vendors have been disclosed
	// to a given user by a CMP.
	OOBDisclosedVendors *OOBVendorList
	// Signals which vendors the publisher permits to use OOB legal bases.
	OOBAllowedVendors *OOBVendorList
	// Publishers may need to establish transparency and consent for a set of personal data processing
	// purposes for their own use. For example, a publisher that wants to set a frequency-capping
	// first-party cookie should request user consent for Purpose 1 "Store and/or access information on
	// a device" in jurisdictions where it is required.
	//
	// The Publisher TC segment in the TC string represents publisher purposes transparency & consent
	// signals which is different than the other TC String segments; they are used to collect consumer
	// purposes transparency & consent for vendors. This segment supports the standard list of purposes
	// defined by the TCF as well as Custom Purposes defined by the publisher if they so choose.
	*PublisherTCEntry
}

V2ParsedConsent represents data extracted from an v2 TCF Consent String.

func ParseV2 added in v0.3.0 

func ParseV2(s string) (*V2ParsedConsent, error)

ParseV2 takes a base64 Raw URL Encoded string which represents a TCF v2 string and returns a ParsedConsent with its fields populated with the values stored in the string.

Example Usage: 

var pc, err = iabconsent.ParseV2("COvzTO5OvzTO5BRAAAENAPCoALIAADgAAAAAAewAwABAAlAB6ABBFAAA")

Source Files

View all Source files

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.