icloud

Documentation

Overview

Package icloud implements Apple iCloud authentication and CloudKit Photos access entirely in Go, without depending on icloudpd or any Python runtime.

Authentication uses Apple's SRP-6a variant:

• 2048-bit safe prime (RFC 5054 group 14)
• SHA-256 hash
• PBKDF2 password derivation (s2k / s2k_fo protocols)

Session cookies are persisted to ~/.imole/icloud-session.json and reused across invocations, so interactive 2FA is only needed once.

Index

• func DeleteSession(username string)
• func SaveSession(username string, s *Session) error
• func StdinTwoFA() (string, error)
• type AssetRecord
• type Client
  • func Login(username, password, domain string, interactive bool, ...) (*Client, error)
  • func NewClient(domain string) (*Client, error)
  • func (c *Client) DownloadAsset(ar AssetRecord, destDir string) (string, error)
  • func (c *Client) QueryByFilenames(filenames []string) ([]AssetRecord, error)
• type SRPClient
  • func NewSRPClient() (*SRPClient, error)
  • func (c *SRPClient) PublicB64() string
  • func (c *SRPClient) Respond(username, password, saltB64, serverBB64, protocol string, iterations int) (m1B64 string, sessionKey []byte, err error)
• type Session
  • func LoadSession(username string) *Session
  • func (s *Session) Apply(req *http.Request)
  • func (s *Session) IsValid() bool
• type SimpleCookie

Functions

func DeleteSession

func DeleteSession(username string)

DeleteSession removes the saved session (e.g. after auth failure).

func SaveSession

func SaveSession(username string, s *Session) error

SaveSession persists the session to disk.

func StdinTwoFA

func StdinTwoFA() (string, error)

StdinTwoFA reads a 2FA code from os.Stdin. Use as twoFAInput in Login.

Types

type AssetRecord

type AssetRecord struct {
	RecordName string
	Filename   string
	FileSize   int64
	CreatedAt  time.Time
	// download info
	DownloadURL   string
	DownloadToken string
}

AssetRecord represents a photo/video asset from CloudKit.

type Client

type Client struct {
	Session *Session
	// contains filtered or unexported fields
}

Client is an authenticated iCloud HTTP client.

func Login

func Login(username, password, domain string, interactive bool, twoFAInput func() (string, error)) (*Client, error)

Login authenticates with Apple ID and returns a ready Session. If a valid cached session exists it is returned immediately. interactive controls whether 2FA prompts are shown on stdin/stdout.

func NewClient

func NewClient(domain string) (*Client, error)

NewClient creates a Client for the given domain ("com" or "cn").

func (*Client) DownloadAsset

func (c *Client) DownloadAsset(ar AssetRecord, destDir string) (string, error)

DownloadAsset downloads an AssetRecord to destDir/filename. Returns the path of the saved file.

func (*Client) QueryByFilenames

func (c *Client) QueryByFilenames(filenames []string) ([]AssetRecord, error)

QueryByFilenames searches the iCloud Photos library for assets matching any of the given filenames. Returns matched AssetRecords.

type SRPClient

type SRPClient struct {
	A *big.Int // public ephemeral  g^a mod N
	// contains filtered or unexported fields
}

SRPClient holds the per-session SRP state.

func NewSRPClient

func NewSRPClient() (*SRPClient, error)

NewSRPClient creates a new SRP client with a random private ephemeral.

func (*SRPClient) PublicB64

func (c *SRPClient) PublicB64() string

PublicB64 returns the client's public value A as base64 (what Apple expects).

func (*SRPClient) Respond

func (c *SRPClient) Respond(username, password, saltB64, serverBB64, protocol string, iterations int) (m1B64 string, sessionKey []byte, err error)

Respond computes M1 (client proof) given the server's response fields. protocol is "s2k" or "s2k_fo". Returns M1 (base64) and the session key K.

type Session

type Session struct {
	AccountCountry string `json:"account_country"`
	DSID           string `json:"dsid"`
	// Session cookies
	WebAuthToken      string `json:"web_auth_token"`
	WebAuthUser       string `json:"web_auth_user"`
	WebAuthValidate   string `json:"web_auth_validate"`
	WebKB             string `json:"web_kb,omitempty"`
	DSWebSessionToken string `json:"ds_web_session_token,omitempty"`
	// Routing
	Domain    string `json:"domain"` // "com" or "cn"
	Partition int    `json:"partition"`
	// Timestamps
	SavedAt time.Time `json:"saved_at"`
	// Raw cookies for direct HTTP use
	Cookies []*SimpleCookie `json:"cookies,omitempty"`
	// Headers needed for re-authentication
	Scnt      string `json:"scnt,omitempty"`
	SessionID string `json:"session_id,omitempty"`
}

Session holds all state needed to make authenticated iCloud API calls.

func LoadSession

func LoadSession(username string) *Session

LoadSession loads a previously saved session. Returns nil if none exists.

func (*Session) Apply

func (s *Session) Apply(req *http.Request)

Apply injects the session cookies into an http.Request.

func (*Session) IsValid

func (s *Session) IsValid() bool

IsValid returns true if the session was saved recently enough to try. iCloud sessions last ~2 weeks; we conservatively accept up to 12 days.

type SimpleCookie

type SimpleCookie struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

SimpleCookie is a serialisable subset of http.Cookie.