Skip to content

fix(awm): gate and authorize MPCv2 recovery #271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ralph-bitgo wants to merge 1 commit into from
Closed

fix(awm): gate and authorize MPCv2 recovery #271

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 23 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,11 +205,25 @@ These settings are only required when you want to use a **separate AWM instance
| Variable | Description | Default | Applies To |
| -------------------- | --------------------------------------------------- | ---------------------- | ---------- |
| `RECOVERY_MODE` | Enable recovery mode for wallet recovery operations | `false` | Both |
| `MPCV2_RECOVERY_ALLOWED_CLIENT_FINGERPRINTS` | Dedicated mTLS client fingerprints authorized for ECDSA MPCv2 share combination | Unset (disabled) | AWM |
| `MPCV2_RECOVERY_APPROVALS` | JSON array of operator-approved `{ "coin", "pub", "txHexSha256" }` recovery transactions; SHA-256 is over decoded transaction bytes | Unset (disabled) | AWM |
| `HTTP_LOGFILE` | Path to HTTP access log file | `logs/http-access.log` | Both |
| `KEEP_ALIVE_TIMEOUT` | Keep-alive timeout in milliseconds | - | Both |
| `HEADERS_TIMEOUT` | Headers timeout in milliseconds | - | Both |
| `IPC` | IPC socket path (alternative to TCP port binding) | - | Both |

ECDSA MPCv2 recovery requires `RECOVERY_MODE=true` and `TLS_MODE=mtls`. A dedicated
recovery client's SHA-256 certificate fingerprint (uppercase hex, without colons)
must be in **both** `MTLS_ALLOWED_CLIENT_FINGERPRINTS` and
`MPCV2_RECOVERY_ALLOWED_CLIENT_FINGERPRINTS`. Before sending the recovery
request, an operator must verify the target wallet's common keychain and the
exact unsigned transaction (including destination) and approve its SHA-256
hash in `MPCV2_RECOVERY_APPROVALS`, e.g.
`[{"coin":"hteth","pub":"<130 hex characters>","txHexSha256":"<64 hex characters>"}]`.
The hash is of the bytes decoded from `txHex`, not of the UTF-8 hex string.
Absent authorization or approval, AWM refuses the request before contacting
either KMS; returned shares must independently match the approved keychain.

### TLS/mTLS Configuration

#### Basic TLS Settings
Expand All @@ -218,6 +232,7 @@ These settings are only required when you want to use a **separate AWM instance
| ------------------------------- | ------------------------------------- | ------- |
| `TLS_MODE` | TLS mode (`mtls` or `disabled`) | `mtls` |
| `CLIENT_CERT_ALLOW_SELF_SIGNED` | Allow self-signed client certificates | `false` |
| `MTLS_ALLOWED_CLIENT_FINGERPRINTS` | Allowed client certificate fingerprints | Comma-separated uppercase SHA-256 fingerprints without `sha256:` or colons; surrounding whitespace is ignored |

#### Server Certificates (for incoming connections)

Expand Down Expand Up @@ -474,11 +489,14 @@ export KEY_PROVIDER_SERVER_CA_CERT_PATH=/secure/certs/key-provider-ca.crt
# Security settings - production-grade
export CLIENT_CERT_ALLOW_SELF_SIGNED=false
export KEY_PROVIDER_SERVER_CERT_ALLOW_SELF_SIGNED=false
export MTLS_ALLOWED_CLIENT_FINGERPRINTS=sha256:1a2b3c...,sha256:4d5e6f...
export MTLS_ALLOWED_CLIENT_FINGERPRINTS=A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1,B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2B2
export BITGO_ENV=prod
npm start
```

The AWM setup above intentionally leaves ECDSA MPCv2 recovery disabled. To enable recovery, also set `RECOVERY_MODE=true`, add the recovery client fingerprint to `MPCV2_RECOVERY_ALLOWED_CLIENT_FINGERPRINTS`, and configure `MPCV2_RECOVERY_APPROVALS` with the approved coin, 130-hex common keychain, and 64-hex digest before starting AWM.


#### 2. Start Master Express (Port 3081)

Run the following in a new terminal:
Expand All @@ -499,7 +517,7 @@ export AWM_SERVER_CA_CERT_PATH=/secure/certs/awm-ca.crt
# Security settings - production-grade
export CLIENT_CERT_ALLOW_SELF_SIGNED=false
export AWM_SERVER_CERT_ALLOW_SELF_SIGNED=false
export MTLS_ALLOWED_CLIENT_FINGERPRINTS=sha256:7g8h9i...,sha256:0j1k2l...
export MTLS_ALLOWED_CLIENT_FINGERPRINTS=C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3C3,D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4D4
npm start
```

Expand Down Expand Up @@ -547,13 +565,13 @@ For local testing, you can generate and use demo certificates with the self-sign

#### Getting Client Certificate Fingerprints

To obtain certificate fingerprints for `MTLS_ALLOWED_CLIENT_FINGERPRINTS`:
To obtain a certificate fingerprint for the two AWM client allowlists:

```bash
openssl x509 -in /path/to/client-cert.crt -noout -fingerprint -sha256 | cut -d'=' -f2
openssl x509 -in /path/to/client-cert.crt -noout -fingerprint -sha256 | cut -d'=' -f2 | tr -d ':'
```

The output format is: `sha256:AB:CD:EF:...` which you can use in the configuration.
Use the resulting uppercase hex in both allowlists; do not include `sha256:`. The same canonical format applies to `MTLS_ALLOWED_CLIENT_FINGERPRINTS` for incoming mTLS clients.

#### Certificate Requirements for Production

Expand Down
34 changes: 17 additions & 17 deletions certs/test-ssl-cert.pem
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
-----BEGIN CERTIFICATE-----
MIIDCTCCAfGgAwIBAgIUYN0EUBLwq7uoLwDuTx7gDW0HS2UwDQYJKoZIhvcNAQEL
BQAwFDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI1MDUxNDIxMTUzMVoXDTI2MDUx
NDIxMTUzMVowFDESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEF
AAOCAQ8AMIIBCgKCAQEAmxdCF7xCJcE6yyG+wrdhHMwRiQxbhDLW/hiKQcO/nn7z
QMM9LAV04+WG5LCmm0ygocbfXXhfWn5D6SSSESKTb8dbSj6AJbLSmYjA5vDSzh9R
rO9GzNTDCDne+epo+rN4BOjGh7K83naLei/bEfmklMp7x+TyoBC8Ps/3Eq4HOJfd
UzgV2L3oC/4dCbAnkgK2zanL8KEaH6aM0HytIaqMFYLBs2t8s7HHHcSEadHfjlJu
GwTmTS0nVhJBWYJvF6Pv/SwLFuSo93TJybaMMUSF3oJK35NEYXg6EtibJLUC9RvX
FVLytRA5z+x7FBnGBdi4ctMseecokV4u15ePCB3MXwIDAQABo1MwUTAdBgNVHQ4E
FgQUxHrQZFFBfTfuXeOOoXmHZQ8E6rswHwYDVR0jBBgwFoAUxHrQZFFBfTfuXeOO
oXmHZQ8E6rswDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAj0hy
bwWh2B26cR0ADhuDC0MtGPBH0BrHypJEZ96nUPTY4oxRrjZusgdq60ooqsNyIW6k
cZHkajC/O0V6hnV4yMhLE8ZwA+31iyQakonpT5N1OON4Ddv9Bfvx8xOn75x/+RP+
GlAa31XxivryIi/5y7MEI0PwU34T/6bbMWdBaFRQtbuIXJ/90AZ0fBwIV0vJWjaO
1DriZAJe7hl63ZUw6CsfutpoyKkanF5GQB2CpolR3t1oeHwuDbZ550p1g2XFB6UI
9W+zlggQFeAnthzMoi3erO4sQ3j2b15QLZbk1HXHZcn3+89QcvdUcpG0u51bZdFW
SJ+bnT3TZ9H+szoa1w==
MIIDJTCCAg2gAwIBAgIUVGeg7p1/ntt2W18CUNjYSpsMnbkwDQYJKoZIhvcNAQEL
BQAwFDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI2MDkyNDE1MjA0MloXDTM2MDky
MTE1MjA0MlowFDESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEF
AAOCAQ8AMIIBCgKCAQEAvG0x4QrDDFIfdhJNqX0DBYtPvSpt6ByBexatAZFF5M7I
3FOqAAauX/HriseKG7QtVQkvsQdlZsMyYsQN4amzxDAAg+8FAtKU2no7kMKx4G1m
YKb7d2GBgoEHMdO5Rc42P2YUR8KUpf1MjBHdcA4sCDwMOR5YDkkIeT/ZmPbcsz9R
FDgp09xAYd6XTbS68lnVqh4yQF4+7KhamnzY50Zx6xBvjGj4BOowB7IKYVf4+387
25BnqgrkmXEcpkOjf16Q8GShN5s1HEDzEet4LzD82WYSF+/0+m5HdHKda32McsR3
SyIJu4PDoBhTTAl/i1R9xHJUwU3A+tsLwlup2qBmrQIDAQABo28wbTAdBgNVHQ4E
FgQUWuHWOI25OAqQYnkrdBvw3H6GdJkwHwYDVR0jBBgwFoAUWuHWOI25OAqQYnkr
dBvw3H6GdJkwDwYDVR0TAQH/BAUwAwEB/zAaBgNVHREEEzARgglsb2NhbGhvc3SH
BH8AAAEwDQYJKoZIhvcNAQELBQADggEBAKiEKdTGrg88U7rwg8bm51LxLtqnt0NT
gTCtAZRHAmeQHFx/mklb5ffLZnmZ5pNyN7+tP+5fetStiRzGNU+v4+d8t5SucV2x
Auj2HooDyax24EUUbLS8ra6eiUJHt/qAy2yvaF2JKArIfbVlUnAu/P3PEDj3WPV9
Ywe38MXdEXFeX1HGzB2kXM888YqZYt9iHrm/2fuBxsUhopY2rw5xBQVakaurh42O
QmXtr59K8Vox22fEMyPze9zOk/SVM2BXQiIAoONKN+Pr+bNBGqC8PVeG4cvhDYO/
HoHa76jv+K2FYQX/WpnEa80uFgmttxMFGc2iKMKEBOA9spyPkUyxj+g=
-----END CERTIFICATE-----
52 changes: 26 additions & 26 deletions certs/test-ssl-key.pem
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCbF0IXvEIlwTrL
Ib7Ct2EczBGJDFuEMtb+GIpBw7+efvNAwz0sBXTj5YbksKabTKChxt9deF9afkPp
JJIRIpNvx1tKPoAlstKZiMDm8NLOH1Gs70bM1MMIOd756mj6s3gE6MaHsrzedot6
L9sR+aSUynvH5PKgELw+z/cSrgc4l91TOBXYvegL/h0JsCeSArbNqcvwoRofpozQ
fK0hqowVgsGza3yzsccdxIRp0d+OUm4bBOZNLSdWEkFZgm8Xo+/9LAsW5Kj3dMnJ
towxRIXegkrfk0RheDoS2JsktQL1G9cVUvK1EDnP7HsUGcYF2Lhy0yx55yiRXi7X
l48IHcxfAgMBAAECggEAAft4dHXgi+ZTX7iiXTobe1MUakxbzcMZ7QzX6jfxTA+o
APeTNuvURFFxDvKUaT8VJ9wzNgOi3F+UHffCB4a0nGTPmDxXm6O/KLKPHKSOso8Y
ln2cdGPHy7l0TdIe3g113EI0FL9GcLrSf5D7Bi4gWhKDJdlETKLKH9dn+2IkD3zE
VM+7pwqYV6XZu2GuZ1om1JE+Hx2D5YLIuRCON0RKpzCLikmM7VErA7sjy7LsCSh9
ty5n1s9GoNtF+YuOD9WeMWGDonMyJdYWTsmFYoT+LF7W+GHoEwvYm9595QuNnxVx
KQ4P5oKm/EfcSiBhCC8BdCIGch9tQPT7c/syVhHG4QKBgQDTdUVW7rJNnLtHgWF2
ubjh9b3ZfxPuTEu6ueKON5XXvSgfsMBNgCxwkemefGJ6xIjDu+swud+2H33Tqj23
GMMTZ1JEzNYINO1m/laSAK+DcL81q4sLLlJTbBhYeE6FBeEO1hAmU2IiYrgU6zbO
eyo4ysXtFJdnHSR9PHjZpt/cMQKBgQC7wmxw2UNPlmwTzl6l7z5DqYxizIfezb9l
pIYrmcD92asxZKPi1soz8PcOn30gGmjtZn/7FkXFHSRsNknUmqJOEbZrvNCcKndz
O+RbKGs8FAKlyog8k3CTToAng4PutsYrAuK/kx84P9FPCgTxdhejRMkfkSebCJQH
fmXRnlRdjwKBgQCm2Drz0rcBIg9q5hz+zp+gOoOnnusc9TozhQPLbvReGzQTfSTe
gamO0LJiiIYzk+rNdfKmqaJoUwS3A/ZaB8G0B6wT+QNPymMfBsNLxBq4PTfBoy68
jboLdJjpBVP/BZqEWEa51sTxmK7iYo0F8oxn7yaoX7zucUIfRp2cLl0noQKBgB+K
RG8cgAshiJw3IX0cWEhDdfquwvAxfcJURdmTJXE/HFvavREA5cyd4NKLBhjbdt7S
RhNmpWe8Qn8PC430P+l/XjZw7FYfaBtqZyzM+F6KOfuhrwsF9XY5TJvWotX5zAYz
oOVvkGIBjmaJl1T8cnIRvvtXheCsKzmrCO2SfDePAoGAM1ToKwXSeZEm2Kyf/PV9
74lvBKYP5LP+pSmrcTq9jUbPQy3KmlhBi+kyhVK+2Awmh0J9tzu83C8lWR25L4mc
/Uwjhv2KwmvJKyZ4/5t/oMZ+BsZERSHj39juLNW+UL82M2heM5tv5/MI779SAmzl
VJMN4N1x+L7408dEGu0j2ds=
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC8bTHhCsMMUh92
Ek2pfQMFi0+9Km3oHIF7Fq0BkUXkzsjcU6oABq5f8euKx4obtC1VCS+xB2VmwzJi
xA3hqbPEMACD7wUC0pTaejuQwrHgbWZgpvt3YYGCgQcx07lFzjY/ZhRHwpSl/UyM
Ed1wDiwIPAw5HlgOSQh5P9mY9tyzP1EUOCnT3EBh3pdNtLryWdWqHjJAXj7sqFqa
fNjnRnHrEG+MaPgE6jAHsgphV/j7fzvbkGeqCuSZcRymQ6N/XpDwZKE3mzUcQPMR
63gvMPzZZhIX7/T6bkd0cp1rfYxyxHdLIgm7g8OgGFNMCX+LVH3EclTBTcD62wvC
W6naoGatAgMBAAECggEABUZ1DYhaYpUiSeyWi0/YBXSkpqRWz84eNr7Dj59Q7Pqc
ybJSyruJuTqkJOCT9nnhO+ED45T4yLbMt0Am5VaslReXOvXIxHzRxwhddB60/3G3
fxum0aQDjde2xqL74vYPxb0LF07v63IIxISPPLpg2DS+vEnIjFL6r2Uuud4W2rKk
3UXUHIpeZdOIZOAkXepXzqj5YWLREqzuYKIR332bj+0ik9DC0tr5ZcGJuEBKsGi8
X+mBU9LLL2Kr+3RvAUr8blkxrx2Zp4qkSDQxVIDacXSd7tC0BWIT8RjHHBs0xEa+
CA6zvF6Wxts+Jb+Q07BZlD3NqLwSYwIdhSSBBORO8QKBgQDk/cnZ3J5+M7mfDupH
A9bH7jimI/w8E4l2+ZJRT1kQLy0zZKE/wQzyH6qK5fqWuotUX7lE2Y4b8Gbo2pc8
uB8YhMSdsHpPfY8wMsMrrFGblf66MjWm7cshlvRoy+oVi+22Va0S9mKltr2hGBnd
+C328p5oL7u9MrZZct+Mz8HldQKBgQDSppWBYE6Uem9Tf3xk6ihH7QAZ9VkROGqN
+wwVs7m62zarwMhl44UbH1IHMLJpx691BaOOyA8ioSWO0YuWrw0o9q9Y3U5Le98K
wk8aLMJyHOBO0VaG4lZS0WdBL9duZy5z3mwnICyqx8ur73gJfGxINao9W9cz4IzU
I7C2SUf9WQKBgQC9Glxb/tYgMEUE9oNAHAp91tuPUD5XumaWCunrHdTWCa+RNnP3
O0yeksn6pIs5eFnhVp+gHO0/Y1sIxqOIcCC11cas1nVbObxKuFD2uvo1uzu9tgMa
lFtgpNG3zVXFb2XiYoRoGXJDmVKmO0n5RZ9nxNpN/cVTLBLscXHtThC4lQKBgQCL
kxU8xDNM7lMVYENsGjrWbZLDoG2Dm33+1XkMaCmIRffTlckyua5YakhPu1R8AnOf
dj0JPkXJDD12hCGZliOCIPHOT9Sw70K6PkVrcnzkX33Au7Q5a38HIPjpmGmGHZgJ
7jZ7NjZicj/hjKpcnrSgo+5I+bF+DitB5OQR5DxvAQKBgCtqFGcgblexwcfnduwk
SSgg8NiySq+jABDkRUMienBtbugZpLQVKj0TZn6ldPjeUAl4ZAn8U8N4lHhXZgdT
dFio8hMQnjIJzyDC0PO9fHD1madsctPtLU+3eYYN8+/U8BxHUX71+tbUH5JtSBPV
7mCMEYAEKI1vaiGwyDaqjI23
-----END PRIVATE KEY-----
10 changes: 10 additions & 0 deletions masterBitgoExpress.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1495,6 +1495,16 @@
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
Expand Down
Loading
Loading