Commit 23b986cf authored by Clark's avatar Clark
Browse files

Adding a Style Guide draft, still unpublished

parent 657d79a0
#+TITLE: Style Guide
#+SUBTITLE: The spec for this blog, and for life.
#+BEGIN_VERSE
An exhaustive style guide for this blog and syntax guide for covered programming languages.
#+END_VERSE
* Prerequisites
Emacs text editor, using [[https://git.bytecache.io/ehacks/ehacks][this config]]. The following should install Emacs and apply this config.
#+BEGIN_SRC sh
sudo apt install -y emacs elpa-evil graphviz elpa-rainbow-mode && \
mkdir ~/.emacs.d && \
cd ~/.emacs.d && \
git clone --recursive https://git.bytecache.io:ehacks/ehacks.git .
#+END_SRC
Then open Emacs. A couple restarts may be necessary to install all packages and dependencies.
* Accessibility
Accessibility is a theme throughout. Content should be easy to read and follow for all people, given reasonable expectations.
The color theme of the blog is selected to be accessible for those with color blindness. Dark (default) and light themes are provided, with the following color palettes:
#+CAPTION: Color Palettes
#+NAME: Color Palettes
| Color Key | Dark Theme Value | Light Theme Value |
|--------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------|
| foreground-color-1 | @@html: <span style = "background-color:#d6deeb;">&emsp;</span>@@ #d6deeb | @@html: <span style = "background-color:#403f53;">&emsp;</span>@@ #403f53 |
| background-color-1 | @@html: <span style = "background-color:#011627;">&emsp;</span>@@ #011627 | @@html: <span style = "background-color:#fbfbfb;">&emsp;</span>@@ #fbfbfb |
| foreground-color-2 | @@html: <span style = "background-color:#4373c2;">&emsp;</span>@@ #4373c2 | @@html: <span style = "background-color:#90a7b2;">&emsp;</span>@@ #90a7b2 |
| background-color-2 | @@html: <span style = "background-color:#0b253a;">&emsp;</span>@@ #0b253a | @@html: <span style = "background-color:#e0e0e0;">&emsp;</span>@@ #e0e0e0 |
| foreground-color-e | @@html: <span style = "background-color:#7e57c2;">&emsp;</span>@@ #7e57c2 | @@html: <span style = "background-color:#994cc3;">&emsp;</span>@@ #994cc3 |
| background-color-e | @@html: <span style = "background-color:#5f7e97;">&emsp;</span>@@ #5f7e97 | @@html: <span style = "background-color:#d3e8f8;">&emsp;</span>@@ #d3e8f8 |
| border-color-1 | @@html: <span style = "background-color:#234d70;">&emsp;</span>@@ #234d70 | @@html: <span style = "background-color:#cccccc;">&emsp;</span>@@ #cccccc |
| border-color-e | @@html: <span style = "background-color:#4373c2;">&emsp;</span>@@ #4373c2 | @@html: <span style = "background-color:#93a1a1;">&emsp;</span>@@ #93a1a1 |
| code-builtin | @@html: <span style = "background-color:#82aaff;">&emsp;</span>@@ #82aaff | @@html: <span style = "background-color:#4876d6;">&emsp;</span>@@ #4876d6 |
| code-comment | @@html: <span style = "background-color:#4b6479;">&emsp;</span>@@ #4b6479 | @@html: <span style = "background-color:#989fb1;">&emsp;</span>@@ #989fb1 |
| code-constant | @@html: <span style = "background-color:#f78c6c;">&emsp;</span>@@ #f78c6c | @@html: <span style = "background-color:#aa0982;">&emsp;</span>@@ #aa0982 |
| code-function-name | @@html: <span style = "background-color:#82aaff;">&emsp;</span>@@ #82aaff | @@html: <span style = "background-color:#994cc3;">&emsp;</span>@@ #994cc3 |
| code-keyword | @@html: <span style = "background-color:#c792ea;">&emsp;</span>@@ #c792ea | @@html: <span style = "background-color:#994cc3;">&emsp;</span>@@ #994cc3 |
| code-string | @@html: <span style = "background-color:#ecc48d;">&emsp;</span>@@ #ecc48d | @@html: <span style = "background-color:#c96765;">&emsp;</span>@@ #c96765 |
| code-variable-name | @@html: <span style = "background-color:#addb67;">&emsp;</span>@@ #addb67 | @@html: <span style = "background-color:#4876d6;">&emsp;</span>@@ #4876d6 |
* TODO File structure
This section describes how to write a blog post. This begins with requirements that apply to /all/ blog posts, then provides additional requirements for specific types of blog posts.
** Org files
This blog is published with Emacs (Org-mode) using [[https://git.bytecache.io/ehacks/ehacks][this config]]. For example, the raw =.org= file used to write /this post/ [[https://git.bytecache.io/bytecache/blog/-/raw/master/content/Style-Guide.org][is here]].
Provided this config, the following guidelines applies to writing =.org= files used for publishing this blog:
- Only the =#+TITLE=, and optionally the =#+SUBTITLE=, need to be set in org files.
- It is not necessary to include the =#+DATE=, as /last modified/ is used during publishing.
- =#+AUTHOR= and =#+EMAIL= should be set in the org config????????? These can be overridden on a per-file basis if desired.
- Code blocks should not execute on export ????? Should be pre-executed and cached. This is for safety.
*** Types of publishing
There are 3 types of publishing in this config???
- orgfiles
- ux - css and js files
- pgp
- images
Blog posts should be published one file at a time (=org-publish-current-file=), rather than across the entire project.
*** Source blocks
Put a =#+CAPTION:= in front to denote when a file is saved, with the contents. For example:
#+CAPTION: example_file.sh
#+BEGIN_SRC sh
#!/bin/bash
echo "example file"
#+END_SRC
Otherwise, if code should be run interactively, omit the caption.
#+BEGIN_SRC sh
echo "interactive command"
#+END_SRC
*** TODO Quote blocks
*** TODO Example blocks
*** TODO Verse blocks
*** TODO Tables
Tables may or may not include a label / caption? Depends on purpose... Sometimes table format is used to make a tidy list.
This is actually a weird use of a list...
#+CAPTION: One Time Pad on 2 bytes
#+NAME: tab:otp-example
| m | 0 | 1 | 1 | 1 | 0 | 1 | 0 | 1 | 0 | 0 | 1 | 0 | 1 | 1 | 0 | 0 |
| $\oplus$ | | | | | | | | | | | | | | | | |
| k | 1 | 0 | 1 | 0 | 0 | 0 | 1 | 1 | 0 | 1 | 1 | 0 | 0 | 0 | 0 | 0 |
|----------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---|
| c | 1 | 1 | 0 | 1 | 0 | 1 | 1 | 0 | 0 | 1 | 0 | 0 | 1 | 1 | 0 | 0 |
Here is some list:
| Key | Value |
|-----+-------|
| Foo | 1 |
| Bar | 2 |
| Zar | 3 |
*** TODO Markup
Org mode markup works like so:
*bold*
/italics/
+strikethrough+
_underline_
=printf('code')=
@@html:<div style="color:#4b6479;background-color:#fff;">Here is a custom div</div>@@
** File outline
All blog posts should begin with a verse, briefly describing the purpose. This should immediately be followed by a =level 1= header labeled *Prerequisites*, describing what is necessary to follow the blog post.
Headings / subheadings - all content is within the subheading (no escaping back to the parent heading).
*** Headers
Level1 thru level4
Levels are also part of their parent levels, cannot escape back to higher level once lower level established for parent
*** Whitespace
Org files create new paragraphs where there is an empty line break between paragraphs.
This is the second paragraph of this subheader.
*** Use of footnotes
Footnotes are encouraged, particularly when cross-referencing 3rd party resources. Inline description should be included, and name should be excluded (defaulting to integers). This provides for minimal maintenance of the =.org= file. For example, to create this footnote[fn::This is an example footnote], I use =[fn::This is an example footnote]=. Here is a second footnote[fn::Just for good measure].
*** Numbers
No numbers should be written out (e.g., one hundred), and sentences should not begin with numbers. Blog posts are expected to use the most appropriate type of numeric format based on the content (e.g., decimal, scientific, binary/hex).
* TODO Types of blog posts
There are various types of blog posts. They each require specific elements and formats.
*** Reference guides
Guides to reproduce shit I've done.
*** Trip reports
Notes from places I've gone.
* TODO Images
** Types of images
Different purposes. Not always possible. When possible:
*** TODO UML diagrams
An encouraged method of communication, UML diagrams are a great and interactive way to communicate complex subjects.
*** TODO Ditaa
#+BEGIN_SRC ditaa :file img/Semantic_Security_Proof.png :cmdline -e utf-8 -A -T -E :java -Dfile.encoding=UTF-8
/-------------------------\
| |
| =Adv[A,E] |
| cEFF |
+------------+------------+
| | |
| =Adv[B,G] | =Adv[B,G] |
| cEFF | cEFF |
*-----*------------*------------*-----*
0 Pr[W₀] Pr[Rb] Pr[W₁] 1
=Pr[R₀]
=Pr[R₁]
#+END_SRC
#+RESULTS[6876a4750dba5df51a3ffa746e8d6b5fe6a4656b]:
[[file:img/Semantic_Security_Proof.png]]
*** SVG
Transparent backgrounds.
This blog encourages use of interactive SVGs with embedded links and detailed explanations.
*** PNG
Transparent backgrounds.
Should be preferred format for images which do not provide additional functionality. This makes it easy to embed /these/ PNGs into SVGs used elsewhere on the blog.
*** JPG
Large images, like wallpapers or high resolution photos.
* TODO Mathematics
Math equations are written in =LaTeX=. Math can be written inline, such as: $k \oplus m = k + m \mod 2$. Otherwise, they may be written in block format, in which case they need to include a label, which makes it easy to dynamically reference in the document.
#+BEGIN_LATEX
\begin{equation}\label{equivalence}
E: \quad \mathscr{K} \times \mathscr{M} \rightarrow \mathscr{C},\qquad D: \quad \mathscr{K} \times \mathscr{C} \rightarrow \mathscr{M} \\
{\bf \ni \quad \forall m \in \mathscr{M}, \quad k \in \mathscr{K}: \quad D(k, E(k,m)) = m}
\end{equation}
#+END_LATEX
You could also put a title, which should be similar to the label??? doesn't really work... better to quote it?
#+NAME: Predictability
#+CAPTION: Predictability
#+BEGIN_LATEX
\begin{equation}\label{predictability}
\underset{k \xleftarrow{R} \mathscr{K}}{Pr}[ \mathscr{A}(\mathscr{G}(k))|_{1,...,i} = \mathscr{G}(k)|_{i+1} ] \geq \frac{1}{2} + \varepsilon,\\
\textrm{where } \varepsilon \textrm{ is positive and non-negligible}
\end{equation}
#+END_LATEX
** TODO Proofs
Put proofs in =#+QUOTE= blocks, like so, with a TITLE???
Actually, this looks a little fucked up...
#+BEGIN_QUOTE
Given:
$G: K \rightarrow {\{0,1\}}^n$ is a secure PRG,
where stream cipher E is derived from G.
Efficient adversary A is attacking the /semantic security/ if stream cipher E, while efficient adversary B is attacking the PRG function G.
Begin with the following assertions:
- $|Pr[R_0] - Pr[R_1]| = Adv_{SS} [A, OTP] = 0$
- $\exists B: |Pr[W_b] - Pr[R_b] | = Adv_{PRG} [B, G] \textrm{ for b=0,1}$
where $W_\#$ represents the probability that adversary A identifies a [binary] message encrypted using generator G resolves to 1, while $R_\#$ represents the probability that adversary A identifies a [binary] message encrypted with a *otp* resolves to 1.
The first claim is trivial, given the property that *otp* ciphertext are random independent and identical distributions (IID).
The second claim is given by examining the relationship between the adversaries and the control (*otp*):
$\Rightarrow Adv_{SS}[A,E] = |Pr[W_0] - Pr[W_1] | \leq 2 * Adv_{PRG}[B,G]$
As proof that $\exists B: |Pr[W_0] - Pr[R_0] | = Adv_{PRG} [B, G] \textrm{, }$ let adversary B's statistical test of A, $Adv_{PRG}[B,G] = y \oplus m_0 \textrm{, }$
where $y \in {\{0,1\}}^n \textrm{, }$ and $m_0$ is the challenge message from adversary A corresponding to b=0.
That is, $B(G(k)) = B(y) = W_0$.
$\therefore Adv_{PRG}[B,G] = | \underset{k \xleftarrow{R} \mathscr{K}}{Pr} [B(G(k)) = 1] - \underset{r \xleftarrow{R} {\{0,1\}}^n}{Pr} [B(r) = 1] | = | Pr[W_0] - Pr[R_0] |$
#+END_QUOTE
* TODO Programming languages
I follow standardized best practices for syntax and stylizing code, with the only exception being =max-line-length=, typically increased from 80 characters to 100 characters.
** Bash
** TODO C / C++
What here?
** Python
PEP8
#+NAME: MTP Attacker
#+CAPTION: mtp-attacker.py
#+BEGIN_SRC python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Command line to attack on ciphertext encrypted using One-Time-Pad (otp) cipher with a recycled key.
"""
import argparse
from itertools import combinations
# Argument parsing and help docs
def parse_args():
parser = argparse.ArgumentParser(
description=('\x1b[4;30;41mMTP Attacker\x1b[0m performs an attack on the One-Time-Pad (otp) stream cipher when\n'
'the key is reused to encrypt multiple messages. Natural language assumptions with ASCII analysis\n'
'is used to attempt to recover the key.'),
formatter_class=argparse.RawTextHelpFormatter)
requiredNamed = parser.add_argument_group('required arguments')
requiredNamed.add_argument('-i', '--inputFile', metavar='inputFile', type=str, required=True,
help='Input file containing row separated hex encoded ciphertext.')
parser.add_argument('-o', '--outputFile', action='store_true',
help='Output result to filename, instead of stdout.')
return vars(parser.parse_args())
# Flatten input file list into list of strings
def FlattenInput(fileList):
ret = []
for inFile in fileList:
with open(inFile) as f:
ret.extend([row.strip() for row in f.readlines()])
return ret
if __name__ == '__main__':
parser = parse_args()
ctInput = FlattenInput([parser['inputFile']])
[print(msg, file=open(parser['outputFile'], 'a') if parser['outputFile'] else None) for msg in MTP_Attack(ctInput)]
#+END_SRC
** Rust
** Haskell
** R
** HTML
** CSS
** JavaScript
** Dockerfiles
*** Docker-compose files
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment