PIR: illustrations of PIR structure

Author: sipma

chb/ast/doc/pirexamples/6f891f20_d4b98.md

@@ -0,0 +1,48 @@
+## Libcrypto: crypto/asn1/a_enum.c: ASN1_ENUMERATED_get
+
+### Predicated: 1
+
+#### source code fragment:
+
+```
+	i=a->type;
+	if (i == V_ASN1_NEG_ENUMERATED)
+		neg=1;
+```
+
+#### CodeHawk annotated assembly of basic block:
+
+```
+   0xd4ba4  LDR     R2, [R0,#0x4]   R2 := R0_in[4]_in (C: __pderef_R0_in.type_in)
+   0xd4ba8  LDR     R3, 0xd4c2c     R3 := 0x10a (C: 0x10a) (addr: 0xd4c2c; C: 0xd4c2c)
+   0xd4bac  CMP     R2, R3          compare R2 and R3 ((R0_in[4]_in - 0x10a)) (C: (__pderef_R0_in.type_in - 0x10a))
+   0xd4bb0  MOVEQ   R4, #1          if (R0_in[4]_in == 0x10a)(C: (__pderef_R0_in.type_in == 0x10a)) then R4 := 0x1 (C: 0x1)
+   0xd4bb4  BEQ     0xd4bd0         if (__pderef_R0_in.type_in == 0x10a) then goto 0xd4bd0
+```
+
+#### CodeHawk lifting:
+
+    if ((a->type == 266)) {
+      neg = 1; // 0xd4bb0, MOV
+    } // if 
+
+
+#### High-level PIR for if statement:
+
+The if-statement node is annotated with the property predicated:1, indicating that this
+if statement was created for a single predicated instruction, and both the single
+instruction in the then block and the condition have associated address 0x4bb0.
+
+![pirview_d4b98_stmt97_high_level](pirview_d4b98_stmt97.png)
+
+
+### Predicated: 2
+
+The same function also contains an example of the combination of two consecutive
+predicated instructions representing the source code fragment:
+
+#### source code fragment
+
+
+
+![pirview_d4b98_stmt114_high_level](pirview_d4b98_stmt114.png)

chb/ast/doc/pirexamples/6f891f20_e26e4.md

@@ -0,0 +1,52 @@
+## Libcrypto: crypto/asn1/ameth_lib.c: ameth_cmp
+
+#### source code:
+
+```
+static int ameth_cmp(const EVP_PKEY_ASN1_METHOD * const *a,
+		     const EVP_PKEY_ASN1_METHOD * const *b)
+	{
+        return ((*a)->pkey_id - (*b)->pkey_id);
+	}
+```
+
+#### CodeHawk annotated assembly:
+
+```
+int (struct evp_pkey_asn1_method_st * * a, struct evp_pkey_asn1_method_st * * b)
+
+--------------------------------------------------------------------------------
+   0xe26e4  LDR   R3, [R0]     R3 := R0_in[0]_in (C: __pderef_R0_in[<[0]>]_in) (addr: a; C: a)
+   0xe26e8  LDR   R2, [R1]     R2 := R1_in[0]_in (C: __pderef_R1_in[<[0]>]_in) (addr: b; C: b)
+   0xe26ec  LDR   R1, [R3]     R1 := R0_in[0]_in[0]_in (C: __pderef___pderef_R0_in[<[0]>]_in.pkey_id_in)
+   0xe26f0  LDR   R0, [R2]     R0 := R1_in[0]_in[0]_in (C: __pderef___pderef_R1_in[<[0]>]_in.pkey_id_in)
+   0xe26f4  RSB   R0, R0, R1   R0 := (R1 - R0) (= (R0_in[0]_in[0]_in - R1_in[0]_in[0]_in)) (C: (__pderef___pderef_R0_in[<[0]>]_in.pkey_id_in - __pderef___pderef_R1_in[<[0]>]_in.pkey_id_in))
+   0xe26f8  BX    LR           return (R0_in[0]_in[0]_in - R1_in[0]_in[0]_in) (C: (__pderef___pderef_R0_in[<[0]>]_in.pkey_id_in - __pderef___pderef_R1_in[<[0]>]_in.pkey_id_in))
+--------------------------------------------------------------------------------
+```
+
+#### CodeHawk lifting:
+
+```
+int ameth_cmp(struct evp_pkey_asn1_method_st * * a, struct evp_pkey_asn1_method_st * * b) {
+
+  return (a[0]->pkey_id - b[0]->pkey_id);
+}
+```
+
+#### High-level PIR
+
+The high-level PIR has, like the original source code, just one statement, the
+return statement, with a return expression. The lval-expressions in the return
+expressions are connected to the instructions that define them via the
+reaching definitions.
+
+![pirview_e26e4_high_level](./pirview_e26e4.png)
+
+
+#### Low-level PIR
+
+The low-level PIR includes the full control-flow graph with all its instructions,
+without any high-level control flow constructs.
+
+![pirview_e26e5_low_level](./pirview_e26e4_low.png)

chb/ast/doc/pirexamples/6f891f20_e277c.md

@@ -0,0 +1,40 @@
+## Libcrypto: crypto/asn1/ameth_lib.c: EVP_PKEY_get0_asn1 
+
+#### source code
+
+```
+const EVP_PKEY_ASN1_METHOD* EVP_PKEY_get0_asn1(EVP_PKEY *pkey)
+	{
+	return pkey->ameth;
+	}
+```
+
+
+#### CodeHawk annotated assembly:
+
+```
+struct evp_pkey_asn1_method_st * (struct evp_pkey_st * pkey)
+
+--------------------------------------------------------------------------------
+   0xe277c  LDR   R0, [R0,#0xc]   R0 := R0_in[12]_in (C: __pderef_R0_in.ameth_in)
+   0xe2780  BX    LR              return R0_in[12]_in (C: __pderef_R0_in.ameth_in)
+--------------------------------------------------------------------------------
+```
+
+#### CodeHawk lifting:
+
+```
+struct evp_pkey_asn1_method_st * EVP_PKEY_get0_asn1(struct evp_pkey_st * pkey) {
+
+  return pkey->ameth;
+}
+```
+
+#### High-level PIR
+
+![pirview_277c_high_level](pirview_e277c.png)
+
+
+#### Low-level PIR
+
+![pirview_277c_low_level](pirview_e277c_low.png)

chb/ast/doc/pirexamples/6f891f20_e2860.md

