Secrets
Secrets can either by obscured or generated.
Obscured Secrets
Obscured secrets are secrets that are those that are given to Avendesora to securely hold. The may be things like account numbers or existing passwords. There are several ways for Avendesora to hold a secret, presented in order of increasing security.
Hide
This marks a value as being confidential, meaning that it will be protected when shown to the user, but value is not encoded or encrypted in any way. Rather, it accounts on the protections afforded the accounts file to protect its secret.
Hide(plaintext, secure=True)plaintext (str):The secret in plain text.secure (bool):Indicates that this secret should only be contained in anencrypted accounts file. Default is True.
Example:
account = Hide('9646-3440')
GPG
The secret is fully encrypted with GPG. Both symmetric encryption and key-based encryption are supported. This can be used to protect a secret held in an unencrypted account file, in which case encrypting with your key is generally preferred. It can also be used to further protect a extremely valuable secret, in which case symmetric encryption is generally used.
GPG(ciphertext, encoding=None)ciphertext (str):The secret encrypted and armored by GPG.encoding (str):The encoding to use for the deciphered text.
Example:
secret = GPG('''
-----BEGIN PGP MESSAGE-----
Version: GnuPG v2.0.22 (GNU/Linux)
jA0ECQMCwG/vVambFjfX0kkBMfXYyKvAuCbT3IrEuEKD//yuEMCikciteWjrFlYD
ntosdZ4WcPrFrV2VzcIIcEtU7+t1Ay+bWotPX9pgBQcdnSBQwr34PuZi
=4on3
-----END PGP MESSAGE-----
''')
To generate the cipher text, use:
> avendesora conceal -e gpg
The benefit of using symmetric GPG encryption on a secret that is contained in an encrypted account file is that the passphrase will generally not be found in the GPG agent, in which case someone could not walk up to your computer while your screen is unlocked and successfully request the secret. However, the GPG agent does retain the password for a while after you decrypt the secret. If you are concerned about that, you should follow your use of Avendesora with the following command, which clears the GPG agent:
> killall gpg-agent
Scrypt
The secret is fully encrypted with Scrypt. You personal Avendesora encryption key is used (contained in ~/.config/avendesora/.key.gpg). As such, these secrets cannot be shared. This encryption method is only available if you have installed scrypt on your system (pip3 install –user scrypt). Since the Scrypt class only exists if you have installed scrypt, it is not imported into your accounts file. You would need to import it yourself before using it.
Script(ciphertext, encoding=None)ciphertext (str):The secret encrypted by scrypt.encoding (str):The encoding to use for the deciphered text.
Example:
from avendesora import Scrypt
...
secret = Scrypt(
'c2NyeXB0ABAAAAAIAAAAASfBZvtYnHvgdts2jrz5RfbYlFYj/EQgiM1IYTnX'
'KHhMkleZceDg0yUaOWa9PzmZueppNIzVdawAOd9eSVgGeZAIh4ulPHPBGAzX'
'GyLKc/vo8Fe24JnLr/RQBlTjM9+r6vbhi6HFUHD11M6Ume8/0UGDkZ0='
)
To generate the cipher text, use:
> avendesora conceal -e scrypt
Generated Secrets
Generated secrets are secrets for which the actual value is arbitrary, but it must be quite unpredictable. Generated secrets are generally used for passwords and pass phrases, but it can also be used for things like personal information requested by institutions that they have no need to know. For example, a website might request your birth date to assure that you are an adult, but then also use it as a piece of identifying information if you ever call and request support. In this case they do not need your actual birth date, they just need you to give the same date every time you call in.
Password
Generates an arbitrary password by selecting symbols from the given alphabet at random. The entropy of the generated password is length*log2(len(alphabet)).
Password(length=12, alphabet=DISTINGUISHABLE, master=None, version=None,sep=’’, prefix=’’, suffix=’’)length (int):The number of items to draw from the alphabet when creating thepassword. When using the default alphabet, this will be thenumber of characters in the password.alphabet (str):The reservoir of legal symbols to use when creating thepassword. By default the set of easily distinguishedalphanumeric characters are used. Typically you would use thepre-imported character sets to construct the alphabet. Forexample, you might pass:ALPHANUMERIC + ‘+=_&%#@’master (str):Overrides the master seed that is used when generating thepassword. Generally, there is one master seed shared by allaccounts contained in an account file. This argument overridesthat behavior and instead explicitly specifies the master seedfor this secret.version (str):An optional seed. Changing this value will change the generatedpassword.shift_sort(bool):If true, the characters in the password will be sorted so thatthe characters that require the shift key when typing are placedlast, making it easier to type. Use this option if you expect tobe typing the password by hand.sep (str):A string that is placed between each symbol in the generatedpassword.prefix (str):A string added to the front of the generated password.suffix (str):A string added to the end of the generated password.
Example:
passcode = Password(10)
Passphrase
Similar to Password in that it generates an arbitrary pass phrase by selecting symbols from the given alphabet at random, but in this case the default alphabet is a dictionary containing about 10,000 words.
Passphrase(length=4, dictionary=None, master=None, version=None, sep=’ ‘,prefix=’’, suffix=’’)length (int):The number of items to draw from the alphabet when creating thepassword. When using the default alphabet, this will be thenumber of words in the passphrase.dictionary (str, [str], or callable):The reservoir of legal symbols to use when creating thepassword. If not give, or if ‘default’ is given, this is apredefined list of 10,000 words. If given as ‘bip39’ or‘mnemonic’, this is a predefined list of the 2048 bitcoin BIP-39seed words. Any other string is treated as a path to a filethat would contain the words. A list is taken as is. Finally, you canpass a function that returns the list of words, in which case thecalling of the function is deferred until the words are needed, which ishelpful if creating the list is slow.master (str):Overrides the master seed that is used when generating thepassword. Generally, there is one master seed shared by allaccounts contained in an account file. This argument overridesthat behavior and instead explicitly specifies the master seedfor this secret.version (str):An optional seed. Changing this value will change the generatedpass phrase.sep (str):A string that is placed between each symbol in the generatedpassword.prefix (str):A string added to the front of the generated password.suffix (str):A string added to the end of the generated password.
Example:
passcode = Passphrase()
verbal = Passphrase(2)
PIN
Similar to Password in that it generates an arbitrary PIN by selecting symbols from the given alphabet at random, but in this case the default alphabet is the set of digits (0-9).
PIN(length=4, alphabet=DIGITS, master=None, version=None)length (int):The number of items to draw from the alphabet when creating thepassword. When using the default alphabet, this will be thenumber of digits in the PIN.alphabet (str):The reservoir of legal symbols to use when creating thepassword. By default the digits (0-9) are used.master (str):Overrides the master seed that is used when generating thepassword. Generally, there is one master seed shared by allaccounts contained in an account file. This argument overridesthat behavior and instead explicitly specifies the master seedfor this secret.version (str):An optional seed. Changing this value will change the generatedPIN.
Example:
pin = PIN(6)
Question
Generates an arbitrary answer to a given question. Used for website security questions. When asked one of these security questions it can be better to use an arbitrary answer. Doing so protects you against people who know your past well and might be able to answer the questions.
Similar to Passphrase() except a question must be specified when created and it is taken to be the security question. The question is used rather than the field name when generating the secret.
Question(question, length=3, dictionary=None, master=None, version=None,sep=’ ‘, prefix=’’, suffix=’’, answer=None)question (str):The question to be answered. Be careful. Changing the questionin any way will change the resulting answer.length (int):The number of items to draw from the alphabet when creating thepassword. When using the default alphabet, this will be thenumber of words in the answer.dictionary (str, [str], or callable):The reservoir of legal symbols to use when creating thepassword. If not give, or if ‘default’ is given, this is apredefined list of 10,000 words. If given as ‘bip39’ or‘mnemonic’, this is a predefined list of the 2048 bitcoin BIP-39seed words. Any other string is treated as a path to a filethat would contain the words. A list is taken as is. Finally, you canpass a function that returns the list of words, in which case thecalling of the function is deferred until the words are needed, which ishelpful if creating the list is slow.master (str):Overrides the master seed that is used when generating thepassword. Generally, there is one master seed shared by allaccounts contained in an account file. This argument overridesthat behavior and instead explicitly specifies the master seedfor this secret.version (str):An optional seed. Changing this value will change the generatedanswer.sep (str):A string that is placed between each symbol in the generatedpassword.prefix (str):A string added to the front of the generated password.suffix (str):A string added to the end of the generated password.answer:The answer. If provided, this would override the generatedanswer. May be a string, or it may be an Obscured object.
Example:
questions = [
Question('Favorite foreign city'),
Question('Favorite breed of dog'),
]
PasswordRecipe
Generates passwords that can conform to the restrictive requirements imposed by websites. Allows you to specify the length of your password, and how many characters should be of each type of character using a recipe. The recipe takes the form of a string that gives the total number of characters that should be generated, and then the number of characters that should be taken from particular character sets. The available character sets are:
l - lower case letters (a-z)u - upper case letters (A-Z)d - digits (0-9)s - punctuation symbolsc - explicitly given set of characters
For example, ‘12 2u 2d 2s’ is a recipe that would generate a 12-character password where two characters would be chosen from the upper case letters, two would be digits, two would be punctuation symbols, and the rest would be alphanumeric characters. It might generate something like: @m7Aqj=XBAs7
Using ‘12 2u 2d 2c!@#$%^&*’ is similar, except the punctuation symbols are constrained to be taken from the given set that includes !@#$%^&*. It might generate something like: YO8K^68J9oC!
PasswordRecipe(recipe, def_alphabet=ALPHANUMERIC, master=None, version=None,)recipe (str):A string that describes how the password should be constructed.def_alphabet (list of strs):The alphabet to use when filling up the password after all theconstraints are satisfied.master (str):Overrides the master seed that is used when generating thepassword. Generally, there is one master seed shared by allaccounts contained in an account file. This argument overridesthat behavior and instead explicitly specifies the master seedfor this secret.version (str):An optional seed. Changing this value will change the generatedanswer.shift_sort(bool):If true, the characters in the password will be sorted so thatthe characters that require the shift key when typing are placedlast, making it easier to type. Use this option if you expect tobe typing the password by hand.
Example:
passcode = PasswordRecipe(‘12 2u 2d 2c!@#$%^&*’)
BirthDate
Generates an arbitrary birth date for someone in a specified age range.
BirthDate(year, min_age=18, max_age=65, fmt=’YYYY-MM-DD’,master=None, version=None,)year (int):The year the age range was established.min_age (int):The lower bound of the age range.max_age (int):The upper bound of the age range.fmt (str):Specifies the way the date is formatted. Consider an exampledate of 6 July 1969. YY and YYYY are replaced by the year (69 or1969). M, MM, MMM, and MMMM are replaced by the month (7, 07,Jul, or July). D and DD are replaced by the day (6 or 06).master (str):Overrides the master seed that is used when generating thepassword. Generally, there is one master seed shared by allaccounts contained in an account file. This argument overridesthat behavior and instead explicitly specifies the master seedfor this secret.version (str):An optional seed. Changing this value will change the generatedanswer.
Example:
birthdate = BirthDate(2015, 21, 55)
Base58
Generates an arbitrary Base58 encoded stringa. Base58 is an encoding developed for Bitcoin addresses. It is nice because the characters are limited to standard ASCII numbers and letters, and those characters that could be confused for one another are removed. Specifically, the Base58 character set are all ASCII numbers and letters except for 0, O, I, and l.
Base58 generates the shortest strings for a given amount of entropy of any of the secrets generated by Avendesora.
Base58(bytes=4, master=None, version=None, is_secret=True,)bits (int):The number of bytes of entropy encoded in the result.master (str):Overrides the master seed that is used when generating thepassword. Generally, there is one master seed shared by allaccounts contained in an account file. This argument overridesthat behavior and instead explicitly specifies the master seedfor this secret.version (str):An optional seed. Changing this value will change the generatedanswer.is_secret (bool):Should value be hidden from the user unles explicitly requested.
Example:
secret = Base58(8)
OTP
Generates a secret that changes once per minute that generally is used as a second factor when authenticating. It can act as a replacement for, and is fully compatible with, Google Authenticator. You would provide the text version of the shared secret (the backup code) that is presented to you when first configuring your second factor authentication.
OTP(shared_secret, interval=30, digits=6)shared_secret (base32 string):The shared secret, it will be provided by the account provider.interval (int):Update interval in seconds.max_age (int):The number of digits to output.
Example:
otp = OTP('JBSWY3DPEHPK3PXP')
Changing a Generated Secret
It is sometimes necessary to change a generated secret. Perhaps because it was inadvertently exposed, or perhaps because the account provider requires you change your secret periodically. To do so, you would simply add the version argument to the secret and then update its value. version may be a number or a string. You should choose a way of versioning that is simple, easy to guess and would not repeat. For example, if you expect that updating the version would be extremely rare, you can simply number them sequentially. Or, if you you need to update them every month or every quarter, you can name them after the month or quarter (ex: jan19 or 19q1).
Examples:
passcode = PasswordRecipe('16 1d', version=2)
passcode = PasswordRecipe('16 1d', version='19q2')