.Dd April 28th, 2022 .Dt NOTARYTOOL 1 .Os "macOS" .Sh NAME .Nm notarytool .Nd Manage submissions to the Apple notary service. .Sh SYNOPSIS .Nm .Sy submit Ar file-path .Sy "{" Fl k Ar "key-path" Fl d Ar "key-id" Op Fl i Ar "issuer" .Sy "|" Fl -apple-id Ar apple-id Op Fl -password Ar "app-specific-password" .Fl -team-id Ar "team-id" "|" Fl p Ar profile-name Op Fl -keychain Ar "keychain-path" .Sy "}" .Op Fl -wait Fl -no-s3-acceleration Fl -force .Pp .Nm .Sy info Ar "submission-id" .Sy "{" Fl k Ar "key-path" Fl d Ar "key-id" Op Fl i Ar "issuer" .Sy "|" Fl -apple-id Ar apple-id Op Fl -password Ar "app-specific-password" .Fl -team-id Ar "team-id" "|" Fl p Ar profile-name Op Fl -keychain Ar "keychain-path" .Sy "}" .Pp .Nm .Sy log Ar "submission-id" .Sy "{" Fl k Ar "key-path" Fl d Ar "key-id" Op Fl i Ar "issuer" .Sy "|" Fl -apple-id Ar apple-id Op Fl -password Ar "app-specific-password" .Fl -team-id Ar "team-id" "|" Fl p Ar profile-name Op Fl -keychain Ar "keychain-path" .Sy "}" .Op Ar output-path .Pp .Nm .Sy history .Sy "{" Fl k Ar "key-path" Fl d Ar "key-id" Op Fl i Ar "issuer" .Sy "|" Fl -apple-id Ar apple-id Op Fl -password Ar "app-specific-password" .Fl -team-id Ar "team-id" "|" Fl p Ar profile-name Op Fl -keychain Ar "keychain-path" .Sy "}" .Pp .Nm .Sy wait Ar "submission-id" .Sy "{" Fl k Ar "key-path" Fl d Ar "key-id" Op Fl i Ar "issuer" .Sy "|" Fl -apple-id Ar apple-id Op Fl -password Ar "app-specific-password" .Fl -team-id Ar "team-id" "|" Fl p Ar profile-name Op Fl -keychain Ar "keychain-path" .Sy "}" .Pp .Nm .Sy store-credentials Ar "profile-name" .Sy "{" Fl k Ar "key-path" Fl d Ar "key-id" Op Fl i Ar "issuer" .Sy "|" Fl -apple-id Ar apple-id Op Fl -password Ar "app-specific-password" .Fl -team-id Ar "team-id" .Sy "}" .Op Fl -no-validate .Op Fl -keychain Ar "keychain-path" "|" Fl -sync .Pp .Sh DESCRIPTION Common subcommands include .Sy "submit", .Sy "info", .Sy "wait", .Sy "history", .Sy "log", .Sy "store-credentials", and .Sy "help". .Sh BACKGROUND Notarization gives users more confidence that the Developer ID-signed software you distribute has been checked by Apple for malicious components. Notarization is not App Review. The Apple notary service is an automated system that scans your software for malicious content, checks for code-signing issues, and returns the results to you quickly. If there are no issues, the notary service generates a ticket for you to staple (see stapler(1)) to your software; the notary service also publishes that ticket online where Gatekeeper can find it. .Pp .Nm is a developer interface to this service. For example, .Nm .Sy submit .Op options .Ar --wait .Ar file-path will verify .Ar file-path is one of the .Ar Supported Upload File Formats, initiate a connection with the Apple notary service, return the .Ar "Submission ID", upload the file to the Apple notary service, wait for the submission to be processed by the Apple notary service, and exit when the processing is complete. .Pp For more information on notarization, see the "Notarizing macOS Software Before Distribution" documentation at: .Sh AUTHENTICATION OPTIONS The following authentication options are available for all .Nm subcommands: .Pp .Bl -tag -width "-issuer" .It Sy App Store Connect API Keys .Pp .Nm supports two types of App Store Connect API Keys. Team Keys and Individual Keys. .Pp Developer ID team administrators can create Team Keys for the developers on their team by logging into .Ar and selecting the "Keys" tab. For security purposes, the private key can only be downloaded once. .Pp Developers can create an Individual Key by following the instructions to "Generate an Individual Key" at .Ar . For security purposes, the private key can only be downloaded once. .Bl -tag -width "-issuer" .It Fl k, -key Ar key-path App Store Connect API key. File system path to the private key. .It Fl d, -key-id Ar key-id App Store Connect API Key ID. For most teams this will be a 10 character alphanumeric string. .It Op Fl i, -issuer Ar issuer App Store Connect API Issuer ID. The issuer ID is a UUID format string. Required for Team keys. Do not provide for Individual keys, this will result in a "401 Unauthorized" response from the server. .El .It Sy App-specific Passwords .Pp Create App-specific passwords by following the instructions on "Using app-specific passwords" at .Ar "". Any developer that has accepted the relevant agreements can use app-specific passwords with the Apple notary Service. .Bl -tag -width "-issuer" .It Fl -apple-id Ar apple-id The Apple ID login username you use with Developer ID services. .It Op Fl -password Ar app-specific-password App-specific password for your Apple ID. You will be given a secure prompt on the command line if Apple ID and Team ID are provided but the .Fl -password option is not specified. .It Fl -team-id Ar wwdr_team_id The team identifier for the Developer Team to be used with this .Nm subcommand. Usually 10 alphanumeric characters. Your Apple ID may be a member of multiple teams, you can find Team IDs for teams you belong to by going to .Ar "". You cannot get information on Submission IDs created by another .Ar "wwdr_team_id". .El .El .Pp The following options are available for all subcommands except .Sy "store-credentials": .Bl -tag -width "-issuer" .It Fl p, -keychain-profile Ar profile-name Authenticate using credentials stored in the Keychain by .Nm . Use the profile name that you previously provided via the .Sy "store-credentials" command. .It Fl -keychain Ar keychain-path Pass the path to a keychain file to use for reading the keychain item specified by .Fl p Ar "profile-name". If the specified keychain file is locked, you will be prompted to unlock it. .El .Sh SUPPORTED UPLOAD FILE FORMATS .Nm .Sy submit works only with UDIF disk images, signed "flat" installer packages, and zip files. .Nm will do a shallow validation of the file before submission. Passing any other file format in .Ar file-path to .Nm .Sy submit will result in an error. .Pp .Sh SUBMISSION ID .Nm .Sy submit returns a Submission ID as a UUID formatted string used to identify your submission. This Submission ID is necessary for the following subcommands: .Sy "info", .Sy "wait", and .Sy "log". The Submission ID is also necessary when requesting support for most Apple notary service issues. .Pp Submission IDs are unique to the development team that generated them. You can only retrieve information for submissions created by your team. .Pp .Sh COMMON OPTIONS The following output control options are available for all .Nm subcommands: .Pp .Bl -tag -width "-output-format" .It Fl -version Outputs the current version and build number of .Nm . .It Fl v, -verbose Enable streaming of DEBUG level logs to stderr. This option can help the user decipher why a particular operation may have failed. Subsequent versions of .Nm may change the verbose logging. Do not write scripts assuming specific messages will continue to exist in the current form. .It Fl -progress, -no-progress Display progress indicators. Only compatible with .Ar normal output formal. .Nm defaults to .Sy "--progress". .It Fl f, -output-format Ar format Desired output format. Note that .Ar json and .Ar plist are incompatible with .Sy "--progress" as all output will be suppressed until the subcommand has completed. Options are .Sy "normal", .Sy "json", or .Sy "plist". .Nm defaults to .Ar normal output format. .El .Pp .Sh SUBCOMMANDS .Bl -tag -width "history" -compact .It Sy help Display summary usage information. See .Nm .Sy help .Ar subcommand for more detailed help. .Pp .\" store-credentials -------------- .It Sy store-credentials Ar profile-name Ar "authentication_options" Op options Save authentication credentials for the Apple notary service to the default login keychain. If using .Fl -key-path to pass the file path of a private key, the contents of the private key are stored in the new keychain item and the private key file can be deleted. .Pp .Ar profile-name is the name of the new keychain item to create. Passing in a previously saved profile name will cause the old keychain item to be overwritten. .Pp Other options: .Bl -tag -width "-no-wait" .It Fl -validate, -no-validate Verify that the authentication credentials are valid for use with the Apple notary service before saving them to the keychain and return an error otherwise. The default is .Fl "-validate". .It Fl -keychain Ar keychain-path Pass the path to a keychain file to use for writing the keychain item specified by .Ar "profile-name". If the specified keychain file is locked, you will be prompted to unlock it. Cannot be specified if .Fl -sync is used. .It Fl -sync Make the new profile synchronize and accessible across devices with iCloud Keychain. Uses the "Local Items" keychain if iCloud Keychain is disabled. Cannot be specified if .Fl -keychain is used. .El .Pp .\" submit -------------- .It Sy submit Ar file-path Ar "authentication_options" Op options Submit an archive to the Apple notary service. .Ar file-path must be a .Ar "Supported Upload File Format". .Pp Other options: .Bl -tag -width "-no-wait" .It Fl -wait, -no-wait Rather than exiting after a successful upload, begin waiting for your submission to complete. The default is .Fl "-no-wait". See the .Sy wait subcommand for more information. .It Fl -timeout Ar duration If .Fl -wait is enabled, .Nm will exit after polling for the specified duration. Although .Nm exits, the submission will continue to be processed by the Apple Notary service. See the .Sy wait subcommand for more information. .It Fl -s3-acceleration, -no-s3-acceleration Use S3 Transfer Acceleration for potentially faster uploads. The default is .Fl "-s3-acceleration" .It Fl -force Upload the file even if pre-flight validation problems are encountered. The .Fl -force option can be useful if you think the pre-flight validation is incorrect or slow. .El .Pp .It Sy info Ar submission-id Ar "authentication_options" Op options Get status information for a previous submission. .Ar "submission-id" is a Submission ID returned from a previous invocation of the .Sy submit subcommand. .Pp .It Sy log Ar submission-id Ar "authentication_options" Op Ar "output-path" options Retrieve notarization log for a single completed submission as JSON. .Ar "submission-id" is a Submission ID returned from a previous invocation of the .Sy submit subcommand. .Pp Use .Ar "output-path" to specify a path for the new notarization log file, otherwise the notarization log is printed to .Sy "stdout". .Pp .\" history -------------- .It Sy history Ar "authentication_options" Op options Get a list of previous submissions for your development team that were submitted via .Nm . .Pp .It Sy wait Ar submission-id Ar "authentication_options" Op options Wait for completion of a previous submission. .Ar "submission-id" is a Submission ID returned from a previous invocation of the .Sy submit subcommand. .Pp Only return from .Nm once the Apple notary service has responded with a status of "Accepted", "Invalid", "Rejected", or if a fatal error has occurred during submission. This option replaces the need for polling from a script. .Pp Other options: .Bl -tag -width "-no-wait" .It Op Fl -timeout Ar duration .Nm will exit after polling for .Ar "duration". The Notary service will continue processing the submission even if the timeout is reached. .Ar Duration is an integer followed by an optional suffix: seconds 's' (default), minutes 'm', hours 'h'. For example, these values all set the timeout to an hour: .Ar "3600", .Ar "3600s", .Ar "60m", .Ar "1h". .El .El .Sh ALTOOL MIGRATION .pp In fall of 2023, altool will no longer be supported for notarization. Use .Nm instead. If you previously invoked altool like this: altool --notarize-app -f path/to/app.pkg --primary-bundle-id com.example.myapp --apiKey 7UD13000 --issuerId 6bc36aee-c5c8-11ec-9d64-0242ac120001 Instead, use notarytool like this: notarytool submit path/to/app.pkg --key path/to/AuthKey_7UD13000.p8 --key-id 7UD13000 --issuer 6bc36aee-c5c8-11ec-9d64-0242ac120001 --wait .Sh EXAMPLES .Bl -tag -width "--issuer" .It To store app-specific password credentials in the default keychain as a profile named MyGreatCompany-ASP: .Nm Sy "store-credentials" Ar "MyGreatCompany-ASP" Fl -apple-id Ar "mygreataccount@example.com" Fl -team-id Ar K36BKF7T3D .Pp .It To store App Store Connect credentials in the iCloud keychain as a profile named MyGreatCompany: .Nm Sy "store-credentials" Ar MyGreatCompany Fl -key Ar "~/.private_keys/AuthKey_59GAB85EFG.p8" Fl -key-id Ar 59GAB85EFG Fl -issuer Ar a04788a9-0819-478d-936f-6ff0fd860df5 Fl -sync .Pp .It To submit a disk image to the notarization service, using previously saved credentials while waiting for response: .Nm Sy "submit" Ar MyDiskImage.dmg Fl p Ar MyGreatCompany Fl -wait .Pp .It If the previous command returned a Submission ID of d0d37a38-dc80-4603-bca9-80705a49cbbd, download the log: .Nm Sy "log" Ar d0d37a38-dc80-4603-bca9-80705a49cbbd Fl p Ar MyGreatCompany Ar "~/Desktop/developer_log.json" .El .Sh PERFORMANCE TUNING .Nm has some options that are designed to allow a developer to tune some characteristics specifically for their network conditions. .Pp .Bl -tag -width "--issuer" .\" .It defaults write "com.apple.gke.notary.tool" upload-chunk-size-mb -integer Ar chunk-size-in-megabytes .\" The submission of files over 8MB in size are uploaded in discrete data chunks. By default, all submissions under 8GB use 8MB chunks and all submissions over 8GB are divided into 1000 data chunks. Specify a value between 8 and 5000 for .\" .Ar chunk-size-in-megabytes .\" "to finely control the size of the data chunks if it better suits your network conditions. .\" .It defaults write "com.apple.gke.notary.tool" upload-connection-timeout -integer Ar timeout-in-seconds .\" Each discrete data chunk must complete uploading before .\" .Ar timeout-in-seconds .\" expires. One retry of uploading the chunk occurs if the timeout has expired. The default timeout 100 seconds. Values over 300 seconds may not be respected, depending on local network conditions. .It Nm Sy submit Ar .. Op Fl "-s3-acceleration" | Fl "-no-s3-acceleration" If you experience performance or connectivity issues, please try disabling S3 Transfer Acceleration with .Fl "-no-s3-acceleration" when submitting files to the notary service. .El .Sh SEE ALSO .Pp .Xr codesign 1 , .Xr stapler 1 , .Xr altool 1 , .Xr spctl 8 , .Xr syspolicyd 8 .Sh HISTORY The .Nm command first appeared in Xcode 13