netrc

README

netrcgo

A Go library for reading .netrc files.

About .netrc files

The .netrc file format is a widespread and well-used concept for storing login credentials, though not formally standardized. Originally developed for FTP clients, it's now used by many tools including curl, git, and various HTTP clients.

Format:

machine hostname
login username
password secret

default
login anonymous
password user@domain.com

File location: This library looks for .netrc in the user's home directory on all platforms (unlike curl which uses _netrc on Windows).

Install

go get github.com/albertocavalcante/netrcgo

Usage

package main

import (
    "fmt"
    "log"
    
    "github.com/albertocavalcante/netrcgo"
)

func main() {
    // Get credentials from ~/.netrc
    creds, found, err := netrc.GetHostCredentials("api.github.com")
    if err != nil {
        log.Fatal(err)
    }
    if found {
        fmt.Printf("Login: %s\n", creds.Login)
        // Use creds.Password for authentication
    }
}

API

Core Functions

// Get credentials from default ~/.netrc file
creds, found, err := netrc.GetHostCredentials("hostname")

File Operations

// Use specific .netrc file
f, err := netrc.NewFile("/path/to/.netrc")
creds, found, err := f.GetCredentials("hostname")

Utilities

// Parse .netrc content directly
login, password, found, err := netrc.ParseNetrcFile(content, "hostname")

// Get default .netrc file path
path, err := netrc.DefaultPath()

// Check if credentials are empty
if creds.IsEmpty() {
    // no credentials found
}

Types

type Credentials struct {
    Login    string
    Password string
}

Implementation Notes

• File permission validation on Unix systems (mode 0600 or 0400)
• Cross-platform home directory detection
• Uses .netrc filename on all platforms
• Handles default machine entries
• Memory-safe parsing with no external dependencies

Environment Variables

• NETRC - Custom path to .netrc file
• HOME - User home directory (Unix)
• USERPROFILE - User profile directory (Windows)

Contributing

Contributions welcome! Please check the issues or open a new one.

License

MIT License - see LICENSE file for details.

Documentation

Overview

Package netrc provides functionality for reading and parsing .netrc files.

Security Note: .netrc files store credentials in plaintext and should have restrictive permissions (0600) to prevent unauthorized access. This package validates file permissions and will return an error if the file is readable by others.

Example usage:

// Get credentials for a specific host
creds, found, err := netrc.GetHostCredentials("example.com")
if err != nil {
	log.Fatal(err)
}
if found {
	fmt.Printf("User: %s\n", creds.Login)
}

// Use a specific .netrc file
f, err := netrc.NewFile("/path/to/.netrc")
if err != nil {
	log.Fatal(err)
}
creds, found, err := f.GetCredentials("example.com")

Index

• Constants
• func DefaultPath() (string, error)
• func ParseNetrcFile(content string, targetHost string) (login, password string, found bool, err error)
• type Credentials
  • func GetHostCredentials(host string) (Credentials, bool, error)
  • func (c Credentials) IsEmpty() bool
• type File
  • func NewFile(path string) (*File, error)
  • func (f *File) GetCredentials(host string) (Credentials, bool, error)

Constants

const DefaultNetrcFilename = ".netrc"

DefaultNetrcFilename is the standard filename for netrc files.

Functions

func DefaultPath

func DefaultPath() (string, error)

DefaultPath returns the path to the default .netrc file. It checks NETRC, USERPROFILE, HOME environment variables, then os.UserHomeDir().

func ParseNetrcFile

func ParseNetrcFile(content string, targetHost string) (login, password string, found bool, err error)

ParseNetrcFile parses .netrc file content and returns credentials for the given host. It aims to follow common .netrc conventions, including handling of 'machine', 'default', 'login', 'password' keywords, quoted strings with escapes, and skipping comments/macdef. The first complete 'machine' entry matching targetHost wins. If no specific machine matches, the first complete 'default' entry wins.

Types

type Credentials

type Credentials struct {
	Login    string
	Password string
}

Credentials represents a username and password pair from a .netrc file. It holds the Login (username) and Password.

func GetHostCredentials

func GetHostCredentials(host string) (Credentials, bool, error)

GetHostCredentials is a convenience function that gets credentials for the specified host using the default .netrc path.

func (Credentials) IsEmpty

func (c Credentials) IsEmpty() bool

IsEmpty returns true if both Login and Password are empty.

type File

type File struct {
	// contains filtered or unexported fields
}

File represents a .netrc file and provides methods to retrieve credentials. Its main purpose is to encapsulate the file path.

func NewFile

func NewFile(path string) (*File, error)

NewFile creates a new File instance for the specified .netrc file path. If the provided path is empty, it uses the default .netrc file location.

func (*File) GetCredentials

func (f *File) GetCredentials(host string) (Credentials, bool, error)

GetCredentials reads the .netrc file and parses it to find credentials for the specified host. If the .netrc file does not exist, it returns false for found and no error.