diff --git a/builtin/providers/google/data_source_storage_object_signed_url.go b/builtin/providers/google/data_source_storage_object_signed_url.go index 9149d45f8..6813bf950 100644 --- a/builtin/providers/google/data_source_storage_object_signed_url.go +++ b/builtin/providers/google/data_source_storage_object_signed_url.go @@ -9,6 +9,7 @@ import ( "crypto/x509" "encoding/base64" "encoding/pem" + "errors" "fmt" "log" "net/url" @@ -17,11 +18,15 @@ import ( "strings" "time" + "sort" + + "regexp" + + "github.com/hashicorp/errwrap" "github.com/hashicorp/terraform/helper/pathorcontents" "github.com/hashicorp/terraform/helper/schema" "golang.org/x/oauth2/google" "golang.org/x/oauth2/jwt" - "sort" ) const gcsBaseUrl = "https://storage.googleapis.com" @@ -36,6 +41,11 @@ func dataSourceGoogleSignedUrl() *schema.Resource { Type: schema.TypeString, Required: true, }, + "content_md5": &schema.Schema{ + Type: schema.TypeString, + Optional: true, + Default: "", + }, "content_type": &schema.Schema{ Type: schema.TypeString, Optional: true, @@ -50,20 +60,17 @@ func dataSourceGoogleSignedUrl() *schema.Resource { Optional: true, Default: "1h", }, + "extension_headers": &schema.Schema{ + Type: schema.TypeMap, + Optional: true, + Elem: schema.TypeString, + ValidateFunc: validateExtensionHeaders, + }, "http_method": &schema.Schema{ - Type: schema.TypeString, - Optional: true, - Default: "GET", - }, - "http_headers": &schema.Schema{ - Type: schema.TypeMap, - Optional: true, - Elem: schema.TypeString, - }, - "md5_digest": &schema.Schema{ - Type: schema.TypeString, - Optional: true, - Default: "", + Type: schema.TypeString, + Optional: true, + Default: "GET", + ValidateFunc: validateHttpMethod, }, "path": &schema.Schema{ Type: schema.TypeString, @@ -77,6 +84,26 @@ func dataSourceGoogleSignedUrl() *schema.Resource { } } +func validateExtensionHeaders(v interface{}, k string) (ws []string, errors []error) { + hdrMap := v.(map[string]interface{}) + for k, _ := range hdrMap { + if !strings.HasPrefix(strings.ToLower(k), "x-goog") { + errors = append(errors, fmt.Errorf( + "extension_header (%s) not valid, header name must begin with 'x-goog-'", k)) + } + } + return +} + +func validateHttpMethod(v interface{}, k string) (ws []string, errs []error) { + value := v.(string) + value = strings.ToUpper(value) + if !regexp.MustCompile(`^(GET|HEAD|PUT|DELETE)$`).MatchString(value) { + errs = append(errs, errors.New("HTTP method must be one of [GET|HEAD|PUT|DELETE]")) + } + return +} + func dataSourceGoogleSignedUrlRead(d *schema.ResourceData, meta interface{}) error { config := meta.(*Config) @@ -87,7 +114,7 @@ func dataSourceGoogleSignedUrlRead(d *schema.ResourceData, meta interface{}) err if method, ok := d.GetOk("http_method"); ok && len(method.(string)) >= 3 { urlData.HttpMethod = method.(string) } else { - return fmt.Errorf("not a valid http method") + return errors.New("not a valid http method") } // convert duration to an expiration datetime (unix time in seconds) @@ -97,16 +124,23 @@ func dataSourceGoogleSignedUrlRead(d *schema.ResourceData, meta interface{}) err } duration, err := time.ParseDuration(durationString) if err != nil { - return fmt.Errorf("could not parse duration") + return errwrap.Wrapf("could not parse duration: {{err}}", err) } expires := time.Now().Unix() + int64(duration.Seconds()) urlData.Expires = int(expires) + // content_md5 is optional + if v, ok := d.GetOk("content_md5"); ok { + urlData.ContentMd5 = v.(string) + } + + // content_type is optional if v, ok := d.GetOk("content_type"); ok { urlData.ContentType = v.(string) } - if v, ok := d.GetOk("http_headers"); ok { + // extension_headers (x-goog-* HTTP headers) are optional + if v, ok := d.GetOk("extension_headers"); ok { hdrMap := v.(map[string]interface{}) if len(hdrMap) > 0 { @@ -117,10 +151,6 @@ func dataSourceGoogleSignedUrlRead(d *schema.ResourceData, meta interface{}) err } } - if v, ok := d.GetOk("md5_digest"); ok { - urlData.Md5Digest = v.(string) - } - // object path path := []string{ "", @@ -137,26 +167,28 @@ func dataSourceGoogleSignedUrlRead(d *schema.ResourceData, meta interface{}) err } urlData.JwtConfig = jwtConfig - // Sign url object data - signature, err := SignString(urlData.CreateSigningString(), jwtConfig) - if err != nil { - return fmt.Errorf("could not sign data: %v", err) - } - urlData.Signature = signature - // Construct URL - finalUrl := urlData.BuildUrl() - d.SetId(urlData.EncodedSignature()) - d.Set("signed_url", finalUrl) + signedUrl, err := urlData.SignedUrl() + if err != nil { + return err + } + + // Success + d.Set("signed_url", signedUrl) + + encodedSig, err := urlData.EncodedSignature() + if err != nil { + return err + } + d.SetId(encodedSig) return nil } -// This looks for credentials json in the following places, +// loadJwtConfig looks for credentials json in the following places, // in order of preference: -// -// 1. Credentials provided in data source `credentials` attribute. -// 2. Credentials provided in the provider definition. +// 1. `credentials` attribute of the datasource +// 2. `credentials` attribute in the provider definition. // 3. A JSON file whose path is specified by the // GOOGLE_APPLICATION_CREDENTIALS environment variable. func loadJwtConfig(d *schema.ResourceData, meta interface{}) (*jwt.Config, error) { @@ -180,17 +212,17 @@ func loadJwtConfig(d *schema.ResourceData, meta interface{}) (*jwt.Config, error if strings.TrimSpace(credentials) != "" { contents, _, err := pathorcontents.Read(credentials) if err != nil { - return nil, fmt.Errorf("Error loading credentials: %s", err) + return nil, errwrap.Wrapf("Error loading credentials: {{err}}", err) } cfg, err := google.JWTConfigFromJSON([]byte(contents), "") if err != nil { - return nil, fmt.Errorf("Error parsing credentials: \n %s \n Error: %s", contents, err) + return nil, errwrap.Wrapf("Error parsing credentials: {{err}}", err) } return cfg, nil } - return nil, fmt.Errorf("Credentials not found in datasource, provider configuration or GOOGLE_APPLICATION_CREDENTIALS environment variable.") + return nil, errors.New("Credentials not found in datasource, provider configuration or GOOGLE_APPLICATION_CREDENTIALS environment variable.") } // parsePrivateKey converts the binary contents of a private key file @@ -208,29 +240,29 @@ func parsePrivateKey(key []byte) (*rsa.PrivateKey, error) { if err != nil { parsedKey, err = x509.ParsePKCS1PrivateKey(key) if err != nil { - return nil, fmt.Errorf("private key should be a PEM or plain PKSC1 or PKCS8; parse error: %v", err) + return nil, errwrap.Wrapf("private key should be a PEM or plain PKSC1 or PKCS8; parse error: {{err}}", err) } } parsed, ok := parsedKey.(*rsa.PrivateKey) if !ok { - return nil, fmt.Errorf("private key is invalid") + return nil, errors.New("private key is invalid") } return parsed, nil } +// UrlData stores the values required to create a Signed Url type UrlData struct { JwtConfig *jwt.Config + ContentMd5 string ContentType string HttpMethod string Expires int - Md5Digest string HttpHeaders map[string]string Path string - Signature []byte } -// Creates a string in the form ready for signing: -// https://cloud.google.com/storage/docs/access-control/create-signed-urls-program +// SigningString creates a string representation of the UrlData in a form ready for signing: +// see https://cloud.google.com/storage/docs/access-control/create-signed-urls-program // Example output: // ------------------- // GET @@ -239,59 +271,78 @@ type UrlData struct { // 1388534400 // bucket/objectname // ------------------- -func (u *UrlData) CreateSigningString() []byte { +func (u *UrlData) SigningString() []byte { var buf bytes.Buffer - // HTTP VERB + // HTTP Verb buf.WriteString(u.HttpMethod) buf.WriteString("\n") - // MD5 digest (optional) - buf.WriteString(u.Md5Digest) + // Content MD5 (optional, always add new line) + buf.WriteString(u.ContentMd5) buf.WriteString("\n") - // request content-type (optional) + // Content Type (optional, always add new line) buf.WriteString(u.ContentType) buf.WriteString("\n") - // signed url expiration + // Expiration buf.WriteString(strconv.Itoa(u.Expires)) buf.WriteString("\n") - // additional request headers (optional) + // Extra HTTP headers (optional) // Must be sorted in lexigraphical order var keys []string for k := range u.HttpHeaders { keys = append(keys, strings.ToLower(k)) } sort.Strings(keys) - - // To perform the opertion you want + // Write sorted headers to signing string buffer for _, k := range keys { buf.WriteString(fmt.Sprintf("%s:%s\n", k, u.HttpHeaders[k])) } - // object path + // Storate Object path (includes bucketname) buf.WriteString(u.Path) - fmt.Printf("SIGNING STRING: \n%s\n", buf.String()) - return buf.Bytes() } -func (u *UrlData) EncodedSignature() string { +func (u *UrlData) Signature() ([]byte, error) { + // Sign url data + signature, err := SignString(u.SigningString(), u.JwtConfig) + if err != nil { + return nil, err + + } + + return signature, nil +} + +// EncodedSignature returns the Signature() after base64 encoding and url escaping +func (u *UrlData) EncodedSignature() (string, error) { + signature, err := u.Signature() + if err != nil { + return "", err + } + // base64 encode signature - encoded := base64.StdEncoding.EncodeToString(u.Signature) + encoded := base64.StdEncoding.EncodeToString(signature) // encoded signature may include /, = characters that need escaping encoded = url.QueryEscape(encoded) - return encoded + return encoded, nil } -// Builds the final signed URL a client can use to retrieve storage object -func (u *UrlData) BuildUrl() string { +// SignedUrl constructs the final signed URL a client can use to retrieve storage object +func (u *UrlData) SignedUrl() (string, error) { - // set url + encodedSig, err := u.EncodedSignature() + if err != nil { + return "", err + } + + // build url // https://cloud.google.com/storage/docs/access-control/create-signed-urls-program var urlBuffer bytes.Buffer urlBuffer.WriteString(gcsBaseUrl) @@ -301,16 +352,17 @@ func (u *UrlData) BuildUrl() string { urlBuffer.WriteString("&Expires=") urlBuffer.WriteString(strconv.Itoa(u.Expires)) urlBuffer.WriteString("&Signature=") - urlBuffer.WriteString(u.EncodedSignature()) + urlBuffer.WriteString(encodedSig) - return urlBuffer.String() + return urlBuffer.String(), nil } +// SignString calculates the SHA256 signature of the input string func SignString(toSign []byte, cfg *jwt.Config) ([]byte, error) { // Parse private key pk, err := parsePrivateKey(cfg.PrivateKey) if err != nil { - return nil, fmt.Errorf("could not parse key: %v\nKey:%s", err, string(cfg.PrivateKey)) + return nil, errwrap.Wrapf("failed to sign string, could not parse key: {{err}}", err) } // Hash string @@ -320,7 +372,7 @@ func SignString(toSign []byte, cfg *jwt.Config) ([]byte, error) { // Sign string signed, err := rsa.SignPKCS1v15(rand.Reader, pk, crypto.SHA256, hasher.Sum(nil)) if err != nil { - return nil, fmt.Errorf("error signing string: %s\n", err) + return nil, errwrap.Wrapf("failed to sign string, an error occurred: {{err}}", err) } return signed, nil diff --git a/builtin/providers/google/data_source_storage_object_signed_url_test.go b/builtin/providers/google/data_source_storage_object_signed_url_test.go index e4a78c032..b59b5a7a5 100644 --- a/builtin/providers/google/data_source_storage_object_signed_url_test.go +++ b/builtin/providers/google/data_source_storage_object_signed_url_test.go @@ -6,15 +6,15 @@ import ( "bytes" "encoding/base64" "fmt" + "io/ioutil" + "net/http" + "net/url" + "github.com/hashicorp/go-cleanhttp" "github.com/hashicorp/terraform/helper/acctest" "github.com/hashicorp/terraform/helper/resource" "github.com/hashicorp/terraform/terraform" "golang.org/x/oauth2/google" - "io/ioutil" - "net/http" - "net/url" - "strings" ) const fakeCredentials = `{ @@ -64,7 +64,7 @@ func TestUrlData_Signing(t *testing.T) { } // create url data signature - toSign := urlData.CreateSigningString() + toSign := urlData.SigningString() result, err := SignString(toSign, cfg) if err != nil { t.Error(err) @@ -77,17 +77,7 @@ func TestUrlData_Signing(t *testing.T) { } -func TestUrlData_BuildUrl(t *testing.T) { - // unescape and decode the expected signature - encodedSig, err := url.QueryUnescape(testUrlExpectedSignatureBase64Encoded) - if err != nil { - t.Error(err) - } - sig, err := base64.StdEncoding.DecodeString(encodedSig) - if err != nil { - t.Error(err) - } - +func TestUrlData_SignedUrl(t *testing.T) { // load fake service account credentials cfg, err := google.JWTConfigFromJSON([]byte(fakeCredentials), "") if err != nil { @@ -98,10 +88,12 @@ func TestUrlData_BuildUrl(t *testing.T) { HttpMethod: "GET", Expires: testUrlExpires, Path: testUrlPath, - Signature: sig, JwtConfig: cfg, } - result := urlData.BuildUrl() + result, err := urlData.SignedUrl() + if err != nil { + t.Errorf("Could not generated signed url: %+v", err) + } if result != testUrlExpectedUrl { t.Errorf("URL does not match expected value:\n%s\n%s", testUrlExpectedUrl, result) } @@ -125,6 +117,11 @@ func TestDatasourceSignedUrl_basic(t *testing.T) { func TestDatasourceSignedUrl_accTest(t *testing.T) { bucketName := fmt.Sprintf("tf-test-bucket-%d", acctest.RandInt()) + headers := map[string]string{ + "x-goog-test": "foo", + "x-goog-if-generation-match": "1", + } + resource.Test(t, resource.TestCase{ PreCheck: func() { testAccPreCheck(t) }, Providers: testAccProviders, @@ -133,55 +130,8 @@ func TestDatasourceSignedUrl_accTest(t *testing.T) { Config: testAccTestGoogleStorageObjectSingedUrl(bucketName), Check: resource.ComposeTestCheckFunc( testAccGoogleSignedUrlRetrieval("data.google_storage_object_signed_url.story_url", nil), - ), - }, - }, - }) -} - -func TestDatasourceSignedUrl_wHeaders(t *testing.T) { - - headers := map[string]string{ - "x-goog-test": "foo", - } - - resource.Test(t, resource.TestCase{ - PreCheck: func() { testAccPreCheck(t) }, - Providers: testAccProviders, - Steps: []resource.TestStep{ - resource.TestStep{ - Config: testAccTestGoogleStorageObjectSingedUrl_wHeader(), - Check: resource.ComposeTestCheckFunc( testAccGoogleSignedUrlRetrieval("data.google_storage_object_signed_url.story_url_w_headers", headers), - ), - }, - }, - }) -} - -func TestDatasourceSignedUrl_wContentType(t *testing.T) { - resource.Test(t, resource.TestCase{ - PreCheck: func() { testAccPreCheck(t) }, - Providers: testAccProviders, - Steps: []resource.TestStep{ - resource.TestStep{ - Config: testAccTestGoogleStorageObjectSingedUrl_wContentType(), - Check: resource.ComposeTestCheckFunc( testAccGoogleSignedUrlRetrieval("data.google_storage_object_signed_url.story_url_w_content_type", nil), - ), - }, - }, - }) -} - -func TestDatasourceSignedUrl_wMD5(t *testing.T) { - resource.Test(t, resource.TestCase{ - PreCheck: func() { testAccPreCheck(t) }, - Providers: testAccProviders, - Steps: []resource.TestStep{ - resource.TestStep{ - Config: testAccTestGoogleStorageObjectSingedUrl_wMD5(), - Check: resource.ComposeTestCheckFunc( testAccGoogleSignedUrlRetrieval("data.google_storage_object_signed_url.story_url_w_md5", nil), ), }, @@ -189,35 +139,6 @@ func TestDatasourceSignedUrl_wMD5(t *testing.T) { }) } -// formatRequest generates ascii representation of a request -func formatRequest(r *http.Request) string { - // Create return string - var request []string - request = append(request, "--------") - // Add the request string - url := fmt.Sprintf("%v %v %v", r.Method, r.URL, r.Proto) - request = append(request, url) - // Add the host - request = append(request, fmt.Sprintf("Host: %v", r.Host)) - // Loop through headers - for name, headers := range r.Header { - //name = strings.ToLower(name) - for _, h := range headers { - request = append(request, fmt.Sprintf("%v: %v", name, h)) - } - } - - // If this is a POST, add post data - if r.Method == "POST" { - r.ParseForm() - request = append(request, "\n") - request = append(request, r.Form.Encode()) - } - request = append(request, "--------") - // Return the request as a string - return strings.Join(request, "\n") -} - func testAccGoogleSignedUrlExists(n string) resource.TestCheckFunc { return func(s *terraform.State) error { @@ -244,43 +165,37 @@ func testAccGoogleSignedUrlRetrieval(n string, headers map[string]string) resour return fmt.Errorf("signed_url is empty: %v", a) } + // create HTTP request url := a["signed_url"] - fmt.Printf("URL: %s\n", url) method := a["http_method"] - req, _ := http.NewRequest(method, url, nil) - // Apply custom headers to request + // Add extension headers to request, if provided for k, v := range headers { - fmt.Printf("Adding Header (%s: %s)\n", k, v) req.Header.Set(k, v) } + // content_type is optional, add to test query if provided in datasource config contentType := a["content_type"] if contentType != "" { - fmt.Printf("Adding Content-Type: %s\n", contentType) req.Header.Add("Content-Type", contentType) } - md5Digest := a["md5_digest"] - if md5Digest != "" { - fmt.Printf("Adding Content-MD5: %s\n", md5Digest) - req.Header.Add("Content-MD5", md5Digest) + // content_md5 is optional, add to test query if provided in datasource config + contentMd5 := a["content_md5"] + if contentMd5 != "" { + req.Header.Add("Content-MD5", contentMd5) } - // send request to GET object using signed url + // send request using signed url client := cleanhttp.DefaultClient() - - // Print request - //dump, _ := httputil.DumpRequest(req, true) - //fmt.Printf("%+q\n", strings.Replace(string(dump), "\\n", "\n", 99)) - fmt.Printf("%s\n", formatRequest(req)) - response, err := client.Do(req) if err != nil { return err } defer response.Body.Close() + + // check content in response, should be our test string or XML with error body, err := ioutil.ReadAll(response.Body) if err != nil { return err @@ -318,42 +233,15 @@ data "google_storage_object_signed_url" "story_url" { bucket = "${google_storage_bucket.bucket.name}" path = "${google_storage_bucket_object.story.name}" -}`, bucketName) -} - -func testAccTestGoogleStorageObjectSingedUrl_wHeader() string { - return fmt.Sprintf(` -resource "google_storage_bucket" "bucket" { - name = "tf-signurltest-%s" -} - -resource "google_storage_bucket_object" "story" { - name = "path/to/file" - bucket = "${google_storage_bucket.bucket.name}" - - content = "once upon a time..." } data "google_storage_object_signed_url" "story_url_w_headers" { bucket = "${google_storage_bucket.bucket.name}" path = "${google_storage_bucket_object.story.name}" - http_headers { + extension_headers { x-goog-test = "foo" + x-goog-if-generation-match = 1 } -}`, acctest.RandString(6)) -} - -func testAccTestGoogleStorageObjectSingedUrl_wContentType() string { - return fmt.Sprintf(` -resource "google_storage_bucket" "bucket" { - name = "tf-signurltest-%s" -} - -resource "google_storage_bucket_object" "story" { - name = "path/to/file" - bucket = "${google_storage_bucket.bucket.name}" - - content = "once upon a time..." } data "google_storage_object_signed_url" "story_url_w_content_type" { @@ -361,26 +249,12 @@ data "google_storage_object_signed_url" "story_url_w_content_type" { path = "${google_storage_bucket_object.story.name}" content_type = "text/plain" -}`, acctest.RandString(6)) -} - -func testAccTestGoogleStorageObjectSingedUrl_wMD5() string { - return fmt.Sprintf(` -resource "google_storage_bucket" "bucket" { - name = "tf-signurltest-%s" -} - -resource "google_storage_bucket_object" "story" { - name = "path/to/file" - bucket = "${google_storage_bucket.bucket.name}" - - content = "once upon a time..." } data "google_storage_object_signed_url" "story_url_w_md5" { bucket = "${google_storage_bucket.bucket.name}" path = "${google_storage_bucket_object.story.name}" - md5_digest = "${google_storage_bucket_object.story.md5hash}" -}`, acctest.RandString(6)) + content_md5 = "${google_storage_bucket_object.story.md5hash}" +}`, bucketName) } diff --git a/website/source/docs/providers/google/d/signed_url.html.markdown b/website/source/docs/providers/google/d/signed_url.html.markdown index ff49e1d0a..afb372b49 100644 --- a/website/source/docs/providers/google/d/signed_url.html.markdown +++ b/website/source/docs/providers/google/d/signed_url.html.markdown @@ -14,7 +14,7 @@ For more info about signed URL's is available [here](https://cloud.google.com/st ## Example Usage -``` +```hcl data "google_storage_object_signed_url" "artifact" { bucket = "install_binaries" path = "path/to/install_file.bin" @@ -27,7 +27,7 @@ resource "google_compute_instance" "vm" { provisioner "remote-exec" { inline = [ - "wget ${data.google_storage_object_signed_url.artifact.signed_url}", + "wget '${data.google_storage_object_signed_url.artifact.signed_url}' -O install_file.bin", "chmod +x install_file.bin", "./install_file.bin" ] @@ -35,6 +35,23 @@ resource "google_compute_instance" "vm" { } ``` +## Full Example + +```hcl +data "google_storage_object_signed_url" "get_url" { + bucket = "fried_chicken" + path = "path/to/file" + content_md5 = "pRviqwS4c4OTJRTe03FD1w==" + content_type = "text/plain" + duration = "2d" + credentials = "${file("path/to/credentials.json")}" + + extension_headers { + x-goog-if-generation-match = 1 + } +} +``` + ## Argument Reference The following arguments are supported: @@ -42,10 +59,20 @@ The following arguments are supported: * `bucket` - (Required) The name of the bucket to read the object from * `path` - (Required) The full path to the object inside the bucket * `http_method` - (Optional) What HTTP Method will the signed URL allow (defaults to `GET`) -* `duration` - (Optional) For how long shall the signed URL be valid (defaults to 1 hour `1h`). See [here](https://golang.org/pkg/time/#ParseDuration) for info on valid duration formats. -* `credentials` - (Optional) What Google service account credentials json should be used to sign the URL. This data source checks the following locations for credentials, in order of preference: data source `credentials` attribute, provider `credentials` attribute and finally the GOOGLE_APPLICATION_CREDENTIALS environment variable. - +* `duration` - (Optional) For how long shall the signed URL be valid (defaults to 1 hour - i.e. `1h`). + See [here](https://golang.org/pkg/time/#ParseDuration) for info on valid duration formats. +* `credentials` - (Optional) What Google service account credentials json should be used to sign the URL. + This data source checks the following locations for credentials, in order of preference: data source `credentials` attribute, provider `credentials` attribute and finally the GOOGLE_APPLICATION_CREDENTIALS environment variable. + > **NOTE** the default google credentials configured by `gcloud` sdk or the service account associated with a compute instance cannot be used, because these do not include the private key required to sign the URL. A valid `json` service account credentials key file must be used, as generated via Google cloud console. + +* `content_type` - (Optional) If you specify this in the datasource, the client must provide the `Content-Type` HTTP header with the same value in its request. +* `content_md5` - (Optional) The [MD5 digest](https://cloud.google.com/storage/docs/hashes-etags#_MD5) value in Base64. + Typically retrieved from `google_storage_bucket_object.object.md5hash` attribute. + If you provide this in the datasource, the client (e.g. browser, curl) must provide the `Content-MD5` HTTP header with this same value in its request. +* `extension_headers` - (Optional) As needed. The server checks to make sure that the client provides matching values in requests using the signed URL. + Any header starting with `x-goog-` is accepted but see the [Google Docs](https://cloud.google.com/storage/docs/xml-api/reference-headers) for list of headers that are supported by Google. + ## Attributes Reference