WebDNA Software | [encrypt]

Technical References - [encrypt]

[encrypt] and [decrypt] allow you to store sensitive data in your databases without risk of exposing it to prying eyes.

[encrypt seed=secret_value]passwords, credit card number, etc.[/encrypt]

[decrypt seed=secret_value][YourEncryptedField][/decrypt]

Encrypted text will render as unintelligible, such as

;)g*fg&x#98d(lk$K]esdL,J^`F*j24h0'1

Use [decrypt] (with the same seed value) to decode the text later. The seed may be a sequence of up to 8 characters (anything you can type on the keyboard, except '&' or '=' or '[' or ']'). Keep the seed private, as you would a password.

A specific method would use some code like

[encrypt method=blowfish&seed=secret_value]passwords, credit card number, etc.[/encrypt]

Do not lose or change your seed value, as it is unrecoverable; even the programmers at WSC cannot recover encrypted values without the original seed.

When writing your encrypted value to your database, you must wrap the value in double [url] tags. When reading them back out of the database, use a single [unurl] context. (See explanation* below.)

Example:

[replace ...]UserPassword=[url][url][Encrypt 
seed=1234][UserPassword][/Encrypt][/url][/url][/replace]

[search ...][founditems]
[sendmail ...]
Your password is:
[decrypt seed=1234][unurl][UserPassword][/unurl][/decrypt]
[/sendmail]
[/founditems][/search]

Note that the [url] tags are outside the [encrypt] tags when writing to the database, but inside the [decrypt] tags when retrieving. Think about this a while, and it will make sense.

Logic behind the [url] requirement:
When writing to a database, any value that has potentially misunderstood characters, such as "&" "=" and "]" must be wrapped in a [url] context to change these characters into ascii equivalents (&, etc.). When reading data out of a database, WebDNA automatically converts these escaped characters back to normal characters, so no [unurl] is needed. However, with encryption, some of the encrypted characters may be high ASCII characters that are not encoded enough with a single [url]. Running it through a second time will encode them properly. Because WebDNA is already applying one [unurl] to anything coming out of a database, you will only have to add one [unurl] to balance the two [url]s.

type	ratio [url]'s to [/unurl]'s	example
[url][/url] / [unurl][/unurl]'ing conventions ensure a proper decrypt value!
Variables	1 to 1	[text]var=some value[/text] [text]var=[url][!] [/!][encrypt seed=xxxx][var][/encrypt][!] [/!][/url][/text] [decrypt seed=xxxx][!] [/!][unurl][var][/unurl][!] [/!][/decrypt]
Databases	2 to 1	[text]var=some value[/text] [append db=some.db]id=1&db_value=[url][url][!] [/!][encrypt seed=xxxx][var][/encrypt][!] [/!][/url][/url][/append] [search db=some.db&eqIDdatarq=1] [founditems] [decrypt seed=xxxx][!] [/!][unurl][db_value][/unurl][!] [/!][/decrypt] [/founditems] [/search]
Cookies	2 to 0	[text]var=some value[/text] [setcookie name=thecookie&value=[url][url][!] [/!][encrypt seed=xxxx][var][/encrypt][!] [/!][/url][/url]] [decrypt seed=xxxx][!] [/!][getcookie name=thecookie][!] [/!][/decrypt]
Orderfile	2 to 1	[text]var=some value[/text] [setheader cart=[cart]]header40=[url][url][!] [/!][encrypt seed=xxxx][var][/encrypt][!] [/!][/url][/url][/setheader] [orderfile cart=[cart]] [decrypt seed=xxxx][!] [/!][unurl][header40][/unurl][!] [/!][/decrypt] [/orderfile]

You may optionally choose different special-purpose encryption methods as described in the following table:

