2 Permissions management on Arvados locator hashes.
4 The permissions structure for Arvados is as follows (from
5 https://arvados.org/issues/2328)
7 A Keep locator string has the following format:
9 [hash]+[size]+A[signature]@[timestamp]
11 The "signature" string here is a cryptographic hash, expressed as a
12 string of hexadecimal digits, and timestamp is a 32-bit Unix timestamp
13 expressed as a hexadecimal number. e.g.:
15 acbd18db4cc2f85cedef654fccc4a4d8+3+A257f3f5f5f0a4e4626a18fc74bd42ec34dcb228a@7fffffff
17 The signature represents a guarantee that this locator was generated
18 by either Keep or the API server for use with the supplied API token.
19 If a request to Keep includes a locator with a valid signature and is
20 accompanied by the proper API token, the user has permission to GET
23 The signature may be generated either by Keep (after the user writes a
24 block) or by the API server (if the user has can_read permission on
25 the specified object). Keep and API server share a secret that is used
26 to generate signatures.
28 To verify a permission hint, Keep generates a new hint for the
29 requested object (using the locator string, the timestamp, the
30 permission secret and the user's API token, which must appear in the
31 request headers) and compares it against the hint included in the
32 request. If the permissions do not match, or if the API token is not
33 present, Keep returns a 401 error.
48 // The PermissionSecret is the secret key used to generate SHA1
49 // digests for permission hints. apiserver and Keep must use the same
51 var PermissionSecret []byte
53 // MakePermSignature returns a string representing the signed permission
54 // hint for the blob identified by blobHash, apiToken and expiration timestamp.
55 func MakePermSignature(blobHash string, apiToken string, expiry string) string {
56 hmac := hmac.New(sha1.New, PermissionSecret)
57 hmac.Write([]byte(blobHash))
58 hmac.Write([]byte("@"))
59 hmac.Write([]byte(apiToken))
60 hmac.Write([]byte("@"))
61 hmac.Write([]byte(expiry))
62 digest := hmac.Sum(nil)
63 return fmt.Sprintf("%x", digest)
66 // SignLocator takes a blobLocator, an apiToken and an expiry time, and
67 // returns a signed locator string.
68 func SignLocator(blobLocator string, apiToken string, expiry time.Time) string {
69 // If no permission secret or API token is available,
70 // return an unsigned locator.
71 if PermissionSecret == nil || apiToken == "" {
74 // Extract the hash from the blob locator, omitting any size hint that may be present.
75 blobHash := strings.Split(blobLocator, "+")[0]
76 // Return the signed locator string.
77 timestampHex := fmt.Sprintf("%08x", expiry.Unix())
79 "+A" + MakePermSignature(blobHash, apiToken, timestampHex) +
83 var signedLocatorRe = regexp.MustCompile(`^([[:xdigit:]]{32}).*\+A([[:xdigit:]]{40})@([[:xdigit:]]{8})`)
85 // VerifySignature returns nil if the signature on the signedLocator
86 // can be verified using the given apiToken. Otherwise it returns
87 // either ExpiredError (if the timestamp has expired, which is
88 // something the client could have figured out independently) or
90 func VerifySignature(signedLocator string, apiToken string) error {
91 matches := signedLocatorRe.FindStringSubmatch(signedLocator)
93 // Could not find a permission signature at all
94 return PermissionError
96 blobHash := matches[1]
99 if expTime, err := ParseHexTimestamp(expHex); err != nil {
100 return PermissionError
101 } else if expTime.Before(time.Now()) {
104 if sigHex != MakePermSignature(blobHash, apiToken, expHex) {
105 return PermissionError
110 // ParseHexTimestamp parses timestamp
111 func ParseHexTimestamp(timestampHex string) (ts time.Time, err error) {
112 if tsInt, e := strconv.ParseInt(timestampHex, 16, 0); e == nil {
113 ts = time.Unix(tsInt, 0)