@@ -0,0 +1,55 @@
+## Libcrypto: crypto/asn1/ameth_lib.c: EVP_PKEY_ans1_set_private
+
+#### source code
+
+```
+void EVP_PKEY_asn1_set_private(EVP_PKEY_ASN1_METHOD *ameth,
+		int (*priv_decode)(EVP_PKEY *pk, PKCS8_PRIV_KEY_INFO *p8inf),
+		int (*priv_encode)(PKCS8_PRIV_KEY_INFO *p8, const EVP_PKEY *pk),
+		int (*priv_print)(BIO *out, const EVP_PKEY *pkey, int indent,
+							ASN1_PCTX *pctx))
+	{
+	ameth->priv_decode = priv_decode;
+	ameth->priv_encode = priv_encode;
+	ameth->priv_print = priv_print;
+	}
+```
+
+#### CodeHawk annotated assembly code
+
+```
+void (struct evp_pkey_asn1_method_st * ameth, int__(struct pkcs8_priv_key_info_st * p8inf, struct evp_pkey_st * pk) * priv_decode, int__(struct evp_pkey_st * pk, struct pkcs8_priv_key_info_st * p8) * priv_encode, int__(struct asn1_pctx_st * pctx, int indent, struct evp_pkey_st * pkey, struct bio_st * out) * priv_print)
+
+--------------------------------------------------------------------------------
+   0xe2860  STR    R3, [R0,#0x2c]  R0_in[44] := priv_print (C: __pderef_R0_in.priv_print := priv_print)
+   0xe2864  STR    R1, [R0,#0x24]  R0_in[36] := priv_decode (C: __pderef_R0_in.priv_decode := priv_decode)
+   0xe2868  STR    R2, [R0,#0x28]  R0_in[40] := priv_encode (C: __pderef_R0_in.priv_encode := priv_encode)
+   0xe286c  BX     LR              return ameth (C: ameth)
+--------------------------------------------------------------------------------
+```
+
+#### CodeHawk lifting
+
+```
+void EVP_PKEY_asn1_set_private(struct evp_pkey_asn1_method_st * ameth,
+     int (*priv_decode)(struct evp_pkey_st * pk, struct pkcs8_priv_key_info_st * p8inf),
+     int (*priv_encode)(struct pkcs8_priv_key_info_st * p8, struct evp_pkey_st * pk),
+     int (*priv_print)(struct bio_st * out, struct evp_pkey_st * pkey,
+     int indent, struct asn1_pctx_st * pctx)) {
+
+  ameth->priv_print = priv_print; // 0xe2860, STR
+  ameth->priv_decode = priv_decode; // 0xe2864, STR
+  ameth->priv_encode = priv_encode; // 0xe2868, STR
+  return;
+}
+
+```
+
+#### High-level PIR
+
+![pirview_2860_high_level](./pirview_e2860.png)
+
+
+#### Low-level PIR
+
+![pirview_2860_low_level](./pirview_e2860_low.png)

chb/ast/doc/pirexamples/6f891f20_e28a8.md