Parameter	Description
method	(optional) "CyberCash", "APOP", "Base64", "SHA1", "blowfish", "AES", "SHA256", "GCM" or "twofish". If not specified, then standard WebDNA encryption is assumed. CyberCash is the triple-DES encryption used to communicate with the CyberCash CashRegister servers. Base64 is the encoding (not safe for encryption) standard HTML browsers use for Basic Authentication. APOP is the MD5 encryption used by email servers that support APOP authentication. It is a hash method. A hash is simply a one-way function, that will take a string or data source and create an encrypted looking string. BLOWFISH is a symmetric-key block cipher, designed in 1993 by Bruce Schneier. Blowfish provides a good encryption rate in software and no effective cryptanalysis of it has been found to date. However, TwoFish or AES will be prefered in most cases. The following method have been implemented from WebDNA version 8.1: SHA256 is one of the strongest hash method, meaning that no way is known to recover the original string from the hash. It is a Secure Hash Standard. TWOFISH is a symmetric key block cipher with a block size of 128 bits and key sizes up to 256 bits. Twofish is related to the earlier block cipher Blowfish and improves it further. AES (Advanced Encryption Standard), is a specification for the encryption of electronic data established by the U.S. National Institute of Standards and Technology. AES has been adopted by the U.S. government and is now used worldwide. AES is included in the ISO/IEC 18033-3 standard. AES is available in many different encryption packages, and is the first publicly accessible and open cipher approved by the National Security Agency (NSA) for top secret information when used in an NSA approved cryptographic module. The following method have been implemented from WebDNA version 8.2: SHA1 is considered as a weak method but is still requested by services like cloudify. Galois/Counter Mode (GCM) is a mode of operation for symmetric key cryptographic block ciphers that has been widely adopted because of its efficiency and performance. GCM throughput rates for state of the art, high speed communication channels can be achieved with reasonable hardware resources. The operation is an authenticated encryption algorithm designed to provide both data authenticity (integrity) and confidentiality (see below how to implement it in WebDNA) Bcrypt (8.6) is a password salt / hashing setup that conforms with current standards.
seed	(required, except for Base64, SHA256 and APOP/MD5) Key used to encrypt the text. For CyberCash, this should be the MerchantKey you were assigned when you created a CyberCash merchant account. For standard WebDNA encryption, this is your secret key for decryption later. CyberCash encryption is one-way; it cannot be decrypted by your server.
file	(optional) Specifies a file that is to be encoded using Base64. This is useful for sending e-mail attachments using the WebDNA sendmail context. Note that anything between the opening and closing encrypt tag will be ignored if this parameter is present.
emailformat	(optional) For Base64 only, this specifies if the resulting encoded string should contain line breaks suitable for e-mail applications. Valid values are either 'T' or 'F' the later being the default. This should be used in conjunction with the file parameter above when sending e-mail attachments from a WebDNA template.

Hash algorithms are one way functions. They turn any amount of data into a fixed-length "fingerprint" that cannot be reversed. They also have the property that if the input changes by even a tiny bit, the resulting hash is completely different. This is great for protecting passwords, because we want to store passwords in a form that protects them even if the password file itself is compromised, but at the same time, we need to be able to verify that a user's password is correct.
When the user attempts to login, the hash of the password they entered is checked against the hash of their real password (retrieved from the database). If the hashes match, the user is granted access. If not, the user is told they entered invalid login credentials. The password is not stored anywhere.

Bcrypt
The simplest way to use it is:

[encrypt method=bcrypt]secretpassword[/encrypt]

When no arguments besides method are provided, WebDNA will pick the prefix and a random salt to use.

Later, when you need to check the hash, you pass the old hash in as the seed. This way the proper salt, prefix, and count get used to regenerate the hash. Example:

[text]myhash=$2y$10$jVw1GVXv56uAr2.zDDriK.BkuxORc1y9.qJbkGyRDLWK26Gy3hRSq[/text]
[encrypt method=bcrypt&seed=[myhash]]secretpassword[/encrypt]

If your [encrypt] output is identical to the hash, then you know the password matches the hash.

WebDNA defaults to a prefix of $2y$. If you need to generate new hashes that are compatible with older software, you can provide your own prefix.

A default count of 10 is used. You can increase this to make the passwords harder to break in the future, however, it will also slow down the hashing process. The count cannot be less than 4, or greater than 31.

Example:

[encrypt prefix=$2a$&count=12]password[/encrypt]

If a seed argument is provided, then the prefix and count are used from the seed, and the prefix and count arguments are ignored.

GCM with AES or twofish

GCM is an authentication encryption mode of operation, it is composed by two separate functions: one for encryption (AES-CTR) and one for authentication (GMAC). It receives as input:

- a Key
- a unique IV (Initialization Vector)
- Data to be processed only with authentication
- Data to be processed by encryption and authentication

It outputs:

- The encrypted data of input 4
- An authentication TAG
- The authentication TAG is an input to the decryption, if someone tampered with your associated data or with your encrypted data, GCM decryption will notice this and will not output any data (or return an error and you should discard the received data without processing it)

Mandatory parameters are the same as the other encryption methods:

METHOD=aesgcm or METHOD=twofishgcm
SEED=ascii text value of the key

Optional parameters are:

IV=Hex value of initialization vector. If this is not provided during encryption, 8 bytes will be randomly generated by WebDNA and appended to the beginning of ADATA and the output. If it is not provided during decryption, WebDNA will automatically remove the first 8 bytes of data from the beginning of the cipher text for use as the IV and prepend to ADATA.

ADATA=Hex value of any additional plaintext data that won't be sent in the ciphertext. This will be hashed and validated during decryption.

TAGSIZE=Integer number of bytes for hash tag. The hash is appended to the end of the encrypted data. The default is 12 bytes.

All optional parameters are not required, but if they are provided, they need to be identical during encryption and decryption to avoid a hash failure error.
A failure produces this output:
Exception in DECRYPT command: HashVerificationFilter: message hash or MAC not valid.

Here are some examples

Encrypt

TWOFISHGCM:
[encrypt method=twofishgcm&seed=secret_value]Twofish: passwords, credit card number, etc.[/encrypt]

AESGCM:
[encrypt method=aesgcm&seed=secret_value]passwords, credit card number, etc.[/encrypt]

AESGCM with IV and ADATA and TAGSIZE:
[encrypt method=aesgcm&seed=secret_value&iv=0123456789abcdef&adata=abcdefabcdef&tagsize=8]passwords, credit card number, etc.[/encrypt]

Decrypt

[decrypt method=twofishgcm&seed=secret_value&iv=89e12236ce056aa2&adata=89e12236ce056aa2]999fe9ff644e7e835c3d9d46cfedce88b2de6d1b5d114e29f161e6246d40380b639e73f006a073db567c6e7aa5740f9db45d81fd6a646cbd[/decrypt]

[decrypt method=twofishgcm&seed=secret_value]89e12236ce056aa2999fe9ff644e7e835c3d9d46cfedce88b2de6d1b5d114e29f161e6246d40380b639e73f006a073db567c6e7aa5740f9db45d81fd6a646cbd[/decrypt]

[decrypt method=aesgcm&seed=secret_value] 1a0ce107ed9ede09835b4c25336d8fd49699d21edd4fa365c545ed52b598b341df124b606934ca10f09bd31fbd3f03e993ca82c3f4d0eb[/decrypt]

[decrypt method=aesgcm&seed=secret_value&iv=0123456789abcdef&adata=abcdefabcdef&tagsize=8]7888f14d14bf5d87df292ad7171d391b9da2d6d42da0247683e95d2774bac82e580bde64c9e56bd97e8783[/decrypt]

How to encrypt your templates

Sometimes you will want to give someone else a WebDNA template without letting him or her see your "source code" in the file. For example, if you create a WebDNA solution that is for sale, you may not want others to be able to read the templates and make modifications or see your proprietary algorithms.

To create an encrypted template, you must first design and debug the template as you normally would. Then use the [encrypt] context with a seed of your choosing to create the encrypted version of the original template. Note that you shouldn't make your seed value public in any way. After the template has been encrypted, a special tag must be added to the top of the file so it can be recognized as an encrypted file, and then your seed value must be encrypted using WebDNA's default encryption.

Use the following WebDNA to do all of the necessary steps at once: encrypt your file and add the special WebDNA header tag to the beginning of the file. Note that you may put any unencrypted text (such as copyright information) before the header tag. The encrypted WebDNA must start on the line after the header tag. In this example, to automatically convert your template (file.dna) to an encrypted template (newfile.dna) you would execute the following on some other page:

[writefile file=newfile.dna&secure=F]Copyright 2015 Your Name Here
http://www.yourwebsitehere.com/
<!--HAS_WEBDNA_TAGS[!][/!]_ENCRYPTED_2--> 
[encrypt]seed=XXXX&product=WDNA[/encrypt] 
[encrypt seed=XXXX][include file=file.dna&raw=T][/encrypt][/writefile]

After using the above template, your hard disk will contain a file called "newfile.dna" which you can give to other users, confident that they cannot read or modify it. Using the template is easy it works just like any other template.

[!][/!] is a special trick to fool WebDNA into thinking this page is not an encrypted page, and should be treated like a normal template. The [!][/!] is removed during processing, which causes the resulting template to contain the correct tag that indicates it is encrypted.

In order to prevent someone from displaying or accessing the decrypted templates, the following precaution has been made: [include raw=T] cannot be done on encrypted templates; nothing is returned.

Terry Wilson

DOWNLOAD WEBDNA NOW!

Technical References - [encrypt]

How to encrypt your templates

Top Articles:

Related Readings: