Skip to content

Commit e09fb25

Browse files
thomastenthomasten
committed
AB#530 cli doc
1 parent 1e1163f commit e09fb25

File tree

4 files changed

+172
-46
lines changed

4 files changed

+172
-46
lines changed

‎cmd/ego/main.go

Lines changed: 37 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,14 @@ func main() {
4343
}
4444
// also print usage
4545
fmt.Println()
46+
case "run":
47+
if len(args) > 0 {
48+
os.Exit(cli.Run(args[0], args[1:]))
49+
}
50+
case "marblerun":
51+
if len(args) == 1 {
52+
os.Exit(cli.Marblerun(args[0]))
53+
}
4654
case "signerid":
4755
if len(args) == 1 {
4856
id, err := cli.Signerid(args[0])
@@ -61,14 +69,6 @@ func main() {
6169
fmt.Println(id)
6270
return
6371
}
64-
case "run":
65-
if len(args) > 0 {
66-
os.Exit(cli.Run(args[0], args[1:]))
67-
}
68-
case "marblerun":
69-
if len(args) == 1 {
70-
os.Exit(cli.Marblerun(args[0]))
71-
}
7272
case "env":
7373
if len(args) > 0 {
7474
os.Exit(cli.Env(args[0], args[1:]))
@@ -89,21 +89,20 @@ func help(cmd string) {
8989

9090
switch cmd {
9191
case "sign":
92-
s = `sign [executable|json]
92+
s = `sign [executable | config.json]
9393
9494
Sign an executable built with ego-go. Executables must be signed before they can be run in an enclave.
95-
There are 3 different ways of signing an executable:
9695
97-
1. ego sign
98-
Searches in the current directory for enclave.json and signs the therein provided executable.
96+
This command can be used in different modes:
9997
100-
2. ego sign <executable>
101-
Searches in the current directory for enclave.json.
102-
If no such file is found, create one with default parameters for the executable.
103-
Use enclave.json to sign the executable.
98+
ego sign <executable>
99+
Generates a new key "private.pem" and a default configuration "enclave.json" in the current directory and signs the executable.
104100
105-
3. ego sign <json>
106-
Reads json and signs the therein provided executable.`
101+
ego sign
102+
Searches in the current directory for "enclave.json" and signs the therein provided executable.
103+
104+
ego sign <config.json>
105+
Signs an executable according to a given configuration.`
107106

108107
case "run":
109108
s = `run <executable> [args...]
@@ -117,46 +116,46 @@ Set OE_SIMULATION=1 to run in simulation mode.`
117116
case "marblerun":
118117
s = `marblerun <executable>
119118
120-
Run a signed executable as a Marblerun marble.
119+
Run a signed executable as a Marblerun Marble.
121120
Requires a running Marblerun Coordinator instance.
122-
Environment variables are only readable from within the enclave if they start with "EDG_".
123-
Environment variables will be extended/overwritten with the ones specified in the manifest.
121+
Environment variables are only readable from within the enclave if they start with "EDG_" and
122+
will be extended/overwritten with the ones specified in the manifest.
123+
124124
Requires the following configuration environment variables:
125-
- EDG_MARBLE_COORDINATOR_ADDR: The Coordinator address
126-
- EDG_MARBLE_TYPE: The type of this marble (as specified in the manifest)
127-
- EDG_MARBLE_DNS_NAMES: The alternative DNS names for this marble's TLS certificate
128-
- EDG_MARBLE_UUID_FILE: The location where this marble will store its UUID
125+
EDG_MARBLE_COORDINATOR_ADDR The Coordinator address
126+
EDG_MARBLE_TYPE The type of this Marble (as specified in the manifest)
127+
EDG_MARBLE_DNS_NAMES The alternative DNS names for this Marble's TLS certificate
128+
EDG_MARBLE_UUID_FILE The location where this Marble will store its UUID
129129
130130
Set OE_SIMULATION=1 to run in simulation mode.`
131131

132132
case "env":
133133
s = `env ...
134134
135-
Run a command within the ego environment. For example, run
135+
Run a command within the EGo environment. For example, run
136136
` + me + ` env make
137137
to build a Go project that uses a Makefile.`
138-
case "signerid":
139-
s = `signerid <executable|keyfile>
140138

141-
Print the signerID either from the executable or by reading the keyfile.
139+
case "signerid":
140+
s = `signerid <executable | key.pem>
142141
143-
The keyfile needs to have the extension ".pem"`
142+
Print the SignerID either from a signed executable or by reading a keyfile.`
144143

145144
case "uniqueid":
146-
s = `signerid <executable>
145+
s = `uniqueid <executable>
147146
148-
Print the uniqueID from the executable.`
147+
Print the UniqueID of a signed executable.`
149148

150149
default:
151150
s = `<command> [arguments]
152151
153152
Commands:
154-
sign Sign an executable built with ego-go.
155-
run Run a signed executable.
156-
env Run a command in the ego environment.
157-
marblerun Run a signed Marblerun marble.
158-
signerid Print the signerID of an executable.
159-
uniqueid Print the uniqueID of an executable.
153+
sign Sign an executable built with ego-go.
154+
run Run a signed executable in standalone mode.
155+
marblerun Run a signed executable as a Marblerun Marble.
156+
signerid Print the SignerID of a signed executable.
157+
uniqueid Print the UniqueID of a signed executable.
158+
env Run a command in the EGo environment.
160159
161160
Use "` + me + ` help <command>" for more information about a command.`
162161
}

‎doc/ego_cli.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# ego command reference
2+
`ego` is a tool for managing EGo enclaves.
3+
4+
Usage:
5+
```
6+
ego <command> [arguments]
7+
```
8+
9+
Commands:
10+
```
11+
sign Sign an executable built with ego-go.
12+
run Run a signed executable in standalone mode.
13+
marblerun Run a signed executable as a Marblerun Marble.
14+
signerid Print the SignerID of a signed executable.
15+
uniqueid Print the UniqueID of a signed executable.
16+
env Run a command in the EGo environment.
17+
```
18+
19+
## sign
20+
Usage:
21+
```
22+
ego sign [executable | config.json]
23+
```
24+
Sign an executable built with ego-go. Executables must be signed before they can be run in an enclave.
25+
26+
This command can be used in different modes:
27+
* `ego sign <executable>`\
28+
Generates a new key `private.pem` and a default configuration `enclave.json` in the current directory and signs the executable.
29+
30+
* `ego sign`\
31+
Searches in the current directory for `enclave.json` and signs the therein provided executable.
32+
33+
* `ego sign <config.json>`\
34+
Signs an executable according to a given configuration.
35+
36+
See [this section](#enclave-configuration-file) for more information on the configuration file.
37+
38+
## run
39+
Usage:
40+
```
41+
ego run <executable> [args...]
42+
```
43+
Run a signed executable in an enclave. You can pass arbitrary arguments to the enclave.
44+
45+
Environment variables are only readable from within the enclave if they start with "EDG_".
46+
47+
You need an SGX-enabled machine to run an enclave. For development, you can also enable simulation mode by setting OE_SIMULATION=1, e.g.:
48+
```
49+
OE_SIMULATION=1 ego run helloworld
50+
```
51+
52+
## marblerun
53+
Usage:
54+
```
55+
ego marblerun <executable>
56+
```
57+
Run a signed executable as a Marblerun Marble.
58+
Requires a running Marblerun Coordinator instance.
59+
60+
Environment variables are only readable from within the enclave if they start with "EDG_" and will be extended/overwritten with the ones specified in the manifest.
61+
62+
Requires the following configuration environment variables:
63+
* EDG_MARBLE_COORDINATOR_ADDR\
64+
The Coordinator address
65+
* EDG_MARBLE_TYPE\
66+
The type of this Marble (as specified in the manifest)
67+
* EDG_MARBLE_DNS_NAMES\
68+
The alternative DNS names for this Marble's TLS certificate
69+
* EDG_MARBLE_UUID_FILE\
70+
The location where this Marble will store its UUID
71+
72+
Set OE_SIMULATION=1 to run in simulation mode.
73+
74+
## signerid
75+
Usage:
76+
```
77+
ego signerid <executable | key.pem>
78+
```
79+
Print the SignerID either from a signed executable or by reading a keyfile.`
80+
81+
## uniqueid
82+
Usage:
83+
```
84+
ego uniqueid <executable>
85+
```
86+
Print the UniqueID of a signed executable.
87+
88+
## env
89+
Usage:
90+
```
91+
ego env ...
92+
```
93+
Run a command within the ego build environment. For example, run
94+
```
95+
ego env make
96+
```
97+
to build a Go project that uses a Makefile.
98+
99+
## Enclave configuration file
100+
An enclave configuration is defined in JSON and applied when signing an executable.
101+
102+
Here is an example configuration:
103+
```json
104+
{
105+
"exe": "helloworld",
106+
"key": "private.pem",
107+
"debug": true,
108+
"heapSize": 512,
109+
"productID": 1,
110+
"securityVersion": 1
111+
}
112+
```
113+
114+
`exe` is the (relative or absolute) path to the executable that should be signed.
115+
116+
`key` is the path to the private RSA key of the signer. When invoking `ego sign` and the key file does not exist, a key with the required parameters is automatically generated. You can also generate it yourself with:
117+
```
118+
openssl genrsa -out private.pem -3 3072
119+
```
120+
121+
If `debug` is true, the enclave will be debuggable.
122+
123+
`heapSize` specifies the heap size available to the enclave in MB. It should be at least 512 MB.
124+
125+
A `productID` (SGX: ISVPRODID) is assigned by the developer and enables the attester to distinguish between different enclaves signed with the same key.
126+
127+
The developer should increment the `securityVersion` (SGX: ISVSVN) whenever a security fix is made to the enclave code.

‎internal/cli/sign.go

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,15 @@ type config struct {
2424
Exe string `json:"exe"`
2525
Key string `json:"key"`
2626
Debug bool `json:"debug"`
27-
Heapsize int `json:"heapsize"`
27+
HeapSize int `json:"heapSize"`
2828
ProductID int `json:"productID"`
2929
SecurityVersion int `json:"securityVersion"`
3030
}
3131

32-
// Validate Exe, Key, Heapsize
32+
// Validate Exe, Key, HeapSize
3333
func (c *config) validate() error {
34-
if c.Heapsize == 0 {
35-
return fmt.Errorf("heapsize not set in config file")
34+
if c.HeapSize == 0 {
35+
return fmt.Errorf("heapSize not set in config file")
3636
}
3737
if c.Exe == "" {
3838
return fmt.Errorf("exe not set in config file")
@@ -55,8 +55,8 @@ func (c *Cli) signWithJSON(conf *config) error {
5555
cDebug = "Debug=0\n"
5656
}
5757

58-
// calculate number of pages: Heapsize[MiB], pageSize is 4096B
59-
heapPages := conf.Heapsize * 1024 * 1024 / 4096
58+
// calculate number of pages: HeapSize[MiB], pageSize is 4096B
59+
heapPages := conf.HeapSize * 1024 * 1024 / 4096
6060
cNumHeapPages := "NumHeapPages=" + strconv.Itoa(heapPages) + "\n"
6161

6262
cStackPages := "NumStackPages=1024\n"
@@ -107,7 +107,7 @@ func (c *Cli) signExecutable(path string) error {
107107
Exe: path,
108108
Key: defaultPrivKeyFilename,
109109
Debug: true,
110-
Heapsize: 512, //[MB]
110+
HeapSize: 512, //[MB]
111111
ProductID: 1,
112112
SecurityVersion: 1,
113113
}

‎samples/remote_attestation/enclave.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"exe": "server",
33
"key": "private.pem",
44
"debug": true,
5-
"heapsize": 512,
5+
"heapSize": 512,
66
"productID": 1234,
77
"securityVersion": 2
88
}

0 commit comments

Comments
 (0)