@@ -0,0 +1,82 @@
+## Libcrypto: crypto/asn1/ameth_lib.c: EVP_PKEY_asn1_free
+
+#### source code
+
+```
+void EVP_PKEY_asn1_free(EVP_PKEY_ASN1_METHOD *ameth)
+	{
+	if (ameth && (ameth->pkey_flags & ASN1_PKEY_DYNAMIC))
+		{
+		if (ameth->pem_str)
+			OPENSSL_free(ameth->pem_str);
+		if (ameth->info)
+			OPENSSL_free(ameth->info);
+		OPENSSL_free(ameth);
+		}
+	}
+```
+
+#### CodeHawk annotated assembly:
+
+```
+void (struct evp_pkey_asn1_method_st * ameth)
+
+--------------------------------------------------------------------------------
+   0xe28a8  PUSH      {R4,LR}        SP := (SP_in - 0x8); var_0008 := R4_in; var_0004 := LR_in
+   0xe28ac  SUBS      R4, R0, #0     R4 := (R0 - 0x0) (= ameth) (C: ameth)
+   0xe28b0  POPEQ     {R4,PC}        if (ameth == 0x0)(C: (ameth == 0x0)) then SP := SP_in; R4 := R4_in; PC := LR_in; return 0x0 (C: 0x0)
+--------------------------------------------------------------------------------
+   0xe28b4  LDR       R3, [R4,#0x8]  R3 := R0_in[8]_in (C: __pderef_R0_in.pkey_flags_in) 
+   0xe28b8  TST       R3, #2         compare 0x2 and R3 ((R3 & 0x2))
+   0xe28bc  POPEQ     {R4,PC}        if ((R0_in[8]_in & 0x2) == 0x0)(C: ((__pderef_R0_in.pkey_flags_in & 0x2) == 0x0)) then SP := SP_in; R4 := R4_in; PC := LR_in; return ameth (C: ameth)
+--------------------------------------------------------------------------------
+   0xe28c0  LDR       R0, [R4,#0xc]   R0 := R0_in[12]_in (C: __pderef_R0_in.pem_str_in)
+   0xe28c4  CMP       R0, #0          compare R0 and 0x0 (R0_in[12]_in) (C: __pderef_R0_in.pem_str_in)
+   0xe28c8  BEQ       0xe28d0         if (__pderef_R0_in.pem_str_in == 0x0) then goto 0xe28d0
+--------------------------------------------------------------------------------
+   0xe28cc  BL        0x3be80         call CRYPTO_free(R0_in[12]_in) (C: (__pderef_R0_in.pem_str_in))
+--------------------------------------------------------------------------------
+   0xe28d0  LDR       R0, [R4,#0x10]  R0 := R0_in[16]_in (C: __pderef_R0_in.info_in)
+   0xe28d4  CMP       R0, #0          compare R0 and 0x0 (R0_in[16]_in) (C: __pderef_R0_in.info_in)
+   0xe28d8  BEQ       0xe28e0         if (__pderef_R0_in.info_in == 0x0) then goto 0xe28e0
+--------------------------------------------------------------------------------
+   0xe28dc  BL        0x3be80         call CRYPTO_free(R0_in[16]_in) (C: (__pderef_R0_in.info_in))
+--------------------------------------------------------------------------------
+   0xe28e0  MOV       R0, R4          R0 := ameth (C: ameth)
+   0xe28e4  POP       {R4,LR}         SP := SP_in; R4 := R4_in; LR := LR_in
+   0xe28e8  B         0x3be80         call CRYPTO_free(ameth) (C: (ameth))
+--------------------------------------------------------------------------------
+```
+
+#### CodeHawk lifting:
+
+```
+void EVP_PKEY_asn1_free(struct evp_pkey_asn1_method_st * ameth) {
+
+  if ((ameth == 0)) {
+    return;
+  } // if 
+  if (((ameth->pkey_flags & 2) == 0)) {
+    return;
+  } // if 
+  if ((ameth->pem_str != 0)) {
+    CRYPTO_free(ameth->pem_str); // 0xe28cc, BL
+  } // if 
+  if ((ameth->info != 0)) {
+    CRYPTO_free(ameth->info); // 0xe28dc, BL
+  } // if 
+  CRYPTO_free(ameth); // 0xe28e8, BL
+  return;
+}
+```
+
+#### High-level PIR
+
+The PIR visualization below shows the four if statements contained in
+this function (only the statement/instruction skeleton is shown here
+to keep the size of the graph manageable). The first two if statements
+originate from a predicated instruction (they currently do not have
+a reference to the 'branch' instruction). The last two if statements
+are regular branches constructed from conditional jumps.
+
+![pirview_28a8_high_level](pirview_e28a8.png)

chb/ast/doc/pirexamples/README.md

@@ -0,0 +1,33 @@
+# PIR ILLUSTRATED
+
+## A few small functions
+
+- [crypto/asn1/ameth_lib.c: EVP_PKEY_get0_asn1](6f891f20_e277c.md):
+  A small function that returns the value of a field.
+  
+- [crypto/asn1/ameth_lib.c: ameth_cmp](6f891f20_e26e4.md):
+  Another small function that returns a slightly more complex expression.
+
+- [crypto/asn1/ameth_lib.c: EVP_PKEY_asn1_set_private](6f891f20_e2860.md):
+  A small void-returning function with three updates.
+
+
+## Predicated Instructions
+
+ARM allows conditional execution of instructions using condition codes
+that are part of almost all instruction types. Predicated instructions
+are handled in a few different ways in the lifting to C, depending on
+their context and purpose.
+
+The first option is to create full control flow in the control flow
+graph. This approach is followed, for example, when a return instruction
+(usually POP) is predicated. The following function provides an example:
+
+- [crypto/asn1/ameth_lib.c: EVP_PKEY_asn1_free](6f891f20_e28a8.md):
+
+The second option is to create light-weight control flow, which is not
+present in the cfg, but is introduced in the process of lifting by
+breaking up a basic block into fragments and inserting if statements
+accordingly. This approach is illustrated in the following function:
+
+- [crypto/asn1/a_enum.c: ASN1_ENUMERATED_get](6f891f20_d4b98.md):