Package: trinomial
TrinomialTrinomial is a simple Python library for performing a one-way transformation from a text string (such as a person's name or email address) to a short hexadecimal character sequence. The result can be used in place of the original string to hide a person's identity in log messages and similar situations.Table of contentsIntroductionInstallationUsageKnown issues and limitationsGetting helpContributingLicenseAuthors and historyAcknowledgmentsIntroductionIf you want to preserve user's privacy in software applications, you need to avoid storing or printing user identities to the maximum extent possible. One of the situations in which user identities can leak is software logging or debugging messages. Even when stored only on servers in server logs, user identities are at risk of exposure to systems administrators, hackers, or the developers of the software. The challenge is that it's often important for debugging or other analysis to be able to recognize the same user in multiple messages even if we don't need to know their real identities. Thus, what we need is a way to tell userAfrom userB, even if we don't care to know whoAandBare in the real world.Trinomial (trivial anonymizationlibrary) is a Python package that can help keep users anonymous in such situations. It takes a string (such as an email address, or a name) and transforms it in a consistent way – the same input will always yield the same output – that is alsoirreversible: given only the output, it is impossible to determine the unique original input that produce it, even knowing Trinomial's source code. You can apply Trinomial to names in error messages in your application, and the names will be transformed to short strings of (essentially) random hexadecimal digits everywhere they appear.Using Trinomial in code is simply a matter of calling a certain function when you want to print something that may be identifiable. Here is a hypothetical example:fromtrinomialimportanon# do some stuff ...email=request.forms.get('email')logging.info(f'got submission from user{anon(email)}')# do some other stuff ...logging.info(f'redirecting{anon(email)}to page /flowers')Please be aware that this kind of approachonly offers pseudoanonymity at best. It cannot protect against a number of other methods of breaking anonymity, such as analyzing correlations between information in your logs or reading IP addresses (if your logs also contain IP addresses).  Trinomial can help improve anonymity, but it cannot do everything alone. It isnot intended for sensitive applications, or legal requirements such as the GDPR,  HIPAA, or producing public data sets, or similar situations.InstallationThe instructions below assume you have a Python interpreter installed on your computer; if that's not the case, please firstinstall Python version 3and familiarize yourself with running Python programs on your system.OnLinux,macOS, andWindowsoperating systems, you should be able to installtrinomialwithpip.  To installtrinomialfrom thePython package repository (PyPI), run the following command:python3 -m pip install trinomialAs an alternative to getting it fromPyPI, you can usepipto installtrinomialdirectly from GitHub, like this:python3-mpipinstallgit+https://github.com/caltechlibrary/trinomial.gitUsageThe main function provided by Trinomial isanon. It takes an input string of characters and returns a transformed, shorter string.>>>fromtrinomialimportanon>>>email='flower@example.com'>>>anon(email)'bcb403adb7'The output ofanonis a string of hexadecimal digits.  The functionanonaccepts an optional argument to control the length of the output string.  The default length is 10 hex digits.  (See the section onKnown issues and limitationsfor more information about the implications of this.)>>>anon(email,length=5)'ed598'Special functionsTrinomial takes measures to increase anonymity beyond what would be obtained by simply hashing text strings.  One is that it computes hashes by incorporating a unique key derived from the identity of the computer on which it is running.  Thus, a given input to theanonfunction on two different computers will produce two different results. This is on purpose, so that someone can't take the output ofanonand easily mount an offline brute-forcepreimage attackto guess what input produced that outputwithout alsohaving access to the machine that produced the output, to determine the unique key.  Nevertheless, for some purposes such as software testing, it may be desirable to set the unique key to a known value. This can be done using the functionset_unique_key:>>>importtrinomial>>>trinomial.set_unique_key('my secret unique key here')Do not do this in production code. Setting the value in your code makes it much easier for someone to try to reverse the process of producing the output. The functionset_unique_keyis meant for testing and debugging.Known issues and limitationsTrinomial is intended as a simple package to replace meaningful textual information with meaningless identifiers, such that (a) it is impractically difficult to discover the original text given only such an identifier, and (b) correlations between occurrences of the original text are preserved. However, it is at best a pseudoanonymization tool. It is not intended for sensitive applications, or legal requirements such as the GDPR,  HIPAA, or similar situations.The possibility of output collisions between two or more identical input values is low, but not zero. The calculation of collisions for a hash function is based on the number of bitsbin the hashed output value, according to the function 2b/2.  A hexadecimal character can encode 4 bits, which means a hexadecimal string of lengthnis equal ton×4 bits. This means that theTrinomial default length of 10 output characters gives a maximum of 2(4×10)/2= 1,048,576 possible unique values. In the author's opinion, this is reasonable for a situation such as (e.g.) anonymizing email addresses in the logs of a program at a small educational institution, but may be too low for other situations. Users may want to increase thelengthparameter toanonaccordingly.Getting helpIf you find an issue, please submit it inthe GitHub issue trackerfor this repository.ContributingWe would be happy to receive your help and participation with enhancing Trinomial!  Please visit theguidelines for contributingfor some tips on getting started.LicenseSoftware produced by the Caltech Library is Copyright (C) 2021, Caltech.  This software is freely distributed under a BSD/MIT type license.  Please see theLICENSEfile for more information.Authors and historyTrinomial was designed and implemented byMichael Hucka.AcknowledgmentsThis work was funded by the California Institute of Technology Library.Thevector artworkused as a starting point for the logo for this repository was created byRflorfor theNoun Project.  It is licensed under the Creative CommonsAttribution 3.0 Unportedlicense.  The vector graphics was modified by Mike Hucka to change the color.